Current and outdated values¶
A computed value is only as good as the inputs it was computed from. Correct a thickness reading, and the stress computed from it last month is now wrong, though nothing in its number says so. SampleKit tells you, for every computed value, whether it is still what its formula gives from the file as it now is, and if not, why. This page says how it knows, what the states mean, and what to do about each.
The record a computed value carries¶
When SampleKit computes a value, it writes beside it a record of what it was computed from:
area:
v: 25.05586444444445
u: 0.05217296159913354
unit: mm²
computed: {thickness: 2b1079ab857e, width: 25920047999d}
fingerprint: 17b7fdf04105
computed:names each input the formula read, with a short code (a digest) of that input's content at the time.fingerprint:is the same kind of digest, of the value itself as the formula gave it.
A digest is a short summary of content: the same numbers always give the same code, and any change to them gives a different one. It covers what a property is, its value, uncertainty and readings, and not how it is shown: changing a unit's spelling or a precision makes nothing outdated.
With these two records, two questions are answered from the files alone, in milliseconds, with no Python and nothing run:
Has an input changed since? SampleKit computes the digest of
thicknessas it is now and compares it with the one recorded inarea'scomputed. Different:areais outdated.Was this value changed by hand since? It computes
area's own digest and compares it with itsfingerprint. Different:areawas edited.
Stored codes are never compared with each other, only with what the content gives now. A hand edit changes the content and neither code, so comparing two stored codes would agree about something no longer true.
A computed value whose input is itself not current is not current either: the
problem is further up the chain, and status says so (outdated — area
(itself not current)).
What the files cannot know: the formula¶
A file records what a value read, never the code that computed it. The
project's history records that instead, in .samplekit/history/: for each
value SampleKit computes and writes, a digest of the formula that computed it
(its code, read without comments and blank lines, what it declares, and the
functions and constants of your model it uses), kept by what the value's
record says rather than by the file it is in. When you edit a formula, the
values it computed are formula changed, and the next compute runs them
again. What reads them is computed again only if their value actually moved.
A project's first write takes the values it holds as computed by the model
as it is then, where no history records what computed them: a project
copied or received without its .samplekit/ folder. It says how many: a
model edited before that first command is not seen changed, and samplekit compute --rerun --write runs them again, to be sure.
Anything else you change in the model makes nothing outdated: a comment, a docstring, a new figure, a helper no formula uses. This matters when a full recompute takes hours.
Because this record is kept by the value and travels with the history:
a value you restore from an earlier snapshot is judged by the formula that computed it then;
a project you move, copy or clone keeps it;
a value a colleague computed is judged by what their history says of it, once their history has arrived (Share a project).
A value whose formula the history does not know, computed on a computer
whose history is not here or by a SampleKit before this one, is judged by
its inputs alone, and status says how many there are:
samplekit compute --rerun computes them again.
The states¶
State |
What it means |
What to do |
|---|---|---|
current |
the value is what its formula gives from the file as it is |
nothing |
outdated |
an input changed after the value was computed (outdated — thickness), a reading was corrected (outdated — readings), or the formula was edited (formula changed) |
|
edited |
someone typed this value over its formula (edited — typed over its formula). A computed-looking value with no record at all (record missing) is treated the same way |
keep it, or |
failed |
the formula raised an error when last run; the file keeps the last value it gave |
read the error ( |
never computed |
the model declares this value and the file does not hold it yet (or, beside a value you entered, uncertainty never computed) |
|
waiting |
an input is empty: nobody entered it (waits for thickness) |
enter the input; the next |
Not current is the word for any of outdated, edited, failed and never
computed: the values status --exit-code fails on. A waiting value is not
among them: a sample halfway through its measurements is not in error. What
reads a waiting value waits too, waits for area, which waits, rather than
being called outdated or failed. A
value whose input was emptied since it was computed keeps its number, the
one computed before, and says that it waits: a table shows it in brackets,
(69), on the terminal as in a pipe, JSON writes "state": "waiting", and
Python's state is "waiting". A CSV gives a column of states to each
property one of whose values is not current or waits, area_state,
after its own: outdated, edited, failed, waiting…, empty where the
value is current.
Values not current are counted by cells, wherever a number of them is
given: a column of a table outdated in its 13 rows counts 13, as view lists
13. A value and its uncertainty count once when one formula gives both, and
twice when each has its own formula, since each can be outdated without the
other. Under a table, the count is of the cells the table shows.
One more word describes a whole sample rather than a value: defective,
when validate reports a defect in its file (a value that is text where a
number is expected, two rows with the same index, a unit that disagrees). A
defective sample can still have only current values.
Seeing the states¶
The same states appear on every surface, in the same words:
samplekit FOLDER statuslists every value not current or waiting, sample by sample, and says what to run.samplekit FILE explain VALUEshows one value: its inputs, the state of each, and why it is in its state.In a table on the terminal, a value is marked
⚠when outdated,✎when edited,✗when failed. The TUI adds∅for never computed or waiting, and·for readings with no statistic.?in the TUI lists every mark.stateis a field:-f 'state == outdated'keeps the samples with an outdated value, and-c name,stateshows each sample's states. Its words arecurrent,outdated,edited,failed,never_computed,waiting,defective, andnot_currentfor any of outdated, edited, failed and never computed. A sample can be in several at once.specimens.filter("state == failed")in Python and/in the TUI read the same words.In Python, reading a value that is not current returns it, with a warning saying why;
sample.not_current()lists everythingstatuswould report.
never_computed, waiting, not_current and current need the model, since
only the model knows which values it owes: SampleKit reads what the model
declares from its description, .samplekit/model.json, and runs nothing
(Models and formulas); after
an edit to the model, the first such command starts Python once to describe
it again. Where the model cannot be read, those words select
nothing, and a line says why. The other words are read from the files alone.
What makes a value outdated, and what does not¶
Outdated:
a change to an input's value, uncertainty or readings, however it was made:
set, the TUI, Python, or your text editor;a corrected reading, for a value computed from readings;
an edit to the formula itself, or to a function or constant it uses;
an input that was itself recomputed and moved.
Not outdated:
a change of unit spelling, symbol or precision (presentation, not content);
a change to anything the formula does not declare it reads, which is why
depends_onmust be complete (Models and formulas);a comment, a docstring or a new figure in the model;
the name of a method or of the model's class: renaming
_areaorSpecimenrecomputes nothing;an input typed over its formula: what reads it rests on it as it stands, and becomes outdated only if that value itself changes.
Nothing is recomputed at the moment of a change. A change marks; compute
recomputes, when you ask.
A unit the model declares is part of its formula: changed, the values are
formula changed, and compute --write writes them again in the new unit.
A value the model no longer computes, its formula renamed or removed,
keeps its number in the file, and blocks nothing: status and validate
name it, the model no longer computes it, with its two ways out. samplekit samples/steel-01.md set hardness= removes it; removing its computed record by hand keeps
it as a value entered, which is how what reads it takes it meanwhile.
Values typed over their formula, and --force¶
Sometimes the right value is not what the formula gives: a figure copied from
a certificate, a correction you trust more than the model. You can type it
over the formula, in the file, with set, in the TUI or in Python. It is
edited:
it is marked
✎and listed as edited — typed over its formula;computeleaves it alone, even with--rerun: a value you typed is not replaced without being asked by name;compute --force(optionally with-p NAME) gives it back to its formula. In the TUI,con the value does so, after asking.
The formula stays in the model; only this sample's value is held. An edited
value counts as not current, so status --exit-code fails on it; where such
values are deliberate, status --exit-code --accept edited lets them pass.
Exports and figures are current or not too¶
A file SampleKit writes from your samples, an export, a table written with
-o, a figure, is recorded in the project's history, by its exact
content. samplekit FILE explain then says, for that file, even copied
elsewhere or renamed, what made it, from which samples, what changed since in
what it was made from, and so whether it is still current, with the command
that makes it again (History).
An export is judged by the fields it writes, and by what those are computed from: changing a specimen's grade leaves an export that shows no grade, and nothing computed from it, current.
Before writing, an export's preview says which of the values it would write
are not current. A CSV never carries the marks ⚠ ✎ ✗; --status adds a
state column when you want each row's state kept with the data.
Common mistakes¶
Thinking a value is current because its number looks right. Look at
status, or the marks.Expecting
compute --rerunto replace a value typed over its formula. It does not; that is--force.Changing a unit in a file and expecting values to be outdated. A unit is a label; change the numbers too if the unit really changed. (A unit the model declares is different: changed there, it is part of the formula.)
Sharing the samples without their history. A computer that has the project's history,
.samplekit/history/committed beside the samples, knows which formula computed each value, and says formula changed after an edit made elsewhere. One that has the samples alone cannot know: compute there with--rerun, or share the history (Share a project).Forgetting that
status --exit-codefails on edited values. Add--accept editedif they are intended.
Where to go next¶
A check that fails when something is not current: Check a project in continuous integration.
Practised on the home page.
status,explain,computeand their options: Command line reference; the exit codes: Exit codes.