Bring existing data in¶
This guide is for measurements you already have, in a spreadsheet, CSV files or a notebook, to turn into sample files: one Markdown file per sample, in a project. Your original data is only read; SampleKit writes new files beside it.
The example is the home page's tensile specimens: a material, a width and a thickness per specimen, and the force read at each strain, which the testing machine wrote to a CSV file per specimen.
1. Make the project¶
$ samplekit tensile-tests init --no-model --no-venv --write
This writes .samplekitrc and an empty samples/ folder. --no-model
leaves the model for later, and --no-venv makes no Python environment,
which reading and writing samples do not need; init without them asks
(start a project).
2. Declare your properties¶
A measured quantity with a unit is a property; a fact without one, the
material or the grade, is an attribute (samples and their
files). Declare each property in
.samplekitrc, with its unit and its digits, before writing any sample:
[property.width]
unit = "mm"
precision = ".2f"
[property.thickness]
unit = "mm"
precision = ".2f"
A name .samplekitrc declares is then written as a property, with its unit,
and so is one the project's model declares, once there is one. A name nothing
declares is written as an attribute, and new and set warn you when that
name is given a number.
3. Write the samples¶
One sample at a time, from the command line:
$ samplekit samples new steel-01 material=steel grade=S355 width=12.51 thickness=2.00 --write
width.u=0.01 gives an uncertainty, and width.readings=12.494,12.528,12.518
repeated measurements. Write decimals with a point, never a comma (edit
samples).
From a CSV file, a shell loop gives each row to new. With
specimens.csv holding name,material,grade,width,thickness, a row per
specimen:
tail -n +2 specimens.csv | while IFS=, read -r name material grade width thickness; do
samplekit samples new "$name" material="$material" grade="$grade" \
width="$width" thickness="$thickness" --write
done
From a spreadsheet, save the sheet as CSV first. A field that holds a comma
needs a real CSV reader: Python's csv module, as below.
A table per sample, such as each test's curve, is simpler from Python.
With machine/steel-01/curve.csv holding strain [%],force [kN] for each
specimen, and its sample written above:
import csv
from pathlib import Path
import samplekit as sk
for folder in sorted(Path("machine").iterdir()):
sample = sk.Sample(Path("samples") / f"{folder.name}.md")
with (folder / "curve.csv").open(newline="") as exported:
rows = [{"strain": float(row["strain [%]"]), "force": float(row["force [kN]"])}
for row in csv.DictReader(exported)]
sample.curve = sk.Table(
{"strain": sk.Property(unit="%"), "force": sk.Property(unit="kN")},
index="strain",
rows=rows,
)
sample.save()
Run it with the Python where SampleKit's package is installed (work from
Python). Step 1 made none: samplekit init, run again
in the project, offers to make it, .venv/, or make it yourself (the Python
package). The CSV files stay where they are, and
[collection] files = ["machine/{name}/*"] keeps them attached to their
sample (files).
By hand, write one file in a text editor, then the next ones from it:
new --keep takes the fields it names from a sample, and nothing else:
$ samplekit samples new steel-02 --keep samples/steel-01.md material,grade --write
In the terminal interface, N on the list makes a new sample beside the
one under the cursor: its name, then field=value for each value, and
keep:material,grade to take fields from the one under the cursor. e on its
screen fills a value, and A adds an attribute; each change is shown before
y writes it (work in the terminal
interface).
4. Check¶
list fields shows each name under properties or attributes: a property
listed as an attribute was not declared in step 2. validate reports what
is wrong in a file, and changes nothing. Then compare a few files with your
original data by eye before trusting the rest:
$ samplekit list fields
properties (2)
width thickness
attributes (4)
material grade direction tested
always
name path filename project state tags
$ samplekit validate
3 samples · 0 defects · 0 notes
Next¶
Write a model: what your formulas compute from these values.
Data from several series, or several people: several projects.