# 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 = { "<" = "<" }`. 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 = ""` | | `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 `` | 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](../guides/colours.md) shows every theme SampleKit has, says how one is chosen, and how to make your own. ## `[history]` The project's [history](../concepts/history.md), 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](../guides/share-a-project.md). ## A complete example ```toml 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" ```