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-darkandsamplekit-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 rolesbackgroundandforegroundof[colors].Tchooses the theme, on the start page, the collection and a sample: each is tried on the screen as the cursor reaches it,Enterkeeps it for the folder and as your choice for the projects naming none. A project names its own withtheme = "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 itsbasenames. 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
wwrites 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;wshows one preview of them all and writes them as one change of the history, andutakes 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:
eenters it, and what is typed replaces the cell under the cursor, as in a spreadsheet, the arrows going from cell to cell;Escleaves it. A value and its uncertainty are typed in one cell,12.6 +- 0.02, an attribute is renamed by typing over its name, andDeletetakes out an attribute or a table's row.A value's card in the terminal interface:
ion 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#sectionis kept apart from its path.renamekeeps each link as it was written, its folder, extension and heading.The addresses of other tools:
zotero://,obsidian://,mailto:,ftp://andfile://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
validateto 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;
validatean 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 amodel.pyfirst, 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,
pon a figure under a folder such asThèsesaid 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 assamplekitdoes.Paths written on Windows read on Linux and macOS: a
\in a path of.samplekitrcor 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, thensamplekit 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 rolestaleisoutdated, a style'sseparatoris written as itsproperty,{collection}in a path is{project}; in Python,stale()andis_staleareoutdated()andis_outdated. Each old name is refused, naming the new one.new --like SAMPLEisnew NAME --keep SAMPLE FIELDS.Rename a property's formulas, in this order:
compute=becomescompute_value=, thencompute_quantity=becomescompute=. No value is outdated by it. A value formula left ascompute=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/samplekiton Linux,~/Library/Application Support/samplekiton macOS,%LOCALAPPDATA%\samplekiton Windows):computed.json,computed,consent,accepted/, and the run logs namedlogs/compute-YYYY-MM-DDT…Z-PID.logcan be deleted.samplekit-migrate.pyz --clean-statelists 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, thengit 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]withfigure = "curves"andoutput = "paper/curves.pdf", where a table's names itsprofile.samplekit export curves --writethen draws it to its file, as a table for a paper is written again; Python'sexport("curves")and the TUI'spmenu 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 alinefigure without markers, anderrorbar.capsizesets the error bars' caps.styleapplies matplotlib's style sheets, by name or as.mplstylefiles, andfontsmakes 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.importtakes a file, and a list:import = ["..", "figures.samplekitrc"]merges the folder above's.samplekitrcand 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 initinstalls the package into a.venv/without pip withuv pip install, when uv is on thePATH, and otherwise says the command to type.Write a command in any order:
samplekit samples status,samplekit status samplesandsamplekit -f 'mass > 10' status samplesare 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 folderstatus/.Select samples on every command:
-f(a filter) and--query(a filter saved in.samplekitrc) now work withset,log,diff,restore,validate,list,explainandopentoo.samplekit samples set -f 'material == steel' supplier=acmepreviews each sample it changes, asks once, and writes them together.Every change is previewed, then asked:
set,new,tag,export,restoreandcomputeshow what they would change and end onapply these changes? [y/N].--writeanswers 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,markdownandhtmlare given:samplekit samples --style latex -c name,density -o table.texwrites a LaTeX table ready to include.Filters reach into tables:
results has 42, a sample with 42 in any cell of itsresultstable;results.status has failed, in one column; andresults 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.scriptis an action on a sample or on a selection, with options;samplekit run NAMEruns it, orpin the TUI, and what it changes is previewed before it is written.Share the history through git with one line:
[history] shared = truein.samplekitrc, andgit add -Atakes 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;
Aadds an attribute to a sample, its name then its value;pruns 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=NAMEorexport=NAMEon a table declares its filter, its columns, sort and groups, or both and an export, in.samplekitrc, previewed first; the TUI'sWdoes the same.Remove a sample:
samplekit FILE removedeletes sample files, previewed first; the history keeps them, andrestoregives 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, andnote=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 writtenhttps://…a web page. A list of links names several. The TUI opens each withEnteroro, a sample even where the filter leaves it out, its title bar saying the way taken andEscgoing back along it; Python reads the samples withsample.linked("reference"), a file that is no sample as its path; andvalidatereports a link that leads nowhere. A link is shown as Markdown shows it, its text alone, underlined in the colour rolelink,↗after a web page and✗after one leading nowhere, in the TUI, and in a table andviewdrawn 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 filterlinks to NAMEselects the samples whose links name it;set parents=[[a]],[[b]]writes a list of links, and Tab after[[completes a sample's name, onsetand in the TUI.Rename a sample:
samplekit FILE rename NEWrenames its file, its own files and itsname, 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).removelists the links it leaves leading nowhere.A sample's own table written to a file:
samplekit FILE view curveshows the tablecurvealone, and--csv,--tsv,--jsonor-o curve.csvwrite its rows, previewed and kept in the history as a table of samples is; over several samples, a columnnamefirst. 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:
Cpreviews what it would compute, ascomputedoes; inH,rputs files back as a change left them,dshows what a change changed and, on another, compares the two;trenames a tag,old=new;Ntakes a new sample's values,field=value, and fields kept from another,keep:FIELD,…;Dremoves a sample.An editor of its own window leaves the TUI drawn: with Notepad or
code --wait,EandMsay 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;
EandMopen 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 FIELDScopies the fields named from another sample, and nothing else;[property.NAME] range = [MIN, MAX]makes a value outside the range a defect forvalidate;compute --timeout SECONDSstops 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.
noteis a reserved name: a file holding an attributenote:is refused, saying to rename itremarks:orcomment:;set note=andsample.noteare the text below the frontmatter.A number typed is previewed as the table shows it:
set area=25.0beside an uncertainty of0.028previews25.000, and25.0123keeps 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.computecounts 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 written0.001, and 0.121 at.2fis0.13, where rc.1 wrote0.000and0.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, sovalidateand an export no longer warn of one.A property's formulas are
compute,compute_valueandcompute_uncertainty:compute=fgives the whole property,f()returning a number or(value, uncertainty);compute_value=the value alone, beside an uncertainty given apart. They werecompute_quantity,computeandcompute_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, orcompute_column=f, given the columns it reads and returning one cell per row;compute_valueandcompute_uncertaintygive one number of each cell, the other entered.sk.Columnis gone. A formula filling several columns at once is ask.ComputedColumns, in the table'scomputed=;compute_rowsandcompute_columnsare 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] recursiveistrueunless.samplekitrcsaysfalse, so thatsamplekit .at a project's root readssamples/. 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"), orindex=["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,
✓andwritten: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.00beside1.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.004above12.513 ± 0.010. A summary's median, minimum and maximum follow their column, andsetsays 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
-onames the values that are outdated, failed or never computed. In a CSV, a columnNAME_statebeside the quantity says which.Exports write units as the sample files spell them,
degCrather than the screen's°C;--style plaingives the screen's forms.restorewithout--attakes 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
Endkeeps 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 saysnothing written.validatereads 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
-qor a redirected error stream does not hide it;--accept waitingis refused, since a waiting value fails nothing.Over several projects, a snapshot's number is one project's:
log --at,diff --fromand--tofrom 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 afterexplain 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 FOLDERprints the path of each sample; with-cit shows a table of the columns you name, and with--profilea table declared in.samplekitrc.-ffilters (-f 'og > 1.050 && tags has medal'),-ssorts,--groupmakes a table per value of a field,--summarysummarises each column.--csv,--tsvand--jsonprint the same table as data, and-o FILE --writewrites it.listenumerates 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.viewshows a sample whole: its values, then its tables, and its note with--note.statuslists every computed value that is not current, and why;status --exit-codemakes it a check for continuous integration.computeruns the model's formulas: alone it says what would run, with--tryit computes and shows the results without writing, and with--writeit writes each sample as soon as it is done.explain FILE FIELDsays where one value came from, and prints a formula's error.validatereports the defects of sample files and changes nothing.newcreates a sample from what the project already knows,setchanges its values (set brew.md og=1.052 og.u=0.001, readings, table cells, the name), andtag add,tag removeandtag renamechange its tags. Each shows what it would change and writes only with--write.export NAMEwrites a table declared in.samplekitrcas CSV, TSV or JSON, after a preview;--statusadds a column holding each row's state.plotdraws a figure with matplotlib, in a window or to a file: one declared in.samplekitrcor by the model, or one given by its axes (-x,-y), over properties, attributes or a table's columns.openopens a sample's own files — photos, reports, raw data — which[collection] filessays where to find.initsets 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;--examplewrites a project that runs, one formula of every kind.tuiopens the full-screen interface on a folder, andsamplekitalone, in a terminal, opens its start page.completionssets up tab completion for bash, zsh, fish, elvish and PowerShell.Every command has
--help, with examples, and-hfor 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.
loglists the snapshots,diffcompares two states value by value (abv 6.8 ± 0.1 % → 7.2 ± 0.1 %), andrestoreputs files back: the last change taken back, or the state of a given snapshot.--atreads 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 Nprints the script as it ran, andkeep()marks a snapshot of its own from inside a script.Every export and figure SampleKit writes is recorded.
explain FILEfinds 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 --exportwrites 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.logshows amachinecolumn 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.gitignorestops 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.stateis also a field:-f 'state == outdated',-c name,state.A value typed over its formula is an override:
computeleaves it alone untilcompute --forcegives 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
uto 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;
Shiftand the arrows select;Ctrland the arrows move by word;Ctrl+BackspaceandCtrl+Deletetake a word out;Ctrl+Zundoes,Ctrl+Shift+Zredoes;Ctrl+Ccopies a selection,Ctrl+Xcuts, and a paste goes where the cursor is. In the note, Markdown by keys:*,_or~around a selection,Alt+1toAlt+6a heading,Alt+La link,Alt+Ian image,Alt+Ca 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 givesn/atoo, 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] filessays, 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] filesand an export'soutput.What the current folder offers:
list profiles,queries,exportsandfigures, the completion and the TUI'sfshow the configuration of the folder a command runs from, with what it imports, each name markedlocalor with the file it comes from. A sample still follows its own collection's configuration wherever the command runs from.validatenotes a declaration identical to the one imported, a copy to remove, and--show-rcnames 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: 1heads the file. Quantities go underproperties:, tables undertables:, and any other top-level key is an attribute.A quantity is a bare number or a short mapping:
vfor the value (wasvalue),ufor the standard uncertainty in the value's unit (wasuncertainty),readingsfor the repeated measurements (wasdata), andunit.og.vandog.uare also how a filter, a column,setand Python name the two numbers.A table has
index,columnsas a mapping androws(was_index,_columnsas 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ératureandbièreare names,dry-hoppedis 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=(wascompute_unc) the uncertainty beside a value you enter, andcompute_quantity=both. A table's cells are computed a row at a time (compute_rows) or a column at once (compute_columns).depends_onnames the inputs by name ("og","fermentation.gravity"), not asPropertyobjects, 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.Propertyandsk.Columnrefusesymbol=andprecision=, saying where each is declared.Nothing is computed when a value is read. Values are computed when you ask —
samplekit compute,Corcin 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] pythonnames, where the SampleKit package must be installed in the same version. It runs without asking, aspythonruns 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,newandset, astatefilter, 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 (wasSampleList(path, sample_class=…)andSample.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, andnot_current()lists whatstatuswould.A
SampleListfilters 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.statsnames the statistics readings can stand for, andsk.plotdraws 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:anduncertainty:. 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 thereportmodule: the note is no longer generated. Tables for a paper are profiles and exports; figures are drawn withplot.pandas:
to_dataframe()and theconvertersmodule;stats()on a list gives aSummaryrather than a DataFrame.to_csv()orto_dict()give data pandas reads, and--summary,Summaryandsk.statssummarise.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.