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:

  1. A value written beside them, {v: 2.0, readings: [...]}, typed by a person. It is the value, and it stays when the readings change.

  2. 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.

  3. 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.991 is refused: one number is a value, thickness=1.991.

  • A decimal comma. width.readings=12,5,12,6 is 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

thickness.readings

the readings, as a list

thickness.stats.count

how many

thickness.stats.mean, thickness.stats.median

their mean, their median

thickness.stats.minimum, thickness.stats.maximum

the extremes

thickness.stats.sample_stdev, thickness.stats.population_stdev

their spread

thickness.stats.standard_error

the standard error of their mean

thickness.stats.first_quartile, thickness.stats.third_quartile

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 --summary on the command line, stats() in Python and S in 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 says mean (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.mean as "the value". It is a description of the readings. The value is thickness.

  • A decimal comma in a list of readings. Use points.

Where to go next