Readings and statistics¶
A property measured several times, three micrometer readings of a thickness, five of a temperature, has readings: every result, kept as it was taken. This page says how SampleKit keeps them, how a value comes to stand for them, and why it never takes their mean on its own.
Readings are the evidence¶
properties:
thickness: {readings: [1.995, 2.004, 2.008], unit: mm}
The readings are kept in the file, all of them, in the order written. They are never replaced by their mean. A statistic of them can always be recomputed, a suspect reading can always be found again, and a different convention (the median rather than the mean, say) can be applied later. A mean with the readings thrown away can do none of that.
A value stands for its readings only if someone chose how¶
Which number represents three readings? The mean is common, but not the only answer: the median resists an outlier, the maximum is what a safety limit wants. That choice is yours, and SampleKit does not make it for you.
So the value of a property with readings is, in this order:
A value written beside them,
{v: 2.0, readings: [...]}, typed by a person. It is the value, and it stays when the readings change.Otherwise, the statistic the model declares for this property: the project's model says, for example, that the value is the mean of the readings and the uncertainty their standard error. Read without a model, a file's
statistics:beside the readings (below) says the same.Otherwise, no value. The readings are there; nothing says what stands for them, and SampleKit says so rather than guessing.
A mean taken where nobody chose it would be a number nobody decided on,
written into files and later read back as if someone had. That is the silent
kind of error this tool exists to prevent, so readings without a declared
statistic have no value, and every surface says it: the TUI marks the value
·, a table shows —, Python reads None, and samplekit set says that
the readings give no value until a statistic is declared or a value written.
Declaring the statistic¶
The model declares it on the property:
self.thickness = sk.Property(unit="mm", value=sk.stats.mean,
uncertainty=sk.stats.standard_error)
sk.stats offers, for a value, mean, median, minimum, maximum,
first_quartile and third_quartile; for an uncertainty,
standard_error, sample_stdev and population_stdev.
Models and formulas explains the model itself.
Once computed, the file carries the statistic's result beside the readings, with a note of which statistic it is and a record of the readings it was taken from:
thickness:
v: 2.0023333333333335
readings: [1.995, 2.004, 2.008]
u: 0.003844187531556873
unit: mm
statistics: {v: mean, u: standard_error}
computed: {readings: 3160016f6c6e}
fingerprint: 1d88e7bb89d3
statistics: is there so that a reader without the model knows what the two
numbers are. computed: and fingerprint: are the record every computed
value carries (Current and outdated).
When a reading changes¶
A value taken from the readings is a computed value like any other.
Correct a reading, and the value is outdated — readings until you compute
again; everything computed from that value is outdated in turn. samplekit compute --write (or C in the TUI, or compute() in Python) takes the
statistic again.
A value written by hand beside readings is different. It outranks the
statistic, and new readings do not replace it: the preview of the change says
that your value stays. If the model declares a statistic, a typed value there
is edited, listed as edited — typed over its formula, and compute --force gives the property back to its statistic. Emptying the value
(samplekit FILE set thickness=) does the same without computing.
A value beside readings with no statistic recorded, as a file written by
hand may hold, is read the same way: nothing in the file tells it apart from
one typed. Where the model declares a statistic, compute --force hands the
value over to it.
Giving readings¶
Readings are the property's readings, with or without brackets:
$ samplekit samples/steel-01.md set thickness.readings=1.991,1.994,1.989 --write
$ samplekit samples/steel-01.md set 'thickness.readings=[1.991, 1.994, 1.989]' --write
The same spelling works in samplekit new, for a table cell, and in
--add-row. The list you give replaces the old one. In Python,
steel.thickness.readings = [1.991, 1.994, 1.989]; a list assigned to a
measured property's value, steel.thickness.value = [...], is its readings
too. In the TUI,
e on a property edits its value, uncertainty and readings together.
Two things are refused or warned about, because each is usually a typing slip:
One number is not readings.
thickness.readings=1.991is refused: one number is a value,thickness=1.991.A decimal comma.
width.readings=12,5,12,6is read as four readings, and a warning says so: write[12.5, 12.6].
A value that a formula computes takes no readings: readings under a formula
are refused, since both cannot be kept and neither may be dropped without a
word. An n/a value keeps readings written beside it, but they give it no
uncertainty.
Statistics of the readings, any time¶
Whatever the value, the readings can always be described. These are fields you read, not values anyone chose:
Field |
Reads |
|---|---|
|
the readings, as a list |
|
how many |
|
their mean, their median |
|
the extremes |
|
their spread |
|
the standard error of their mean |
|
the quartiles |
They work in a filter, a column, a profile and a sort, and in Python
(steel.thickness.stats.count, steel["thickness.stats.mean"]). They need no
model and write nothing. thickness.stats.mean is always the mean of the
readings; thickness is the value, which is the mean only if someone chose
it.
Readings in a table cell¶
A cell of a table can hold readings as a property does: the force read on three dials at one strain, for example.
$ samplekit samples/steel-01.md set 'curve.force[0.2].readings=9.51,9.52,9.52' --write
$ samplekit samples/steel-01.md set --add-row curve strain=0.1 'force.readings=[5.12, 5.14]' --write
The statistic is declared once for the whole column, in the model:
"force": sk.Property(unit="kN", value=sk.stats.mean,
uncertainty=sk.stats.standard_error),
and the file writes it beside the column's unit, so that the table still says what its numbers are without the model. Each cell then behaves as a property with readings: its value is computed, recorded, and outdated when a reading changes; a value typed in a cell outranks the statistic; a column declaring no statistic leaves its cells' readings without a value.
Readings are not a summary¶
Two kinds of statistics are easy to confuse:
Statistics of one property's readings, inside one sample: the mean of three micrometer readings of one specimen. They are the declared statistic, or the
thickness.stats.*fields.A summary of a column across samples: the mean thickness of twelve specimens. That is
--summaryon the command line,stats()in Python andSin the TUI. It counts how many samples have a value (11/12), and when every value has an uncertainty its mean is weighted by 1/u², each value counting as much as it is precise; the header then saysmean (1/u²).
A summary reads each sample's value, whatever gave it: a typed value, a declared statistic, or a formula.
Common mistakes¶
Expecting readings to give a value on their own. They do not. Declare a statistic in the model, or write a value beside them.
Writing a value beside readings and then correcting a reading. Your written value stays; the preview says so. Empty it (
thickness=) to let the statistic stand again.Reading
thickness.stats.meanas "the value". It is a description of the readings. The value isthickness.A decimal comma in a list of readings. Use points.
Where to go next¶
The model's side: Models and formulas.
The home page declares statistics for a specimen's width and thickness, and edit samples changes readings.
The exact syntax of
set: Command line reference; of the fields: fields;sk.stats,sk.Property: Python reference.