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 by import.

  • A folder below a project with a .samplekitrc of its own is a separate project.

  • Paths written in .samplekitrc are 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's f offer is the configuration of the folder a command runs from, or of its target.

  • --rc PATH uses another configuration for one command; --show-rc prints 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

schema_version

integer

required, in every file

The version of the configuration's format: 1. A file importing another writes its own

schema_version = 1

import

folder or file, or a list

none

What this file takes, merged beneath it: a folder's .samplekitrc, or a file of any name; relative to this file, absolute, or starting with ~. A list is merged in order, a later one over an earlier one

import = ["..", "figures.samplekitrc"]

The sections below are all optional.

import

  • What is imported: everything but [model] path and class, which stay each file's own. [model] python is 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, its schema_version written.

  • Paths: a relative [collection] files, [export.*] output, [query.*] directory, [model] python, or [matplotlib] style file or font reads from the file declaring it. [collection] include and exclude are 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] files and [export.*] output, is the folder of the project a sample follows, written from the file declaring it (data/ana from the root; . in the project's own file): files = ["{project}/photos/{name}*"], output = "exports/{project}/overview.csv". {project}.tsv in the project's own file writes ..tsv, which validate notes.

  • Where each comes from: samplekit list queries (profiles, exports, figures) marks each name local, with the imported file, or local over it; --show-rc names the files imported; samplekit validate notes 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

path

none

The model's file; without it, [model] names only the Python that draws the figures

path = "model/specimen.py"

class

text

the file's one class

The class to use, when the file defines several

class = "Specimen"

python

path

required to compute or draw

The Python that runs the model and draws the figures: an environment folder, whose bin/python (Scripts\python.exe on Windows) runs, or an interpreter. Declared without path too, for the figures of a project without a model. Nothing is searched for

python = ".venv"

[render]

How values are written when nothing else says.

Key

Type

Default

Meaning

Example

style

text

"plain"

The style tables use: plain, or a [style.*] declared. --style overrides it

style = "math"

precision

precision

none

The precision of every number no [property.*] or column gives one

precision = ".3f"

table

text

"plain"

How a terminal table is drawn: plain or boxed, any other name an error. --table-style overrides it

table = "boxed"

identify

text

"name"

The column added first to a table shown in a terminal, unless the columns name it: name, filename or none; a table piped or written to a file has only the columns asked for

identify = "filename"

figure_style

text

none

The style a figure's labels use when the figure names none

figure_style = "figure"

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

recursive

boolean

true in a project

Read the folders below the folder named too. A folder outside any project is read alone

recursive = false

include

list of patterns

["*.md", "*.MD", "*.markdown"]

The files read

include = ["*.sample.md"]

exclude

list of patterns

[]

The files skipped. samplekit list skipped lists them

exclude = ["draft-*"]

files

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 {name}, the sample's file name without .md; {project} is its project's folder (see import)

files = ["photos", "raw/{name}/**"]

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

plain

text

the spelling

The unit in the plain style

plain = "°C"

any style's name

text

the spelling

The unit in that style

math = '^\circ\mathrm{C}'

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

property

text or false

"{value} ± {uncertainty} {unit}"

How a property is written, with {value}, {uncertainty}, {unit} and {symbol} in the style's forms; in a document, false writes its two columns. A unit placed inside it, \SI{…}{{unit}}, is written in each cell and not in the column's header

property = '\SI{{value} \pm {uncertainty}}{{unit}}'

uncertainty

text

the number

The piece {uncertainty} stands for in property and unitless, with {uncertainty} the number in it; written only where a value has an uncertainty

uncertainty = ' \pm {uncertainty}'

unitless

text

property, its unit empty

How a property with no unit is written, instead of property

unitless = '\num{{value}{uncertainty}}'

missing

text

"" in a document

An absent value

missing = "--"

escape

text, table or false

false; the given styles' own

What text is escaped for: latex, html, markdown, or a table of replacements, escape = { "<" = "&lt;" }. A template and the style's own lines and forms are written as they are

escape = "latex"

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

extension

text

the name; tex, md, html

The file's extension, which -o recognises for the given three

extension = "txt"

before

text

""

The lines before the table; {align} is the columns' alignment

before = '\begin{tabular}{{align}}'

after

text

""

The lines after it

after = '\end{tabular}'

header

text or false

"{cells}"

The header line, {cells} its cells joined; false writes none

header = '{cells} \\'

header_cells

text

cells

Between two cells of the header line

header_cells = "</th><th>"

rule

text

none

A line of this cell under each column, after the header, as Markdown's ---

rule = "---"

row

text

"{cells}"

Each row's line

row = '{cells} \\'

cells

text

" "

Between two cells

cells = " & "

between_groups

text

none; LaTeX's \midrule, Markdown's | **{group}** |, HTML's </tbody><tbody>

A line where a column the profile groups by changes value. Holding {group}, it heads each group, the first included: {group} is its values, {columns} the number of columns

between_groups = '\midrule \multicolumn{{columns}}{l}{{group}} \\'

header_unit

text or false

" ({unit})"

Written after a header cell holding a unit; false writes none

header_unit = " [{unit}]"

align_text, align_number

text

"l", "r"

{align}'s letter for a column of text, and of numbers

align_number = "S"

[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

unit

text

none

The unit, for files that give none

unit = "mm"

symbol

text

none

The symbol, which labels a figure's axis

symbol = "Rm"

symbol_STYLE

text

symbol

The symbol in a style

symbol_math = 'R_\mathrm{m}'

precision

precision

[render] precision

How the number is written. Files hold none

precision = [".3f", ".4f"]

range

two numbers

none

The values it may take, in its declared unit, inf leaving a side open: validate reports one outside as a defect, and set and compute write it and warn

range = [0, 50]

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

filter

text

required

The filter, in the language of -f

filter = 'material == steel'

directory

path

none

The folder it applies to when a command names no target

directory = "samples"

[profile.NAME]

A named table shape, used with --profile NAME.

Key

Type

Default

Meaning

Example

columns

list of columns

required, not empty

The columns, in order

columns = [{ field = "width" }]

sort

list of fields

[]

The order; a - before a field sorts it from high to low

sort = ["material", "-width"]

group

list of fields

[]

A table per group of samples sharing these fields' values, as --group

group = ["material"]

Each column is an inline table:

Key

Type

Default

Meaning

Example

field

field

required

What the column shows, as -c names it

field = "width.u"

label

text

the field

The column's title on the terminal and in a document (--style latex, an export's style)

label = "Tensile strength"

header

text

the field

The column's name in a CSV, TSV or JSON file: a property's two columns are Rm_value [MPa] and Rm_uncertainty [MPa], the suffixes and the unit saying what each holds

header = "Rm"

precision

precision

[property.*]'s

How the column's numbers are written

precision = ".4f"

template

text

none

The cell as text, with {value}, {uncertainty}, {unit} and {symbol} filled in; {value:.3f} takes a precision. A CSV or TSV writes the text, in one column named by header, its unit and symbol spelled in [render] style; JSON writes the numbers

template = '\num{{value:.3f}}'

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

profile

text

one of the two

The profile giving the columns of a table

profile = "overview"

figure

text

one of the two

The figure drawn, declared in [figure.*] or by the model; its file's format is its output's extension

figure = "curves"

format

text

none

A table's: csv, tsv or json; without it, style names a style writing documents

format = "csv"

output

path

required

The file written; its folder is created if needed; {project} names the project's folder, so that projects importing it write apart; for a figure of one sample, {name} writes a file per sample

output = "out/overview.csv"

query

text

none

The query selecting the samples

query = "ductile"

filename

boolean

false

A table's: add a column holding each sample's file name

filename = true

path

boolean

false

A table's: add a column holding each sample's path, from its project's folder

path = true

style

text

files; a figure's, [render] figure_style

How units are spelled in a data file: files, as the samples write them (degC); plain, the forms [unit.*] declares for the screen (°C); or a style. With no format, the style writing the document. For a figure, the style its labels use

style = "latex"

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

kind

text

"scatter"

scatter, line, step, bar or box

kind = "line"

x

field

required

The horizontal axis

x = "curve.strain"

y

field

required

The vertical axis

y = "curve.stress"

group

field

none

One series per value of this field

group = "material"

query

text

none

The query selecting the samples

query = "ductile"

title

text

none

The title drawn above the axes; none by default, a caption in the document saying what the figure shows

title = "Stress against strain"

x_label, y_label

text

the field's symbol and unit

An axis's label

y_label = '$\sigma$ [MPa]'

style

text

[render] figure_style

The style the labels use

style = "figure"

x_limits, y_limits

two bounds

matplotlib's

An axis's range; "auto" leaves a bound free; a first bound above the second turns the axis over

x_limits = [0, "auto"]

x_scale, y_scale

text

"linear"

linear, log or symlog

y_scale = "log"

aspect

text

"auto"

equal draws a unit the same length on both axes, auto does not

aspect = "equal"

legend

text

"best"; "outside" past six series

best, outside, none, or a place: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center

legend = "outside"

figsize

two numbers

[matplotlib] "figure.figsize"

Width and height, in centimetres

figsize = [18, 12]

matplotlib

table

none

matplotlib's settings for this figure alone, over [matplotlib]; style and fonts are the project's

matplotlib = { "lines.marker" = "s" }

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

"axes.grid" = true

"figure.figsize"

two numbers

matplotlib's

A figure's size, in centimetres

"figure.figsize" = [15, 10]

style

text or list

none

matplotlib's style sheets, by name or as .mplstyle files, applied in order before the section's own settings, which win

style = ["seaborn-v0_8-paper", "figures.mplstyle"]

fonts

text or list

none

Font files, or patterns of them, that matplotlib learns before it draws: a font that travels with the project

fonts = ["fonts/*.otf"]

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

lines.marker, or marker in axes.prop_cycle

a round marker on each point of a scatter and a line

lines.markersize

the points of a box drawn at size 3

errorbar.capsize

caps of 3 points on the error bars

legend.fontsize

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

theme

text

none

The terminal interface's theme for this project: one SampleKit has, or one of your own; a theme chosen with T in this folder comes first. A name no theme bears is said, and passed over

theme = "nord"

background

colour

default

The background of the terminal interface's whole screen; the command line leaves the terminal's

background = "#1e1e2e"

foreground

colour

default

The terminal interface's text, where nothing else colours it

foreground = "#cdd6f4"

failed

colour

red

A value whose formula failed

failed = "light-red"

outdated

colour

yellow

A value that is not current

outdated = "#ff8800"

edited

colour

magenta

A value written by hand over its formula

edited = "light-magenta"

current

colour

green

A computed value that is current

current = "light-green"

selected

colour

cyan

The line or item under the cursor

selected = "light-cyan"

attribute

colour

blue

Attributes, and an attribute's value

attribute = "light-blue"

link

colour

blue

A link, underlined; one leading nowhere takes error's colour

link = "light-blue"

value

colour

default

A value and its uncertainty, drawn bold

value = "white"

unit

colour

cyan

A unit, after a number and in a header

unit = "grey"

table

colour

magenta

Tables

table = "magenta"

index

colour

cyan

A table's index column

index = "cyan"

key

colour

cyan

Keys, in the help and at the foot

key = "yellow"

muted

colour

dark-grey

Secondary text

muted = "grey"

message

colour

yellow

Messages

message = "default"

error

colour

red

Errors

error = "light-red"

accent

colour

cyan

The name in the title bar, a computation in progress

accent = "#5fafd7"

waiting

colour

light-magenta

What waits to be written in the terminal interface, in italics

waiting = "light-yellow"

line

colour

dark-grey

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

line = "#313244"

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

shared

boolean

not set

Whether git carries the history with the samples: true lets git see what must travel and keeps out what each computer makes for itself; false hides the history from git. Not set, a new history is hidden, and one shared by hand is left as it is.

shared = true

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"