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.

samplekitrc.toml
# 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"

Download samplekitrc.toml

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.

model.py
"""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"

Download model.py

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.

sample.md
---
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.

Download sample.md

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).

script.py
"""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()

Download script.py

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:

  1. samplekit init offers what is missing, the Python environment .venv/ with SampleKit's package in it, and writes it once you answer y.

  2. samplekit validate checks every file. It notes that photos and raw, the folders [collection] files names, do not exist yet: make them, or change that line to your own folders.

  3. samplekit compute --write computes the area and the column stress, and writes them in the sample.

  4. samplekit run classify --set limit=150 runs the model's script on each sample, shows what it changes and asks before writing it (run a script of the model).

  5. samplekit opens the project in the terminal interface; p runs 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