Tables and figures for a paper¶
This guide is for the tables and figures of a paper or a report: with the labels and digits the paper wants, written by a command you run again at each draft, and made again as they were when a reviewer asks, months later.
The commands run in the last step of the home page's tensile
example, which shows the same steps more briefly: tables written to
files and figures.
A table written once, for a spreadsheet or a script, needs no more than -o
(write the table to a file).
1. The table, as a profile¶
A profile says which columns, with which titles and digits, in which order, and in which groups. The tensile example's:
[profile.overview]
columns = [
{field = "name"},
{field = "material"},
{field = "young_modulus", label = "E", precision = ".1f"},
{field = "yield_strength", label = "Rp0.2"},
{field = "tensile_strength", label = "Rm"},
{field = "elongation", label = "A"},
]
sort = ["material", "name"]
Each column takes these keys, besides its field (every
key):
labeltitles the column in a terminal and in a document;headernames it in a CSV or JSON file, where a short name suits the program that reads it. A property is two columns in a CSV,E_value [GPa]andE_uncertainty [GPa], the suffixes and the unit saying what each holds.precisionsets the digits of the column, over the property's own. A file is written at the precision declared, as a table shows it;.17gwrites every digit a number carries. Two,[".1f", ".2g"], give the uncertainty digits of its own: an uncertainty is rounded up, never understated, so at.1fone of 0.012 would be written0.1, eight times its size.templatewrites the cell as text,'\num{{value:.1f}}': a CSV holds that text, for a LaTeX package that reads CSV, and JSON keeps the numbers.
group = ["material"] gives a table per material in a terminal; in a file it
stays one table, each group's rows together.
Look at it before writing anything, with --status, which adds a state
column: a table for a paper should hold only current values.
$ samplekit --profile overview --status --csv
note: yield_strength_uncertainty is left out: it is empty for every sample
note: tensile_strength_uncertainty is left out: it is empty for every sample
note: elongation_uncertainty is left out: it is empty for every sample
name,material,young_modulus_value [GPa],young_modulus_uncertainty [GPa],yield_strength_value [MPa],tensile_strength_value [MPa],elongation_value [%],state
aluminium-01,aluminium,69.2,0.3,285,318,12.0,current
copper-01,copper,117.2,0.9,76,221,44.0,current
steel-01,steel,206.3,1.1,387,518,24.0,current
2. The table, as a document¶
A style writes the table as a document holds it: latex, a booktabs
table with its units in the headers, markdown and html are given. -o -
prints it, -o table.tex --write writes it, the extension naming the style:
$ samplekit --profile overview --style markdown -o -
| name | material | E (GPa) | Rp0.2 (MPa) | Rm (MPa) | A (%) |
| --- | --- | --- | --- | --- | --- |
| aluminium-01 | aluminium | 69.2 ± 0.3 | 285 | 318 | 12.0 |
| copper-01 | copper | 117.2 ± 0.9 | 76 | 221 | 44.0 |
| steel-01 | steel | 206.3 ± 1.1 | 387 | 518 | 24.0 |
To change how a style writes, declare it again under the same name, with only
what changes; the rest is kept (every key of a
style). A LaTeX table written with
siunitx, each value \SI{…}{…} with its unit in the cell:
[style.latex]
property = '\SI{{value}{uncertainty}}{{unit}}'
uncertainty = ' \pm {uncertainty}'
unitless = '\num{{value}{uncertainty}}'
header_unit = false
[unit."%"]
latex = '\percent'
A unit given no spelling in the style is written as its text, escaped:
\SI{24.0}{\%}. Where .samplekitrc already has a section, add the key to it
rather than write the section again: a section written twice makes the file
unreadable, duplicate key.
3. The figures¶
A figure for a paper is declared once, its axes, kind and group, and its look
is the project's: [matplotlib] for the font and the size, symbol_figure
for mathematics in the labels (one style for the whole
project). Sizes are in
centimetres: "figure.figsize" = [8.5, 6] fits one column of most journals.
A figure the model draws for one sample writes a file per sample where its
path holds {name}.
4. Written again by one command¶
An export names what a file holds and where it goes: a profile with a
style, or a figure. One command then writes it again at each draft, with no
-o to remember:
[export.paper]
profile = "overview"
style = "latex"
output = "paper/results.tex"
[export.curves]
figure = "curves"
output = "paper/curves.pdf"
$ samplekit list exports
paper paper/results.tex · profile overview
curves paper/curves.pdf · figure curves
$ samplekit export paper --write
export paper · paper/results.tex · 3 rows
written: paper/results.tex, 3 rows
$ samplekit export curves --write
export curves · figure curves · paper/curves.pdf · 3 samples
written: paper/curves.pdf
A data file, format = "csv", tsv or json, is exported the same way
(every key of an export). A table
shown with -c or --profile declares one from what it shows, --save export=NAME, previewed before it writes .samplekitrc (saved
shapes).
Written from values that are not current, outdated, edited, failed or
never computed, an export writes its file all the same, says which values, and
exits with code 2, so that a script writing the paper stops there; a table
written with -o and a figure do the same. Compute them, or name their states
after --accept, --accept outdated,failed, if the file is meant as it
stands: the words are outdated, edited (or edited:NAME,… for those
values alone), failed and never_computed. A failed value is written as its
last number, its state saying not to trust it. A data file gives each such column its states,
elongation_state (values out of date).
Where a sample could not be read, nothing is written: its rows would be
missing.
In the terminal interface, p offers the exports, previewed before y
writes them; its first line, what is shown, writes the screen's table once
to a file you name, and W declares what is shown as an export (work in the
terminal interface).
5. From Python¶
From Python, to_text writes a table in a style, as --style NAME -o -
does, its profile= naming the columns; export writes a declared export, a
table or a figure, and returns the path written; sk.plot(samples, "curves", output="curves.pdf") draws a figure that no export declares. Each is
recorded in the history, as the command's is. Unlike --write, export and
sk.plot never replace a file that exists: they raise FileExistsError, and
overwrite=True, export("paper", overwrite=True), replaces the file, as
the script below does, so that it runs again at each draft:
"""The paper's table and figure, from Python."""
import samplekit as sk
specimens = sk.load("samples")
print(specimens.to_text("markdown", profile="overview"))
# Written again at each draft: a file there already is replaced.
print(specimens.export("paper", overwrite=True).name)
print(specimens.export("curves", overwrite=True).name)
$ python scripts/paper.py
| name | material | E (GPa) | Rp0.2 (MPa) | Rm (MPa) | A (%) |
| --- | --- | --- | --- | --- | --- |
| aluminium-01 | aluminium | 69.2 ± 0.3 | 285 | 318 | 12.0 |
| copper-01 | copper | 117.2 ± 0.9 | 76 | 221 | 44.0 |
| steel-01 | steel | 206.3 ± 1.1 | 387 | 518 | 24.0 |
results.tex
curves.pdf
6. Made again as they were¶
Every export and figure written is recorded in the project's history.
explain finds a file again, even copied into the paper's folder, says
whether what it was made from has changed since, and gives the command that
makes it again exactly as it was:
$ samplekit paper/results.tex explain
paper/results.tex
made 2026-10-06 19:16, by samplekit export paper --write
written paper/results.tex
from snapshot #1, 3 samples
nothing it was made from has changed since: it is up to date
made again as it was, from the project's folder: samplekit export paper --write -o paper/results.tex --at 246d92a
--at reads the project as the history kept it then, its samples, its
configuration and its model, and writes where -o says; the project is not
changed. A table made again this way is the same file, byte for byte; a
figure is drawn from the same data and settings, and a newer matplotlib may
draw it slightly differently.
See also¶
Written files: the columns and cells of a data file.