Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
SampleKit 1.0.0-rc.3
Light Logo Dark Logo
SampleKit 1.0.0-rc.3

An older version. The latest

  • Guides
    • Install SampleKit
    • Start a project
    • Bring existing data in
    • Write a model
    • Start from templates
    • Edit samples
    • Find and select samples
    • Link samples
    • Work in the terminal interface
    • Choose the colours
    • Work from Python
    • Run a script of the model
    • Tables and figures for a paper
    • Several projects
    • Organise a project's settings
    • Share a project
    • Check a project in continuous integration
    • When something goes wrong
    • Upgrade from an older SampleKit
  • Concepts
    • Samples and their files
    • Values, uncertainty and units
    • Readings and statistics
    • Models and formulas
    • Current and outdated values
    • History
    • Projects
  • Reference
    • The command line
    • The Python API
    • The TUI's keys
    • Configuration
    • Filters
    • Sample files
    • Written files
    • Fingerprints
    • Exit codes
    • Glossary
  • Changelog
Back to top
View this page

Link samples¶

This guide is for a sample that names another: a specimen compared with a reference one, a piece cut from a plate, the file its machine wrote, the standard it was tested to. A link is an attribute, so it is written, read, filtered and exported as one; SampleKit also shows where it leads, follows it from either side, checks it, and keeps it when a sample is renamed.

The commands run in the fourth step of the home page's tensile example, 04-results, where the aluminium and copper specimens name the steel one they are compared with:

compared_with: "[[steel-01]]"

The demo's sixth step, 06-links, holds a link in every form, and one that leads nowhere (links).

1. Write a link¶

A link leads to one of three places (every form):

Written

Leads to

"[[steel-01]]", "[[steel-01|the steel]]"

a sample of the project: the one whose file is steel-01.md, or else the one whose name is steel-01

"[[curve.csv]]", "[[method.pdf#page=12]]"

a file of the project, by its name and its extension; a PDF at a page

"[the curve](../machine/steel-01/curve.csv)"

a file, a sample of another project among them, by its path from the sample's own folder

"https://…", "[ISO 6892-1](https://…)", "zotero://…"

a web page, or a reference in another tool

These are the forms Obsidian and Markdown write, so a project opened in either reads its links the same way. The quotes are needed in the file: unquoted, [[steel-01]] reads as a list, and the file is refused at that line, with the quoted form to write.

set writes them quoted. Here the steel specimen gets the file its testing machine wrote, beside the samples' folder, and the standard it was tested to:

$ samplekit samples/steel-01.md set 'raw=[the curve](../machine/steel-01/curve.csv)' 'standard=https://www.iso.org/standard/78322.html' --write
samples/steel-01.md · 2 changes

  raw        —  →  [the curve](../machine/steel-01/curve.csv)
             new
  standard   —  →  https://www.iso.org/standard/78322.html
             new

  nothing becomes not current

written: samples/steel-01.md

After [[, Tab offers the project's samples by their file's name, on the command line as in the terminal interface. Several links typed one after another, set 'parents=[[aluminium-01]],[[copper-01]]', write a list of two.

2. See where it leads¶

In a terminal, a link is shown as Markdown shows one: its text alone, steel-01 for [[steel-01]] and the curve for the machine's file, underlined in the link colour (colours). Nothing marks a link to a sample or a file; a web page is marked ↗, and a link that leads nowhere ✗, in the error colour. So in a table, in view and in the terminal interface.

What is written to a file or a pipe keeps the text as written, so that the program reading it finds the link whole. A table written as a document, Markdown, HTML or LaTeX, holds it as text too, not as a link of that format:

$ samplekit -c name,compared_with --csv
name,compared_with
aluminium-01,[[steel-01]]
copper-01,[[steel-01]]
steel-01,

In the terminal interface, Enter or o on a link goes where it leads: a sample opens on its screen, even one the filter leaves out or one of another project, Esc coming back; a file opens in its application, a web page in the browser. On a list of links, Enter lists them, and Enter or o follows the one under the cursor.

3. The samples linking to one¶

A sample's screen in the terminal interface ends with the samples whose links lead to it, linked from, each followed by Enter. On the command line, the filter links to NAME selects them, FIELD links to NAME for one attribute:

$ samplekit -f 'links to steel-01'
samples/aluminium-01.md
samples/copper-01.md

The filter reads the links as they are written, [[steel-01]] or […](steel-01.md): a link written with a sample's name rather than its file's, [[Steel A]], is found by links to "Steel A", and a name no link writes selects nothing. Linked from, in the terminal interface, finds every link leading to the sample, however it names it.

4. A link that leads nowhere¶

A sample renamed by hand or removed, a name mistyped: validate reports a link that leads to no sample, or to several, and a path where nothing is, and exits with code 2. A web page is not checked. remove lists, before it removes a sample, the links leading to it, and leaves them as written: validate finds them after. Here the aluminium specimen's link was set to [[steel-1]]:

$ samplekit samples validate
  aluminium-01           compared_with: [[steel-1]] leads to no sample — no file of the project is named steel-1, and no sample's name is

3 samples · 1 defect · 0 notes
error: 1 defect in 1 file

5. Rename a sample, and its links with it¶

samplekit samples/steel-01.md rename steel-02 renames the steel specimen and writes again the two links leading to it, compared_with: "[[steel-02]]" in the aluminium and copper files; a Markdown link, [text](steel-01.md), is written again the same way. Its own files, a folder named after it, and its name where it was the file's name, are renamed with it, and a link to one of those files, [the curve](../machine/steel-01/curve.csv), is written to follow it. It is previewed first, and --write makes it (rename a sample); in the terminal interface, R on a sample.

6. From Python¶

linked reads where a link leads: the sample, for a link to a sample; a pathlib.Path, for a file that is no sample; a list, for a list of links. A web address is no place to read, and raises ValueError; the attribute holds it as text. filter takes links to NAME as -f does, and rename renames a sample and the links leading to it (work from Python):

scripts/links.py¶
"""The links of the guide to linking samples, from Python."""

import samplekit as sk

copper = sk.load("samples/copper-01.md")
steel = copper.linked("compared_with")
print(steel.name, steel.tensile_strength)
specimens = sk.load("samples")
print([specimen.name for specimen in specimens.filter("links to steel-01")])
$ python scripts/links.py
steel-01 518 MPa
['aluminium-01', 'copper-01']

7. In Obsidian¶

A project opened in Obsidian as a vault finds the same links: Obsidian reads a Markdown link's path from the note's own folder, as SampleKit does, and opens a file outside the vault in its application. Among a note's properties, Obsidian makes only [[…]] clickable; a Markdown link stays text there, and SampleKit still follows it.

See also¶

  • Links in a sample file, every form.

  • The filter links to.

  • Work in the terminal interface.

Next
Work in the terminal interface
Previous
Find and select samples
Copyright © 2026, zelyph
Made with Sphinx and @pradyunsg's Furo
On this page
  • Link samples
    • 1. Write a link
    • 2. See where it leads
    • 3. The samples linking to one
    • 4. A link that leads nowhere
    • 5. Rename a sample, and its links with it
    • 6. From Python
    • 7. In Obsidian
    • See also