Written files¶
The shape of the files SampleKit writes from a table: what their columns are called, what a cell holds, and how a value not current is said. The guides show how to write them; this page says what is in them.
What writes one¶
Written by |
Holds |
|---|---|
|
the table of samples shown, a row per sample |
|
an export |
|
a sample's own table, a row per row of it |
Python's |
the same files, from a list of samples; |
-o names the format by its extension: .csv, .tsv and .json are data
files, .tex, .md and .html documents in the style of that name. A file
is previewed, and written by --write, which replaces it; each one written
is kept in the project's history, which explain FILE reads
(the history).
Columns¶
A data file names its columns after the fields, never after the labels a terminal shows, so that a program reading it finds them by name:
Column |
Header |
|---|---|
an attribute, |
the field: |
a property |
two columns, |
a property named in |
|
a part of a value, |
the part as named, with its unit |
a cell, |
the cell as named, with its unit |
|
|
The unit is written as the sample files spell it, degC rather than °C,
unless --style, or the export's style, names another. An uncertainty
column empty in every row is left out, and a note says so. Two columns
writing one header are refused.
Cells¶
$ samplekit -c name,young_modulus:.1f=E,thickness.readings,compared_with --csv
name,E_value [GPa],E_uncertainty [GPa],thickness.readings [mm],compared_with
aluminium-01,69.2,0.3,1.993;1.98;2.007,[[steel-01]]
copper-01,117.2,0.9,1.995;1.988;2.007,[[steel-01]]
steel-01,206.3,1.1,1.995;2.004;2.008,
A number is written at the precision declared for its column or its property, here
.1f; where none is declared, every digit stored. An uncertainty is rounded up, never understated.Nothing entered is an empty cell; a value that does not apply,
n/a, is writtenn/a.A list, readings or a list attribute, and tags are their items joined by
;.A link is its text as written,
[[steel-01]], in a data file and in a document alike.Lines end with a line feed on every system, so that a file written on two computers is the same file.
TSV is CSV with tabs between the cells.
JSON¶
A JSON file is a list of objects, one per row, each keyed by the columns'
fields, or by the name -c or header gives them. A property is an object
holding its value, its uncertainty, its unit and its state; a list and the
tags are arrays, and n/a is null:
$ samplekit samples/steel-01.md -c name,young_modulus:.1f=E,thickness.readings,tags --json
[
{
"name": "steel-01",
"E": {
"value": 206.3,
"uncertainty": 1.1,
"unit": "GPa",
"state": "current"
},
"thickness.readings": [
1.995,
2.004,
2.008
],
"tags": []
}
]
Values not current¶
A column holding a value not current gets a column of its states beside it,
FIELD_state, empty where the value is current: outdated, edited,
failed, never_computed. JSON says it in each property's state. Written
to a file with -o, or by an export, the file is written all the same, the
values not current are said, and the command exits with code 2, unless
--accept names their states. Here after the steel specimen's width was
measured again, its area not yet computed:
$ samplekit -c name,area:.3f --csv
name,area_value [mm²],area_uncertainty [mm²],area_state
aluminium-01,24.922,0.098,
copper-01,24.967,0.070,
steel-01,25.056,0.053,outdated
$ samplekit -c name,area:.3f -o area.csv --write
the table is written from values that are not current: 1 outdated in 1 sample
steel-01 area
samplekit status says why, and compute --write brings them up to date
written: area.csv
error: area.csv is written from values not current — --accept outdated exits 0 for it
A sample's own table¶
view TABLE writes a row of the file per row of the table: its index first,
then each column, a property's two columns as above. Over several samples,
a column name comes first, and each sample's rows follow one another:
$ samplekit samples/steel-01.md view curve --csv
note: strain_uncertainty is left out: it is empty in every row
note: force_uncertainty is left out: it is empty in every row
note: stress_uncertainty is left out: it is empty in every row
strain_value [%],force_value [kN],stress_value [MPa]
0,0.0,0.0
0.025,1.281,51.1
…
Documents¶
A document, .tex, .md or .html, is the table as the style writes it:
its columns headed by their labels, a property in one cell with its
uncertainty, its units spelled as the style spells them. Tables and figures
for a paper shows the styles given and how
to declare one ([style.NAME]).