Projects¶
A project is a folder with a .samplekitrc file: its samples, the rules
for reading them, and optionally a model. This page says what a project
decides, how SampleKit finds the project a sample belongs to, and what
happens when one command reads samples from several projects.
Why a project¶
The sample files hold the data. What they do not hold is said once for all of them, in the project:
how to show the properties: their units' display forms, symbols and precisions (Values and uncertainty);
which files are samples, and where each sample's own files are (Samples and their files);
the model that computes derived values (Models and formulas);
named selections and layouts: queries, profiles, exports, figures;
the TUI's colours.
A project is also the unit of one kind of sample: one set of properties and one model. When the properties or the formulas change from one series to the next, the next series is a new project.
A project costs nothing to the person with ten samples. A folder of samples
with no .samplekitrc works: every command reads it with the default
settings. samplekit init makes the file when you want one, and the
history needs one.
The configuration file¶
.samplekitrc is written in TOML, a plain text format of sections and
key = value lines:
schema_version = 1
[collection]
recursive = true
exclude = ["README.md"]
[model]
path = "model/specimen.py"
class = "Specimen"
python = ".venv"
[property.width]
symbol = "w"
precision = [".3f", ".4f"]
[query.strong]
filter = 'tensile_strength > 400'
Paths inside it are relative to the file itself, so a project can be moved or
copied as a whole. You can edit it in any text editor, or section by section
in the TUI (P, or c on the start page), which keeps its comments.
The configuration reference lists every
section and key.
A configuration is checked every time it is read. An unknown key, a misspelled section or a precision that is not valid is an error that names where it is and suggests the nearest valid name. A configuration with an error is set aside, and the command says so: the samples it covers are then read with the default settings, never with a half-read configuration.
The nearest configuration¶
A sample follows the nearest .samplekitrc above it: in its own folder
first, then in each folder above, up to the first one found. That one applies,
with what it imports (below), and no other.
So a project's configuration covers its subfolders too, unless a subfolder
has a .samplekitrc of its own; that subfolder is then a separate
project, with its own units, model, queries and history: the snapshots the
project above took of its files come with it (A folder made a
project). A new project made inside
another one is a project of its own; the TUI's setup says which project is
above it.
A sample follows its project wherever a command runs from. What it shows, computes, filters, exports and draws is the same whether you run the command in its folder, from the folder above several projects, or name its file alone.
Which folders a command reads¶
In a project, a command reads the folder you name and every folder below
it: samplekit . at the project's root reads samples/ and whatever other
folder holds samples. Markdown that is no sample, a README.md or notes, is
left alone: no command warns of it but with -v, and list skipped names it. A project can keep to the folder named alone:
[collection]
recursive = false
exclude = ["draft-*"]
Outside any project, a folder is read alone: a folder no configuration
describes may be anything, and reading everything below it is asked for by
naming more (samplekit rolled cast). include and exclude choose
file names by pattern; samplekit list skipped lists what an exclude left
out, so that a pattern written too widely is found.
When a recursive read meets a subfolder with its own .samplekitrc, it reads
that subfolder's samples too, but each under its own project: a collection
can span several projects, and SampleKit shows them apart.
Several projects in one view¶
Comparing two series, rolled and cast specimens, or two people's tests, is a real need. So a command can read samples from several projects at once:
$ samplekit rolled cast status
$ samplekit rolled cast -c material,tensile_strength
Each sample keeps its own project's rules. Its units, precisions, model, queries and profiles are its project's, whatever else the command reads. What that looks like:
On the terminal, one table per project, headed by the project's folder. A table mixing two projects' precisions and models in one column would compare numbers declared differently, silently. With
--group, each project comes first and its groups follow:cast · material = aluminium.A CSV or JSON is one table, since a file has one header. Its rows each keep their project's precision, and its header the unit every project gives the column. A summary,
--summary, takes the unit, precision and table drawing the projects agree on, and none where they differ: the order you name them in changes nothing. Add the fieldproject(the project's folder name) orpathto the columns to tell the rows apart. A profile written to a data format over several projects is refused, since each project's profile may differ: narrow the target to one project, or give--rc.A query, a profile or a style is looked up in each sample's own project, a profile's sort included.
--style mathshows in its own style a project that declares none, and says so.--query strongkeeps, in each project, the samples that project'sstrongselects. A query declared in a folder above reaches a sub-project's samples only when the sub-project imports it. Samples whose project lacks it are left out, said in one line;-vnames each project.A declared export writes the samples of the project that declares it; over several projects, each writes its own.
Computing runs each project's model on its own samples. When one project cannot run (its model is missing, say), the error names it and the others are still computed.
In the TUI, the collection is split by project, each part headed by its folder's name.
In Python,
sk.load("rolled", "cast")gives one list; each sample keeps its project's rules, andto_csv()writes each row at its own project's precision.
Two projects can share one model, by pointing their [model] path at the same
file (path = "../model/specimen.py"): the formulas are then the same, and each
project keeps its own configuration.
What the current folder offers¶
Where you run a command decides what is offered, never how a sample is
read. samplekit list profiles (and queries, exports, figures), the
completion of --profile and --query, and f in the TUI show the
configuration of the folder you are in, or of the target you name, with what
it imports: at the root of several projects, what they have in common; in a
project, what is common and its own. Where that configuration imports
another, each name says where it comes from.
Here cast declares a profile of its own, porosity, and redeclares the
sort of strengths, which the folder above declares:
$ cd cast && samplekit list profiles
overview name, material, young_modulus, yield_strength, tensile_strength, elongation · ../.samplekitrc
strengths name, yield_strength, tensile_strength · local over ../.samplekitrc
porosity name, elongation · local
local over is a profile the project redeclares in part. Naming several
targets lists each one's under its file.
A command that would warn several times of one thing, such as a profile that
several projects lack, says it once, in one line counting them and ending
-v shows them; -v lists each beneath it.
Queries, profiles and groups¶
Three things shape what a command shows, and each answers one question:
Answers |
Declared as |
Used with |
|
|---|---|---|---|
Query |
which samples? |
|
|
Profile |
which columns, in which order, sorted how, grouped how? |
|
|
Group |
split into which tables? |
|
|
A query names no columns and a profile names no samples, so one of each can be
combined: --profile overview --query strong. An option beside a profile
replaces one part of it: -c the columns, -s the sort, --group the
groups.
A group is computed from the data each time, never saved as a list of
samples. A set you choose by hand, the reference specimens of a series, is
a tag on each of them, reached by a query (tags has reference): the tag
travels with the file, where a saved list of paths breaks when a file is
renamed.
--save on a table, and W in the TUI, save what is shown (its filter,
columns, sort and grouping) as a query, a profile or an export of the
project, to use by name from then on (saved
shapes).
Common mistakes¶
Expecting a folder's configuration to add to the one above by itself. The nearest one applies alone, unless it says
import = "..".Copying the shared sections into each project. Declare them once above and import them;
samplekit validatenotes the copies left.Expecting a folder outside any project to be read with its subfolders. Name them, or make the folder a project.
Comparing two projects in one CSV without a
projectcolumn. Add it.Declaring a query at the top of a tree of projects and expecting it in each without an import. Import the top's configuration in each project that uses it.
An imported export writing one file for every project. Name the project in its destination:
output = "exports/{project}/overview.csv".Keeping a list of files as a "group". Tag the samples instead.
Where to go next¶
Two projects side by side: several projects; queries and profiles: find and select samples.
Share a project with a colleague.
Every key of
.samplekitrc: Configuration reference;init,--rc,--show-rc: Command line reference.