Lab Kit

Live calculation tables, lab snippet forms and a hazard header for a chemistry lab notebook in Obsidian.

Lab Kit turns a plain note into an experiment page: a hazard table built from your chemical notes, tables that calculate like a spreadsheet, and pop-up forms that write the tables you use every day (solutions, recipes, RAFT, sampling timetables, NMR / GPC / DLS sample tables). It started as a PhD lab notebook; the vocabulary is a chemistry lab's, but nothing stops you using it for anything that needs small calculations in a note.

[!note] Beta Version 1.0.0 is a beta: the planning kit and the multi-kit system are new and not yet tested by many people. Report problems on GitHub.

Contents

• Features
• Install
• Quick start
• Calc tables
• Chemical database
• Snippet forms (Alt+S)
• Analysis methods
• Experiment header
• Built-in kit
• Folder contract
• Settings
• Commands
• Privacy & permissions
• Mobile
• Troubleshooting
• Support and contributing
• Development
• Licence

Features

• Calc tables: ```calc blocks with Excel-style formulas (SUM, XLOOKUP, IF, …), references between tables, and MW() read from your chemical notes. Click a cell to edit; everything that depends on it updates, and the cells a formula points at are ringed while you type it.
• Chemical database: point Lab Kit at your folder of chemical notes; typing [[ in a calc cell and the reagent/solvent fields of the forms suggest them, by note name or by the names in a note's Names property.
• Snippet forms (Alt+S, needs Templater): solution prep (targets by concentration or ratio, added in g or mL), recipe by equivalents, RAFT recipe, sample lists, sampling timetables, NMR / GPC / DLS sample tables, combined results, flow column prep, residence times.
• Your own analysis methods: one note per method (and per machine) in a Methods folder defines the sample table; each shows up in the Alt+S menu and feeds the combined results.
• Experiment header: hazard table built from the note's Chemicals property, and a button that opens the experiment's data folder.
• Built-in kit (desktop and mobile): the templates, scripts and CSS snippet that go with the plugin are bundled in it, so a plugin update brings the new kit. Choose which snippets you want, review every change before it's made, update only the files you never edited, merge or resolve the ones you changed, and get a backup of anything replaced.

Install

Needs Obsidian 1.14 or newer. For the snippet forms, also install Templater.

1. Settings → Community plugins → Browse → search Lab Kit → Install → Enable.
2. Settings → Lab Kit → Built-in kit → Review update… installs the templates and scripts. The first install can also turn on the CSS snippet and, if Templater has no user scripts folder yet, set one.
3. For Alt+S: Settings → Lab Kit → Kit folders and setup → Check setup… → Fix the Templater rows, then Obsidian → Hotkeys → search Insert snippet → set Alt+S.
4. Settings → Lab Kit → Initials: your initials go into sample codes (ABC0016-A). Until then the snippets use XX.

The full walk-through, with every feature explained, is the tutorial. What changed in each version: changelog.

Quick start

1. Create a new note in your Notes folder and type the title in the box that pops up. You get a numbered note (0016 - Batch esterification) with a hazard table, a data-folder button and five sections: Objectives, Apparatus, Procedure, Results / Analysis, Notes for next time.
2. Put your chemicals in the Chemicals property as links ([[DCM]]). The hazard table fills in from each chemical note's H_Phrase list.
3. Press Alt+S, type a few letters (raft, sol, nmr), press Enter, fill in the form, press Enter. The table appears in your note.
4. Click any blue (calculated) cell to see or change its formula; type a value in any cell, and the tables that use it update.

Calc tables

A ```calc block holds a Markdown table that behaves like a small spreadsheet.

```calc
name: sol1
title: Stock solution
| Item | MW | mass (mg) | mmol |
|---|---|---|---|
| [[DCM]] | =MW(A2) | 250 | =C2/B2 |
```

