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

  • label titles the column in a terminal and in a document; header names 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] and E_uncertainty [GPa], the suffixes and the unit saying what each holds.

  • precision sets the digits of the column, over the property's own. A file is written at the precision declared, as a table shows it; .17g writes every digit a number carries. Two, [".1f", ".2g"], give the uncertainty digits of its own: an uncertainty is rounded up, never understated, so at .1f one of 0.012 would be written 0.1, eight times its size.

  • template writes 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:

scripts/paper.py
"""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