Start from templates¶
This guide is for a project of your own started from files rather than from
nothing: a .samplekitrc, a model, a sample and a script, each ready to fill
in, the places for your own choices marked in its comments with ← change.
Together they make a project that validates and computes as downloaded; a
test of SampleKit builds one from them and computes it, so that they keep
working.
They are files to copy, not the demo: the demo, the home page's tensile
test, is in the command line already (the guides). samplekit init sets a project up too, with a model that declares nothing yet (start
a project); the templates are the same project with one
value of each kind already declared.
The configuration¶
A project's .samplekitrc: which files are samples and where a sample's own
files are, the model and its Python, the digits of two values, a query, a
profile, an export and a figure. Save it as .samplekitrc, with the leading
dot, in the project's folder. Every key is explained in the configuration
reference.
# A project's configuration: save this file as `.samplekitrc` in the
# project's folder. It works as it is, with the model, the sample and the
# script of the same templates; every value marked `← change` is one of your
# own choices. Every section but `schema_version` is optional, and each key is
# explained in the configuration reference.
schema_version = 1
# Which files are samples, and where a sample's own files are.
[collection]
recursive = true # read the folders below this one too
exclude = ["draft-*"] # ← files left out: drafts, notes
files = ["photos", "raw/{name}/*"] # ← a folder searched for files named
# as the sample, and a pattern where
# {name} is the sample's file name
# The Python model, and the environment it runs in.
[model]
path = "model/model.py" # ← where your model's file is
class = "Specimen" # ← its class
python = ".venv" # ← the environment, made by samplekit init
# How many digits a value is shown with: one section per property, and a
# table's column quoted as "table.column".
[property.area]
precision = ".2f" # ← two decimals
[property."curve.stress"]
precision = ".1f" # ← your column, your digits
# A named filter: samplekit --query large
[query.large]
filter = "area > 100" # ← in the language of -f
# A named table: samplekit --profile overview
[profile.overview]
columns = [
{ field = "name" },
{ field = "material" }, # ← your attributes
{ field = "length", precision = ".2f" },
{ field = "width", precision = ".2f" },
{ field = "area", label = "A" }, # ← a column's title
]
sort = ["-area"] # ← a leading - sorts from high to low
# A file written again by one command: samplekit export overview --write
[export.overview]
profile = "overview"
format = "csv" # ← csv, tsv or json
output = "out/overview.csv" # ← where it is written
# A figure: samplekit plot curves
[figure.curves]
kind = "line" # ← scatter, line, step, bar or box
x = "curve.strain"
y = "curve.stress"
group = "material" # ← one series per value of this field
# The colours of the terminal interface and the command line, by role: the
# guide "Choose the colours" has a [colors] table for each of nine themes, to
# copy here.
# [colors]
# outdated = "#ff8800"
The model¶
The class that says what a sample holds: two values measured several times,
their mean and standard error as value and uncertainty; an area computed
from them; a table curve whose index is strain, a column measured and a
column computed in each row; and a script with an option. Save it where
[model] path names it, model/model.py. Write a model
explains each kind.
"""A model: what a sample of this project holds, and what is computed from what.
Save it where `.samplekitrc` names it, `[model] path`, and name its class
there, `[model] class`. Every name marked `← change` is one of your own:
a property, a unit, a formula. The sample template is a sample of this model.
"""
import math
import samplekit as sk
class Specimen(sk.Sample): # ← your class, as [model] class names it
"""A specimen: what it holds, and in which units."""
def __init__(self, path=None, name=None):
super().__init__(path, name=name)
# Measured several times: the value is the mean of the readings, and
# the uncertainty their standard error.
self.length = sk.Property( # ← your measured value
unit="mm", # ← its unit
value=sk.stats.mean,
uncertainty=sk.stats.standard_error,
)
self.width = sk.Property(
unit="mm",
value=sk.stats.mean,
uncertainty=sk.stats.standard_error,
)
# Computed from others: it says what it reads, so that a reading
# changed makes it outdated.
self.area = sk.Property( # ← your computed value
unit="mm²",
compute=self._area,
depends_on=["length", "width"],
)
# A table: its index, a column measured, and a column computed in
# each row from that row's force and the area.
self.curve = sk.Table( # ← your table
{
"strain": sk.Property(unit="%"), # ← its index
"force": sk.Property(unit="N"), # ← a column measured
"stress": sk.Property( # ← a column computed
unit="MPa",
compute=self._stress,
depends_on=["row.force", "area"],
),
},
index="strain",
)
def _area(self):
"""The length times the width, and its uncertainty from theirs."""
length = self.length
width = self.width
value = length.value * width.value
uncertainty = math.sqrt(
(width.value * length.uncertainty) ** 2
+ (length.value * width.uncertainty) ** 2
)
return value, uncertainty
def _stress(self, row):
"""The force over the area: N over mm² is MPa."""
return row.force.value / self.area.value
@sk.script
def classify(self, limit: float = 100.0): # ← its options, with defaults
"""Class the specimen by its area: large from the limit up."""
self.size = "large" if self.area.value >= limit else "small"
A sample¶
One sample of that model: two attributes, the readings of the two values
with their units, the table's rows, and a note below the second ---. The
area and the column stress are not written in it: compute writes them.
Save it in samples/ as specimen-01.md, the name it holds.
---
schema_version: 1
name: specimen-01
material: steel
tested: 2026-11-11
properties:
length: {readings: [20.02, 20.05, 19.98], unit: mm}
width: {readings: [10.01, 9.98, 10.03], unit: mm}
tables:
curve:
index: strain
columns:
strain: {unit: "%"}
force: {unit: N}
rows:
- strain: 0
force: 0
- strain: 0.1
force: 4180
- strain: 0.5
force: 7210
- strain: 2
force: 9050
- strain: 10
force: 9840
---
A sample of the model template: save it in `samples/`, named as its `name`,
`specimen-01.md`. Its attributes and readings are yours to change; the area
and the table's stress are computed by `samplekit compute --write`, which
writes them here. This note, below the second `---`, is yours: SampleKit
never changes it.
A script¶
A Python script of your own, beside the model's: it reads the samples, calls
the model's script classify on each, and prints what it gives. Its
options, --limit and --save, are its own. Save it in scripts/ and run
it from the project's folder with the project's Python, .venv/bin/python scripts/script.py --limit 150 (work from Python).
"""A script of your own: the samples read, the model's script called, what it
gives printed.
Save it in the project's `scripts/` folder and run it from the project's
folder with the project's Python:
.venv/bin/python scripts/script.py --limit 150
Every line marked `← change` is one of your own choices.
"""
import argparse
import samplekit as sk
options = argparse.ArgumentParser(description=__doc__.splitlines()[0])
options.add_argument("--limit", type=float, default=100.0) # ← your options
options.add_argument("--save", action="store_true", help="write what changed")
given = options.parse_args()
specimens = sk.load("samples").sorted("-area") # ← which samples, in which order
for specimen in specimens:
# The model's script, called as a method: its option is a keyword.
specimen.classify(limit=given.limit)
print(f"{specimen.name:14} {specimen.area} {specimen.size}") # ← what it prints
if given.save:
specimen.save()
Put them together¶
In a new folder, each file where the configuration expects it:
.samplekitrc samplekitrc.toml, renamed
model/model.py model.py
samples/specimen-01.md sample.md
scripts/script.py script.py
Then, in that folder:
samplekit initoffers what is missing, the Python environment.venv/with SampleKit's package in it, and writes it once you answery.samplekit validatechecks every file. It notes thatphotosandraw, the folders[collection] filesnames, do not exist yet: make them, or change that line to your own folders.samplekit compute --writecomputes the area and the columnstress, and writes them in the sample.samplekit run classify --set limit=150runs the model's script on each sample, shows what it changes and asks before writing it (run a script of the model).samplekitopens the project in the terminal interface;pruns the same script there.
Then change what is marked ← change: your values and their units in the
model, the same names in the sample and in the configuration's profile,
query and figure. samplekit validate says, with its line, a name that
refers to nothing.
See also¶
Choose the colours: a
[colors]table for your terminal's theme, to add to the configuration.Bring existing data in: samples made from a spreadsheet or CSV files rather than written by hand.