• Formulas start with an equals sign and use Excel syntax. Row 1 is the header, so the first data row is row 2. Other tables in the note are reached by name (sol1!D2, SUM(sol1!D2:D4)).
• Functions: SUM AVERAGE MIN MAX COUNT COUNTA PRODUCT SUMPRODUCT ROUND ROUNDUP ROUNDDOWN INT ABS SQRT POWER EXP LN LOG LOG10 MOD PI IF IFERROR AND OR NOT CONCAT MATCH INDEX XLOOKUP CLOCK MW PROP. MW("DCM") reads the molecular weight from a chemical note, PROP("PABTC", "Density") any property, CLOCK("10:30", 90) gives a clock time 90 minutes later.
• Editing: click a cell, type, Enter or Tab to save, Esc to throw it away. + Row adds a row and copies the formulas down; right-click a row to insert or delete one. References update like Excel, including those in other tables.
• Colours: plain = typed, blue = calculated, amber = "needs …" (an input is missing, it tells you which), red = a real problem (hover for the reason).
• Copy puts the table on the clipboard for Excel or Origin; A1 shows cell addresses.
• Block options (lines above the table): name, title, icon, decimals, sig, grid, copy. See the tutorial.
• From Excel: the optional excel_to_calc.py script turns the sheets of an .xlsx into calc blocks, formulas included (tutorial section 5).

Chemical database

Set Chemical folder to the folder that holds your chemical notes (one note per chemical). Lab Kit then uses them in three places:

