Configuration¶
.samplekitrc is a project's configuration, in TOML. It is optional: a
folder of samples without one is read with the defaults below.
Where it applies¶
A sample follows the nearest
.samplekitrc: in its own folder, else in the closest folder above, with what that file imports, wherever the command runs from. Configurations are combined only byimport.A folder below a project with a
.samplekitrcof its own is a separate project.Paths written in
.samplekitrcare relative to the file itself, imported ones to the file that declares them. Write them with/, which every system reads; a\written on Windows is read as/on Linux and macOS too, so that the project reads wherever it is copied.What
list, the completion and the TUI'sfoffer is the configuration of the folder a command runs from, or of its target.--rc PATHuses another configuration for one command;--show-rcprints the configuration, model and Python a command would use.The file is checked each time it is read. An unknown section or key, a value of the wrong type, or a name that refers to nothing declared is an error naming the line and the nearest valid name. A configuration with an error is set aside and said; the samples it covers are read without it.
Top level¶
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
integer |
required, in every file |
The version of the configuration's format: |
|
|
folder or file, or a list |
none |
What this file takes, merged beneath it: a folder's |
|
The sections below are all optional.
import¶
What is imported: everything but
[model] pathandclass, which stay each file's own.[model] pythonis imported.The merge rule: key by key, this file winning. A table (a section, a
[property.NAME], a profile) merges key by key, recursively; any other value (a number, a text, a list) replaces the imported one whole.A list: each is merged in order, a later one over an earlier one, and this file over all. A file listed twice is merged once.
Chains: the imported file may import another. A file importing itself, directly or through others, is an error naming the files.
Errors: a folder without a
.samplekitrc, or a path naming nothing, is an error naming the importing file. The imported file must be valid on its own, itsschema_versionwritten.Paths: a relative
[collection] files,[export.*] output,[query.*] directory,[model] python, or[matplotlib]style file or font reads from the file declaring it.[collection] includeandexcludeare patterns on the collection's own files and apply as written. Each project's own decide which files are its samples, whichever folder a command names: the patterns of a folder above never reach into a project inside it.{project}, in[collection] filesand[export.*] output, is the folder of the project a sample follows, written from the file declaring it (data/anafrom the root;.in the project's own file):files = ["{project}/photos/{name}*"],output = "exports/{project}/overview.csv".{project}.tsvin the project's own file writes..tsv, whichvalidatenotes.Where each comes from:
samplekit list queries(profiles, exports, figures) marks each namelocal, with the imported file, orlocal overit;--show-rcnames the files imported;samplekit validatenotes a declaration identical to the imported one.
[model]¶
The project's Python model. Reading a configuration never runs it.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
path |
none |
The model's file; without it, |
|
|
text |
the file's one class |
The class to use, when the file defines several |
|
|
path |
required to compute or draw |
The Python that runs the model and draws the figures: an environment folder, whose |
|
[render]¶
How values are written when nothing else says.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
|
The style tables use: |
|
|
precision |
none |
The precision of every number no |
|
|
text |
|
How a terminal table is drawn: |
|
|
text |
|
The column added first to a table shown in a terminal, unless the columns name it: |
|
|
text |
none |
The style a figure's labels use when the figure names none |
|
A precision is a format specifier, written as in Python: ".3f" (three
decimals), ".2e" (scientific notation), ".4g" (four significant digits),
or a list of two, [".3f", ".4f"]: the value's, then the uncertainty's.
".17g" writes every digit a value carries, and an uncertainty's too:
0.8787328442349305 is written as it is.
[collection]¶
Which files are samples, and where a sample's own files are.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
boolean |
|
Read the folders below the folder named too. A folder outside any project is read alone |
|
|
list of patterns |
|
The files read |
|
|
list of patterns |
|
The files skipped. |
|
|
list of folders or patterns |
|
Where a sample's own files are: a folder, searched for files whose name starts with the sample's; or a pattern holding |
|
Patterns are globs: * any characters within a name, ? one character,
** any number of folders, [0-9] one of a set, {a,b} either. A pattern
holding a / is matched against the path from the project's folder; without
one, against the file name.
[unit."SPELLING"]¶
How a unit is shown, in each style. The key is the unit as the files write it, quoted. SampleKit never converts units: a unit no section names is shown as written.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
the spelling |
The unit in the |
|
any style's name |
text |
the spelling |
The unit in that style |
|
A spelling no section names is shown as written: the sections are display
forms, never a closed list of units. What validate reports is a file whose
unit contradicts the one [property.*] declares.
[style.NAME]¶
A style says how a kind of document writes: named by [render] style,
--style, an export's and a figure's style, and the variants of
[unit.*] and [property.*], [unit.g] latex = '\gram'. plain is built
in; latex, markdown and html are given, and a [style.latex] changes
the given one key by key. A style of units and symbols alone may be declared
empty, [style.figure].
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text or |
|
How a property is written, with |
|
|
text |
the number |
The piece |
|
|
text |
|
How a property with no unit is written, instead of |
|
|
text |
|
An absent value |
|
|
text, table or |
|
What text is escaped for: |
|
A style writing documents writes a table as a document holds it: -o table.tex, --style latex -o - to the standard output, an export naming it
as its style, and Python's to_text("latex"). The given three write
documents; a style of your own does once it declares one of these keys:
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
the name; |
The file's extension, which |
|
|
text |
|
The lines before the table; |
|
|
text |
|
The lines after it |
|
|
text or |
|
The header line, |
|
|
text |
|
Between two cells of the header line |
|
|
text |
none |
A line of this cell under each column, after the header, as Markdown's |
|
|
text |
|
Each row's line |
|
|
text |
|
Between two cells |
|
|
text |
none; LaTeX's |
A line where a column the profile groups by changes value. Holding |
|
|
text or |
|
Written after a header cell holding a unit; |
|
|
text |
|
|
|
[property.NAME]¶
What a property's files need not repeat. The name is the property's; a
table's column is [property."table.column"], quoted.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
none |
The unit, for files that give none |
|
|
text |
none |
The symbol, which labels a figure's axis |
|
|
text |
|
The symbol in a style |
|
|
precision |
|
How the number is written. Files hold none |
|
|
two numbers |
none |
The values it may take, in its declared unit, |
|
A unit or a symbol a file writes wins over these. An attribute's
symbol_figure titles a figure's legend when the figure is grouped by it.
[query.NAME]¶
A named filter, used with --query NAME.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
required |
The filter, in the language of |
|
|
path |
none |
The folder it applies to when a command names no target |
|
[profile.NAME]¶
A named table shape, used with --profile NAME.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
list of columns |
required, not empty |
The columns, in order |
|
|
list of fields |
|
The order; a |
|
|
list of fields |
|
A table per group of samples sharing these fields' values, as |
|
Each column is an inline table:
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
field |
required |
What the column shows, as |
|
|
text |
the field |
The column's title on the terminal and in a document ( |
|
|
text |
the field |
The column's name in a CSV, TSV or JSON file: a property's two columns are |
|
|
precision |
|
How the column's numbers are written |
|
|
text |
none |
The cell as text, with |
|
A field listed twice, two columns sharing a header, and an empty label or
header are errors. sort and group are lists even for one field.
[export.NAME]¶
A named file, written by samplekit export NAME --write: a table, from a
profile, or a figure, drawn as samplekit plot draws it.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
one of the two |
The profile giving the columns of a table |
|
|
text |
one of the two |
The figure drawn, declared in |
|
|
text |
none |
A table's: |
|
|
path |
required |
The file written; its folder is created if needed; |
|
|
text |
none |
The query selecting the samples |
|
|
boolean |
|
A table's: add a column holding each sample's file name |
|
|
boolean |
|
A table's: add a column holding each sample's path, from its project's folder |
|
|
text |
|
How units are spelled in a data file: |
|
An export names a profile or a figure, never both. format, filename
and path are a table's, and refused beside a figure; --precision and
--status likewise, on the command line.
[figure.NAME]¶
A named figure, drawn by samplekit plot NAME. Drawing it runs no code from
the project.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
|
|
|
|
field |
required |
The horizontal axis |
|
|
field |
required |
The vertical axis |
|
|
field |
none |
One series per value of this field |
|
|
text |
none |
The query selecting the samples |
|
|
text |
none |
The title drawn above the axes; none by default, a caption in the document saying what the figure shows |
|
|
text |
the field's symbol and unit |
An axis's label |
|
|
text |
|
The style the labels use |
|
|
two bounds |
matplotlib's |
An axis's range; |
|
|
text |
|
|
|
|
text |
|
|
|
|
text |
|
|
|
|
two numbers |
|
Width and height, in centimetres |
|
|
table |
none |
matplotlib's settings for this figure alone, over |
|
Limits are also written as one text, "0,auto". A bound is finite, two equal
bounds are refused, and a log axis takes no bound at or below zero.
[matplotlib]¶
matplotlib's own settings, by their matplotlib names, for every figure of the project. Quote a dotted name.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
any matplotlib setting |
as matplotlib takes it |
matplotlib's |
That setting |
|
|
two numbers |
matplotlib's |
A figure's size, in centimetres |
|
|
text or list |
none |
matplotlib's style sheets, by name or as |
|
|
text or list |
none |
Font files, or patterns of them, that matplotlib learns before it draws: a font that travels with the project |
|
Other sizes keep matplotlib's units: points for fonts and lines. A name
matplotlib does not know, a value it refuses and a date are errors;
backend and interactive are refused. A style sheet matplotlib does not
have, a file that is not there and a pattern that finds none are errors too.
A .mplstyle file and a font are read from the file declaring them.
SampleKit makes a few choices of its own, and gives way where the project declares the setting, in this section or in a style sheet:
Setting |
SampleKit's choice |
|---|---|
|
a round marker on each point of a |
|
the points of a |
|
caps of 3 points on the error bars |
|
a small legend, where it is placed outside |
A scatter draws no line between its points, whatever lines.linestyle says.
plot --no-project-style ignores the section, and a figure's own
matplotlib.
[colors]¶
The colours of the TUI and of the command line, by role. The command line
wears them only on a terminal, and never with --no-color, NO_COLOR or
TERM=dumb; a file it writes, and a pipe, carry none. A colour is default (the terminal's own), one
of the terminal's sixteen by name (black, red, green, yellow, blue,
magenta, cyan, grey, dark-grey, light-red, light-green,
light-yellow, light-blue, light-magenta, light-cyan, white; gray
and dark-gray too), or #rrggbb.
In the terminal interface, a role the table leaves out is its theme's:
SampleKit's own, samplekit-dark or samplekit-light, or terminal where
the terminal does not say it draws every colour, unless one is chosen with T
or named by theme, and the roles the table names are laid over it.
The command line has no theme: a role left out there is the default below,
one of the terminal's sixteen, which is also the theme terminal.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
text |
none |
The terminal interface's theme for this project: one SampleKit has, or one of your own; a theme chosen with |
|
|
colour |
|
The background of the terminal interface's whole screen; the command line leaves the terminal's |
|
|
colour |
|
The terminal interface's text, where nothing else colours it |
|
|
colour |
|
A value whose formula failed |
|
|
colour |
|
A value that is not current |
|
|
colour |
|
A value written by hand over its formula |
|
|
colour |
|
A computed value that is current |
|
|
colour |
|
The line or item under the cursor |
|
|
colour |
|
Attributes, and an attribute's value |
|
|
colour |
|
A link, underlined; one leading nowhere takes |
|
|
colour |
|
A value and its uncertainty, drawn bold |
|
|
colour |
|
A unit, after a number and in a header |
|
|
colour |
|
Tables |
|
|
colour |
|
A table's index column |
|
|
colour |
|
Keys, in the help and at the foot |
|
|
colour |
|
Secondary text |
|
|
colour |
|
Messages |
|
|
colour |
|
Errors |
|
|
colour |
|
The name in the title bar, a computation in progress |
|
|
colour |
|
What waits to be written in the terminal interface, in italics |
|
|
colour |
|
The background of the cursor's line on the collection, a sample and a table; in the typing mode the cell under the cursor reversed on it |
|
Choose the colours shows every theme SampleKit has, says how one is chosen, and how to make your own.
[history]¶
The project's history, kept in
.samplekit/history/.
Key |
Type |
Default |
Meaning |
Example |
|---|---|---|---|---|
|
boolean |
not set |
Whether git carries the history with the samples: |
|
Imported as any key: a root declaring it shares the history of every project importing it. See Share a project.
A complete example¶
schema_version = 1
[model]
path = "model/specimen.py"
class = "Specimen"
python = ".venv"
[render]
table = "boxed"
figure_style = "figure"
[collection]
recursive = true
exclude = ["draft-*"]
files = ["photos", "machine/{name}/*"]
[unit."degC"]
plain = "°C"
math = '^\circ\mathrm{C}'
figure = "°C"
[style.math]
property = '${value} \pm {uncertainty}$ {unit}'
[style.figure]
[property.tensile_strength]
symbol = "Rm"
symbol_math = 'R_\mathrm{m}'
precision = ".0f"
[query.steels]
filter = 'material == steel'
[profile.overview]
columns = [
{ field = "name", label = "Specimen" },
{ field = "material", label = "Material" },
{ field = "tensile_strength", label = "Tensile strength", header = "Rm" },
]
sort = ["material", "-tensile_strength"]
[export.overview]
profile = "overview"
format = "csv"
output = "out/overview.csv"
[figure.curves]
kind = "line"
x = "curve.strain"
y = "curve.stress"
group = "material"
legend = "outside"
[matplotlib]
"axes.grid" = true
[colors]
outdated = "#ff8800"