Work from Python¶
This guide is for reading, analysing and changing your samples from Python: a
script of your own, a notebook, or a few lines typed at the prompt. The
samplekit package reads the same files as the command line, with the same
names and the same model, and changes them the same way: nothing is written
until you save.
The examples run in the last step of the home page's tensile
example, whose scripts/ folder holds them.
The Python to use¶
The package is installed in the project's Python environment, the one [model] python names in .samplekitrc: .venv/ beside the samples, which samplekit init makes (install SampleKit). Run a script
with that Python, .venv/bin/python script.py, or activate the environment
first, source .venv/bin/activate, after which python is that one; on
Windows, .venv\Scripts\activate. A notebook uses it as its kernel. Another
Python says No module named 'samplekit'.
Reading¶
sk.Sample(path) reads one sample with its project's model; sk.load(folder)
reads a folder, as the command line does, and gives a SampleList. A
property is a value, an uncertainty and a unit; .value is a number to
compute with. Any field the command line reads is read by its address too,
sample["curve.stress[10]"]:
"""One specimen and the collection, read as the command line reads them."""
import samplekit as sk
steel = sk.Sample("samples/steel-01.md")
print(steel.name, steel.material)
print(steel.area)
print(steel.area.value, steel.area.uncertainty, steel.area.unit)
print(steel.thickness.readings, steel.thickness.stats.mean)
print(steel["curve.stress[10]"])
print(steel.curve.values("strain")[:4])
specimens = sk.load("samples")
ductile = specimens.query("ductile").sorted("-elongation")
print([specimen.name for specimen in ductile])
print(specimens.stats("elongation").mean)
print(specimens.to_dict(columns=["name", "tensile_strength"]))
$ python scripts/read.py
steel-01 steel
25.056 ± 0.053 mm²
25.05586444444445 0.05217296159913354 mm²
[1.995, 2.004, 2.008] 2.0023333333333335
504.3130732135541
[0, 0.025, 0.05, 0.2]
['copper-01', 'steel-01']
26.666666666666668
{'name': ['aluminium-01', 'copper-01', 'steel-01'], 'tensile_strength_value': [318.0726127367075, 221.0919691412931, 517.8428398975834], 'tensile_strength_uncertainty': [None, None, None]}
filter,sortedandquerytake what-f,-sand--querytake, and give a new list.statsgives the statistics--summarygives: of a property's readings, or of a field over a list.to_dictgives each column as a list, as--csvnames it. A value missing isNone, and pandas reads the dict as it is,pd.DataFrame(…)(pandas is not installed with SampleKit:pip install pandasin the environment).to_csv,to_jsonandto_text("latex")write a table as the command line writes it, with the precision the project declares. A sample's own table has itsto_csvtoo,steel.curve.to_csv(), its rows asview curve --csvprints them.
In a notebook, dir(sample) and help(sample) list what an object offers; a
mistake raises a standard exception naming the nearest name: steel.aera is
an AttributeError that says area.
Changing, computing, saving¶
A sample changes as an object does: steel.width.readings = [12.49, 12.53, 12.52], steel.grade = "S355J2", steel.ductility = None to remove an
attribute. not_current() says what the change made out of date, compute()
runs the model's formulas, and save() writes the file. Nothing is written
before it:
import samplekit as sk
steel = sk.Sample("samples/steel-01.md")
steel.width.readings = [12.49, 12.53, 12.52]
print(steel.not_current())
steel.compute()
print(steel.area, steel.tensile_strength)
steel.save()
$ python scripts/remeasure.py
{'width': 'outdated', 'area': 'outdated', 'young_modulus': 'outdated', 'yield_strength': 'outdated', 'tensile_strength': 'outdated', 'curve.stress': 'outdated'}
25.056 ± 0.054 mm² 518 MPa
A write is safe as a command's is: it refuses a file someone changed since it
was read. The files a script saved are kept in the project's history as one
change when it ends, with the script beside them; sk.keep("message") keeps
what was saved so far as a change of its own, so that the history shows the
script's steps apart (the history).
sk.Sample.new("samples/steel-02.md") makes a sample where none is; set its
fields, then save().
steel.note = "…" replaces the note below the data, written by save().
steel.remove() deletes the file, which the history keeps: samplekit restore gives it back. steel.rename("steel-04") renames it, its own files
and the links of the project leading to it. An attribute that links to another sample,
reference: "[[aluminium-01]]" or "[the plate](../plates/P3.md)", is read as
text, and steel.linked("reference") reads the sample it names, the path of
a file that is no sample, a list of links a list
(link samples).
Figures and exports¶
sk.plot(samples, "curves", output="curves.pdf") draws a figure, declared or
the model's, as plot does; with x= and y= it draws one from two fields.
samples.export("paper") writes a declared export, a table or a figure, as
samplekit export paper --write does. Unlike --write, neither replaces a
file that exists: each raises FileExistsError, and overwrite=True
replaces it. Both are recorded in the history, so that explain finds the
file again.
A script of the model¶
A function you run yourself is a script of your own. A method of the model
marked @sk.script is a script of the project: samplekit run runs it on the
samples selected, previews what it changes, and the TUI offers it (run a
script of the model).
See also¶
The Python API, every class and method.
Values and uncertainty:
Nonefor a value nobody entered,sk.NAfor one that does not apply.