• MW() and PROP() read the note's properties (MW from the property you choose in Molecular weight property, or MW, Mr, Molecular weight and similar).
• Typing [[ in a calc cell, or in a reagent, solvent, monomer, CTA or initiator field of a form, suggests your notes by file name or by their Names property (a list or a single value). A name found through Names inserts [[Note|name]].
• The hazard table lists each chemical from its H_Phrase property.

Give a chemical a Chemical class (any text, or a list: solvent, monomer, initiator, CTA, or a class of your own). Form fields that ask for a class (Solvent, Monomer, CTA, Initiator) then suggest those chemicals first; switch on Only suggest chemicals of the asked class to hide the others. Reagents and solutes stay unfiltered.

A chemical note is an ordinary note with properties, for example:

---
Names:
  - dichloromethane
  - methylene chloride
MW: 84.93
Density: 1.33
H_Phrase:
  - H315
  - H336
---

Snippet forms (Alt+S)

Put the cursor where you want the table, press Alt+S, pick a snippet, fill in one form, press Enter. Forms start empty (grey placeholders show what to type), and submitting an untouched form inserts nothing.

Choose which snippets you want in Manage files… (each has a Use toggle). Icons for the Alt+S menu are a setting.

Analysis methods

One note per method in your Methods folder, with a Columns property, gives you a sample table of your own (mass spec, XRD, TGA, …), a Results property chooses what goes into Combined results, and one note per machine fills in defaults. Each method appears in the Alt+S menu by itself. NMR, GPC and DLS are built in. Details and an example: tutorial section 6.1.

Experiment header

A ```lab-header block shows, for the note it is in:

• a hazard table with every chemical in Chemicals, worst first, each H-code coloured by severity, as one row per chemical with chips (default) or as the two-column table;
• an Open data folder button that creates <data folder root>/<note name> and opens it (desktop only; set the root in Settings → Lab Kit → Lab header).

It only redraws when this note's Chemicals or a linked chemical note changes. The command Insert lab header block adds one; the Lab Book template already has it. Every option is in Settings → Lab Kit → Hazards and can be overridden for one note with lines inside the block (layout: table, collapsed: false, …): see tutorial section 4.

Built-in kit

The templates (Lab Book, Alt+S menu, one file per snippet), the Templater scripts and a CSS snippet are bundled inside the plugin. Updating the plugin brings the new kit, but your files only change when you say so:

• Review update… previews every file (new, updated, changed by you, missing) and writes nothing until you press Apply.
• Update all safe files adds new files and updates the ones you never edited.
• Manage files… lists every kit file with a status and buttons to update, restore the original, detach, or open it; files that need action come first. Each snippet row has Make my own copy: it asks for a name and saves a plain, editable note in the Snippets folder.
• A file you edited is never overwritten. If your changes and the kit's touch different lines you can merge; if they touch the same lines you resolve them change by change.
• Every replaced file is copied to a backup folder first.

The kit is split into two kits, each with its own files, state and switch: the lab kit (Lab Book template, snippets, scripts; on by default) and the planning kit (homepage, to-do board, projects, meetings, knowledge notes; preview, off until you switch it on). Review, Manage and Update work per kit.

Folder contract

The kits expect these folders. Each is a setting; empty means the default below, and a folder you rename inside Obsidian is followed by its setting.

A new vault can get this layout, the plugin list and the Templater settings from the generated starter (see Development).

Settings

Settings → Lab Kit is searchable and grouped:

Folder settings left empty are detected; the data folder roots are empty until you set them. Rename or move folders inside Obsidian and the folder settings follow; a folder moved outside Obsidian (Finder, File Explorer, a sync tool) is found again with Find moved folders. Settings changed on another device (Obsidian Sync, iCloud, Dropbox, Syncthing, Git) are read again when they arrive.

Commands

Open the command palette and type Lab Kit. There are no default hotkeys.

With the planning kit on (Settings → Lab Kit → Built-in kit), these are added. Open meeting deck is desktop only.

Privacy & permissions

• No network use. Lab Kit never connects to the internet, has no account, no ads, no telemetry and no paid features. The "full changelog" button only opens a link in your browser when you press it.
• Files in your vault: the built-in kit reads and writes only the folders you set in Settings → Lab Kit, and copies a replaced file to a backup folder first. To find where your templates and scripts are, it lists the files in your vault.
• Other plugins' settings: never changed without asking. Before the first kit install (and before a Check setup Fix) a confirmation lists every file, folder and setting it will touch, each setting with a switch: the kit's CSS snippet, Templater's user scripts folder when Templater has none (a folder you set is never changed; the lab scripts go into a lab-kit folder inside it), Templater's template folder when it is empty (Set up only), and the Alt+S template in Templater's hotkeys.
• Clipboard: the Copy button on a table writes to the clipboard, only when you click it.
• Files outside your vault (optional, desktop only): the data-folder button in the experiment header creates <data folder root>/<note name> on your computer and opens it in your file manager, only when you press it. The root is empty until you set it in Settings → Lab Kit → Lab header. Nothing else reads or writes outside your vault.

Mobile

Calc tables, the hazard header and the built-in kit work on mobile. The data-folder button is desktop only: on mobile the header shows "Data folder: desktop only". Snippet forms need Templater.

Troubleshooting

More in the tutorial.

Support and contributing

Found a bug or want a feature? Open an issue and say what you did, what you expected and what happened (a screenshot of the table helps). Pull requests are welcome; run npm test and npm run lint first.

Development

npm install
npm run dev          # builds into test-vault/.obsidian/plugins/lab-kit/ and watches
npm test             # vitest
npm run lint
npm run build
npm run starter     # new-vault settings + plugin list, from the kits, into dist/starter/

npm run tidy-fixture writes test-vault-tidy/, a small vault of old-style notes (from tests/fixtures/) to try Tidy up notes on; open it as its own vault, never your real one.

npm run starter writes dist/starter/: empty contract folders, Obsidian settings (plugin list, CSS snippets, Alt+S, Templater folders) and install-plugins.sh / .ps1, generated from the kits so they can't drift. Copy it into an empty folder, run the install script with Obsidian open, then Check setup. Steps in GETTING-STARTED.

Open test-vault/ as a vault in Obsidian to try changes. Never develop in your real vault. The kit files live in kits/ and are embedded in main.js at build.

Licence

MIT, see LICENSE.