Find and select samples

This guide is for answering a question from your samples: which ones, which values, in which order, grouped how, and the answer written to a file. Every command on this page only reads, but for a file written with --write.

The commands run on the home page's tensile example, in its last step.

Which samples a command reads

A command reads the folder or the files you name, samples/ or samples/steel-01.md; naming nothing, the folder you are in. In a project, a folder is read with the folders below it (which folders a command reads). Given nothing else, a command lists the samples' files:

$ samplekit .
samples/aluminium-01.md
samples/copper-01.md
samples/steel-01.md

Columns

-c names the columns, by the names the files use. A column may also be one part of a value, or one cell of a table:

Column

Is

width

the value, with its uncertainty and its unit

width.u

its uncertainty alone

thickness.readings

its readings

'curve.stress[10]'

the stress in the row whose index, the strain, is 10

name, path, filename, project, tags, state

what every sample has

$ samplekit -c width.u,thickness.readings,'curve.stress[10]'
name           width.u [mm]   thickness.readings [mm]   curve.stress[10] [MPa]
──────────────────────────────────────────────────────────────────────────────
aluminium-01     0.00375648   1.993, 1.98, 2.007                         318.1
copper-01        0.00328296   1.995, 1.988, 2.007                        179.9
steel-01         0.0100885    1.995, 2.004, 2.008                        504.3

3 of 3 samples

samplekit list fields lists every name the samples use, properties, attributes and tables apart, with an example of a cell's address.

Filters

-f keeps the samples a condition selects. It compares a field with ==, !=, <, <=, >, >=; combines with && (and), || (or) and ! (not); and knows a few words: has for a tag, in (a, b) for a list, is missing for a value nobody entered, links to steel-01 for the samples linking to one (link samples). Quote the whole condition, so that the shell leaves it alone (every form).

A table is searched with where: the samples one of whose rows holds what the condition says. Here, the specimens that stretched past 30 %:

$ samplekit -f 'curve where (strain > 30)' -c material
name        material
────────────────────
copper-01   copper

1 of 3 samples

Several -f all hold. A filter used often is saved in .samplekitrc as a query, [query.ductile] with filter = "elongation > 20", and --query ductile selects with it (the home page).

Order and groups

-s sorts by a field, a - before it for the highest first; several, comma-separated, sort by the first, then the next. -r reverses the order. --group gives a table per value of a field:

$ samplekit -c elongation -s -elongation -f 'elongation > 20'
name        elongation [%]
──────────────────────────
copper-01             44.0
steel-01              24.0

2 of 3 samples
$ samplekit -c material,elongation --group material
material = aluminium
name           material    elongation [%]
─────────────────────────────────────────
aluminium-01   aluminium             12.0

material = copper
name        material   elongation [%]
─────────────────────────────────────
copper-01   copper               44.0

material = steel
name       material   elongation [%]
────────────────────────────────────
steel-01   steel                24.0

3 of 3 samples

--summary gives each column's statistics instead of its rows, and --group with it, the statistics of each group.

Write the table to a file

Every table on this page can go to a file. --csv, --tsv and --json print it as data for another program: a value and its uncertainty in two columns, each headed with its unit, and a column empty in every sample left out, with a note saying so:

$ samplekit -c name,material,tensile_strength=Rm -s -tensile_strength --csv
note: Rm_uncertainty is left out: it is empty for every sample
name,material,Rm_value [MPa]
steel-01,steel,518
aluminium-01,aluminium,318
copper-01,copper,221

-o names the file, and its extension says what it holds: .csv, .tsv or .json a data file, .tex, .md or .html a table for a document, in that style. It is previewed, and --write writes it:

$ samplekit -c name,tensile_strength=Rm -s -tensile_strength -o strongest.md --write
written: strongest.md
strongest.md
| name | Rm (MPa) |
| --- | --- |
| steel-01 | 518 |
| aluminium-01 | 318 |
| copper-01 | 221 |

A file is written at the precision a table shows, and --precision .17g writes every digit; a value not current is written all the same, said, and the command exits with code 2, unless --accept names its state. A table written again at each draft is better declared once, as an export: --save export=NAME, below, declares one from what the table shows, and tables and figures for a paper goes further, labels, styles and the history of each file written.

A sample's own table

A sample's own table, its curve, is written the same way, a row of the curve a row of the file. view followed by the table's name shows that table alone, and takes --csv, --tsv, --json and -o:

$ samplekit samples/steel-01.md view curve -o curve.csv --write
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
written: curve.csv
curve.csv (its first rows)
strain_value [%],force_value [kN],stress_value [MPa]
0,0.0,0.0
0.025,1.281,51.1
0.05,2.585,103.2

Its columns are written as a table of samples writes a property, at the precision declared for each, every digit stored where none is. Over several samples, samplekit samples view curve --csv, a column name comes first and each sample's rows follow one another. From Python, steel.curve.to_csv() gives the same text.

Saved shapes

A profile saves columns, labels, an order and groups; a query saves a filter; both are declared in .samplekitrc, and listed:

$ samplekit list queries
ductile   elongation > 20
$ samplekit list profiles
overview   name, material, young_modulus, yield_strength, tensile_strength, elongation
data       name, young_modulus, yield_strength

--save declares what a table shows, under a name: query=NAME its filter, profile=NAME its columns, order and groups, export=NAME both and an export to out/NAME.csv. It shows the lines it adds to .samplekitrc, and asks:

$ samplekit -c name,tensile_strength=Rm -s -tensile_strength --save profile=strongest
save in .samplekitrc
  +  45  [profile.strongest]
  +  46  columns = [{ field = "name" }, { field = "tensile_strength", label = "Rm", header = "Rm" }]
  +  47  sort = ["-tensile_strength"]
  +  48

apply these changes? [y/N] n
nothing written

In the terminal interface

On the list of samples, each question is a key, and the table changes as you type (work in the terminal interface):

Key

Does what the command line does with

/

-f: the same language, Tab completing fields, operators and values

s

-s: choose the columns to sort by; r on one sorts it highest first

c

-c: tick the columns to show

g

--group: a heading above each group

f

--query, --profile: apply a saved one

S

--summary: the columns' statistics, or the samples again

W

save what is shown in .samplekitrc, as a query, a profile or an export

From Python

The same questions from Python: filter, query and sorted take what -f, --query and -s take, and give a new list; stats gives what --summary gives (work from Python):

scripts/selecting.py
"""The questions of the guide to selecting samples, from Python."""

import samplekit as sk

specimens = sk.load("samples")
print([specimen.name for specimen in specimens.filter("curve where (strain > 30)")])
for specimen in specimens.query("ductile").sorted("-elongation"):
    print(specimen.name, specimen.elongation)
print(specimens.stats("elongation").mean)
$ python scripts/selecting.py
['copper-01']
copper-01 44.0 %
steel-01 24.0 %
26.666666666666668

A mistake is said, never guessed

SampleKit refuses what it would have to guess, and says why:

  • A name misspelt is refused naming the nearest one; in a terminal, it asks whether to use it, use 'tensile_strength'? [Y/n].

  • A condition that does not read is refused at the character where it stops:

$ samplekit -f 'material = steel'
error: at character 10: expected a comparison operator, found '='
  material = steel
           ^
  • A text compared with a number, grade > 3, is refused where every sample holds text; where one sample holds text among numbers, the others are compared and the one left aside is named.

  • A file that cannot be read is never skipped in silence: the command names it, reads the rest, and exits with code 2. samplekit list skipped lists every file set aside, and why.

When something goes wrong gathers these and the others.

See also