Changelog

What changed in SampleKit from one version to the next, newest first. Each version says what was added, changed, removed and fixed, for someone who uses SampleKit rather than works on it.

A version ending in -rc.N is a release candidate: tried before the version of that number is published, and replaced by it.

[1.0.0-rc.3] — 2026-11-11

The third release candidate of SampleKit 1.0 (1.0.0rc3 for Python).

Upgrading from 1.0.0-rc.2

Sample files, the configuration and the history are unchanged. Install the command line and the Python package together, at the same version, in each project's environment: this version refuses rc.2's package. The terminal interface now draws in SampleKit's own theme where the terminal draws every colour; theme = "terminal" in [colors], or T, keeps the terminal's sixteen colours, as rc.2 drew.

Added

  • Themes for the terminal interface: SampleKit's own, samplekit-dark and samplekit-light, made to be read, each role a colour of its own and every colour at a contrast checked by a test; it is the default, light where the terminal says its background is (COLORFGBG), and the terminal's own sixteen colours where it does not say it draws every colour (COLORTERM; Windows Terminal draws them all). Ten more are built in by name: terminal, the sixteen colours as before, and Catppuccin Mocha and Latte, Dracula, Nord, Tokyo Night, Gruvbox and Solarized, dark and light. A theme paints the whole screen, its background and its text, the two new roles background and foreground of [colors].

  • T chooses the theme, on the start page, the collection and a sample: each is tried on the screen as the cursor reaches it, Enter keeps it for the folder and as your choice for the projects naming none. A project names its own with theme = "nord" in [colors]; the roles it names are laid over whichever theme is in force.

  • Your own themes: a file each in themes/ of SampleKit's configuration folder (~/.config/samplekit/themes/ on Linux), a [colors] table over the theme its base names. One that does not read is said, never passed over.

  • The README shows SampleKit at work: its sample's screen, pictures of the terminal interface, its themes and an animation of it, each drawn by the terminal interface itself; and a logo, SampleKit's name as the start page draws it.

  • The terminal interface keeps every change waiting until w writes it: a value, a row, an attribute, the note, tags, a sample made, removed or renamed, what a script changes, a state restored from the history, and what a computation gives. The screens show the files as the changes make them, marked, while the files themselves are untouched; w shows one preview of them all and writes them as one change of the history, and u takes back the last change waiting. A computation can be tried and dropped without leaving a trace. What waits outlasts the terminal interface: leaving asks whether to write, drop or keep it, and the project offers it again when it is next opened. A file changed meanwhile by another hand is not written over: what waits is laid again over it, field by field.

  • A typing mode in the terminal interface: e enters it, and what is typed replaces the cell under the cursor, as in a spreadsheet, the arrows going from cell to cell; Esc leaves it. A value and its uncertainty are typed in one cell, 12.6 +- 0.02, an attribute is renamed by typing over its name, and Delete takes out an attribute or a table's row.

  • A value's card in the terminal interface: i on a value or a table's cell shows its state in words, what it reads and what reads it, each with its value and its state, and each typed in there: what a change makes outdated is seen at once. The list of samples is typed in too, a column for several samples at once, without opening one. A cell never widens as it is typed in, and the status line ends with the value under the cursor, every digit of it.

  • A PDF at a page: [the method](method.pdf#page=12) and [[method.pdf#page=12]] open the PDF at that page, in the web browser.

  • Links as Obsidian writes them: [[steel-02.md]], [[2024/steel-02]] where two samples share a name, [[Steel-02]] in another case, and [[curve.csv]], any file of the project by its name. A Markdown link's #section is kept apart from its path. rename keeps each link as it was written, its folder, extension and heading.

  • The addresses of other tools: zotero://, obsidian://, mailto:, ftp:// and file:// are links, opened by the application that answers to them.

  • A sixth step of the demo, Links: the specimens linked to each other, to their curves, to a PDF at a page and to a web page, in every form a link takes, with one link that leads nowhere for validate to report.

Changed

  • A value's window is gone from the terminal interface: what it showed side by side, a value, its uncertainty and its readings, is typed on the value's line or in its card. A sample's line shows the mark of its value's state, its words being the card's.

  • A large project is quick: over a project of 4,000 samples, the terminal interface opens in a sixteenth of the time it took, and after a write or an edit in an editor it reads again only the files that changed, in a thirtieth. A list takes a sixteenth of the time; validate an eleventh, and under a thirtieth where samples link to one another; compute's preview, a fifth. A project's files are read on every core. Nothing a command or a screen says changes.

  • A file changed outside SampleKit is told by the system: the terminal interface no longer looks at every file of the project after each key and each second. Linux, macOS, Windows and the BSDs each tell it of a change in the project's folders; it looks all the same every thirty seconds, and where the system can tell nothing, a network drive for one, as before.

Fixed

  • A model in a folder is found past another module of its name: [model] path = "model/specimen.py", the demo's, failed with No module named 'model.specimen'; 'model' is not a package where Python found a model.py first, installed or another project's; the file is now imported by its path.

  • A figure under a folder whose name has an accent: on Windows, p on a figure under a folder such as Thèse said the directory …\samples does not exist, Python reading its request in its code page; every Python SampleKit starts now reads and prints UTF-8.

  • PowerShell completes under an alias: Set-Alias sk samplekit, defined before the completion's line, completes as samplekit does.

  • Paths written on Windows read on Linux and macOS: a \ in a path of .samplekitrc or of a Markdown link is read as /, which SampleKit itself always writes.

[1.0.0-rc.2] — 2026-11-04

The second release candidate of SampleKit 1.0 (1.0.0rc2 for Python).

Upgrading from 1.0.0-rc.1

Sample files are unchanged. samplekit-migrate.pyz, attached to this release, makes the renames below in a copy of a project, its samples copied as they are. It reads projects of 0.1.0 to 0.2.0 too: their samples, and their model's declarations written again, its formulas copied to check by hand. It works on a copy and guarantees nothing: back your project up first. Upgrade from an older SampleKit says how to run it, and each step to do by hand; in short:

  • Before upgrading, bring every value up to date with rc.1: samplekit DIR status, then samplekit DIR compute --write. This version does not read rc.1's record of which formula computed each value: at its first write in a project, it takes the values the files hold as computed by the model as it is then, and says how many.

  • Install the command line and the Python package together, at the same version, on every computer that shares a project.

  • Add python = ".venv" under [model] in .samplekitrc, or the path of another environment or interpreter: the model runs only in the Python named there.

  • Rename what changed name: [workbench.colors] is [colors], the colour role stale is outdated, a style's separator is written as its property, {collection} in a path is {project}; in Python, stale() and is_stale are outdated() and is_outdated. Each old name is refused, naming the new one.

  • new --like SAMPLE is new NAME --keep SAMPLE FIELDS.

  • Rename a property's formulas, in this order: compute= becomes compute_value=, then compute_quantity= becomes compute=. No value is outdated by it. A value formula left as compute= still runs, but then owns the whole property: an uncertainty typed beside it is no longer kept.

Cleaning up after rc.1

Nothing breaks if you leave these, but they are no longer used:

  • In the state folder (~/.local/state/samplekit on Linux, ~/Library/Application Support/samplekit on macOS, %LOCALAPPDATA%\samplekit on Windows): computed.json, computed, consent, accepted/, and the run logs named logs/compute-YYYY-MM-DDT…Z-PID.log can be deleted. samplekit-migrate.pyz --clean-state lists them, and removes them with --write.

  • A history shared through git under rc.1 committed files that each computer keeps for itself. Remove them from the repository once, then add [history] shared = true (below): git rm -r --cached .samplekit/history/HEAD .samplekit/history/config .samplekit/history/description .samplekit/history/hooks .samplekit/model.json, then git add -A.

  • A value restored from a snapshot rc.1 took has no record of the formula that computed it, and is taken as current: if that formula changed since, compute it again, samplekit DIR compute -p NAME --rerun --write.

Added

  • A migration tool, samplekit-migrate.pyz, attached to each release: a project of 0.1.0, 0.1.1, 0.1.2, 0.2.0 or 1.0.0-rc.1, carried into a new folder this version reads, and a report of what was carried, left and to check by hand. Run with the Python of an environment where this version's package is installed; it installs nothing and never writes in the folder it reads.

  • An export writes a figure: [export.curves] with figure = "curves" and output = "paper/curves.pdf", where a table's names its profile. samplekit export curves --write then draws it to its file, as a table for a paper is written again; Python's export("curves") and the TUI's p menu do the same.

  • A project's look decides more of its figures: what [matplotlib] declares wins over SampleKit's own choices, so "lines.marker" = "None" draws a line figure without markers, and errorbar.capsize sets the error bars' caps. style applies matplotlib's style sheets, by name or as .mplstyle files, and fonts makes font files kept in the project known to matplotlib. A figure takes settings of its own: matplotlib = { … } in [figure.NAME], @sk.figure(matplotlib={…}) in a model.

  • import takes a file, and a list: import = ["..", "figures.samplekitrc"] merges the folder above's .samplekitrc and a file of any name, a later one over an earlier one, so that a project's settings can be kept in files of their own. Organise a project's settings shows how.

  • An environment made by uv works: samplekit init installs the package into a .venv/ without pip with uv pip install, when uv is on the PATH, and otherwise says the command to type.

  • Write a command in any order: samplekit samples status, samplekit status samples and samplekit -f 'mass > 10' status samples are the same, and a list of files piped in works, … | xargs samplekit status. Where a folder has a command's name, the command wins; write the folder status/.

  • Select samples on every command: -f (a filter) and --query (a filter saved in .samplekitrc) now work with set, log, diff, restore, validate, list, explain and open too. samplekit samples set -f 'material == steel' supplier=acme previews each sample it changes, asks once, and writes them together.

  • Every change is previewed, then asked: set, new, tag, export, restore and compute show what they would change and end on apply these changes? [y/N]. --write answers yes beforehand, for scripts.

  • Documents in LaTeX, Markdown or HTML: a style, [style.NAME] in .samplekitrc, says how values, units and tables are written for a kind of document. latex, markdown and html are given: samplekit samples --style latex -c name,density -o table.tex writes a LaTeX table ready to include.

  • Filters reach into tables: results has 42, a sample with 42 in any cell of its results table; results.status has failed, in one column; and results where (temperature > 100 && status == failed), one row meeting both. A filter also compares two fields of a sample: measured > expected.

  • Scripts in the model: a method of the model marked @sk.script is an action on a sample or on a selection, with options; samplekit run NAME runs it, or p in the TUI, and what it changes is previewed before it is written.

  • Share the history through git with one line: [history] shared = true in .samplekitrc, and git add -A takes the history with the samples; SampleKit keeps out what each computer makes for itself.

  • A folder made a project keeps its history: when a subfolder gets its own .samplekitrc, the snapshots the project above it took of its files are copied into its own history, and this is said.

  • In the TUI: a value, a table or a list opens in a window where each cell is edited, readings and list items included; A adds an attribute to a sample, its name then its value; p runs a script, draws a figure or writes an export from one menu, for the basket, the sample open or the samples shown.

  • Save what a table shows: --save query=NAME, profile=NAME or export=NAME on a table declares its filter, its columns, sort and groups, or both and an export, in .samplekitrc, previewed first; the TUI's W does the same.

  • Remove a sample: samplekit FILE remove deletes sample files, previewed first; the history keeps them, and restore gives them back. A folder alone is refused. In Python, sample.remove().

  • The note from the command line: set note=… replaces the text below the frontmatter, and note= empties it.

  • Links: an attribute written "[[steel-02]]", as Obsidian writes a link, names another sample of the project; one written as Markdown does, "[certificate](../certificates/c.pdf)", a file by its path, a sample of any project or any other file; one written https://… a web page. A list of links names several. The TUI opens each with Enter or o, a sample even where the filter leaves it out, its title bar saying the way taken and Esc going back along it; Python reads the samples with sample.linked("reference"), a file that is no sample as its path; and validate reports a link that leads nowhere. A link is shown as Markdown shows it, its text alone, underlined in the colour role link, ↗ after a web page and ✗ after one leading nowhere, in the TUI, and in a table and view drawn in a terminal; typed, written to a file or a pipe, it is the text written. Unquoted, a link is refused at its line, saying to quote it. A sample's screen lists the samples linking to it, and the filter links to NAME selects the samples whose links name it; set parents=[[a]],[[b]] writes a list of links, and Tab after [[ completes a sample's name, on set and in the TUI.

  • Rename a sample: samplekit FILE rename NEW renames its file, its own files and its name, and writes every link of the project leading to it again, a link to one of its own files too, previewed first; in the TUI, R; in Python, sample.rename(new). remove lists the links it leaves leading nowhere.

  • A sample's own table written to a file: samplekit FILE view curve shows the table curve alone, and --csv, --tsv, --json or -o curve.csv write its rows, previewed and kept in the history as a table of samples is; over several samples, a column name first. In Python, sample.curve.to_csv().

  • A script may ask with input(): on the command line in the terminal, in the TUI in the script's window, which shows what it prints as it prints it. The preview lists the answers, and the history keeps them with the command.

  • The TUI does what the command line does: C previews what it would compute, as compute does; in H, r puts files back as a change left them, d shows what a change changed and, on another, compares the two; t renames a tag, old=new; N takes a new sample's values, field=value, and fields kept from another, keep:FIELD,…; D removes a sample.

  • An editor of its own window leaves the TUI drawn: with Notepad or code --wait, E and M say what they wait for over the TUI; an editor in the terminal takes it as before.

  • Windows: tab completion in PowerShell completes the word after the cursor, where each Tab wrote the word before it again; E and M open the file in Notepad where no editor is named, rather than in the application Windows gives it (Python, for a model); a sample's folder is shown in Explorer, its file selected; a lock or a journal a killed command left is taken back; paths are said with \, never with both separators in one message.

  • new NAME --keep SAMPLE FIELDS copies the fields named from another sample, and nothing else; [property.NAME] range = [MIN, MAX] makes a value outside the range a defect for validate; compute --timeout SECONDS stops a formula that runs too long and computes the others.

Changed

  • The demo is a tensile test: three metal specimens in five steps, from their sizes written by hand to their curves, results, a paper's tables and figures, and two projects read together; in its results, two specimens link to the one they are compared with. The start page writes it, and Reset the demo writes it again as it came.

  • The documentation is in three parts: guides, a task each; concepts, how SampleKit works and why; and the reference. The home page walks through the demo, and a page at an address of rc.1 sends its reader on. New guides install SampleKit, start a project, edit, find and link samples, work in the terminal interface and from Python, organise settings, read several projects together, and say what to do when something goes wrong.

  • note is a reserved name: a file holding an attribute note: is refused, saying to rename it remarks: or comment:; set note= and sample.note are the text below the frontmatter.

  • A number typed is previewed as the table shows it: set area=25.0 beside an uncertainty of 0.028 previews 25.000, and 25.0123 keeps every digit typed.

  • A new row makes what reads its column outdated: after set --add-row, a value reading a computed column is outdated, as are the values reading it, where it was said to wait for the new cell.

  • compute counts unchanged values by cells, as it counts what it computed: computed 61 values in 3 samples, all unchanged.

  • An uncertainty is rounded up, never understated: at .3f, an uncertainty of 0.00006 is written 0.001, and 0.121 at .2f is 0.13, where rc.1 wrote 0.000 and 0.12. A value is still rounded to the nearest. The screen, Python and every file write the same digits, and a standard error in a summary is rounded up too. An uncertainty is never written as zero, so validate and an export no longer warn of one.

  • A property's formulas are compute, compute_value and compute_uncertainty: compute=f gives the whole property, f() returning a number or (value, uncertainty); compute_value= the value alone, beside an uncertainty given apart. They were compute_quantity, compute and compute_uncertainty.

  • A table's columns are declared with sk.Property, its formula with them: sk.Property(unit="MPa", compute=self._stress, depends_on=["row.force", "area"]), the function given each row and returning its cell, or compute_column=f, given the columns it reads and returning one cell per row; compute_value and compute_uncertainty give one number of each cell, the other entered. sk.Column is gone. A formula filling several columns at once is a sk.ComputedColumns, in the table's computed=; compute_rows and compute_columns are gone. A cell a formula gives is a number or (value, uncertainty), as a property's is, where the pair was refused.

  • A project reads its subfolders by default: [collection] recursive is true unless .samplekitrc says false, so that samplekit . at a project's root reads samples/. A folder outside any project is read alone, as before. A folder reading no sample says so, naming the folders below that hold some.

  • A table names its index: sk.Table(columns, index="day"), or index=["day", "hour"]; the index given by position is refused.

  • The command line is in colour on a terminal, with the TUI's colours: a value bold, an attribute and a unit each in its colour, a header bold, a state as the TUI shows it, ✓ and written: in green. One palette, [colors], sets both; a file and a pipe get none.

  • Numbers in a column line up: a column of numbers is written to the decimals of its most precise, 2.00 beside 1.99; a column of values with uncertainties to one number of decimals where every uncertainty can keep one or two significant digits (two when the first is a 1), 12.503 ± 0.004 above 12.513 ± 0.010. A summary's median, minimum and maximum follow their column, and set says the mean of new readings to the place of their uncertainty. A declared precision still wins.

  • The record of which formula computed each value travels with the project, in its history, no longer on your computer: a formula edited on one computer is seen changed on every other, and a colleague's recomputed values are current on yours.

  • Reading computes nothing, in Python too: a value computed from readings, the mean of several measurements, say, has no value until it is computed, and says never computed, rather than computing behind your back.

  • A file written from values that are not current says so and exits 2: an export or a table written with -o names the values that are outdated, failed or never computed. In a CSV, a column NAME_state beside the quantity says which.

  • Exports write units as the sample files spell them, degC rather than the screen's °C; --style plain gives the screen's forms.

  • restore without --at takes back your last change only, value by value, and keeps what was edited by hand or pulled from a colleague since.

  • A sample file must declare schema_version: 1; a file without it is not a sample, as a README is not. A key written twice in a sample is refused rather than silently taking the last.

  • In the TUI: a value opens selected, so that what you type replaces it (an arrow or End keeps it to edit); the basket is kept from one session to the next; a file changed in another editor is read again by itself.

  • Values not current are counted by cells, on every surface: a table's column outdated in its 13 rows counts 13, and a value and its uncertainty given by two formulas count two.

  • What reads a waiting value waits too, said waits for area, which waits, rather than outdated or failed. A value the model no longer computes is listed apart, to keep or remove.

  • One wording for nothing done: a command with nothing to change says nothing to change — WHY, and a question answered no says nothing written.

  • validate reads each sample with the model, and says where the model cannot read one.

  • A file written from values not current says so on the standard output, so that -q or a redirected error stream does not hide it; --accept waiting is refused, since a waiting value fails nothing.

  • Over several projects, a snapshot's number is one project's: log --at, diff --from and --to from a folder above several projects are refused, naming the project to choose.

  • The migration tool keeps every sample's note, 0.x's included.

Removed

  • Reading what earlier versions wrote: sample files, configuration keys, command-line words and Python names of SampleKit 0.2 and rc.1 are refused like any unknown one, naming the nearest valid name. The upgrade guide says how to carry each over.

  • new --like, compute --try, and the folder after explain FILE: a file SampleKit wrote is now found in the projects around it.

Fixed

Many defects found by testing rc.1, among them values reported as current that were not, edits lost when two changes met, and a colleague's work pulled through git that the history took for your own.

[1.0.0-rc.1] — 2026-09-28

The first release candidate of SampleKit 1.0, and a new SampleKit. Version 0.2.0 was a pure Python package for writing samples from a script. 1.0 keeps its idea — a sample is a Markdown file, with its data at the top — and is built around a command line and a full-screen terminal interface, written in Rust, with a Python package beside them for your formulas and your scripts. Both come from one source and carry one version (1.0.0rc1 for Python).

It does not read the files 0.2.0 wrote, and no command converts them: see Upgrading from 0.2.0 below.

Added

The command line, samplekit, a program with no Python inside. Reading, selecting, showing, checking and exporting samples never start Python.

  • samplekit FOLDER prints the path of each sample; with -c it shows a table of the columns you name, and with --profile a table declared in .samplekitrc. -f filters (-f 'og > 1.050 && tags has medal'), -s sorts, --group makes a table per value of a field, --summary summarises each column. --csv, --tsv and --json print the same table as data, and -o FILE --write writes it.

  • list enumerates what a collection holds and declares: its fields, tags, queries, profiles, exports, figures, a sample's own files, and the files it skipped and why.

  • view shows a sample whole: its values, then its tables, and its note with --note.

  • status lists every computed value that is not current, and why; status --exit-code makes it a check for continuous integration.

  • compute runs the model's formulas: alone it says what would run, with --try it computes and shows the results without writing, and with --write it writes each sample as soon as it is done. explain FILE FIELD says where one value came from, and prints a formula's error.

  • validate reports the defects of sample files and changes nothing.

  • new creates a sample from what the project already knows, set changes its values (set brew.md og=1.052 og.u=0.001, readings, table cells, the name), and tag add, tag remove and tag rename change its tags. Each shows what it would change and writes only with --write.

  • export NAME writes a table declared in .samplekitrc as CSV, TSV or JSON, after a preview; --status adds a column holding each row's state.

  • plot draws a figure with matplotlib, in a window or to a file: one declared in .samplekitrc or by the model, or one given by its axes (-x, -y), over properties, attributes or a table's columns.

  • open opens a sample's own files — photos, reports, raw data — which [collection] files says where to find.

  • init sets a project up: its .samplekitrc, a model to fill in or the one you name with --model PATH, and a Python environment, .venv/, with the SampleKit package installed in it. At a terminal it asks; --example writes a project that runs, one formula of every kind.

  • tui opens the full-screen interface on a folder, and samplekit alone, in a terminal, opens its start page.

  • completions sets up tab completion for bash, zsh, fish, elvish and PowerShell.

  • Every command has --help, with examples, and -h for a short summary. Errors name what was asked, what exists instead, and the nearest name. Exit codes tell a usage error (1) from a data error (2) and a file the system refused (3).

A history of every change. Before SampleKit writes to a project, it keeps what the project held, in .samplekit/history/, beside .samplekitrc: the sample files, the configuration and the model's source. There is nothing to set up, and no Git to install.

  • log lists the snapshots, diff compares two states value by value (abv 6.8 ± 0.1 % → 7.2 ± 0.1 %), and restore puts files back: the last change taken back, or the state of a given snapshot.

  • --at reads the whole project as it was at a snapshot or on a date: samplekit brews -c name,abv --at 2026-09-12. An export made again this way is the same file, byte for byte.

  • A change made in your text editor is kept as a snapshot of its own, so it is never credited to the command that follows.

  • A Python script's writes are one snapshot, with the script's source: log --script N prints the script as it ran, and keep() marks a snapshot of its own from inside a script.

  • Every export and figure SampleKit writes is recorded. explain FILE finds it again, even copied into a manuscript's folder and renamed: what made it, from which samples, whether it is still current, and the command that makes it again.

  • log --export writes the history as Markdown, to share beside the samples.

  • One history over several computers: each writes its own branch in .samplekit/history/, and the next snapshot joins another computer's once your files hold its state — no command merges. log shows a machine column where more than one wrote, and an undo takes back only this computer's change. A synchronised folder shares it as it is; git, once the history's own .gitignore stops ignoring everything.

Current and outdated values. Every computed value carries a short record of what it was computed from. SampleKit compares it with the file as it is now, and knows — from the files alone, without running Python — which values are outdated (an input changed), edited (typed by hand over the formula), failed (the formula raised an error) or never computed. Your computer also keeps a digest of each formula, so that editing a formula makes outdated only the values it computed, and a comment or a docstring changes nothing. A value whose input nobody entered yet waits for it, and is not an error.

  • The states appear in the same words everywhere: status, marks in tables (⚠ outdated, ✎ edited, ✗ failed), the TUI, Python. state is also a field: -f 'state == outdated', -c name,state.

  • A value typed over its formula is an override: compute leaves it alone until compute --force gives it back to its formula.

  • A formula that fails does not stop the run: the other values are computed, the file records the error's type, and the full traceback is kept for explain. An interrupted run loses only the sample in progress.

The full-screen interface, the TUI, for a project you work in every day.

  • A start page: recent projects, a new project set up by a few questions, a folder opened or configured, and the guide and demo.

  • The collection: filter, sort, group, choose columns, summarise, and save what it shows as a query, a profile or an export of the project.

  • A sample: its values, tables, readings and note, each value editable; its own files opened; a value computed, or everything not current.

  • The history: the snapshots, what each changed, and u to take the last change back.

  • The configuration edited from the TUI, and the colours set by role in [tui.colors].

  • Editing as in a text editor, wherever you type — the filter, a value, a name, a setting, the note: the mouse selects, by word on a double click; Shift and the arrows select; Ctrl and the arrows move by word; Ctrl+Backspace and Ctrl+Delete take a word out; Ctrl+Z undoes, Ctrl+Shift+Z redoes; Ctrl+C copies a selection, Ctrl+X cuts, and a paste goes where the cursor is. In the note, Markdown by keys: *, _ or ~ around a selection, Alt+1 to Alt+6 a heading, Alt+L a link, Alt+I an image, Alt+C a code block.

  • ? lists every key of the screen you are on.

A demo: a home brewer's notebook in eight steps, from three brews written by hand to a model, tables, figures, two projects and Python. The start page writes it for you (g), and it is also in the source, in examples/brewing/.

Several projects in one command. samplekit status ana/brews tom/brews reads both; each sample keeps its own project's units, precisions, model, queries and profiles, and the terminal shows one table per project.

New in the sample file (the format itself is under Changed):

  • n/a, not applicable: a value that does not apply to this sample, as distinct from one nobody has measured yet. A formula reading it gives n/a too, without running.

  • Attributes: facts about a sample — a style, a supplier, a date, a list of hops — with no unit and no uncertainty, filtered and shown like properties.

  • Tags, a deliberate label on a sample (tags: [medal]), reached by a filter (tags has medal).

  • A sample's own files — photos, reports, raw data — found by the sample's name where [collection] files says, and opened from the command line, the TUI or Python.

A project's configuration, .samplekitrc, in the project's folder: the model; queries, profiles, exports and figures by name; how a unit is shown in a table, in LaTeX and on a figure ([unit.*]); the precision, symbol and unit of each quantity, declared once ([property.*]); matplotlib's settings; which files are samples. Every key is checked: a misspelt one is an error that names the line and the nearest valid key.

  • import = ".." takes the configuration of the folder named, merged key by key beneath this one: what several collections share is declared once, at their common root, and each collection keeps its model and what is its own. Imports chain; a loop is refused. A relative path reads from the file that declares it, and {collection} names a sample's collection folder in [collection] files and an export's output.

  • What the current folder offers: list profiles, queries, exports and figures, the completion and the TUI's f show the configuration of the folder a command runs from, with what it imports, each name marked local or with the file it comes from. A sample still follows its own collection's configuration wherever the command runs from.

  • validate notes a declaration identical to the one imported, a copy to remove, and --show-rc names the files imported.

One warning a command. A command that would warn several times of one thing — samples a profile or an export several projects lack, targets that are not Markdown, histories not kept, what a model logged — says it once, in one line counting them and ending -v shows them; -v lists each.

The documentation, in four parts: a tutorial that follows the demo; explanations, a page per notion; how-to guides for a task you have in mind; and a reference — every command and option, the Python API, the TUI's keys, every key of .samplekitrc, the sample file format, the exit codes.

Changed

The note below the data is yours. 0.2.0 wrote the body of a file from the model's template() at every save. SampleKit now never writes, reformats or reads the note: not a character, not a line ending. Tables for a reader are what the command line, the TUI and exports show.

The sample file. A sample is still one Markdown file with its data in a YAML block at the top, written differently:

---
schema_version: 1
style: stout
properties:
  og: {v: 1.058, u: 0.001, readings: [1.057, 1.058, 1.059]}
  volume: {v: 19.5, unit: L}
tables:
  fermentation:
    index: day
    columns:
      day: {unit: d}
      gravity: {}
    rows:
      - {day: 1, gravity: 1.041}
---
  • schema_version: 1 heads the file. Quantities go under properties:, tables under tables:, and any other top-level key is an attribute.

  • A quantity is a bare number or a short mapping: v for the value (was value), u for the standard uncertainty in the value's unit (was uncertainty), readings for the repeated measurements (was data), and unit. og.v and og.u are also how a filter, a column, set and Python name the two numbers.

  • A table has index, columns as a mapping and rows (was _index, _columns as a list, _rows), an index of one column or several, and cells that are quantities. fermentation.gravity[3] names the gravity on day 3.

  • A precision and a LaTeX spelling are no longer written in each file (precision, precision_unc, symbol_math, unit_math): they are declared once in .samplekitrc, where a quantity's unit and symbol can be too. A formula is never written in a file.

  • name: is optional: without it, the file's name without its extension stands for the sample's name.

  • A computed value carries a short record of what it was computed from (computed:, fingerprint:), which is how SampleKit tells it is current.

  • Names of properties, attributes, tables, columns and tags start with a letter or _ and hold letters, digits and _, in any alphabet: température and bière are names, dry-hopped is not.

  • The data is written in one fixed form: the first write to a file written by hand may change more lines than the value, and after that only what changed. A write goes to a temporary file first, and is refused if the file changed on disk since it was read.

Readings and their statistic. In 0.2.0, a list of measurements gave the mean and the sample standard deviation on its own. The value of readings is now the statistic the model declares — mean, median, minimum, maximum or a quartile, and standard error or a standard deviation for the uncertainty — or a value written beside them. Readings with neither have no value, and every surface says so rather than taking a mean nobody chose. The file notes which statistic gave the numbers (statistics: {v: mean, u: standard_error}).

Units, symbols and precision are the project's. A unit is a label, never converted; [unit."degC"] says how it is shown in a table (°C), in LaTeX and on a figure. Two samples writing different units for one quantity are reported rather than put side by side. A declared precision rounds alike on the screen and in an export.

The model and computing. A project names its model, a subclass of samplekit.Sample, in .samplekitrc ([model] path and class), and every tool uses it. Each computed value has a formula of its own and names what it reads:

self.abv = sk.Property(unit="%", compute_quantity=self._abv, depends_on=["og", "fg"])
  • compute= gives the value, compute_uncertainty= (was compute_unc) the uncertainty beside a value you enter, and compute_quantity= both. A table's cells are computed a row at a time (compute_rows) or a column at once (compute_columns).

  • depends_on names the inputs by name ("og", "fermentation.gravity"), not as Property objects, and it is required: a model with a formula that declares nothing is refused before any formula runs.

  • A model declares no symbol and no precision: both are the project's, in [property.*], as the unit's display is. sk.Property and sk.Column refuse symbol= and precision=, saying where each is declared.

  • Nothing is computed when a value is read. Values are computed when you ask — samplekit compute, C or c in the TUI, compute() in Python — and only what is not current, in the order the inputs require. A change to an input marks what reads it as outdated; it does not recompute it.

  • A value set over a formula is an override: the formula stays in the model, and the value is marked edited, where 0.2.0 dropped the formula.

  • The command line runs the model in the Python of the nearest .venv/ above the samples, or the interpreter [model] python names, where the SampleKit package must be installed in the same version. It runs without asking, as python runs a script you give it, and names the configuration and the model file before it starts.

  • The model is described once, in .samplekit/model.json, written whenever it is imported and again when its files change: what only reads the model's declarations — status, new and set, a state filter, the TUI — reads the description and starts no Python. Python runs to compute and to draw.

  • What a model prints goes to a log file; its warnings are shown during the run.

  • Uncertainties are never propagated on their own: a formula that should give one returns it.

The Python package is built from the same Rust code as the command line, and changes its shape:

  • sk.load(path) reads a sample or a folder, with the project's model (was SampleList(path, sample_class=…) and Sample.load); sk.load(a, b) reads several folders into one list.

  • Sample.new(path) makes a sample, save() writes it, compute() computes what is not current, and not_current() lists what status would.

  • A SampleList filters with the command line's language (brews.filter("og > 1.050")) as well as a function, sorts, groups (group_by), selects with a query of the project, and writes CSV, TSV or JSON at the project's precisions (to_csv, to_tsv, to_json, to_dict).

  • sk.stats names the statistics readings can stand for, and sk.plot draws the same figures as the command line.

  • Reading a value that is not current returns it, with a warning saying why.

  • The package ships type stubs that carry its documentation, so that an editor shows both.

  • Python 3.11 or newer is required (was 3.10), and neither PyYAML nor pandas is needed.

Performance. The package is built in Rust. Reading and writing sample files is 25 to 35 times faster than 0.2.0, and the statistics of readings about 3 times faster. A value computed costs a little more — some 15 µs per formula run — for the record of what it read, which is how SampleKit knows afterwards that it is still current; beside a formula that takes seconds, it does not show. status, new, set and the TUI start no Python while the model's description is current.

Removed

  • Reading 0.2.0 files. Every command names such a file, says why, reads the rest and exits with code 2.

  • The long spellings value: and uncertainty:. They are not read, in a property, a table's cell or anywhere else in a sample file: such a file is not read, and every command names the key and what it is written now — 'value' is written 'v' since schema 1: rename it.

  • template() and the report module: the note is no longer generated. Tables for a paper are profiles and exports; figures are drawn with plot.

  • pandas: to_dataframe() and the converters module; stats() on a list gives a Summary rather than a DataFrame. to_csv() or to_dict() give data pandas reads, and --summary, Summary and sk.stats summarise.

  • Computing on read, and the cache a changed input cleared.

  • The automatic mean and standard deviation of a list: a statistic is declared.

Upgrading from 0.2.0

No command converts a 0.2.0 sample: the model has to be rewritten by hand anyway, and a tool that did half the work would take all the risk of writing to your files. Upgrade from an older SampleKit shows how to carry each sample across — its values, uncertainties, readings, tables and text — with both versions installed side by side, into a new folder, and how to check the result.

[0.2.0]

The previous SampleKit, a Python package published on the Python Package Index. Its changes are not recorded here.