cuvette Install

For lab scientists

What is in a session

A Cuvette session is a conversation about your data. Cuvette saves the work of each session in a folder next to your data. This page shows how a session runs and what the folder holds.

1 How a session runs

A session has four stages. Cuvette stops at each stage until you decide.

  1. Questions about meaning. The agent first looks at your files. It does not change them. Then it asks short questions, one at a time. Examples are what counts as one sample, what counts as positive and which groups to compare. It asks only about what it finds in the data. A recommended answer is selected for each question.
  2. Proposed metrics. The agent writes what it will measure and how. Each setting has a value. You can change any line.
  3. Demonstration on a sample. The agent runs the method on one sample. You see the numbers and a quality control (QC) image. You approve the result, ask for a change or choose another sample. A step that processes many files waits for your approval of the demonstration.
  4. Confirm and run all. You confirm the method. The agent runs it on all samples. The session record shows this stage as “Confirmed”.

To change an answer later, type /change. Results that used the old value become out of date. See section 6.

You can give Cuvette a reference file, for example hand counts. Cuvette then compares its numbers with the reference after the batch. It draws a Bland-Altman plot: a plot of the difference between two measurements against their mean.

2 The session folder

Cuvette makes the folder cuvette/<date>-<title>/ in the data folder. The data folder is the folder where you start Cuvette. The date is the local date of the session. The title comes from the first line of your first message. Cuvette makes it lowercase and cuts it to 40 characters.

Cuvette names the folder when you send the first message. Before that, the folder is .new-<session id>. To use another place, start Cuvette with --output <folder>, or set output_folder. If Cuvette cannot write to the folder, it saves the session in ~/.cuvette/projects/ and tells you.

my-data/
  cuvette/
    2026-10-09-count-nuclei/
      README.txt
      index.html
      results.xlsx
      figures/
      samples.csv
      references.bib
      environment.lock.json
      requirements.txt
      renv.lock
      databook.html, databook.pdf
      images.pptx, images.pdf
      .record/
        log.jsonl

This is an example. Some files exist only after you ask for them, or only if the analysis needs them.

results.xlsx
The numbers. Cuvette writes it after each turn that makes a new step. It has these sheets: Summary, one sheet for each result table, Steps, Metrics, Files, Changes, Packages and References. Steps lists each step with its manual route: the way to repeat the step by hand in the program. The sheets Pilot, Validation, Data check and Samples appear when they have content.
figures/
Each figure of a step. The file name is step<number>-<name>. Cuvette saves a figure as a PNG (Portable Network Graphics) image of at least 300 dots per inch (dpi). A matplotlib figure also gets an SVG (Scalable Vector Graphics) copy. A figure from another program is copied as it is.
index.html
The analysis trail: a web page with each step of the session. Cuvette writes it again after each turn.
The data book
databook.html and databook.pdf. See section 3.
The image decks
images.pptx and images.pdf. See section 4.
.record/log.jsonl
The session record. See section 7.
references.bib
The citations of the programs and methods that ran. See section 5.
environment.lock.json, requirements.txt, renv.lock
The program and package versions of the session. See section 6.
samples.csv
The sample sheet: each sample with its group, its unit of replication and its batch. Cuvette writes it when the agent first reads a table or a folder. You can edit it with /samples, or in the app.
README.txt
A short note. It says what the folder is, how to continue the session and how to read the results without Cuvette.

You can also export the trail in other forms with /export: html, md, pdf, protocol, script, notebook, flow, eln and jsonl. The eln file is an archive in the open format for electronic lab notebooks, for example eLabFTW.

3 The data book

The data book is one document for a session. Type /databook in a session, or cuvette databook in the terminal. In the app, click “Write the data book” in the Results tab. /databook project puts all sessions of the data folder in one book.

The data book has these parts, in this order:

  1. The question and the confirmed analysis.
  2. The data.
  3. The data check and the sample sheet.
  4. The methods. This part is one paragraph that cites each program and method in the text. It also has tables of settings, definitions and exclusions.
  5. The demonstration and the reference check.
  6. The results and the final answer.
  7. The checks: review findings, deviations, steps that are out of date, and the numbers that changed on a rerun.
  8. The manual route of each step.
  9. The references.
  10. An appendix with the steps, the software versions and the record files.

Cuvette always writes the HTML file. It writes the PDF if Chrome or Chromium is on the computer. /databook docx makes a Word file, and it needs pandoc, a free document converter.

Methods text. Cuvette has no separate methods file. The methods text is in the data book. It is also in the draft methods paragraph of the protocol (/export protocol) and on the last page of an image deck.

4 The image decks

An image deck puts the figures and QC images of a session into slides. Type /export images, or click “Make an image deck” in the Results tab. You can choose a PowerPoint file (PPTX), a PDF or both. You can also choose which images to use, their order, the number of images on a page (1, 2, 4, 6 or 9) and the page size.

5 Citations

Type /cite to see what to cite for the session. The list holds the programs and methods that ran. A program that Cuvette loaded but did not run is not in the list. Cuvette itself is always in the list.

The data book, the trail report, the protocol and the References sheet of results.xlsx carry the same list. In the app, the Results tab has a Cite section with buttons to save the list.

6 Files that repeat the analysis

Cuvette records the environment of each step. An environment is the set of program and package versions that ran the step.

environment.lock.json
Each environment with its name, its kind, its packages with versions and the steps that used it.
requirements.txt
The Python packages, one name==version line for each. Cuvette writes it only if the session used Python. With several environments, the files are requirements-<name>.txt.
renv.lock
The R packages with their versions. Cuvette writes it only if the session used R. It is a list of names and versions.

For each step, the record also holds the SHA-256 checksum of each input file, the version of the adapter and of the program, and the decisions that the step used.

A step is out of date if one of these changes: a decision, an input file, the adapter, the program or the packages. A step is also out of date if an earlier step that it uses is out of date. Type /status to see each step and the reason. Type /rerun to run the out-of-date steps again. A table then shows each number that changed.

7 The session record

The session record is .record/log.jsonl. It is a text file with one JSON (JavaScript Object Notation) object on each line. Cuvette only adds lines to it. A line holds one event: a message, a decision, a step or a result. The record names the stages: Questions, Proposed metrics, Demonstration on a sample and Confirmed.

The record shows file paths inside your data folder as {project}/…. You can read the file in any text editor.

8 How to reopen a session

These commands work inside a session:

The changelog lists when each of these functions was added.