sits lens

How we make figures you can check

sits lens shares what we know about time series analysis, with figures built from real runs. This is the method behind them: how a figure is made, how you can check it, and how to use the same method for your own project.

1From a source to the page

Every figure on sits lens follows the same path, from a pipeline to a figure. It starts from an example in a trusted source, runs through one pipeline, and reaches the page as a small data file that keeps a record of how it was made.

  1. A sourceAn example from the sits book or a paper
  2. The pipelineR code that runs the example, one step at a time
  3. Data files191 small files, each with a record
  4. The pagesJourneys, interactive images and tools

2Start from a trusted source

The sits book is our first source: each sits journey follows one of its examples. The same path works for other packages: some journeys are built with stars. When a page says what a package does, we have read its code or run it, never written it from memory.

3Let the pipeline make every number

One pipeline, written in R, runs each example and writes everything the figures need. No number, date or picture is typed by hand: the text takes each value from the pipeline's files.

4Keep a record of every file

Each file comes with a record: where its data came from, which steps made it, and which versions of sits and R ran. Under every figure, "How this figure was made" opens it.

classes.json

Data from
e-sensing/samples_cerrado/labelled_samples_cerrado.parquet
Made by
Read the labelled samples → Write the files
Ran with
sits 2.0.0 and R 4.6.0
A rerun gives
the same file, byte for byte

5Be honest about reruns

The pipeline marks 190 of its 191 files as giving the same bytes when it runs again. One file is marked as recorded: a run cannot repeat such a file, so its own result is kept as the reference.

  • The same file190
  • The same values, within a tolerance0
  • Kept as a record1

6Check before publishing

Before each change, tests check the pipeline's code, read each file against its record, and open every page in a browser. Each figure is also looked at by eye, on a phone and a wide screen, in light and dark.

7Rebuild it yourself

The code and the data files are open. The site builds from them without R. Running the pipeline again also needs R and an internet connection, since it downloads its data. Some of its inputs are our own saved copies, so a run from a fresh copy may not give the same files.

# Get the code and the data files
git clone --branch rebuild https://github.com/sitstools/sitslens && cd sitslens
# Build the site, with no R
(cd web && pnpm install && pnpm exec playwright install chromium && pnpm build)
# Install the R packages, sits included
(cd pipeline && Rscript -e "renv::restore()")
# Run the pipeline again
cd pipeline && Rscript make.R

8Start your own

Everything here is open, so you can reproduce, adapt and extend the material. The method fits any package or subject: copy this prompt into your AI assistant, which asks about your project, then plans a site like this one.

Starter prompt
Read the prompt

I want to build a website that explains a software package or a subject with figures readers can check. Every number, picture and graph on it must come from a pipeline run, never typed by hand. Before you plan anything, interview me, one question at a time, about: the package or subject; its reference text (a book, a manual, a paper); the data its examples use and where that data lives; who will read the site; and what I already have.

Then write a plan for the site that follows these steps:

  1. A source of truth: the reference text and the pinned source code of the package. Never state what a function does from memory; read its source or run it, and say which.
  2. Named data: record every input (dataset and file, catalogue query, settings), and do not host raw data the source can give again.
  3. One pipeline with an explicit graph of steps, each with a plain description beside its code, and every package pinned to an exact version.
  4. Small files for the site, each checked against a schema, each with a record: the step that wrote it, its size and hash, its sources, its graph and the versions it ran with.
  5. Honest reproducibility: for each file, say whether a rerun gives the same bytes, the same values within a tolerance, or another file kept as a record.
  6. Text and figures that take every number from those files by name, a figure gaining one new thing at a time as the text names it.
  7. Checks before every change: lint and tests of the pipeline, a check that its graph is valid and up to date, tests of the site, each file read against its schema and hash, and each figure looked at on a phone and a wide screen, in light and dark.

Suggest tools for each step that fit my language and package, and say why. Keep the plan short: the steps, the first figure to build end to end, and what to leave for later.