Edit samples¶
This guide is for changing what your samples hold: a value measured again, an attribute corrected, a tag, a row of a table, a new sample. Each change is shown before it is written, says what it makes out of date, and is kept in the project's history.
The commands run on the home page's tensile example, in its last step: three specimens, their readings, their curves and their results.
Change a value¶
set names the field, an =, and the new value. Without --write it only
shows the change; with it, it writes:
$ samplekit samples/steel-01.md set grade=S355J2 --write
samples/steel-01.md · 1 change
grade S355 → S355J2
nothing becomes not current
written: samples/steel-01.md
The preview says what the change makes out of date, here nothing: no formula
reads the grade. Several fields change at once, set grade=S355J2 tested=2026-03-05, written together or not at all. A filter changes several
samples, each previewed, and asks once: samplekit samples set supplier=acme -f 'material == steel'.
What a field holds decides how it is written:
To write |
Write |
|---|---|
a number, in the unit the project declares |
|
its uncertainty |
|
repeated measurements |
|
a text, a date |
|
not applicable |
|
nothing: the field removed |
|
A decimal is written with a point, never a comma. A unit is never converted:
set writes the number in the unit the project declares for the field
(units are labels).
n/a says there is nothing to measure, where an empty field says nobody
entered it (no value, not applicable,
zero).
A value that a formula computes can be written too: it is then edited, typed
over its formula,
which compute keeps until --force gives it back to its formula (written
by hand).
Measured several times¶
Readings replace one another as a list: the three readings written are the
three the property holds. Their value and their uncertainty are the
statistics the model declares, and wait for compute (readings and
statistics):
$ samplekit samples/steel-01.md set thickness.readings=1.991,1.994,1.989 --write
samples/steel-01.md · 1 change
thickness.readings 1.995, 2.004, 2.008 → 1.991, 1.994, 1.989
3 readings: 1.991, 1.994, 1.989, their mean 1.9913
they replace the 3 readings it held
its value and its uncertainty, their mean and standard error, wait for samplekit compute
this makes 18 values not current
area outdated — thickness
tensile_strength outdated — curve.stress (itself not current)
thickness outdated — readings
yield_strength outdated — young_modulus (itself not current), curve.stress (itself not current)
young_modulus outdated — curve.stress (itself not current)
curve.stress outdated — area (itself not current) (13 rows)
samplekit samples/steel-01.md compute --write recomputes them
written: samples/steel-01.md
One number is not a list of readings: thickness.readings=1.99 is refused,
saying to write thickness=1.99.
A row of a table¶
A cell is named by its table, its column and its row's index, between brackets; quote it, since a shell reads brackets:
$ samplekit samples/aluminium-01.md set 'curve.force[10]=7.95' --write
samples/aluminium-01.md · 1 change
curve.force[10] 7.927 kN → 7.95 kN
this makes 4 values not current
tensile_strength outdated — curve.stress (itself not current)
yield_strength outdated — young_modulus (itself not current), curve.stress (itself not current)
young_modulus outdated — curve.stress (itself not current)
curve.stress outdated — curve.force (1 row)
samplekit samples/aluminium-01.md compute --write recomputes them
written: samples/aluminium-01.md
--add-row adds a row, each assignment naming one of its columns. What the
model computes in a row, here the stress, is computed by compute:
$ samplekit samples/aluminium-01.md set --add-row curve strain=11 force=7.8 --write
samples/aluminium-01.md · a row in curve
curve.strain — → 11
curve.force — → 7.8
computed by the model stress
this makes 4 values not current
elongation outdated — curve.strain
tensile_strength outdated — curve.stress
yield_strength outdated — curve.strain, curve.stress, young_modulus (itself not current)
young_modulus outdated — curve.strain, curve.stress
written: samples/aluminium-01.md
samplekit samples/aluminium-01.md compute --write fills what the model derives from it
A new sample¶
new makes a sample in the folder named, from the fields given. A name the
project or its model declares as a property is written as one, with its unit:
$ samplekit samples new steel-02 material=steel grade=S355 direction=T --write
samples/steel-02.md · new sample
material — → steel
grade — → S355
direction — → T
written: samples/steel-02.md
samplekit samples/steel-02.md set <field>=<value> fill a value in
samplekit samples/steel-02.md compute --write run the model on it
--keep takes fields from a sample already there, and nothing else:
samplekit samples new steel-03 --keep samples/steel-02.md material,grade --write. From Python, sk.Sample.new(path) makes one, and save() writes
it (work from Python).
The note¶
The text below a sample's frontmatter is its note, read as it is written.
set note=… replaces it, and note= empties it; an editor changes it as
well:
$ samplekit samples/copper-01.md set 'note=Necked at mid-length, broke in the gauge.' --write
samples/copper-01.md · 1 change
note Tested at 2 mm/min, across the rolling direction. → Necked at mid-length, broke in the gauge.
nothing becomes not current
written: samples/copper-01.md
Remove a sample¶
remove deletes the sample files named, or those a filter selects in a
folder; a folder alone is refused. Their own files, the photographs and
the machine's files, stay. The history keeps what is removed, and
samplekit restore gives it back:
$ samplekit samples/copper-01.md remove
remove · 1 sample file
samples/copper-01.md
their own files stay: 2 files under [collection] files
samplekit restore gives it back, as it was
apply these changes? [y/N] n
nothing written
The links of the project leading to a sample removed are listed in its
preview and left as written; validate reports them after (a link that
leads nowhere). From Python,
sample.note is the note, set as any attribute, and sample.remove()
deletes the file.
Rename a sample¶
rename gives a sample a new file's name and keeps what leads to it: its own
files are renamed with it, a folder named after it too, its name where it
was the file's name, and every link of the project naming it is written to
name it again. In the last step, the aluminium and copper specimens link to
the steel one, steel-01, which is renamed:
$ samplekit samples/steel-01.md rename steel-02
samples/steel-01.md · rename to steel-02.md
file samples/steel-01.md → samples/steel-02.md
name steel-01 → steel-02
files machine/steel-01 → machine/steel-02
files photos/steel-01-fracture.jpg → photos/steel-02-fracture.jpg
2 links leading to it, written again:
samples/aluminium-01.md
compared_with [[steel-01]] → [[steel-02]]
samples/copper-01.md
compared_with [[steel-01]] → [[steel-02]]
apply these changes? [y/N] n
nothing written
With --write, it is made. The history keeps the samples as they were, and
restore gives them back; their own files are not in the history, so
renaming back, samplekit samples/steel-02.md rename steel-01 --write, is
what takes the whole change back. In the terminal interface, R; from
Python, sample.rename("steel-02"). Links have a guide of their
own.
In a text editor¶
A sample is a text file, and an editor may change it: SampleKit reads it as it is at the next command. Three things to know:
What a change makes out of date is judged by the values, wherever the change came from:
samplekit statussays it after an edit as afterset.validatefinds a mistake typed by hand: a frontmatter that does not read, a unit that contradicts the other files, a value outside its range (checking them).The next write puts the frontmatter in one fixed form, and drops a comment between the
---lines; the note below them is kept as written (what SampleKit writes).
The history keeps such an edit too, as changed outside SampleKit, at the next command that writes.
In the terminal interface¶
On a sample's screen, e enters the typing mode, where what you type
replaces the cell under the cursor, as in a spreadsheet: a value with its
uncertainty, 12.6 +- 0.02, an attribute's name or value, a table's cell; the
arrows go from cell to cell and Esc leaves. i opens a value's card: what
it reads and what reads it, each typed in there too. A adds an attribute, N edits
the note, and → unfolds the table under the cursor, where the empty row
adds one. The list of samples is typed in the same way, a column for several
samples at once. There, N makes a new sample, t tags the samples Space
put in the basket, or renames a tag, old=new, R renames a sample and D
removes one. Nothing is written at once: every change waits, shown as it will
be, until w writes them all, one change of the history; u takes back the
last change waiting (work in the terminal interface,
the TUI's keys).
From Python¶
The same changes from Python, where a sample changes as an object does: an
attribute set, readings given as a list, a tag appended, a row added to a
table with add. not_current() says what the change made out of date,
compute() runs the model's formulas, and nothing is written before save()
(work from Python):
"""The changes of the guide to editing samples, from Python."""
import samplekit as sk
steel = sk.Sample("samples/steel-01.md")
steel.grade = "S355J2"
steel.thickness.readings = [1.991, 1.994, 1.989]
steel.tags.append("reference")
print(steel.not_current())
steel.save()
aluminium = sk.Sample("samples/aluminium-01.md")
aluminium.curve.add(strain=11, force=7.8)
aluminium.compute()
print(aluminium.elongation, aluminium.tensile_strength)
aluminium.save()
$ python scripts/edit.py
{'thickness': 'outdated', 'area': 'outdated', 'young_modulus': 'outdated', 'yield_strength': 'outdated', 'tensile_strength': 'outdated', 'curve.stress': 'outdated'}
12.0 % 318 MPa
Take a change back¶
samplekit restore takes the last change back, and restore --at puts files
back as the history kept them at a change or on a day; both preview first
(the history).
See also¶
set,new,tag,remove, every option.