Introduction

Dioptra is a desktop program for the part of science that happens between the instrument and the paper. You paste the numbers your plate reader, cytometer or notebook produced. You shape them: subtract a blank, convert units, normalise to a control. You test them. You draw the figure the journal will print. One file holds all of it.

It does the job GraphPad Prism does, and the job of the spreadsheet most people open before Prism. It runs on Linux, Windows and macOS, it is free, and the source is open under the MIT licence.

The name comes from the dioptra of Hero of Alexandria, a sighting instrument for measuring angles and levels. The aim is the same as a good instrument’s: read the quantity accurately, show the scale, and do not decorate.

What it is built on

Four ideas run through every chapter of this manual.

Raw data is never changed. An analysis reads your table; it never writes to it. A transform makes a new column or a new table and remembers how. Excluding an outlier strikes the value through; it does not delete it. Every cell can tell you where it came from: typed by hand, pasted at a certain time, imported from a file and column, or computed by a formula.

Every assumption is shown. A t test assumes something about your data. So does an ANOVA, a regression, a chi-square test. Dioptra checks what can be checked, shows the check above the result, and names the alternative when a check fails. The defaults follow current statistical practice (Welch’s t test rather than Student’s, two-sided tests, Tukey–Kramer for all pairs, Holm rather than plain Bonferroni) and the results sheet says which one ran.

The file is the record. A .dioptra file is a zip of readable JSON. It holds the data, each formula as text, each analysis as a specification, each graph as a specification, and the history of commands. Open it in a year and every number comes back the same way.

The figure on screen is the figure you export. The plot engine writes one SVG; the PDF and PNG are made from it, with the fonts bundled, so a figure rendered on Linux is byte-identical on a Mac. Sizes are in millimetres and points, because that is how journals specify them.

How this manual is organised

• Getting started takes you from download to an exported figure in about ten minutes.
• Data tables explains the eight table kinds and how to choose one.
• Entering and shaping data covers paste, missing and excluded values, provenance and transforms. Formulas is the formula reference.
• Analyses explains the guided flow, assumption checks and p-value styles, then documents each analysis.
• Graphs explains the editor, themes, palettes and export, then each graph family.
• File format, Correctness and Performance are the record: what is stored, how the numbers were verified, and how fast it runs.
• Architecture and internals is for people who want to change the code.
• The complaint map lists what scientists dislike about the Prism workflow and what Dioptra does about each item.

The statistics are explained where they are used, briefly, with a reason for each default. If a chapter tells you to do something, it should also tell you why.

Getting started

This chapter takes you from nothing to an exported figure: install, paste a small data set, describe it, test it, draw it, export it, save it. It takes about ten minutes.

Install

Every release is published on the releases page. Pick the file for your system. The names below are those of version 0.4.0; later versions change only the number.

Linux

The AppImage needs nothing installed:

curl -LO https://github.com/ZahakJ/dioptra/releases/latest/download/Dioptra_0.4.0_amd64.AppImage
chmod +x Dioptra_0.4.0_amd64.AppImage
./Dioptra_0.4.0_amd64.AppImage

If it refuses to start with a message about FUSE, your distribution does not ship libfuse2 by default (Ubuntu 22.04 and later). Install it (sudo apt install libfuse2), or use the .deb.

On Debian and Ubuntu:

curl -LO https://github.com/ZahakJ/dioptra/releases/latest/download/Dioptra_0.4.0_amd64.deb
sudo apt install ./Dioptra_0.4.0_amd64.deb

On Fedora and other rpm systems:

curl -LO https://github.com/ZahakJ/dioptra/releases/latest/download/Dioptra-0.4.0-1.x86_64.rpm
sudo dnf install ./Dioptra-0.4.0-1.x86_64.rpm

Windows

Download Dioptra_0.4.0_x64_en-US.msi and run it. Windows may show a SmartScreen notice because the installer is not signed with a paid certificate; choose More info, then Run anyway. Dioptra uses the WebView2 runtime that ships with Windows 10 and 11.

macOS

Download the .dmg for your processor (the Apple menu, About This Mac, says “Apple M…” for Apple silicon or “Intel” otherwise), open it and drag Dioptra into Applications. The app is ad-hoc signed but not notarized (there is no paid Apple certificate), so the first launch says “Apple could not verify Dioptra”. Control-click the app, choose Open, then Open again; on macOS 15 and later, open it once, then go to System Settings → Privacy & Security and click Open Anyway. Or run once in Terminal:

xattr -cr /Applications/Dioptra.app

macOS remembers the choice.

Paste your first data

Start Dioptra. You see an empty project: the project rail on the left (tables, analyses, graphs, layouts), the work area in the middle and the inspector on the right. The work area offers three ways in: paste data, open the bundled sample project (a cytokine study with a dose comparison, a dose-response fit and a survival curve, each with its analysis and figure), or open this manual.

Copy these three columns (from this page, a spreadsheet or a text file; tabs, commas and semicolons all work):

Control	Low dose	High dose
12.1	15.3	21.0
10.4	16.8	19.2
11.7	14.1	24.6
13.2	17.5	22.3
9.8	15.9	20.8
12.5	16.2	23.1

Choose File → Paste as new table (Ctrl-Shift-V; ⌘-Shift-V on a Mac). The dialog shows a preview, what it detected (separator, decimal mark, whether the first row is a header) and a suggested table kind with a small sketch of each kind. For three groups of replicate values the right kind is Column: each column is a group. Pick it, give the table a title such as “Plasma IL-6”, and press Create table.

Click any cell. The inspector says where it came from (“Pasted from the clipboard at …”). The status line at the bottom shows n, mean, SD and sum of the selection.

Describe it

Press Analyze (Ctrl-Shift-A). The list shows every analysis; those that do not fit a Column table are greyed with the reason. Choose Descriptive statistics and run it. The results sheet opens beside the table: one sentence per group in APA style, then the table of N, mean, SD, SEM, confidence interval, median and quartiles, then a short list headed Before you report this.

Test it

Press Analyze again and choose One-way ANOVA. The options panel holds the few choices that matter, each with one line on what it means: which groups, whether to use Welch’s ANOVA (which does not assume equal SDs), and which multiple comparisons to run (Tukey–Kramer for all pairs by default). Run it.

The sheet starts with the assumption checks: normality of residuals and equality of variances, each with its test result and what it means for this analysis. If one is in doubt it is open and amber, and it names the alternative (Welch’s ANOVA, or Kruskal–Wallis). Then the summary sentence, with the effect size and its confidence interval before the p value. Then the ANOVA table and the comparisons.

Change a number in the table. The sheet marks itself stale and recomputes when you look at it.

Draw it

On the results sheet press Make graph. Dioptra draws a column graph of the three groups with every data point shown, error bars, and a bracket for each comparison from the ANOVA, labelled in the project’s p-value style.

The graph is a live object. Click the Y axis title and the inspector shows its properties; type “IL-6 (pg/mL)”. Change the family to Box or Violin in the toolbar; the data and brackets follow. Choose a theme (Instrument, Night for slides, Journal for black-and-white print) and a palette.

Export it

Press Export (Ctrl-Alt-E). Choose PDF, SVG or PNG; set the size in millimetres or inches (85 × 70 mm is a single journal column); for PNG choose the resolution. The dialog states exactly what will be written, for example “1004 × 827 pixels at 300 dpi, 85 × 70 mm”. PDF embeds the fonts; SVG keeps text as text.

Save it

File → Save (Ctrl-S) writes a .dioptra file: the table, the formulas, both analyses, the graph and the history of what you did. Close Dioptra and open the file again; every result is recomputed from the data and comes out the same.

That is the whole loop. The rest of the manual explains each step in depth.

Data tables

A table in Dioptra is not a blank sheet. It has a kind, and the kind says what the rows and columns mean. That meaning is what lets Dioptra offer the right analyses and draw the right graph without asking you to explain your experiment twice.

Why not one flat sheet for everything? Because the same six numbers mean different things in different experiments. Six values in two columns might be two independent groups of three (an unpaired comparison) or three subjects measured twice (a paired one). The numbers cannot tell you which; the layout can. Prism made this choice, and it is the part of Prism people value most once they have learned it (the guided analysis, K1 in the complaint map). It is also the part they find hardest to learn (P9). Dioptra keeps the idea and tries to make the choice easier: each kind is explained in one sentence with a sketch when you create or paste a table, the paste dialog suggests a kind from the data, and when in doubt the Multiple variables kind is a safe default that can be reshaped into any other.

Shared vocabulary

• A data set is a named group of columns: one group in a Column table, one Y series in an XY table, one variable in a Multiple variables table. Data sets are lettered A, B, C, as in formulas.
• A data set has a subcolumn format. With replicate values each subcolumn holds one replicate (values(3) is three replicates side by side). With a summary format you type statistics computed elsewhere: mean, SD and N; mean, SEM and N; mean and a 95% confidence interval with N; mean and SD; mean and SEM; median and quartiles; lower and upper limits; or a single value. Summary formats exist because published papers and instrument software often give you only the summary, and with N present most analyses can still be computed exactly.
• Row titles label rows: subjects, samples, levels of a factor.
• An empty cell is missing, never zero. Zero is a number.

The eight kinds

Column

Groups side by side, one column each.

Use it for one factor: treatments, genotypes, time points measured in separate subjects. Rows mean nothing unless the design is paired or repeated, in which case each row is one subject and you choose a paired analysis.

Analyses: descriptive statistics, t tests (one-sample, unpaired Welch or Student, paired, ratio paired), Mann–Whitney, Wilcoxon, one-way ANOVA (with Welch and Brown–Forsythe variants), repeated-measures one-way ANOVA, Kruskal–Wallis, Friedman, normality tests, outliers, correlation, ROC curves, Bland–Altman. Default graph: column (bar) with every point shown. Prism: Column table.

XY

An X column and one or more Y data sets.

Use it whenever each value has an X coordinate that is a number: dose–response, time courses, standard curves, calibration. Each Y data set can have replicate subcolumns or a summary format (mean, SD, N).

Analyses: simple linear regression (with confidence and prediction bands and residual diagnostics), nonlinear regression (the curve-fitting library: 4PL and 5PL, exponential decay and association, Michaelis–Menten, binding, Gaussian, polynomials, custom equations), correlation, descriptive statistics, normality, outliers. Default graph: scatter. Prism: XY table.

Grouped

Rows are levels of one factor, data sets are levels of another, subcolumns are replicates.

Use it for two factors at once: genotype by sex, treatment by time. The question it answers is whether each factor matters and whether they interact.

Analyses: two-way ANOVA (type III sums of squares by default, with type I and II available; repeated measures on rows or columns), descriptive statistics, normality, outliers. Default graph: grouped column. Prism: Grouped table.

Contingency

Counts of subjects in each combination of two categories.

Use it when each subject falls into one row category and one column category and you counted them. The cells hold counts, not percentages and not measurements.

Analyses: chi-square (with Yates’ correction for 2 × 2 as an option), Fisher’s exact test (2 × 2 and larger, by the network algorithm), with relative risk and odds ratio and their confidence intervals. Dioptra does not rewrite what you paste: a value such as 1.5 is kept, and the analysis tells you that it expected whole counts (Prism silently turns “1.23” into “123”, P7). Default graph: column. Prism: Contingency table.

Survival

Time in X; for each group, 1 for an event and 0 for a censored observation.

Use it for time-to-event data: one row per subject, the time in X, and in that subject’s group column a 1 if the event happened at that time or a 0 if follow-up ended without it.

Analyses: Kaplan–Meier curves with Greenwood confidence intervals, median survival, log-rank and Gehan–Breslow–Wilcoxon comparisons, hazard ratios. Default graph: Kaplan–Meier with an at-risk table. Prism: Survival table.

Parts of whole

One data set of categories that add up to a whole.

Use it for fractions of a total: cell types in a population, reads per category.

Analyses: chi-square goodness of fit against equal proportions. Default graph: column (pie and donut are available, reluctantly: lengths are easier to compare than angles). Prism: Parts of whole table.

Multiple variables

One column per variable, one row per case, like a data frame.

Use it for anything shaped like a spreadsheet of observations, and whenever you are not sure. Each variable has a declared type: number, category (text labels such as “control”), text (identifiers and notes, never analysed) or date. When you paste, the type is inferred: all numbers become a number; ISO dates (2026-10-11) a date; text with at most twelve distinct values a category; anything else text. Text stays text: a gene called MARCH1 or SEPT2 is never turned into a date.

Analyses: descriptive statistics, t tests, Mann–Whitney and Wilcoxon between numeric variables, correlation (Pearson, Spearman, Kendall), principal component analysis, ROC, Bland–Altman, normality, outliers. To compare groups named in a category column, pivot long to wide: one data set per group (see Entering and shaping data). Default graph: column. Prism: Multiple variables table.

Nested

Groups as data sets, subgroups (such as animals) as subcolumns, observations stacked within each.

Use it when you measured several things (cells, fields, wells) within each experimental unit (animal, culture, patient). This is the table kind that protects you from the most common error in cell biology: treating 300 cells from three mice as 300 independent observations. The experimental unit here is the mouse, so n = 2 per group, not 6.

Analyses: descriptive statistics per subcolumn, normality, outliers, and t tests and one-way ANOVA on the subgroup means, which the results sheet says it did. Mixed-effects models are planned (see the roadmap). Default graph: SuperPlot: every observation small and pale, each unit’s mean large, coloured by unit. Prism: Nested table.

Choosing quickly

Ask three questions.

1. Do the values have a numeric X? Yes: XY (or Survival if X is time to an event).
2. Are they counts of subjects in categories? Yes: Contingency (two classifications) or Parts of whole (one).
3. How many grouping factors? One: Column. Two: Grouped. One, with several measurements inside each unit: Nested.

If none of these fits, or the data arrive in long format from another program, use Multiple variables and reshape later. Changing your mind costs nothing: transforms produce new tables and leave the original as it was.

Entering and shaping data

Most errors in a published figure happen before any statistics: a column pasted one row off, a gene name turned into a date, a value rounded by a spreadsheet’s display format, a baseline subtracted by hand in one column and forgotten in the next. This chapter is about how Dioptra takes data in and changes it, and how it keeps a record of both.

Typing

Select a cell and type. A number is stored as a number. Anything else (<LOD, n.d., see notes) is stored as text, shown in the cell, and never used in arithmetic. It is not converted to zero and it is not thrown away. A text cell in a numeric column is something you should see, so Dioptra shows it.

Start with = and you type a formula; see Formulas.

The grid behaves like a spreadsheet: arrows, Tab and Enter move; Shift extends the selection; F2 or Enter edits; Delete clears; Ctrl-D fills down; Ctrl-Z undoes. The full list is in Keyboard shortcuts.

Pasting

Paste (Ctrl-V into a table, or File → Paste as new table, Ctrl-Shift-V) accepts any delimited text: a block copied from Excel, LibreOffice or Google Sheets, a plate reader’s export, a CSV file opened in a text editor. Dioptra decides three things and tells you what it decided.

The separator. A tab anywhere means tab-separated (this is what spreadsheets put on the clipboard). Otherwise a semicolon or a comma that appears the same number of times on every line wins, semicolon first; then columns of whitespace-separated numbers; then commas.

The decimal mark. Much of the world writes one and a half as 1,5. With tab or semicolon separators, Dioptra counts the fields that look like 1,5 and those that look like 1.5; if comma decimals are the majority, commas are decimal marks, and the paste report says so: “Commas were read as decimal marks (24 values looked like 1,5).” With comma separators the decimal mark is always the point, because a comma cannot be both.

Some values are ambiguous: 1,234 is one thousand two hundred thirty-four in Boston and one point two three four in Berlin. Dioptra does not guess. It keeps such values as text, counts them in the report, and asks you to choose the decimal mark in the dialog.

The header. If the first row is text over columns of numbers, it is read as a header and becomes the data set names.

Missing-value codes are recognised and stored as empty: an empty field, -, ., NA, N/A, NaN, #N/A, null. Everything else that is not a number stays as text.

What Dioptra never does on paste: turn SEPT2 into 2 September, read (1.5) as a positive number, drop a minus sign, or take the rounded value a spreadsheet was displaying instead of the one it stored. When you paste from a spreadsheet, check that the spreadsheet shows enough decimals: the clipboard carries what is displayed. Importing the .xlsx file directly avoids this and reads the stored values.

Importing files

File → Import (Ctrl-I) reads:

• CSV, TSV and plain text, with the same detection as paste;
• Excel workbooks (.xlsx, .xls) and OpenDocument spreadsheets (.ods), by a reader built into Dioptra, so it works the same on every system and needs no Office installation. Cell values are read as stored, at full precision, not as displayed. Date cells become ISO dates (2026-10-11) and the import notes say how many;
• Prism .pzfx files and Prism 10 .prism files: the data tables come across, with their titles, kinds (nested and multiple-variables included), column names, subcolumn titles, row titles and excluded values. Summary formats Dioptra lacks are converted and the import notes say how: mean, %CV, N becomes mean, SD, N; mean with +/− error or with upper and lower limits becomes a “(mean)” data set plus a lower, upper data set. Date X values keep Prism’s elapsed time as X and the dates as row titles. An X error subcolumn is not imported (Dioptra tables have no X error). Prism’s analyses and graphs are not converted; run the analyses again in Dioptra, which takes a minute and gives you assumption checks you did not have before.

Each imported column remembers the file, sheet and column it came from.

Plate readers

Exports of four plate-reader programs are recognised by their content and read as plates:

Without a plate map, an endpoint file becomes a grouped table: rows A, B, … down, one data set per read with the plate columns 1, 2, … as subcolumns. A kinetic file becomes an XY table with time in seconds as X and one data set per well.

After choosing a plate file, Import asks for an optional plate map: paste a grid as copied from a spreadsheet (row letters and column numbers optional), or one well, label line per well. A label is a group (Control), a dose (10), or both (Drug A @ 10); in the list form the dose may be a third column. Empty cells leave a well out.

	1	2	3
A	Blank	Drug A @ 0.1	Drug A @ 1
B	Blank	Drug A @ 0.1	Drug A @ 1

With groups only, the plate becomes a column table, one data set per group. With doses, it becomes an XY table: X is the dose, one data set per group, and wells with the same group and dose are replicates. Kinetic reads keep time as X, with one data set per group.

Not read: spectrum and well-scan reads, SoftMax Pro group (calculation) blocks, Gen5 calculated results in kinetic files and MARS table-view exports. The import notes list what was left out and any well values that were not numbers (OVRFLW, >4.000).

Replacing a table’s data

File → Replace table data… reads a file into the open table instead of a new one. The table keeps its name, data set names and column formulas; its analyses, graphs and layouts recompute. Data columns are filled left to right, skipping formula columns. A file with more columns adds data sets; a file with fewer clears the columns it does not reach. The file must give the same kind of table. One undo restores the old data.

This re-runs a project on new data by hand. Batch analysis does it for many files at once.

Missing values

An empty cell is missing. It is not zero, and zero is not missing. Analyses say how they handle missing values: most use every available value in each group; paired and repeated-measures analyses drop a subject (row) with any missing value and say how many were dropped. Formulas propagate missing (A + 1 is missing where A is) while summaries skip it (mean(A) is the mean of the values present).

Excluded values

Sometimes a value is real but should not be analysed: a well that dried out, a failed injection. Select it and press Ctrl-E (Edit → Exclude or include). The value stays in the table, struck through, and every analysis, formula and graph treats it as missing. Press Ctrl-E again to bring it back.

Why not delete it? Because the record matters. A deleted value is invisible to a reviewer, to your colleague, and to you in six months. An excluded value is still there, and the results sheet counts how many excluded values it left out. If you exclude, write down why; outlier tests (Grubbs, ROUT) can tell you which values are unusual, but whether to exclude one is a decision about the experiment, not about the numbers.

Provenance: where every cell came from

Click a cell. The inspector’s Cell panel says where its value came from:

• Typed by hand;
• Pasted from the clipboard at a time;
• Imported from a file, sheet and column;
• Computed by a formula, which it shows;
• Derived from another table by a transform.

If you edited a pasted or imported value by hand, the edit is recorded on top of the source, with the old value and the time. This is the provenance chain, and it is saved in the file. It answers the question every reviewer eventually asks: where did this number come from?

Transforms: new tables from old

Some operations change the shape of the data, not just its values. Dioptra does these as derived tables: you choose a transform from the Data menu, and a new table appears that remembers its source and the recipe. Change the source and the derived table follows. The original is never modified.

For per-row arithmetic (log transforms, unit conversions, ratios) use a column formula instead: it is shorter, and it shows its recipe in the formula bar.

Exporting tables

File → Export table (Ctrl-Shift-E) writes CSV, TSV or an Excel workbook, at full precision. That is how you hand data to a colleague who uses something else; you never need it to move data between steps in Dioptra.

Formulas

A formula computes numbers from other numbers in the same table. You type it after an =, either for a whole column (the formula bar above a column header) or for a single cell.

Two places a formula can live

A column formula fills every row of a column. = log10(A) in column B means “for each row, B is the base-10 log of A in that row”. One formula, a million rows, no dragging.

A cell formula fills one cell, the way a spreadsheet does. Type =A3 * 2 into cell B3. Fill-down (Ctrl-D) copies it to the rows below and moves the row numbers along: B4 gets =A4 * 2. A column holds either a column formula or cell formulas, not both.

Computed cells show a small corner mark. Change the data and every formula that depends on it is recomputed the next time you look. A formula that would depend on itself, directly or through other columns, is refused when you type it, with the loop spelled out: Circular reference: C → D → C.

Naming columns

The letter X always means the X column, so the twenty-fourth data set is reached by its name in backticks.

Values

A formula works with numbers, text ("mg/dL"), true/false, and missing. An empty cell is missing. An excluded cell is missing too: it stays in the table, struck through, but no formula or analysis uses it. NA (or na()) writes missing on purpose.

Missing spreads: A + 1 is missing wherever A is missing. Summaries such as mean skip missing values instead, because that is almost always what you want from “the mean of A”.

A problem in one row does not stop the column. sqrt(A) on a row where A is −4 shows an error in that cell (hover to read “sqrt: negative number”) and computes every other row. Text in a numeric column (“<LOD”) is kept and shown; arithmetic on it gives an error in that row, never a silent zero.

Arithmetic and logic

From tightest to loosest binding:

True counts as 1 and false as 0 when stored in a column, which is how you make an event code: = if(A > 30, 1, 0). Logic with a missing value follows common sense: false && NA is false, true || NA is true, true && NA is missing.

A single number combines with a whole column row by row: A * 2, A - mean(A). Two columns combine row by row. A list of a different length than the table cannot combine with a column; that is an error, not a guess.

Row-by-row functions

Summaries (one number from many)

These skip missing, excluded and text cells. Give them a column, a slice, a list, or several of these at once: max(A, B) is the largest value in A and B together. (For a row-by-row limit use clamp, not min/max.)

The descriptive-statistics analysis computes quartiles by the (n + 1)p rule, as Prism does; quantile uses the spreadsheet rule. For small samples the two can differ slightly.

Series (whole-column operations that give a column back)

Units

convert(x, "from", "to") knows these units. Metric prefixes work on every base unit: k (kilo), d (deci), c (centi), m (milli), µ or u or mc (micro), n (nano), p (pico), f (femto).

Mass and molar concentrations convert through a substance’s molar mass, so you must name the substance; Dioptra will not guess:

Where formulas are also used

Filter rows takes a formula that is true for the rows to keep: A > 0 && !isna(B).

Differences from a spreadsheet

• log(x) is the natural log. Use log10(x) for base 10.
• Slices are inclusive and count from 1: A[1:3] is three rows.
• % is the remainder, not “per cent”.
• There are no $ absolute references; a column formula already means “this column, every row”, and fill-down moves only single-cell references such as A3.
• Function names are case-insensitive (MEAN(A) works); column letters are capitals.

Statistical analyses: t tests, ANOVA, regression and more

How to run a statistical test in Dioptra: select the data, press Analyze (Ctrl-Shift-A), choose the test and its options, and read the results sheet, which shows the assumption checks first and the effect size with its confidence interval.

An analysis in Dioptra is an object in your project, like a table or a graph. It holds a specification (which table, which test, which options) and a results sheet computed from it. Change the data and the sheet recomputes. Change an option and the sheet recomputes. Delete the analysis and the history still records that it existed.

This page explains the flow, the parts of a results sheet, and the defaults. The analysis reference documents each analysis: when to use it, what it assumes, its options and outputs, its reference, and a worked example.

The flow

1. Select data and press Analyze (Ctrl-Shift-A, or the Analyze… button above the grid). The list holds all twenty analyses. Those that fit the table kind are active; the others are shown greyed with the reason (“needs a contingency table”, “needs at least three data sets”). You see what exists even when it does not apply.
2. Choose options. One compact panel with the few choices that matter, each with one line saying what it means. The defaults are the ones a careful statistician would choose without knowing more about your experiment.
3. Run. The results sheet opens beside the table.
4. Make a graph from the sheet with one click. Brackets for comparisons and fitted curves come from the analysis and stay linked to it.
5. Change anything. The sheet and the graph mark themselves stale and recompute when you look at them.

What a results sheet contains

A results sheet is structured, not a block of text. From top to bottom:

Assumption checks. What the test rests on, what was checked, and what the check means for this result. Collapsed to one line when everything passed; open when something did not.

Summary sentences. The result in words, in the style of a careful methods section:

Welch’s t test: the means differ by 3.2 units (95% CI 1.1 to 5.3), t(17.4) = 3.21, p = .005.

The estimate and its confidence interval come first. The p value comes last, as one piece of evidence among several.

A methods sentence you can paste into a paper: which test, which variant, two-sided or not, which correction for multiple comparisons, how many values were used, and the Dioptra version.

Tables. Every number at full precision, displayed to a sensible number of digits. Copy a single number, a table, or the whole sheet as tab-separated text or Markdown (Copy sheet).

Effect sizes with confidence intervals. Mean differences, Cohen’s d and Hedges’ g, eta squared, odds ratios and relative risks, correlation coefficients, hazard ratios, AUC. In the base product, always shown. An effect size says how big the difference is; a p value only says whether the data are surprising if there were none.

A checklist headed Before you report this: the things the test cannot check for you. Are the values independent? Was the pairing decided before the experiment? Is the experimental unit the row, or something larger?

Assumption checks

Every parametric test assumes things about the data: that values are independent, that they come from a roughly Gaussian distribution, that the groups have similar spreads. Independence can only be judged from the design, so it goes in the checklist. The rest can be checked, and Dioptra checks it, at α = 0.05 for every check:

A failed check does not stop the analysis. It says what the failure means here and names the alternative: Welch’s ANOVA when variances differ, a rank-based test when the distribution is far from Gaussian, more data when n is too small.

Two warnings about normality tests, which the sheet repeats where they matter. With small samples they have little power: a pass at n = 4 tells you almost nothing. With large samples they detect departures too small to matter, and the t test is robust to those. Look at the data as well. Use the checks as a prompt, not as an automatic switch; choosing the test after seeing which one gives the smaller p value is the p-hacking the analysis log is there to make visible.

The defaults, and why

Welch’s t test, not Student’s. Student’s t test assumes the two groups have equal variances. When they do, Welch’s test gives almost the same answer. When they do not, and especially when the smaller group has the larger variance, Student’s test can be badly wrong. Welch costs nothing when the assumption holds and protects you when it fails, so it is the default. Student’s test is one click away for anyone who needs it.

Two-sided. A one-sided test halves the p value in the direction you predicted and cannot detect an effect in the other. It is legitimate only when the direction was fixed before the data were seen and an effect the other way would be treated as no effect. That is rare, so two-sided is the default, and choosing one-sided adds a sentence to the methods line saying so.

Tukey–Kramer for all pairs. After an ANOVA the default compares every pair of groups with Tukey–Kramer, which handles unequal group sizes. For each group against a control, choose Dunnett; for a few pairs chosen in advance, Holm or Šidák. Each of these controls the chance of any false positive across the family of comparisons, with the most power available for that question. Plain Bonferroni is available but needlessly conservative; Holm is uniformly better. Benjamini–Hochberg controls the false discovery rate instead, for screens with many comparisons.

Type III sums of squares for two-way ANOVA, with sum-to-zero coding, so that unbalanced designs give the answer most textbooks and Prism give. (A frequent error is type III with dummy coding; Dioptra’s tests check that it does not make it.)

Exact tests when affordable. Mann–Whitney and Wilcoxon p values are exact when there are no ties and the samples are small enough to enumerate; Fisher’s test is exact for tables larger than 2 × 2 too; Spearman’s p is exact for n ≤ 9. The sheet says which method produced the p value.

P-value styles

A p value can be written several ways. The project’s style is set once (inspector, Project, P values) and applies everywhere: results sheets, summary sentences, and the labels on graph brackets. Changing it changes them all, and never changes the number underneath.

The GP style uses GraphPad’s asterisks: * < .05, ** < .01, *** < .001, **** < .0001, decided on the stored value, not the rounded one. It is available because some journals and labs require it. It is not the default because asterisks turn a continuous measure of evidence into a grade, and the word “significant” invites the reader to stop at the grade.

Reproducibility

Each analysis is saved in the project file as its specification, so reopening the file recomputes every result from the data. Each run, option change and deletion is a command in the history (history.jsonl inside the file), so the record of what was tried is kept with what was reported.

Analysis reference: every statistical test

One entry per analysis kind: when to use it, the tables it accepts, its options (JSON keys of the spec, with defaults; every key may be left out), what it checks, what the results sheet contains, the method it rests on, and a worked example. The general rules (how missing, excluded and summary values are handled, the assumption-check policy, the sentence format) are in METHODS.md, Results sheets.

Every sheet has: assumption checks (shown first), summary sentences, a methods line, typed sections, and a checklist of what the analysis assumes and cannot tell you. columns are flat column indices (the X column, when there is one, is 0); data sets are named by any of their subcolumns. An empty columns means “the first data sets” (or all, as stated). Multiple-comparison requests have the shape {"method": {"name": "tukey" | "dunnett" (+ "control") | "sidak" | "holm" | "bonferroni" | "dunn" | "benjamini_hochberg"}, "comparisons": {"kind": "all_pairs" | "vs_control" (+ "control") | "selected" (+ "pairs")}}.

The default graph family is what CreateGraph picks for an analysis when family is empty or "auto".

Descriptive statistics (descriptive)

How to get descriptive statistics in Dioptra (mean, SD, SEM, confidence interval of the mean, median, quartiles): select a table, press Analyze (Ctrl-Shift-A) and choose Descriptive statistics.

• When: describe each data set (n, mean, SD, SEM, CI of the mean, quartiles, range, CV, geometric mean).
• Tables: column, XY, grouped, variables, nested.
• Options: columns [] (all), ci_level 0.95, percentiles [] (extra, 0–100).
• Checks: values used (text and excluded cells counted); independence and normality stated, not tested.
• Outputs: Descriptive statistics table. Graph: column.
• Method: descriptive; quartiles by the (n + 1)p rule.
• Example:
  • Data: PlantGrowth ctrl (n = 10).
  • Result: M = 5.032, SD = 0.5831, 95% CI [4.615, 5.449].
  • Median 5.155, quartiles by Prism’s rule.
  • Checks: every value used.

t test (unpaired, Welch, paired, one-sample) (t_test)

How to run a t test in Dioptra: enter the two groups as data sets of a column table (one row per subject for a paired test), press Analyze (Ctrl-Shift-A) and choose t test, then pick Welch, unpaired, paired, ratio paired or one-sample.

• When: compare two means (unpaired or paired), a ratio of paired values, or one mean with a hypothetical value.
• Tables: column, variables, nested.
• Options: columns (first two data sets), variant "welch" (also "unpaired" = Student, "paired", "ratio_paired", "one_sample"), mu 0, alternative "two_sided" ("greater": the first data set is larger), ci_level 0.95.
• Checks: values used (pairs dropped for a missing side), sample size, normality of each group / the paired differences / the log ratios, equal variances (informational for Welch), outliers (Grubbs note), effective pairing (correlation of the pairs), independence. Unpaired and one-sample tests also run from mean/SD/N.
• Outputs: Descriptive, Test (t, df, two-sided P, one-sided P with its direction), Difference (estimate, SE, CI), Effect size (Cohen’s d, Hedges’ g with approximate CIs, R²), Normality, Equal variances, Ratio (ratio paired), Pairing. Brackets: the two groups. Graph: column (unpaired, one-sample), paired preset (paired): bars with a line per subject.
• Method: ttest.
• Example:
  • Data: the sleep data, drug1 and drug2 as columns, paired by row.
  • Paired: the mean of the differences was 1.6 (95% CI 0.7 to 2.5), t(9) = 4.06, p = .003, Hedges’ g = 1.17.
  • Welch (as unpaired groups): 1.6 (95% CI -0.2 to 3.4), t(17.8) = 1.86, p = .079.
  • The pairing removes the between-subject scatter: same difference, much narrower CI.

Mann–Whitney test (mann_whitney)

How to run a Mann–Whitney test in Dioptra: enter the two groups as data sets of a column table, press Analyze (Ctrl-Shift-A) and choose Mann–Whitney test.

• When: two unpaired groups, no assumption of Gaussian distributions.
• Tables: column, variables.
• Options: columns (first two), alternative "two_sided", exact null (automatic: exact without ties up to n₁n₂ = 10,000; true forces exact, false asymptotic), ci_level 0.95.
• Checks: values used, sample size, similar shapes (spread, by Brown–Forsythe), exact or approximate P, independence. Not possible from summary data.
• Outputs: Descriptive (medians, quartiles), Test (U, U₁, rank sums, z, P), Difference (Hodges–Lehmann shift with Moses CI and achieved level), Effect size (rank-biserial r), Equal variances. Graph: box with a bracket.
• Method: mannwhitney.
• Example:
  • Data: sleep drug1 against drug2 as independent groups.
  • The Hodges–Lehmann shift was 1.4 (95% CI -0.1 to 3.6), U = 25.5, p = .069.
  • Medians 1.75 and 0.35; ties, so P is the normal approximation.
  • Check “Exact or approximate P” is a caution.

Wilcoxon signed-rank test (wilcoxon)

How to run a Wilcoxon signed-rank test in Dioptra: enter the paired values as two data sets of a column table, one subject per row, press Analyze (Ctrl-Shift-A) and choose Wilcoxon signed-rank test.

• When: paired values (two columns) or one column against a hypothetical median, no Gaussian assumption.
• Tables: column, variables, nested.
• Options: columns (one: against mu; two: paired), mu 0, alternative "two_sided", ci_level 0.95.
• Checks: values used, sample size (6 pairs), symmetric differences (skewness), exact or approximate P, independence.
• Outputs: Descriptive (medians of each column and of the differences), Test (W+, W−, W, zeros dropped, z, P), Pseudo-median (Hodges–Lehmann with CI). Graph: the paired preset (bars with connecting lines) (paired) or box.
• Method: wilcoxon.
• Example:
  • Data: sleep, paired by row.
  • The Hodges–Lehmann median of the differences was 1.3 (95% CI 0.8 to 2.8).
  • W+ = 45, W− = 0, p = .008 (normal approximation: the differences have ties).
  • Symmetry check passes.

One-way ANOVA (one_way_anova)

How to run a one-way ANOVA in Dioptra: enter each group as a data set of a column table, press Analyze (Ctrl-Shift-A) and choose One-way ANOVA, and pick the multiple comparisons.

• When: three or more independent groups, compare means.
• Tables: column, nested.
• Options: columns [] (all), post_hoc Tukey all pairs (null for none), welch false, brown_forsythe false.
• Checks: values used, sample size, normality of the residuals, equal variances (Brown–Forsythe; informational with Welch), outliers, independence. Runs from mean/SD/N (exact), with Bartlett for the variances.
• Outputs: Descriptive, ANOVA table (SS, df, MS, F, P), tests not assuming equal variances (Welch, Brown–Forsythe), Effect size (η², ω², Cohen’s f), multiple comparisons (Comparison, mean difference, CI, q or t, unadjusted and adjusted P, significant, asterisks), Normality, Equal variances. Tukey for all pairs, Dunnett for a control, Holm–Šidák for selected pairs, Šidák/Bonferroni/Benjamini–Hochberg on request. Brackets: every comparison (up to six; else the significant ones). Graph: column.
• Method: anova, posthoc.
• Example:
  • Data: PlantGrowth (ctrl, trt1, trt2; 10 each).
  • F(2, 27) = 4.85, p = .016, η² = .26 (ω² = .20).
  • Tukey: trt1 vs. trt2 differs (mean difference -0.87, 95% CI -1.56 to -0.17, p = .012).
  • The graph carries three brackets: p = .391, p = .198, p = .012.

Repeated-measures ANOVA (repeated_measures_anova)

How to run a repeated-measures one-way ANOVA in Dioptra: enter one subject per row and one condition per data set of a column table, press Analyze (Ctrl-Shift-A) and choose Repeated-measures one-way ANOVA.

• When: each row is one subject measured under every condition (columns).
• Tables: column.
• Options: columns [] (all), gg_correction true, post_hoc all pairs.
• Checks: values used (incomplete rows dropped, counted), sample size, sphericity (Mauchly; pass when corrected), normality of the residuals, independence of subjects.
• Outputs: Descriptive, ANOVA table (treatment, subjects, residual, total), corrected and uncorrected tests (none, Greenhouse–Geisser, Huynh–Feldt, lower bound, with ε), Sphericity (Mauchly W, χ², df, P), Effect size (partial η²), paired multiple comparisons (paired t tests with Holm–Šidák, or the adjustment asked; CIs for Bonferroni and Šidák), Normality. Graph: the paired preset (bars with connecting lines) with brackets.
• Method: anova rm_anova, posthoc p_adjust.
• Example:
  • Data: 6 subjects × Pre, Mid, Post.
  • Greenhouse–Geisser: F(1.53, 7.65) = 61.37, p < .001, partial η² = .92, ε = .77.
  • Every pair differs after Holm–Šidák (largest adjusted p = .007).
  • Sphericity passes (corrected P in use).

Two-way ANOVA (two_way_anova)

How to run a two-way ANOVA in Dioptra: put one factor in the rows and the other in the data sets of a grouped table, replicates in subcolumns, press Analyze (Ctrl-Shift-A) and choose Two-way ANOVA.

• When: two factors: rows of a grouped table (factor A) and its data sets (factor B), replicates in subcolumns.
• Tables: grouped.
• Options: ss_type "iii" (also "i", "ii"), post_hoc null (any request compares the cell means within each row on the pooled residual variance: Tukey for all pairs, else the adjustment named), repeated null ("rows": each row’s subcolumn is one subject measured in every data set; "columns": each subcolumn of a data set is one subject measured in every row).
• Checks: values used, replicates in every cell, normality of the residuals, equal variances across cells, independence; with a repeated factor: sphericity stated (not tested), balance.
• Outputs: ANOVA table (Source, SS, df, MS, F, P, partial η²) of the chosen type, Cell means, within-row comparisons, Normality, Equal variances. The interaction sentence comes first. With a repeated factor: the split-plot table (interaction, repeated factor, between factor, subjects, residual). Graph: column (grouped).
• Method: anova two_way_anova; the split-plot partition is the standard one for one between and one within factor (sequential with unequal groups).
• Example:
  • Data: 2 rows × 2 data sets × 3 replicates.
  • Interaction F(1, 8) = 8.02, p = .022: the column effect depends on the row.
  • Row factor F(1, 8) = 18.69, p = .003; column factor F(1, 8) = 72.20, p < .001.
  • Tukey within rows: B exceeds A in both rows (p = .004 and p < .001).

Kruskal–Wallis test (kruskal_wallis)

How to run a Kruskal–Wallis test in Dioptra: enter each group as a data set of a column table, press Analyze (Ctrl-Shift-A) and choose Kruskal–Wallis test.

• When: three or more independent groups, no Gaussian assumption.
• Tables: column, nested.
• Options: columns [] (all), dunn true.
• Checks: values used, chi-square approximation (groups of 5 or more), similar shapes stated, independence.
• Outputs: Descriptive (medians, quartiles, mean ranks), Test (H, df, P, ε², tie correction), Dunn’s comparisons with Holm adjustment. Graph: box with brackets.
• Method: anova kruskal_wallis, posthoc dunn_kruskal.
• Example:
  • Data: PlantGrowth.
  • H(2) = 7.99, p = .018, ε² = .28.
  • Dunn (Holm): trt1 vs. trt2 differs (p = .015).
  • The other two comparisons do not reach adjusted p < .05.

Friedman test (friedman)

How to run a Friedman test in Dioptra: enter one subject per row and one condition per data set of a column table, press Analyze (Ctrl-Shift-A) and choose Friedman test.

• When: matched rows (subjects) under three or more conditions, no Gaussian assumption.
• Tables: column.
• Options: columns [] (all), dunn true.
• Checks: values used (incomplete rows dropped), chi-square approximation (10 subjects), independence.
• Outputs: Descriptive (medians, mean ranks), Test (χ², df, P, Kendall’s W, subjects used and dropped), Dunn’s comparisons (Holm). Graph: the paired preset (bars with connecting lines).
• Method: anova friedman, posthoc dunn_friedman.
• Example:
  • Data: 6 subjects × Pre, Mid, Post.
  • χ²(2, N = 6) = 12.00, p = .002, Kendall’s W = 1.00 (every subject ranks the conditions alike).
  • Dunn (Holm): Pre vs. Post differs (p = .002).
  • Chi-square approximation flagged (fewer than 10 subjects).

Chi-square test (chi_square)

How to run a chi-square test in Dioptra: enter the counts in a contingency table, press Analyze (Ctrl-Shift-A) and choose Chi-square test.

• When: association between the rows and columns of a table of counts; goodness of fit to equal proportions for a parts-of-whole table (or a one-column table).
• Tables: contingency, parts.
• Options: yates false (2 × 2 only).
• Checks: counts are whole numbers (the bad cell is named), expected counts (Cochran’s rule, Fisher offered), independence of subjects.
• Outputs: Observed counts with totals, Expected counts, Test (Pearson χ², Yates, G, and Fisher’s exact P for 2 × 2), Association (Cramér’s V, φ), Adjusted residuals, and for 2 × 2 the relative risk (Katz CI), odds ratio (Woolf CI) and risk difference (Wald CI). Goodness of fit: observed and expected, χ², df, P. Graph: column.
• Method: contingency.
• Example:
  • Data: 2 × 2 counts [[12, 5], [7, 15]] (rows = groups, columns = outcome).
  • Risk 0.706 vs. 0.318: relative risk 2.2 (95% CI 1.1 to 4.4).
  • χ²(1, N = 39) = 5.77, p = .016, Cramér’s V = .38; Fisher p = .025 shown alongside.
  • Expected counts pass (smallest 8.28).

Fisher’s exact test (fisher_exact)

How to run Fisher’s exact test in Dioptra: enter the counts in a contingency table, press Analyze (Ctrl-Shift-A) and choose Fisher’s exact test.

• When: a 2 × 2 table, especially with small counts; r × c tables by the Fisher–Freeman–Halton test within its work limit.
• Tables: contingency (2 or more data sets).
• Options: alternative "two_sided" ("greater": odds ratio > 1; 2 × 2 only).
• Checks: counts are whole numbers, fixed margins stated, independence.
• Outputs: Observed counts, Test (two-sided and one-sided P, sample and conditional MLE odds ratios with the exact CI), Effect size (relative risk, odds ratio, risk difference). r × c: exact P, probability of the observed table, number of tables, Cramér’s V; a clear message when the table is too large. Graph: column.
• Method: contingency fisher_exact_2x2, fisher_exact_rxc.
• Example:
  • Data: the lady tasting tea, [[3, 1], [1, 3]].
  • Two-sided p = .486.
  • Conditional MLE odds ratio 6.41 (95% CI 0.21 to 626).
  • Relative risk 3.0 (95% CI 0.50 to 18.0).

Correlation (Pearson and Spearman) (correlation)

How to compute a correlation in Dioptra: enter the variables in an XY or Multiple variables table, press Analyze (Ctrl-Shift-A) and choose Correlation.

• When: association between two variables, or a matrix of several.
• Tables: XY (X with each data set by default), variables (numeric variables), column (data sets paired by row).
• Options: columns [] (all), method "pearson" (also "spearman", "kendall"), ci_level 0.95.
• Checks: values used (pairwise deletion counted), sample size, normality of each variable (Pearson), linear or monotonic relationship stated, outliers, independence.
• Outputs: Correlation table (pair, n, r, CI, r², P, Holm-adjusted P for several pairs), the matrix for more than two variables, Normality. Graph: scatter of the pair, or correlation_matrix.
• Method: correlation.
• Example:
  • Data: X = 1…10, Y = 2.1, 3.9, …, 19.7.
  • r(8) = .999 (95% CI .998 to 1.000), p < .001, n = 10.
  • Spearman on request: ρ with the Bonett–Wright CI.
  • Linearity is stated, not tested: look at the scatter plot.

Linear regression (linear_regression)

How to run a simple linear regression in Dioptra: enter X and Y in an XY table, press Analyze (Ctrl-Shift-A) and choose Simple linear regression.

• When: a straight line through XY data, each data set separately.
• Tables: XY (replicates are separate points; mean/SD/N rows give their means).
• Options: datasets [] (all), through_origin false, bands "none" (also "confidence", "prediction", "both", for graphs), ci_level 0.95, residuals false (adds a residuals table).
• Checks: linearity (runs test), replicates test, normality of the residuals, equal scatter (|residual| against X), influential points (standardized residual, Cook’s distance), X without error stated, independence (Durbin–Watson shown).
• Outputs: Best-fit values (slope, intercepts with SE, CI, t, P), Goodness of fit (n, R², Sy.x, SS, F, P, Durbin–Watson), Runs test, Replicates test, Normality, Residuals. Graph: scatter with the line and its band (linear and log X).
• Method: regression simple_linear_regression.
• Example:
  • Data: X = 1…10, Y = 2.1, 3.9, …, 19.7.
  • Slope 1.99 (95% CI 1.94 to 2.05), Y-intercept 0.060 (95% CI -0.280 to 0.400).
  • R² = .999, F(1, 8) = 7052.15, p < .001.
  • Runs test passes.

Nonlinear regression and curve fitting (dose-response, EC50) (nonlinear_regression)

How to fit a curve in Dioptra, such as a dose-response curve for an EC50: enter X and Y in an XY table, press Analyze (Ctrl-Shift-A) and choose Nonlinear regression (curve fit), and pick an equation.

• When: fit a model (dose-response, exponential, enzyme kinetics, binding, growth, or a formula) to XY data.
• Tables: XY.
• Options: datasets [] (all, each fitted separately), equation {"name": "four_parameter_logistic"} (snake_case names such as one_phase_decay, michaelis_menten, log_inhibitor_variable_slope, Prism names and the aliases 4PL, 3PL, 5PL, line, MM; or {"name": "...", "formula": "Y = A*exp(-K*X) + C"}), weighting "none" (also "relative_y2" = 1/Y², "poisson_y" = 1/Y, "inverse_sd2" = 1/SD² of the replicates), robust false, constraints [] ({"kind": "fixed" | "min" | "max", "param", "value"}, {"kind": "shared", "param"} for a global fit), initial {} (by parameter name), compare_with null (a second equation), profile_ci false, rout_q null (ROUT outlier removal at Q percent), ci_level 0.95, bands "confidence" (for graphs).
• Checks: values used, convergence (hit constraint, ambiguous, not converged), runs test, replicates test, normality of the residuals, outliers (ROUT when asked, otherwise stated), X as log(concentration) for the log equations, scatter of Y stated, independence.
• Outputs: Best-fit values (value, SE, CI, profile CI when asked, status, dependency), Derived values (EC50 from LogEC50, half-life, Span…), Goodness of fit (n, df, R², adjusted R², SS, Sy.x, AICc), Convergence, Runs test, Replicates test, Outliers (ROUT), Model comparison (extra-sum-of-squares F test and AICc with probabilities and the preferred model), Normality. Graph: scatter with each curve and its band (linear and log X).
• Method: nonlinear, equations.
• Example:
  • Data: 4PL dose-response, 11 log concentrations in duplicate.
  • LogEC50 = -6.45 (95% CI -6.54 to -6.35), so EC50 = 3.58E-7 (95% CI 2.88E-7 to 4.45E-7).
  • HillSlope = 0.75 (95% CI 0.63 to 0.87); R² = .995.
  • Against the fixed-slope model: F(1, 18) = 14.52, p = .001; AICc prefers the variable slope (99.2%).

Normality tests (Shapiro–Wilk, D’Agostino) (normality)

How to test for normality in Dioptra: select a table, press Analyze (Ctrl-Shift-A) and choose Normality tests.

• When: look at the distribution of each data set.
• Tables: column, XY, grouped, variables, nested.
• Options: columns [] (all), tests ["shapiro_wilk", "dagostino_pearson"] (also "anderson_darling", "kolmogorov_smirnov" = Lilliefors).
• Checks: values used (tests that cannot run are named), power of the tests (n < 8 or n > 500), what the tests mean.
• Outputs: Normality tests (data set, test, n, statistic, P, passed), Descriptive (mean, SD, skewness, excess kurtosis). Graph: qq.
• Method: normality.
• Example:
  • Data: PlantGrowth.
  • ctrl: Shapiro–Wilk W = 0.96, p = .747; D’Agostino–Pearson K² = 0.23, p = .890.
  • All three groups are consistent with a Gaussian distribution.
  • That is absence of evidence, not proof.

Identify outliers (Grubbs, ROUT) (outliers)

How to find outliers in Dioptra: select a table, press Analyze (Ctrl-Shift-A) and choose Identify outliers.

• When: look for values that may be errors, one data set at a time.
• Tables: column, XY, grouped, variables, nested.
• Options: columns [] (all), method {"method": "rout", "q": 1} (Q in percent) or {"method": "grubbs", "alpha": 0.05}.
• Checks: values used, normality of the values without the flagged ones, decision to exclude (flagged values are never removed).
• Outputs: Flagged values (data set, row, cell, value), Before and after (n, flagged, mean and SD with and without), Grubbs’ steps, Normality. Graph: strip.
• Method: outliers.
• Example:
  • Data: 10.1, 9.8, 10.3, 10.0, 9.9, 10.2, 25, 10.1.
  • ROUT (Q = 1%) flags 25 (row 7); so does Grubbs at α = 0.05.
  • Without it M = 10.1, SD = 0.172 (with it M = 11.9, SD = 5.29).
  • The value stays in the table until you exclude it.

Kaplan–Meier survival analysis (survival)

How to draw Kaplan–Meier survival curves and compare them in Dioptra: enter times as X and events (1) or censoring (0) per group in a survival table, press Analyze (Ctrl-Shift-A) and choose Survival curves (Kaplan–Meier).

• When: time to an event with censoring, one or more groups.
• Tables: survival (X = time; each data set 1 = event, 0 = censored).
• Options: compare "log_rank" (also "gehan_breslow_wilcoxon", which leads the sentence; both are always shown), ci_level 0.95.
• Checks: values used, event codes (the bad cell is named), number of events, proportional hazards (stated, not tested), uninformative censoring, independence.
• Outputs: a Kaplan–Meier table per group (time, at risk, events, censored, percent survival, SE, CI), Median survival with the Brookmeyer–Crowley CI, Curve comparison (log-rank, Gehan–Breslow–Wilcoxon, trend for three or more groups), Observed and expected events, Hazard ratio both ways (Mantel–Haenszel and log-rank methods). Graph: kaplan_meier (step curves, censor ticks, CI bands, numbers at risk).
• Method: survival.
• Example:
  • Data: Gehan’s leukaemia trial, 6-MP (21 patients, 9 relapses) and placebo (21, 21).
  • Median survival 23 weeks with 6-MP (95% CI 13 to undefined), 8 with placebo (95% CI 4 to 11).
  • Log-rank χ²(1) = 16.79, p < .001.
  • Hazard ratio (6-MP / placebo, Mantel–Haenszel) 0.19 (95% CI 0.09 to 0.43).

ROC curve (roc)

How to draw a ROC curve in Dioptra: enter controls and patients as two data sets of a column table, press Analyze (Ctrl-Shift-A) and choose ROC curve.

• When: how well a measurement separates patients from controls; choose a cut-off.
• Tables: column (controls first, then patients), variables (a score variable and a category variable with positive_label).
• Options: columns (first two), positive_label null, ci_level 0.95.
• Checks: direction (AUC < 0.5 means the columns are the wrong way round), sample size, representative samples stated, independence.
• Outputs: Area under the curve (DeLong and Hanley–McNeil SEs and CIs), test of AUC = 0.5, Cut-offs (sensitivity and specificity with Wilson CIs, LR+, LR−, Youden J), Best cut-offs (Youden, closest to (0, 1)). Graph: roc.
• Method: roc.
• Example:
  • Data: 10 controls (1.2 … 2.0) and 10 patients (3.4 … 5.2).
  • AUC = .90 (95% CI .77 to 1.00, DeLong), p < .001 against chance.
  • Youden cut-off ≥ 3.3: sensitivity 80.0%, specificity 90.0%.
  • Direction check passes.

Bland–Altman analysis (bland_altman)

How to run a Bland–Altman analysis in Dioptra: enter the two methods as two data sets of a column table, one subject per row, press Analyze (Ctrl-Shift-A) and choose Bland–Altman.

• When: agreement between two methods measured on the same subjects.
• Tables: column, variables (two data sets paired by row).
• Options: columns (first two), method "difference" (also "ratio", "percent_difference"), ci_level 0.95.
• Checks: values used (unpaired rows dropped), sample size (30 pairs), normality of the differences, proportional bias, acceptable agreement stated, independence.
• Outputs: Bias and limits of agreement (bias, SD, lower and upper limits, each with CI), Proportional bias (slope of the difference on the mean), Normality. Graph: bland_altman (differences), scatter with bias and limit lines (ratio, percent).
• Method: agreement bland_altman.
• Example:
  • Data: the ROC example’s two columns read as methods A and B.
  • Bias (A − B) -1.6 (95% CI -2.3 to -0.9).
  • Limits of agreement -3.4 (95% CI -4.6 to -2.2) to 0.20 (95% CI -0.96 to 1.36).
  • No proportional bias (p = .458).

Principal component analysis (PCA) (pca)

How to run a principal component analysis in Dioptra: enter the variables in a Multiple variables table, press Analyze (Ctrl-Shift-A) and choose Principal component analysis.

• When: summarise several correlated numeric variables by a few components.
• Tables: variables.
• Options: columns [] (all numeric), standardize true (correlation matrix), components null (chosen by Horn’s parallel analysis).
• Checks: values used (incomplete rows dropped), rows per variable (5 or more), comparable scales when not standardized, linear relationships stated, independence.
• Outputs: Eigenvalues (% of variance, cumulative %, parallel-analysis 95th percentile, retained), Loadings, Eigenvectors, Scores. Graph: scatter (scores on PC1 and PC2); column gives the scree plot.
• Method: multivariate.
• Example:
  • Data: three variables on 10 cases, two of them strongly correlated with each other and negatively with the third.
  • The first component explains 97.1% of the variance.
  • Parallel analysis and Kaiser’s rule both retain one component.

Statistical methods and references

One line per public function of dioptra-stats: what it computes, the reference it implements, and the conventions that differ between Prism and SciPy. Conventions that hold everywhere:

• NaN is a missing value. Descriptive statistics and tests skip it; paired tests drop incomplete pairs; outlier indices keep the caller’s positions. Infinities are rejected with StatsError::InvalidArgument.
• Two-sample differences are x - y. Prism shows “B - A” (later column minus earlier); the presentation layer flips the sign where it mimics Prism.
• Every test returns the two-sided p and both one-sided p-values (p_less, p_greater) plus p for the requested alternative. Prism’s “one-tailed” p is p_less or p_greater for the predicted direction.
• Upper tails are computed directly, never as 1 - cdf; quantiles invert whichever tail is smaller.
• The low-level special kernels return NaN for invalid arguments; distribution constructors and tests return StatsError.

special (special functions)

dist (distributions)

Each continuous distribution implements Continuous (pdf, cdf, sf, ppf, isf) and has a cdf_sf or quantile_pq method taking both tails.

descriptive

ttest

rank, mannwhitney, wilcoxon

normality

outliers

quad, roots (numerical infrastructure)

anova

Sums of squares are computed on data shifted by the first observation (exact by Sterbenz’s lemma when values share leading digits) with two-pass means and compensated sums.

posthoc

Comparison (i, j) estimates value_i - value_j; all-pairs lists i < j; many-to-one lists (treatment, control). statsmodels’ Tukey reports mean_j - mean_i (opposite sign).

contingency

2 x 2 layout [[a, b], [c, d]]: rows = groups, columns = outcome (event, no event).

correlation

regression

equations (curve-fit equation library)

Prism’s equation and parameter names (GraphPad Curve Fitting Guide, “Models built in to Prism”). Each Equation holds ParamSpecs (name, InitialRule, default bounds, data-set constant flag), DerivedSpecs and its XTransform. Gradients are hand-written for the simple models and exact forward-mode automatic differentiation for the rest (5PL, bell-shaped, two-site competition, fit Ki, [Agonist] variable slope, log-logistic, growth, power series); equations::tests::gradients_match_finite_differences checks every one against Richardson differences.

nonlinear (curve fitting)

survival

roc

agreement

multivariate

resample

Results sheets

dioptra-core::compute turns each analysis specification into a results sheet on top of the functions above. Every sheet has the same parts, in the order the UI shows them: assumption checks, summary sentences, a methods line, typed sections, a checklist. docs/ANALYSES.md describes each analysis kind.

Data. Excluded cells are never used; empty and text cells are missing. Paired and repeated-measures analyses align values by row and drop a row with a missing member, saying how many. Nested tables are averaged within each subgroup first (n counts the experimental units). Data sets entered as mean/SD/N (or mean/SEM/N, mean/CI/N) are used where the result depends only on the means, SDs and sizes: t tests (one-sample, Student, Welch), one-way ANOVA with its post tests, and two-way ANOVA cells. Dioptra builds a synthetic sample with exactly that mean, SD and N, so these results are exact; rank tests, paired designs, normality and outlier tests say they are not possible from summary data. Contingency counts must be non-negative whole numbers; the first bad cell is named and the table is left as it is. Survival codes must be 1 (event) or 0 (censored).

Assumption checks. Each check has a status (pass, caution, fail, not_checked), a one-sentence meaning, and an alternative when the status is not pass. Every check uses α = 0.05.

Summary sentences. APA style, estimate first: the effect with its CI, then the test statistic with its degrees of freedom, then p in the project’s style (p_phrase), then an effect size. Examples: “The mean difference (A − B) was 3.2 (95% CI 1.1 to 5.3), t(17.4) = 3.21, p = .005, Hedges’ g = 1.40.”; “One-way ANOVA: F(2, 27) = 4.85, p = .016, η² = .26 (ω² = .20).” plus one sentence per multiple-comparison family naming the comparisons that differ. Estimates and CI limits share their decimals: two significant digits of the CI width (at least two of the estimate), scientific notation below 0.001 or from 10⁶. Test statistics have two decimals; fractional df one decimal (two below 10); quantities bounded by 1 (r, η², R², AUC) drop the leading zero in APA style.

Methods line. Test, sidedness, correction or adjustment, CI level, data form (for example “computed from the entered mean, SD and N”) and the software version, ready to paste: “Welch’s unpaired t test, two-sided, 95% CI. Dioptra 0.2.0.”

Graphs. A sheet names a default graph family (graph_family) and carries runtime graph material: the analysed data sets, significance brackets (adjusted p of each comparison; all of them up to six, otherwise the significant ones), fit curves with confidence or prediction bands evaluated at 200 X values (linear and, when X > 0, log spaced), survival curves with bands and numbers at risk, ROC points, replacement series (correlation pairs, PCA scores and scree, Bland–Altman ratio or percent differences).

Graphs

A graph in Dioptra is a specification, not a picture: which table or analysis it draws, which family (column, box, violin, scatter, Kaplan–Meier, and so on), how data map to marks, a style, and annotations. The plot engine turns the specification into a scene measured in points and writes it as SVG. What you see in the editor is that SVG; what you export is the same SVG, or a PDF or PNG made from it. There is no separate “export renderer” that can disagree with the screen.

This page is about using the editor. The graph reference lists every family with the data it needs and the options it reads, the themes and palettes in detail, and the specification format.

Making a graph

• From a table: Graph → New graph (Ctrl-Shift-G). The family defaults to the natural one for the table kind: scatter for XY, Kaplan–Meier for survival, SuperPlot for nested, column with points for the others.
• From a results sheet: Make graph. Brackets for the comparisons, fitted curves and their confidence bands come from the analysis and stay linked to it. Paired and repeated-measures analyses offer Graph with connecting lines: bars with a line per subject (Connecting lines and paired graphs).

A column graph shows every data point by default, with the error bar you choose (SD, SEM, 95% CI, range or IQR). A bar alone hides the distribution: two groups with the same mean and SD can look identical as bars and completely different as points. If you want bars without points, untick Points; it is your choice to make, not the default.

The editor

Click anything in the graph (an axis, its title, a tick label, a data series, the legend, a bracket) and it is outlined, and the inspector on the right shows its properties: for an axis, its title, scale (linear, log10 or log2), limits, tick interval, minor ticks, tick direction, number format, label angle and breaks; for a series, its colour, marker, size and line style. Edit a value and the graph redraws.

Drag the legend or an annotation to move it. Double-click text to edit it in place. Graph → Add places a significance bracket, a reference line or a text label. Every change is undoable.

Text in titles accepts a small markup: ^ for superscript and _ for subscript (cm^2, CO_2), \alpha-style names or plain Unicode for Greek letters.

Size: millimetres and points

Journals specify figures in physical units, so Dioptra does too. Figure sizes are in millimetres (or inches); font sizes, line widths and marker sizes in points, where 1 pt is 1/72 inch. The size menu has presets for a single journal column (85 × 70 mm), a double column (174 × 100 mm) and a slide (120 × 90 mm); any other size is typed in. The default figure is 85 × 70 mm with 8 pt tick labels and 9 pt axis titles, which is legible when printed at that size.

Why not pixels? Because a pixel has no size until you print it. A figure designed at “800 pixels” will have 4 pt text at one resolution and 12 pt at another. A figure designed at 85 mm with 8 pt text has 8 pt text in the journal.

Themes

Font size, axis line width and marker size can be overridden for one graph without leaving the theme.

Palettes

The default palette is Okabe–Ito: eight colours chosen so that people with the common forms of colour blindness can still tell them apart. About one man in twelve has some colour-vision deficiency, so a figure that relies on red against green loses part of its audience. The other palettes are Paul Tol’s bright, muted and light sets, viridis and cividis for ordered data, Tol sunset for diverging data such as fold changes, and a grey ramp. Any series can be given its own colour.

Export

Export (Ctrl-Alt-E) offers three formats.

• PDF, with the fonts embedded as subsets. Opens identically everywhere and goes straight into a journal submission system or Illustrator, without missing-font substitutions.
• SVG, with real text (not outlines), grouped and named layers, and no clipping masks or invisible objects, so it edits cleanly in Illustrator or Inkscape.
• PNG at any resolution. The pixel size is the physical size times the resolution: 85 mm at 300 dpi is 85 / 25.4 × 300 = 1003.9, so 1004 pixels. The file records its resolution, so it imports at the right size into Word or PowerPoint.

The dialog states the exact file it will write before you write it. Copy graph as SVG puts the SVG on the clipboard.

Because the fonts are bundled and the engine does its own text measurement, the same graph produces the same bytes on Linux, Windows and macOS.

Layouts

A layout places several graphs on one page with panel letters (A, B, C…), for a multi-panel figure. Graph → New layout. Each panel stays a live graph; edit it and the layout follows. Export a layout exactly as a single graph.

Connecting lines and paired graphs

Why a line

Measure the blood pressure of eight people, give them a drug, measure again. Draw two bars of the mean, before and after, and the bars say the average fell by eight. They do not say whether everyone fell by eight, or whether two people fell by forty and the rest did not move. Those are different drugs.

The data know the difference, because each row is one person. A paired test uses that: it works on each person’s own change, and that is why a paired t test can find an effect that an unpaired test on the same numbers misses. A graph of paired data should show the same thing the test sees. The way to do it is to draw each person’s points and join them with a line, bar to bar. Parallel lines that all slope down are a consistent effect; lines that cross every which way are noise around a mean.

Dioptra draws these lines on any bar graph, dot plot, box plot or violin: connecting lines are an option of the graph, not a separate kind of graph.

A worked example

Paste eight subjects measured at baseline, week 4 and week 8 into a column table. The first row becomes the column titles. The third subject missed the week-4 visit, so that cell is empty.

Baseline	Week 4	Week 8
131	124	118
118	116	105
142		127
109	104	101
125	117	112
137	126	119
114	112	104
128	119	116

Run Analyze → Repeated-measures one-way ANOVA (or a paired t test on two columns, a Wilcoxon test or a Friedman test). The results sheet’s toolbar button reads Graph with connecting lines: these analyses default to the paired graph. Click it.

You get bars of the mean with SEM error bars, every subject’s points on the bar centres, a thin grey line per subject, and the significance brackets from the analysis. Now open the Connecting lines section of the inspector:

• Off / Subjects / Mean / Median / Both chooses what is joined. Subjects joins the values of each row. Mean and Median join the summary of each bar instead. Both draws the subject lines and the line of the graph’s summary (the mean, or the median when Bars and points → Summary says median). In the picture above it is Both.
• Missing says what an empty cell does. Gap (the default) breaks that subject’s line there; Join across connects the values on either side. Subject 3 above has a baseline and a week-8 value only, so with Gap it draws no line at all: there is no pair of neighbouring visits to join. A line from baseline straight to week 8 would hide that the week-4 value was never measured; choose Join across when that is what you want.
• Subject lines: style (solid, dashed, dotted), width in points, opacity, and colour. Colour by is one colour for every line (Prism’s convention), the data set (each segment takes the colour of the bar it starts from), the subject (each row its own colour from a palette), or a grouping column (a column of the table that says, say, Male or Female for each row: lines take a colour per group, a legend appears, and that column is not drawn as a bar).
• Summary line: its own style, width and colour.

Everything is undoable, and the graph redraws as you change it. Click a subject line in the graph to select it: the inspector shows the same controls, and the status line names the row.

How lines are matched

Lines join the values in the same row, as Prism does. Row 5 in Baseline and row 5 in Week 8 are the same subject. If your data are in long format (one row per measurement), pivot them to wide first with Data → Transform… → Pivot long to wide.

Lines run in the order the categories appear on the axis, which is the order of the data sets in the table (or of the analysis’s chosen data sets). Reorder the columns to reorder the lines.

Lines meet the points

When points are jittered sideways so they do not overlap, each line ends at its own point’s jittered position, not at the bar centre, so lines and points always agree. With Bars and points → Jitter at 0 % the points sit on the centre line, the classic before–after look; the paired preset uses 0 %.

Every bar style

The same lines work whatever draws the categories. Switch the family in the toolbar and the connecting lines stay:

Subject lines are drawn on top of bars, boxes and violins and beneath the points; error bars and the summary line sit above the points. Horizontal (Bars and points → Orientation) turns the graph so the categories run down the left; the lines turn with it. Log axes work as usual, and a line that crosses a broken axis is cut at the break, as the axis is.

Grouped tables

In a grouped table each row is a group (Day 1, Day 7, Day 14) and each data set has subcolumns. For repeated measures, subcolumn 1 of every data set is subject 1, subcolumn 2 is subject 2, and so on. Direction chooses which way the lines run:

• Within groups (default): inside each group, from one data set’s bar to the next (Saline to Drug on Day 1). This is Prism’s before–after on a grouped graph.
• Across groups: along each data set, from group to group (Saline on Day 1, Day 7, Day 14), Prism’s “each replicate”. The summary line then takes each data set’s colour.

Stacked bars draw no connecting lines: a stacked bar has no single height per data set to join.

In the file

A graph with connecting lines is an ordinary column (or strip, box, violin) graph with an options.connecting block; the graph reference lists every field and the file format chapter says how graphs of the old Before–after family from Dioptra 0.2 are opened: as the dot plot that draws the same picture.

"options": {
  "jitter": 0,
  "connecting": { "connect": "both", "style": "solid", "colour_by": "single",
                  "opacity": 0.55, "missing": "gap" }
}

Graphs

How Dioptra draws figures: the graph specification the UI edits, the data each family needs, the options each family reads, the themes and palettes, and the hit-test targets the graph editor uses. The engine is crates/dioptra-plot; dioptra-core re-exports its specification types, so the JSON below is exactly what create_graph, update_graph, patch_graph and get_graph_spec carry.

The pipeline

1. dioptra_core::graph::extract reads the source table into GraphData: series with X values (or category positions 1, 2, 3, …), Y values, raw replicates per X (missing cells kept as NaN so rows line up for paired graphs), precomputed error bounds for mean/SD/N-style tables, subgroup ids for nested tables, curves and at-risk tables.
2. The family turns spec + data into a plot: axis plans and marks in data units.
3. The layout measures every label with the bundled Inter metrics, sizes the margins so tick labels, axis titles, legends, colour bars and tables never collide, maps marks to points, clips them geometrically (no clipping masks in exported files) and emits a scene in points.
4. The scene becomes SVG (own writer), PNG (resvg, any DPI) or PDF (svg2pdf, fonts embedded as subsets). The SVG shown in the app is the SVG exported.

Sizes are in millimetres; strokes, ticks and fonts in points (1 pt = 1/72 in). The default figure is 85 × 70 mm (a single journal column), 8 pt tick labels, 9 pt titles. PNG pixel size is round(mm / 25.4 × dpi): 85 mm at 300 dpi is 1003.94 → 1004 px. PNGs carry the DPI in a pHYs chunk.

The specification

Every field has a default, so {"source": "<table id>", "family": "column"} is a valid spec, and merge patches can set one field at a time. Style fields that are absent mean “the theme decides”.

{
  "source": "<table or analysis id>",
  "family": "column",
  "title": "Optional heading",
  "mapping": {
    "datasets": [0, 2],            // which datasets (empty: all)
    "x": 0, "y": [1, 2],           // flat columns, variables tables only
    "label": 3,                    // flat column with point labels (volcano)
    "error_bars": "sem",           // none | sd | sem | ci95 | range | iqr
    "points": true                 // data points over summaries
  },
  "style": {
    "theme": "instrument",         // instrument | night | journal
    "palette": "okabe_ito",        // absent: theme default
    "size_mm": {"width": 85, "height": 70},
    "font_pt": 8,                  // tick labels; titles are +1 pt
    "line_pt": 0.75,               // axis lines; data lines scale with it
    "marker_pt": 4,
    "transparent": false,
    "datasets": [{"dataset": 1, "colour": "#D55E00", "marker": "square_open",
                  "marker_pt": 5, "line_style": "dashed", "line_pt": 1.2,
                  "label": "Knock-out"}]
  },
  "axes": {
    "x": {"title": "Dose (nM)", "scale": "log10", "min": 0.1, "max": 1000,
          "breaks": [{"from": 20, "to": 80}],
          "ticks": {"major": 1, "minor": 1, "direction": "out", "length_pt": 3,
                    "format": "auto", "decimals": 1, "label_angle": 45},
          "hidden": false},
    "y": {"title": "Response (% of max)"},
    "frame": "l",                  // l | box | none
    "origin": "frame",             // frame | zero
    "grid": false,
    "offset_pt": 0
  },
  "legend": {"position": "auto", "title": "Genotype", "at": {"x": 0.05, "y": 0.05}},
  "options": { "...": "family options, below" },
  "annotations": [
    {"kind": "significance_bracket", "from": 0, "to": 2, "text": "p < 0.001"},
    {"kind": "text_label", "text": "R^2 = 0.98", "x": 2, "y": 15, "size_pt": 8},
    {"kind": "line", "x1": 0, "y1": 0, "x2": 10, "y2": 10, "dashed": true},
    {"kind": "reference_line", "axis": "y", "value": 10, "label": "LLOQ", "dashed": true}
  ]
}

(Comments are for this document only; JSON has none.)

Notes:

• Text markup in titles, labels and category names: ^{…} and _{…} for super- and subscripts (^2, ^-1 and _i take one character or a signed number), \alpha … \omega, \Delta, \mu, \degree, \pm, \times, \le, \ge, \infty, \permil for symbols (a following space or {} ends the name, as in TeX), \^, \_, \\ for the literal characters. A newline in a category name forces a line break.
• Ticks are placed by the extended Wilkinson algorithm on 1, 2, 2.5 and 5 × 10ⁿ steps; the axis ends on a tick unless data sit on the last tick, in which case it runs 4% past it. Numbers never show floating noise; they switch to m×10ⁿ for |x| ≥ 10⁶ or ≤ 10⁻⁴, and use a typographic minus. Log axes put majors on powers of ten (1, 10, 100 inside 0.001…10 000, 10ⁿ outside, or as format asks), minors on 2…9 × 10ⁿ, and switch to 1–2–5 steps when the data span less than about a decade. Labels that would collide are thinned (the dropped ones stay as minor ticks); long category labels wrap onto up to three lines before they rotate to 45°.
• Breaks cut the axis, bars and gridlines and draw a gap glyph.
• Legend position auto lets the family decide: right of the plot for most, inside top right for survival, inside bottom right for ROC, above a volcano plot. at places the legend’s top-left corner at fractions of the plot area (set by dragging).
• Significance brackets run between 0-based categories; with no y they sit above the highest point, bar or error bar in their span and stack when they would overlap.
• Markers: circle, square, triangle, triangle_down, diamond, plus, cross, none, and _open variants (circle_open). Line styles: solid, dashed, dotted, dash_dot, none.

Family options (options)

Per data set, style.datasets[].pattern draws a fill pattern over bars: hatch, back_hatch, crosshatch, horizontal, vertical, dots. Patterns are clipped strokes, so SVG, PDF and PNG carry the same geometry.

Connecting lines (options.connecting)

Subjects are matched by row, as in Prism. Lines attach to the jittered point positions, so lines and points always meet; with jitter: 0 the points sit on the category centre (the aligned before–after look). Drawing order: bars, boxes or violins; subject lines; points and error bars; the summary line. Lines are cut where they cross an axis break. Stacked bars draw no lines. Each subject line is an editor target (subject-<row>, subject-g<group>-<row> or subject-s<data set>-<row>) pointing at /options/connecting; the summary line is connect-summary.

Families

Each entry says what data it draws, what it computes, and gives a minimal spec. Every family honours the theme, palette, per-dataset styles, sizes, axis settings, legends and annotations.

scatter

XY points. Data: XY tables (X column, Y datasets with replicates or mean/SD/N formats) or variables tables with mapping.x/mapping.y. Replicates are drawn as their mean (or median) with error bars as error_bars asks; with error_bars: "none" and points the raw replicates are drawn faintly. X error bars come from the data. Fit curves and CI bands in GraphData.curves are drawn under the points in the series colour. {"source": "t1", "family": "scatter", "mapping": {"error_bars": "sem"}}

line

As scatter with every series joined by a line in its line style, markers on. {"source": "t1", "family": "line", "style": {"datasets": [{"dataset": 0, "line_style": "dashed"}]}}

column

Bars of the mean or median with error bars and the points on top (default). Column tables give one bar per dataset; grouped tables give clusters by row with a legend; arrangement stacks them or scales stacks to 100%. On log Y axes bars start at the axis. Dark bars get upward error bars only. connecting joins each row’s points across the bars and/or the means; orientation: horizontal lays the bars sideways. {"source": "t2", "family": "column", "mapping": {"error_bars": "sd", "points": true}}

box

Tukey box plots: quartiles (type 7), whiskers to the furthest point within 1.5 IQR, outliers as open points; notch draws median ± 1.58 IQR/√n; points shows every value. {"source": "t2", "family": "box", "options": {"notch": true}}

violin

Gaussian kernel densities mirrored about each category, cut at the data range unless truncate is false, with a slim box (default), the points, or quartile lines inside. {"source": "t2", "family": "violin", "options": {"violin_inner": "quartiles"}}

strip

All points, jittered deterministically (density-scaled, golden-ratio sequence), with the mean or median line and error bars. {"source": "t2", "family": "strip", "mapping": {"error_bars": "sd"}}

raincloud

Half violin (cloud), slim box and jittered points (rain) per category. {"source": "t2", "family": "raincloud"}

before_after (retired)

Format 1.0’s paired family. A spec naming it is drawn, and on open migrated, as the strip spec with the same picture: jitter: 0, no error bars, no summary tick, connecting.connect: individuals (or both when mean_line was on). New graphs use the paired preset (column bars with subject lines) or the before_after preset, both of which create_graph accepts as family names. {"source": "t3", "family": "column", "options": {"jitter": 0, "connecting": {"connect": "individuals"}}}

estimation

Gardner–Altman: raw data with mean ± SD as a gapped line beside each group; on the right, a floating axis anchored at the control mean (the first dataset) with each group’s mean difference, its bootstrap distribution and its bias-corrected and accelerated 95% CI (5000 resamples, fixed seed, so the figure is reproducible). {"source": "t3", "family": "estimation", "options": {"bootstrap": 5000, "seed": 20261011}}

superplot

Nested tables: small points for every observation coloured (journal: shaped) by subgroup, a large point per subgroup mean, and the mean ± error of the subgroup means, so the error bar reflects biological replicates, not cells. {"source": "nested1", "family": "superplot", "mapping": {"error_bars": "sem"}}

histogram

Shared bins (Freedman–Diaconis width rounded to 1, 2 or 5 × 10ⁿ, or bin_width/bins), counts or density, translucent when several datasets overlap. {"source": "t2", "family": "histogram", "options": {"bin_width": 0.5}}

density

Kernel density curves with a light fill, one per dataset. {"source": "t2", "family": "density"}

heatmap

Rows are table rows (row titles), columns are datasets; cells coloured on viridis (sequential) or Tol sunset (diverging, symmetric around 0 when the data cross it), with a colour bar. Rows and columns can be reordered by average-linkage clustering on Euclidean distance with dendrograms; cell_values prints the numbers. {"source": "g1", "family": "heatmap", "options": {"cluster_rows": true, "cluster_columns": true}}

correlation_matrix

Pearson correlations between datasets (variables, paired by row), lower triangle, coefficients printed, diverging scale from −1 to 1, square cells. {"source": "vars1", "family": "correlation_matrix"}

kaplan_meier

Survival tables (X = time, 1 = event, 0 = censored): step curves in percent, censor ticks, 95% CI bands (exponential Greenwood, log(−log) scale) and the number at risk under each X tick. Curves supplied by an analysis are drawn instead when present. {"source": "surv1", "family": "kaplan_meier", "options": {"ci_band": false}}

roc

The first dataset holds controls, each later one a patient group (higher values mean disease): empirical ROC curves in percent, the chance diagonal, AUC in the legend. {"source": "t3", "family": "roc"}

bland_altman

The first two datasets paired by row: difference against mean, bias and 95% limits of agreement (bias ± 1.96 SD) with their 95% CIs shaded and labelled. {"source": "t3", "family": "bland_altman"}

volcano

Variables table with mapping.x = log₂ fold change and mapping.y = p values (or −log₁₀ p): threshold lines, up/down/not significant colouring with counts in the legend, and labels (from mapping.label or row titles) for the label_top most significant points, placed to avoid each other. {"source": "rnaseq", "family": "volcano", "mapping": {"x": 0, "y": [1], "label": 2}}

forest

One row per estimate, top to bottom, with its CI, a reference line and the numbers in a column on the right. Data: a dataset in a lower_upper, mean_ci_n or mean/SD format (the error bounds), or three datasets read as estimate, lower, upper; row titles label the rows. Log X axes suit ratios. {"source": "or1", "family": "forest", "axes": {"x": {"scale": "log10"}}}

pie, donut

Parts of a whole from a parts table (or one value per dataset), clockwise from twelve o’clock, percentages in slices of 5% or more, shares in the legend. Slice k takes its colour from style.datasets entries with dataset: k. {"source": "parts1", "family": "donut", "options": {"donut_hole": 0.6}}

qq

Sample quantiles against normal quantiles (Blom positions) with a line through the quartiles, per dataset. {"source": "t2", "family": "qq"}

residuals

Observed minus fitted against X: the fitted curve of the series from the analysis when supplied, otherwise a least-squares line; a dashed zero line. {"source": "t1", "family": "residuals"}

Themes

font_pt, line_pt and marker_pt override the theme; titles keep their offset from font_pt, data lines scale with line_pt.

Palettes

Colours are tokens: a per-dataset colour overrides the palette.

Hit-test targets (graph editor)

render_graph and render_layout answer

{"type": "svg", "svg": "<svg …>", "width_mm": 85, "height_mm": 70,
 "targets": [{"id": "axis-x-title", "target": "/axes/x/title",
              "bbox": {"x": 92.4, "y": 182.1, "width": 54.3, "height": 8.7}}]}

bbox is in points in the SVG’s viewBox coordinates (the SVG is width_mm wide; multiply by the displayed pixels per point to draw a selection box). Every <g> with an id also carries data-target with the same pointer, so a click on any SVG element can walk up to its group. Targets, in drawing order:

In layouts, panel i is panel-{i} → /graphs/{i} and every id inside it is prefixed p{i}- (p1-axis-x).

Layout style

update_layout takes an optional style (absent: unchanged), and get_layout returns it:

{"width_mm": 183, "font_pt": 6, "line_pt": 0.5, "letters": "lower", "letter_pt": 8}

width_mm resizes every panel, keeping its aspect ratio, so the columns and their letter gutters fill exactly that width; font_pt and line_pt replace each graph’s own in every panel; letters is upper (default), lower or none, set bold at letter_pt (default 10). Fonts and lines are never scaled with the panel. Setting anything but the default needs Dioptra Lab; files keep drawing as saved in every build.

Determinism

The same spec and data give the same bytes on every platform and in the browser: fonts are bundled (Inter Regular, SemiBold, Bold, Italic) and measured from their own tables, PNG and PDF never consult system fonts, jitter and bootstrap use a fixed-seed SplitMix64 generator, and no output depends on hash-map order. Golden SVGs for every family are in crates/dioptra-plot/tests/snapshots/; regenerate them with UPDATE_SNAPSHOTS=1 cargo test -p dioptra-plot. Series with more than 20,000 points are decimated to one point per 0.75 pt cell (a pixel at 96 dpi) at render time, and the SVG says so in a comment.

Journal figures

Dioptra Lab. SVG, PDF and PNG export at any size, multi-panel layouts and colour-blind-safe palettes are free.

Journal presets

Journal in the graph editor or layout toolbar. Pick a journal and a column width, then Apply to this graph or Apply to every figure (every graph and layout in the project). One undo takes the whole change back.

A preset sets the width, scales the height with it (up to the journal’s maximum), sets the type size and line width, and switches the slides theme to the light one. On a layout it sets the page width, one type size and line width for every panel, and the journal’s panel letters.

Type: tick labels at 7 pt, raised where the smallest text the engine draws (85% of the tick labels: point labels, numbers at risk) would fall below the journal minimum, and lowered to keep axis titles (+1 pt) under the maximum. Axis lines at twice the journal’s minimum line width, at least 0.5 pt; data lines and outlines follow.

The figure check never accepts a line thinner than 0.25 pt, whatever the journal.

Sources, read on 14 October 2026:

• Nature: https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/, https://www.nature.com/documents/nature-final-artwork.pdf, https://research-figure-guide.nature.com/figures/extended-data-formatting-guidelines/
• Cell Press: https://www.cell.com/figureguidelines
• Science: https://www.science.org/content/page/instructions-preparing-revised-manuscript
• PLOS: https://journals.plos.org/plosone/s/figures
• eLife: https://elife-rp.msubmit.net/html/elife-rp_author_instructions.html
• ACS: https://researcher-resources.acs.org/publish/author_guidelines?coden=jacsat
• Elsevier: https://www.elsevier.com/about/policies-and-standards/author/artwork-and-media-instructions/artwork-sizing, https://www.elsevier.com/about/policies-and-standards/author/artwork-and-media-instructions/artwork-types
• APS: https://journals.aps.org/authors/style-basics
• The Journal of Physiology: https://jp.msubmit.net/cgi-bin/main.plex?form_type=display_requirements

Journals revise these pages; the author guidelines of the journal you submit to decide.

Figure check

The Journal popover checks the figure against the chosen journal each time it changes. It reads the drawing that is exported, so it checks what the journal receives.

Click an issue to select the element in the graph editor.

Colour vision is simulated with Machado, Oliveira and Fernandes (2009), doi:10.1109/TVCG.2009.113, at full severity on linear RGB. Two colours count as distinct when their CIEDE2000 difference (Sharma, Wu and Dalal 2005, doi:10.1002/col.20070) is at least 10. Neighbouring Okabe–Ito colours pass in all three simulations; a red and a green of similar lightness fail for deuteranopia.

Layouts at final size

Journal → Final size in the layout view:

• Letters: A B C, a b c or none; Letter size in points (bold).
• Page width: the panels are resized, keeping their shape, so the columns and their letter gutters fill exactly this width. Type and lines are not scaled.
• Text and Lines: one tick-label size and one axis line width in every panel, whatever each graph says.

Empty fields keep each graph’s own setting. A layout made this way draws the same in every copy of Dioptra; changing the settings needs Dioptra Lab.

TIFF

Export… → TIFF: 8-bit RGB with LZW compression, the resolution recorded in the file, rendered from the same drawing as PNG on a white background. EPS is not offered; PDF and SVG carry the same vectors.

Batch analysis

Part of Dioptra Lab. Importing a single file, plate-reader exports included, and replacing a table’s data are free.

A template is any project plus the table that receives the data. Batch analysis puts each data file into a copy of the template, recomputes every formula, analysis, graph and layout, and writes:

• <file>.dioptra, the recomputed project;
• <file> - <graph>.pdf (or .png, .svg) for every graph and layout, at its set size;
• summary.csv, one row per file.

Files are read as by Replace table data: names and column formulas of the receiving table stay, the data change. A plate map, if given, applies to every plate-reader file.

The summary

The summary has a File column, one column per headline number and an Error column. Headline numbers come from every section of every results sheet: the columns headed Value, Best-fit or Estimate, and every column of p values. Each is named after the analysis and the row, such as Fit · Data set A · LogEC50. A nonlinear fit gives its parameters (Bottom, Top, LogEC50, HillSlope) and derived values (EC50); a t test gives t, df, the P value, the difference and the effect sizes. Rename an analysis in the template to name its columns.

A file that cannot be analysed (no data, a table of the wrong kind) gets its error in the summary; the others go on.

In the app

File → Batch analysis… asks for:

• the template: the open project, or a project file;
• the table that receives the data;
• the data files (on the desktop, files or a whole folder);
• the figure format and an optional plate map;
• the output folder (desktop). In the browser, everything downloads as one zip.

The dialog shows progress and, at the end, the summary and any errors.

File → Watch a folder… (desktop) applies a template to each new file that appears in a folder, once its size has stopped changing for two seconds. Results go to the folder’s analysed subfolder, with a summary.csv that grows by one row per file. Files already in the folder are left alone. File → Stop watching the folder ends it; so does quitting.

From the command line

dioptra batch assay.dioptra --table "Plate" exports/ --out results --format png

Inputs are files or folders (their data files, not subfolders). --plate-map map.txt applies a plate map; --dpi sets the PNG resolution (300). The exit status is non-zero when any file fails.

The key is read from $DIOPTRA_LICENSE, or from the file the desktop app keeps:

dioptra license shows it, dioptra license --set <key> stores it and dioptra license --remove deletes it.

Methods and report

Dioptra Lab. The one-line methods text on each results sheet is free.

Methods paragraph

Methods paragraph… on a results sheet copies a paragraph for that analysis; File → Copy methods paragraph… covers every analysis in the project. For each analysis it names the data table, the test, sidedness, the correction for multiple comparisons and the post tests, the confidence level and the data form, then the software and version, and lists the references to cite once each. References are those of the methods Dioptra implements, as listed in Methods and references.

Plasma IL-6: Ordinary one-way ANOVA, Tukey's multiple comparisons (family-wise
α = 0.05). Analyses were performed in Dioptra 0.4.0 (https://github.com/ZahakJ/dioptra).

References: Fisher (1925); Tukey (1953); Kramer (1956), doi:10.2307/3001469.

Report

File → Export report… writes the project as one document:

1. the title, the Dioptra version and the date;
2. Data: each table with its first 20 rows;
3. Methods: the methods paragraph;
4. Results: each results sheet, with its summary sentences, methods line, assumption checks and tables, p values in the project’s style;
5. Figures: every graph and layout, numbered, with its title as the caption.

Long tables continue on the next page with their header repeated.

Records for regulated labs

Part of Dioptra Lab. Dioptra supplies technical controls that support compliance with 21 CFR Part 11 and EU GMP Annex 11. Compliance also depends on the lab’s procedures, validation and storage.

The controls

Users and roles. Users are kept per computer, in lab-users.json in the app’s config directory. Each has a user ID, a full name, a password and a role:

Passwords are stored as PBKDF2-HMAC-SHA256 hashes (600,000 iterations, random 16-byte salt). Five failed sign-ins in a row lock an account until an administrator resets its password. Users are disabled, never deleted, so a user ID is never reused. Every creation, disabling, password reset and lockout is written to the users file’s own hash-chained access log. Dioptra refuses a users file whose accounts do not match its log.

The browser version keeps users in browser storage. It is not suitable for regulated work.

Audit trail. Records → Make this project regulated… turns on the audit trail of the open project. It cannot be turned off. From then on every change (data, formulas, exclusions, analysis options, graphs, layouts, deletions, undo and redo) needs a signed-in user and a reason, and is appended to extensions/lab-audit.jsonl inside the project file:

Opening a regulated project checks the chain. A changed, missing or reordered entry, or project content that differs from the last entry, is reported at once.

Electronic signatures. Records → Sign… asks for the password again, then records the signer’s name and ID, the date and time, the meaning (authored, reviewed or approved), the SHA-256 of the project content and the hash of the trail head, as an entry of the trail. A signed project is locked. Records → New version… records a reason and starts the next version; the earlier signatures stay in the trail, marked superseded. The audit-trail viewer and the audit report show each signature with its name, date and time, meaning and status: valid, superseded, or content changed since signing.

Verification. Records → Audit trail… lists the entries, filters by user and object, and verifies the chain. Records → Export audit report… writes it as PDF or CSV. Verifying, viewing and exporting need no license, and a signed record stays locked when a license ends. Setting up users, making a project regulated, signing and starting a new version need Dioptra Lab.

What the controls cover

Limits of a desktop system

Dioptra runs on the lab’s own computers without a server, as a closed system in the sense of 11.10. The project file and the users file are ordinary files. Anyone who can write them, such as an operating-system administrator, can delete or replace them, including removing the trail from a project. The hash chain uses no secret key: it makes an edit evident, not impossible, and someone who rewrites the whole chain consistently is not detected. Keep regulated projects and the users file on storage with access control, backups and a retention policy, and restrict administrator rights on the computers.

Validation (IQ, OQ, PQ) and the standard operating procedures are the lab’s responsibility. The validation pack supplies the compliance matrix, traceability, IQ and OQ protocols and the automated OQ (Records → Run OQ…).

Validation pack

The validation pack for Dioptra Lab is kept with the source, for QA readers: docs/validation. It holds the Part 11 and Annex 11 compliance matrix, requirements traceability, IQ and OQ protocols, PQ guidance, change control and the supplier assessment. The automated OQ runs from Records → Run OQ….

The .dioptra project file

A .dioptra file is a zip archive (deflate) of pretty-printed JSON. unzip -l lists it; unzip extracts it; git diff on the extracted tree shows exactly what changed. Keys are written in a stable order; numbers use shortest round-trip representation; empty cells are null.

manifest.json            format version, Dioptra version, created/modified timestamps
project.json             title, p-value style, display order of objects, layouts
tables/<id>.json         one table: kind, datasets, subcolumns, columns (columnar arrays),
                         row titles, column sources and formulas, excluded cells, text cells,
                         edit log
analyses/<id>.json       analysis spec (table id, kind, options); no results
graphs/<id>.json         graph spec (source id, family, mapping, style, axes, legend, options, annotations; docs/GRAPHS.md)
results/<id>.json        cached results sheets (optional; recomputed when absent or stale)
history.jsonl            command log: one JSON object per line, newest last
extensions/<name>        UTF-8 files kept for other components, e.g. Dioptra Lab's audit
                         trail; read back and saved unchanged by the core

manifest.json

{ "format": "dioptra/1.2", "app": "0.4.0", "created": "2026-10-11T09:00:00Z", "modified": "..." }

Readers must accept any dioptra/1.x; unknown keys are preserved on round trip where possible and ignored otherwise.

tables/<id>.json

{
  "id": "…", "title": "Dose response", "kind": "xy",
  "x": { "title": "Dose (nM)", "values": [1, 10, 100, null], "source": {"kind": "pasted", "at": "…"} },
  "row_titles": ["", "", "", ""],
  "datasets": [
    { "name": "Control", "format": {"kind": "values", "n": 3},
      "subcolumns": [
        { "values": [0.1, 0.5, 0.9, null], "excluded": [3], "text": {"2": "n/a"},
          "source": {"kind": "formula", "expr": "log10(A)"}, "decimals": 2,
          "edits": [{"row": 1, "at": "…", "from": 0.4, "to": 0.5}] }
      ] }
  ],
  "variables": null
}

• values is a dense array the length of the table’s row count; null means empty.
• excluded is a sorted list of row indices.
• text holds non-numeric entries by row index (kept, shown, never used in numerics).
• title on a subcolumn names it (a replicate or a nested subgroup, e.g. from Prism’s subcolumn titles); absent when unnamed. The X column’s title is the same field.
• source is one of entered, pasted {at}, imported {file, sheet, column}, formula {expr}, derived {table, op}.
• edits is the sparse per-cell edit log that, with source, gives each cell’s provenance.
• For variables tables, each dataset has a single subcolumn and a type.
• Derived tables carry derived_from: {table, op} at the top level.

history.jsonl

Each line is { "at": "…", "command": { … }, "label": "Paste 3×120 into Table 1" }. The engine replays nothing from it on open; it is an audit trail and the source of the undo timeline in the UI.

graphs/<id>.json

{
  "id": "…", "title": "Graph of Paired t test of Table 1",
  "spec": {
    "source": "…", "family": "column",
    "mapping": { "datasets": [0, 1], "error_bars": "sem", "points": true },
    "style": { "theme": "instrument", "size_mm": { "width": 85, "height": 70 },
               "datasets": [{ "dataset": 1, "pattern": "hatch" }] },
    "axes": { … }, "legend": { "position": "auto" },
    "options": { "jitter": 0, …,
                 "connecting": { "connect": "individuals", "style": "solid", "colour_by": "single",
                                 "opacity": 0.55, "missing": "gap", "direction": "within_groups",
                                 "summary_style": "solid" } },
    "annotations": [{ "kind": "significance_bracket", "from": 0, "to": 1, "text": "p = .002" }]
  }
}

Every field of the spec is listed in docs/GRAPHS.md. Fields at their defaults may be left out; connecting, orientation, error_direction, bar_fill and summary_line are written only when they differ from the default, so a graph without connecting lines is written exactly as format 1.0 wrote it.

Versions and migrations

Migration 1.0 → 1.1 runs when a file is opened: a graph whose family is before_after becomes the strip spec that draws the same picture (jitter: 0, error_bars: none, summary_line: false, connecting.connect both when mean_line was on and individuals otherwise, opacity 0.4). Nothing else changes; saving writes the current format. A 0.2 reader opens a 1.1 file (the minor number is additive) and ignores the new fields, so it draws such a graph without its connecting lines.

Compatibility promise

The format version bumps the minor number for additive changes and the major number for anything a 1.x reader could misread. Readers of version N open any file ≤ N.

Correctness

A statistics program is a measuring instrument, and an instrument is only as good as its calibration. This chapter explains how Dioptra’s numbers are checked, then gives the full record: every comparison, every NIST data set, and the cases where a difference was investigated.

The short version: all 58 NIST StRD reference data sets used (univariate, linear regression, one-way ANOVA and nonlinear regression) pass, and 7,841 comparisons in 300 oracle cases across 28 families of methods agree with SciPy, statsmodels, lifelines and scikit-learn within the tolerance stored with each case, with no failures.

What “correct” means for a number

A computer stores a number in 64 bits (IEEE 754 double precision), which holds about 15 to 16 significant decimal digits. Every arithmetic step can lose some of them. Most of the time the loss is invisible. Sometimes it is catastrophic: subtract two nearly equal large numbers and the leading digits cancel, leaving mostly rounding noise.

A classic example is the variance. The textbook “one-pass” formula

s² = (Σx² − (Σx)²/n) / (n − 1)

is exact in algebra and dangerous in a computer. Take the values 100000001, 100000002, 100000003. The answer is 1. But Σx² is about 3 × 10¹⁶, beyond the range in which doubles hold every integer, and the subtraction of two such numbers leaves almost nothing of the right digits. A program using that formula can report a variance of 0, or a negative one. The two-pass formula (compute the mean, then sum squared deviations from it) gets 1 exactly. Both formulas are “correct”; only one is correct in a computer.

So the useful question is not “is the formula right?” but “how many digits of the answer are right?”

LRE: counting correct digits

The log relative error (LRE) answers that question with one number. If the certified value is c and the program reports x,

LRE = −log₁₀( |x − c| / |c| )

An LRE of 15 means the first 15 significant digits agree; 10 means 10 digits; 0 means none. If c = 1.2345678901 and x = 1.2345678312, the relative error is about 4.8 × 10⁻⁸ and the LRE is 7.3: seven digits right. (When c is 0, the absolute error is used instead.) McCullough (1998) introduced LRE for exactly this purpose: judging statistical software on problems with known answers. As a rough scale, 4 digits is enough for any figure or table in a paper, 7 is what a sound algorithm reaches on ordinary data, and 15 is all a double can hold.

LRE is capped at the number of digits the reference certifies: 15 for most NIST sets, 11 for nonlinear regression. A cap means “as right as can be checked”.

NIST StRD: certified answers to hard problems

The US National Institute of Standards and Technology publishes the Statistical Reference Datasets (StRD): data sets with answers certified to 15 digits by computations in multiple-precision arithmetic. They are graded by difficulty. The lower sets are ordinary data. The higher ones are built to break naive algorithms: values like 1000000000000.4 that differ only in the last digits (ANOVA SmLs07–09), a tenth-degree polynomial on nearly collinear predictors (Filip), nonlinear models whose parameters are almost redundant (MGH09, Bennett5).

Dioptra’s test suite reads each NIST file, runs the same routine the app uses, and computes the LRE of every certified quantity. The test fails if any falls below a set bar. The tables below show the result for every data set.

Some LREs are lower than 15 for a reason no program can beat. The certified value of a data set with entries like 1000000.1 is computed from the decimal numbers, but a computer cannot hold 1000000.1 in binary; it stores the nearest double, which is slightly different. The exact answer for the numbers the computer actually holds therefore differs from the certified answer in the ninth or tenth digit. To separate the algorithm’s error from this input rounding, the tables have starred columns: the LRE against the exact answer for the doubles, computed in rational arithmetic. There Dioptra reaches 15 digits, or close to it, nearly everywhere.

Oracle fixtures: agreeing with the reference implementations

NIST covers only four families of methods. For everything else (t tests, rank tests, the studentised range, Fisher’s exact test, Kaplan–Meier, ROC, PCA and so on) the reference is the established open-source implementation: SciPy, statsmodels, lifelines and scikit-learn. A Python script in the repository (scripts/oracle/) runs those libraries on fixed inputs and writes the inputs and outputs to JSON fixture files with a tolerance for each case. Dioptra’s tests read the fixtures and compare.

The tolerance is chosen per quantity: tight (10⁻¹² relative) for exact rational results such as exact p values, looser where the reference itself is approximate (SciPy’s randomised Dunnett integration, for example). Where Dioptra and a reference disagree beyond rounding, the disagreement was investigated to its source, often in high-precision arithmetic. Several of the notes below record cases where the reference library, not Dioptra, was the less accurate of the two.

A method with no reference check does not ship. The few methods without an oracle fixture (intraclass correlation, Cohen’s kappa, the bootstrap, permutation tests) are tested against published worked examples and mathematical identities, listed at the end of the record.

Reproducing the record

Everything below is regenerated by

cargo run -p dioptra-stats --example correctness_report

and the same comparisons run in cargo test -p dioptra-stats on every change.

Generated from cargo run -p dioptra-stats --example correctness_report (the same comparisons as cargo test -p dioptra-stats), then annotated. This page covers special functions, distributions, descriptive statistics, t tests, Mann–Whitney, Wilcoxon, normality tests, outliers, ANOVA (one-way, two-way, repeated measures, Kruskal–Wallis, Friedman), multiple comparisons, contingency tables, correlation, linear regression, nonlinear regression (curve fitting), survival analysis, ROC curves, Bland–Altman and PCA. Intraclass correlation, Cohen’s kappa, the bootstrap and permutation tests have no oracle fixture; they are tested against published worked examples and identities (last section).

Every comparison uses the tolerance stored with its fixture case (research/05-nist-and-oracle-notes.md §3); exact discrete p-values (Mann–Whitney, Wilcoxon) are tightened to 1e-12 relative as that policy asks.

Oracle fixtures

Worst error / tolerance: the largest |got - expected| / max(abs, rel |expected|) over the family, with each case’s own tolerance (< 1 passes). Max rel. error is over expected values with |value| > 1e-290, including tiny values where the abs tolerance governs; min digits = -log10(max rel. error).

NIST StRD univariate (LRE, McCullough 1998)

LRE capped at 15 (NIST certifies 15 digits). Columns without a star score against the NIST certified values; starred columns against the exact statistics of the inputs as parsed into doubles (rational arithmetic), which separates the algorithm from input rounding: the NumAcc3/NumAcc4 values (1e6 + 0.1 and 1e7 + 0.1 steps) are not representable in binary, which caps any double-precision SD at 9.5 and 8.3 digits against the certified 0.1. Minimum LRE: 8.25 against certified values, 14.74 against the exact statistics of the double inputs.

NIST StRD linear regression (LRE)

Parameters and SDs: minimum over the coefficients. ANOVA table: minimum over the regression and residual SS and MS and F (Wampler1’s F is infinite and not scored). Min*: minimum LRE against the exact least-squares solution for the inputs as parsed into doubles (rational arithmetic; values below 1e-12 scored by absolute error).

NIST StRD one-way ANOVA (LRE)

Min*: minimum LRE against the exact statistics of the inputs as parsed into doubles.

On the linear sets the refined QR (equilibrated, pivoted Householder plus double-double refinement of the augmented system) returns the correctly rounded least-squares solution of the double inputs everywhere (Min* = 15) except Wampler5’s R^2 = 0.0022, which is formed as a difference (13.8). Against the certified values the remaining gap is input rounding: Wampler2’s y values and Pontius’s x values are decimal fractions that binary cannot hold. Filip reaches 14.0 (McCullough’s “acceptable” bar is 7; normal equations score 0, and plain Householder QR about 7-8). The simple-regression routine reaches 13.9 on Norris and 14.7 on NoInt1/NoInt2 through the same solver (tests/nist_linear.rs::nist_simple_path).

On the ANOVA sets every statistic is correctly rounded for the double inputs (Min* = 15: sums of squares on data shifted by the first observation, two-pass means, compensated sums). Against the certified values, SmLs04-09 are limited by their inputs: 1000000.4 and 1000000000000.4 are not representable in binary. On the parsed doubles the exact SS_between of SmLs05 is 16.080000001825 (certified 16.08, so at most LRE 9.94) and of SmLs07 1.6801563 (certified 1.68, at most 4.03); no double-precision program can do better on these inputs. AtmWtAg (7 constant digits) reaches 10.2 for the same reason. The tests hold the lower sets to 13, the average sets to 10 (9.9 for the input-capped SmLs05/06) and every set to 13 against the exact statistics of its double inputs.

NIST StRD nonlinear regression (LRE, both starting points)

LRE capped at 11 (NIST certifies 11 digits). Parameters and SDs: minimum over the parameters. Status “Ambiguous” is Prism’s flag for a parameter with dependency > 0.9999 (the fit converged; the parameters are nearly redundant). Starts that did not converge: 0. Worst parameter LRE over all 54 fits: 9.33.

Every one of the 27 sets converges from both NIST starting points with plain Levenberg–Marquardt (MINPACK lmder port: scaled trust region, pivoted QR, Moré’s lambda update) followed by Newton polishing. No restarts and no geodesic acceleration are needed; geodesic acceleration (available as FitOptions::geodesic) was tried and is not the default, because from MGH09’s first start it converges to a different stationary point. The asked bars were lower >= 7, average >= 6, higher >= 4; the worst parameter LRE is 9.3 (Lanczos3, whose data carry five significant digits), and 52 of the 54 fits have every parameter at 10.3 or better. MGH09, MGH10, Bennett5, Eckerle4, Rat43 and BoxBOD reach 10.4 to 11 from both starts (MGH09 start 1 takes 395 iterations, Bennett5 start 1 745).

Why the polish matters: LM stops on a relative sum-of-squares test, and near the optimum SS(b + d) - SS(b) is of order d^2, so a test on SS can only resolve the parameters to about sqrt(eps). Without the polish, ENSO, MGH09 and Thurber stop at LRE 6.8-7.4. The Newton step solves (J’J + sum r_i H_i) d = -J’r with J’r accumulated in compensated arithmetic and the second derivatives H_i from central differences of the exact Jacobian; a step is accepted while the equilibrated gradient norm falls. That resolves the parameters to about eps x condition, which is what the table shows.

Lanczos1 is the exception, and the limit is its data, not the algorithm. Its certified residual SS is 1.4307867721e-25: the y values are the model rounded to 13 digits, so the residuals are about 7.7e-14, roughly 100 units in the last place of y. Parsing the y values into doubles moves each by up to 2.2e-16, which changes the minimum SS by 6.5e-4 relative. Evaluated in 60-digit decimal arithmetic at Dioptra’s parameters, the SS is 1.43078687e-25 with the decimal data (certified: 1.43078677e-25) but 1.42986e-25 with the data as parsed into doubles: an LRE of 3.2 is the best any double-precision program can reach on these inputs. Dioptra’s 2.9 adds the rounding of the model evaluation in double. The parameters themselves reach 10.6, and the parameter SDs and residual SD inherit the SS’s 3.2 because they scale with sqrt(SS). tests/nist_nonlinear.rs holds every other set to 9 on all four quantities from both starts, and Lanczos1’s SS, SDs and residual SD to 2.5.

Notes on the fixtures

• Studentized range, far upper tail. The worst relative errors in that row (8e-6) are in the SciPy-generated reference, not in Dioptra. For k = 2 the studentized range has a closed form, P(Q > q) = P(|T_df| > q/sqrt 2). At q = 8, df = 1000 that is 2.0119785627859e-8 (40-digit mpmath and our t distribution agree); the fixture holds 2.0119947042e-8 (SciPy studentized_range.sf, off by 8.0e-6 relative), and Dioptra gives 2.01197856277e-8 (1e-11). The case passes on the fixture’s absolute tolerance (1e-11). tests/distributions.rs::quadrature_identities pins k = 2 to the t distribution at 1e-10 relative, and the ignored test studentized_range_vs_nested_quadrature checks k = 2..20, df = 1..1000 and inf against nested adaptive quadrature (worst: 1e-13 absolute on the cdf, 1e-11 relative on the upper tail).

• Dunnett. The fixture’s own double integral is accurate to about 2e-9 relative (p_greater = 1.3658528033e-5 for the unequal-n case); nested adaptive quadrature gives 1.36585280593e-5, which Dioptra matches to 3e-14. Dunnett with one treatment equals the t test exactly and is tested that way.

• ROUT robust centre. The fixture’s centre comes from SciPy’s minimize_scalar; its merit gradient there is about 1e-8, ours about 1e-13, and the two centres differ by up to 3e-10 relative (tolerance 1e-9). Flagged indices agree everywhere.

• Noncentral t. All six tables pass at 1e-10, including x = -3, df = 5, nc = 8, where the reference is 1.899970783e-20 and SciPy returns 8.0e-20.

• Shapiro–Wilk. W and p agree with SciPy to 1.3e-13 even though the fixture tolerance is 1e-7 / 1e-6 (the AS R94 polynomials are single precision; we use the full-precision normal scores, as R does, and so does SciPy).

• NIST NumAcc3/NumAcc4. The SD LREs of 9.5 and 8.3 against the certified 0.1 are the limit set by the inputs: 1000000.1 and 10000000.1 are not representable in binary, and the exact SD of the parsed doubles is 0.10000000003492 and 0.10000000055879. Dioptra reproduces those exact values to 15 digits (starred columns).

• Spearman, perfect correlation (correlation row). For n5 the ranks agree exactly, so rho = 1 and the t-approximation p is 0. SciPy reports 1.40e-24 because its rho rounds to 0.9999999999999999; Dioptra’s rounds to a slightly different neighbour of 1 and gives a p of the same order. The case passes on the absolute tolerance (1e-10); it is the only reason the correlation row shows a relative error above 1. Every other correlation comparison, including the exact Spearman and Kendall p-values, agrees to 2e-13 relative or better.

• Tukey–Kramer, Dunnett, p-value adjustment. The 2.0e-9 relative error is the fixture’s own Dunnett double integral (see the Dunnett note above); Tukey p-values agree to 8e-12 (the worst is a tail p of 5.3e-5), Tukey critical values and CIs to 1e-13, and all seven p-adjustment methods to 1e-13. The loose library cross-checks stored in the same fixture (statsmodels’ qsturng interpolation, SciPy’s randomized-QMC dunnett p and CI, tolerance 2e-3) are reported on their own “sanity” row so that they do not mask the exact comparisons; SciPy’s QMC Dunnett p for the unequal-n case is 3.8e-5 against the exact 2.73e-5.

• Two-way ANOVA trap. The fixture’s type3_treatment_coding_WRONG_for_reference (type III with dummy coding) is checked to differ from Dioptra’s sum-to-zero type III on the unbalanced case; matching it would be the classic error.

• Fisher r x c. The network algorithm is checked against plain enumeration of every table on 60 pseudo-random tables (p to 1e-10, table counts exactly, contingency::tests::network_matches_enumeration) and matches all five fixture tables, including the transposed 3 x 2 and the 2 x 2 that equals fisher_exact. The conditional MLE odds ratio and its exact CI agree with SciPy to 1e-13.

• Exact discrete p-values. Runs-test p (Swed–Eisenhart), Kendall and Spearman exact p and Fisher p are compared at 1e-12 relative or tighter where the fixture tolerance is looser, as the tolerance policy asks for rational quantities.

• Nonlinear regression. The fixture optima come from SciPy curve_fit and least_squares, polished with central-difference Jacobians; Dioptra uses exact derivatives (hand-written for the built-in library, forward automatic differentiation for parsed equations). Parameters, SEs, CIs, SS, AICc, R^2 and the covariance agree to 4e-8 relative or better, except two covariance entries of the Gaussian case (Amplitude-Mean and Mean-SD, 2e-10 and 1e-11: zero but for rounding, the X grid being symmetric about the mean), which differ by 3e-4 relative and pass on the absolute tolerance; that is SciPy’s finite-difference Jacobian. Every fit/ case is run twice: through the parsed fixture equation from the fixture’s start, and through the built-in Prism equation (4PL, one phase decay, Michaelis–Menten, specific binding with Hill slope, Gaussian) from the Prism-style initial-value rules; both reach the same optimum. The robust cases (fixed-scale Cauchy and soft-L1) agree to 6e-8.

• Cox regression. lifelines stops its Newton iterations early: its score at its own estimate is -1.6e-6, -2.1e-7 and -4.6e-6 for the three cases, and for small_censor_at_end its coefficient is 2.8e-6 relative from the maximum (the fixture asks 1e-6). Dioptra’s coefficient equals the maximum found by Newton iterations in 50-digit decimal arithmetic (-0.84574684893160798) to 1e-15, and its log-likelihood is higher than lifelines’ (-17.930671038121 against -17.930671038126). The test therefore checks the coefficient, SE and log-likelihood against the 50-digit maxima at 1e-11, checks that Dioptra’s likelihood is at least lifelines’, and compares the lifelines values at 1e-5; that last comparison is the 4.7e-6 in the survival row. Every KM, Greenwood, confidence-interval, log-rank, Gehan–Breslow–Wilcoxon, Tarone–Ware and hazard-ratio value agrees to 1e-11.

• ROC. The relative error of 1.0 in the ROC row is a Wilson lower limit at x = 0: the fixture holds 1.39e-17 (rounding in NumPy) where the exact value, and Dioptra’s, is 0; it passes on the absolute tolerance. Everything else agrees to 1e-14.

• Hand-tested (no fixture). ICC: the six Shrout & Fleiss (1979) coefficients of their worked example with R psych::ICC’s F tests and McGraw–Wong CIs, to the printed digits. Cohen’s kappa and its SEs: a hand-computed 2 x 2 table. Bootstrap: the BCa interval of a normal mean matches the t interval, BCa shifts a skewed variance interval the right way, and results are reproducible from the seed. Permutation test: exact enumeration against a hand count, Monte Carlo against the t test. xoshiro256**: the reference outputs from state (1, 2, 3, 4). DeLong’s paired comparison: identities (a monotone transform gives zero difference and zero SE; swapping the tests flips z). Profile-likelihood CIs equal the t CIs on a straight line to 1e-7 and are right-skewed for a rate constant; a global 4PL fit with shared Top and Bottom recovers noiseless parameters to 1e-9; ROUT on a curve finds the two planted outliers and none in clean data.

Performance (release build, one core)

From cargo test -p dioptra-stats --release --test benches -- --ignored --nocapture:

The r x c limits are the FISHER_RXC_WORK_LIMIT (5e7 path-child expansions) and FISHER_RXC_PATH_LIMIT (4e6 stored paths per stage). Tables near independence finish well inside them up to 5 x 6 with N = 200; strongly associated tables of that size do not (R’s FEXACT also needs an enlarged workspace or simulation there), and the chi-square test is the fallback. Prism offers Fisher’s test for 2 x 2 tables only. The Tukey time is almost all the studentized-range quantile for the simultaneous CI.

Performance

Measured with cargo test -p dioptra-core --release -- --ignored --nocapture bench_ (release profile: thin LTO, opt-level 3) on a 16-core desktop. Times are wall clock for one Session::dispatch_json call, so they include JSON parsing of the command, the work, and the undo snapshot.

How it stays fast:

• Paste parses straight into column vectors of f64; only text cells allocate.
• A formula is compiled once against the table: summaries (mean(A)) and series (lag(A, 1)) are computed whole, then a small expression tree runs once per row.
• Recompute is pull-based and per column: an edit marks downstream formula columns dirty, and they are recomputed when something reads them.
• GetCells materialises only the requested viewport.
• Undo stores the cells a command touches, or the whole previous table when a paste reshapes it (for a paste into an empty table that copy is nearly free).

Graphs (dioptra-plot)

Measured with cargo test -p dioptra-plot --release --test bench -- --ignored --nocapture on the same desktop; medians of 9–30 runs after a warm-up. “SVG” is the whole path from spec and data to the SVG string (family, layout with text measurement, scene, writer).

How it stays fast:

• Text is measured from advance-width tables built once from the bundled fonts; no shaping happens during layout.
• Markers of one series share one <g> with the paint, so each point is one short <circle> or <path>; numbers are written with two decimals by integer arithmetic.
• Above 20,000 points a series keeps one point per 0.75 pt cell (a pixel at 96 dpi) of the plot area, which is invisible at any print size and bounds the SVG; the SVG carries a comment saying how many points were drawn.
• PNG and PDF parse the engine’s own SVG once with usvg against a font database holding only the four bundled Inter files.

Measured by dioptra bench

dioptra bench measures the whole engine through the same JSON commands the app sends, so these are the numbers a user sees, not those of an isolated function. Run it yourself with a release build:

cargo build -p dioptra-cli --release
./target/release/dioptra bench            # or --markdown for this table

Measured on 2026-10-11 on an AMD Ryzen 7 7800X3D (8 cores, 16 threads), Linux, release build; each time is the median of 3 to 9 runs and includes parsing the command and, for mutations, the undo snapshot.

What the rows do:

• Paste: a fresh column table receives 10.8 MB of tab-separated text (10 columns by 100,000 rows); the engine detects separator and decimal mark, parses, and stores every cell.
• Export / save: the same 1,000,000 cells written as CSV, as an Excel workbook, and as a .dioptra project (zip with the data, the analyses and the history).
• Column formula: setting = A * 2 + 1 on a second column of 1,000,000 rows and reading a viewport, which recomputes the column; then editing one cell of A, which marks the formula column dirty, and reading again.
• Scatter: 10,000 points rendered for the graph editor (SVG plus the hit-test boxes of every clickable element), then exported as SVG, as PDF with the fonts embedded, and as PNG at 300 dpi.

Architecture and internals

This chapter is for people who want to read or change the code. It explains how the parts fit, why they are split the way they are, and how to add the two things people most often want to add: an analysis and a graph family. CONTRIBUTING.md in the repository has the setup steps and the rules for numerical code.

The shape of the system

 apps/dioptra (React UI)
        │  Command (JSON)            ▲ Response (JSON)
        ▼                            │
 ┌─ Tauri: invoke("dispatch") ──┐  or  ┌─ browser: wasm Engine.dispatch ─┐
 └──────────────┬───────────────┘      └───────────────┬─────────────────┘
                ▼                                      ▼
            dioptra-core  ── Session: one dispatcher, the document model
             │        │
             ▼        ▼
     dioptra-stats   dioptra-plot
     (numerics)      (scene, SVG, PDF, PNG)

Everything that computes is Rust. The UI is TypeScript and React and never does arithmetic on data. It sends commands and draws responses. This split exists for two reasons. First, one engine means one set of answers: the desktop app, the browser build used in tests and the command line give identical numbers because they run identical code. Second, Rust compiles to native code for the desktop and to WebAssembly for the browser without changes.

The crates

dioptra-stats is the numerical library: special functions (incomplete beta and gamma, their inverses), distributions (t, F, chi-square, noncentral t, studentised range, Dunnett), descriptive statistics, t tests, rank tests, ANOVA, post-hoc comparisons, contingency tables, correlation, linear regression with a refined QR solver, Levenberg–Marquardt nonlinear regression with the equation library, normality tests, outliers, survival, ROC, agreement, PCA, bootstrap and permutation. It knows nothing about tables or files: numbers in, numbers out. Every public function names its reference in docs/METHODS.md.

dioptra-core is the document model: tables of the eight kinds, columns with provenance, the formula language (lexer, Pratt parser, evaluator), derived tables, the dependency graph and pull-based recomputation, analyses as specifications with results sheets, the command history with inverses for undo, import and export, the .dioptra file, and the API. compute/ wires each analysis kind to dioptra-stats and writes its results sheet, including the assumption checks (compute/checks.rs).

dioptra-plot turns a graph specification and extracted data into a scene: a device-independent list of shapes and text measured in points. Text is measured with the bundled Inter fonts’ own metrics, so layout never depends on the system. The scene is written as SVG by the crate’s own writer, as PNG through resvg and as PDF through svg2pdf.

dioptra-wasm is a thin wasm-bindgen facade: an Engine with one method, dispatch(json) -> json.

dioptra-cli runs the same engine from the shell: dioptra analyze data.csv --kind column --test one_way_anova, and info, run, import, render, export, bench and equations on a project file, for scripted pipelines and continuous integration.

apps/dioptra is the Tauri 2 desktop app with the React UI. src-tauri/src/lib.rs exposes one Tauri command, dispatch. src/engine/ holds the bridge with two backends, Tauri and wasm, behind one interface, and a queue that keeps commands in order.

The Command/Response bridge

The whole API is two enums in crates/dioptra-core/src/api.rs. Command is every request the UI can make: create a table, paste text at a position, fetch a viewport of cells, set a column formula, list the analyses that fit a table, create an analysis, get its results sheet, render a graph to SVG, patch a graph specification, undo, save. Response is every answer: Ok with what changed, Error with a message, Cells, PasteReport, Results, Svg with hit-test targets, Bytes for files. Both are serde-tagged JSON.

{"type": "paste", "table": "t1", "row0": 0, "col0": 0,
 "text": "1,5\t2,5\n3,0\t4,5", "options": {}}

Session::dispatch_json parses the command, runs it, and serialises the response. Commands that mutate the project record an inverse for undo and a line in the history.

Why JSON across the bridge instead of typed bindings? Because the same string goes through Tauri’s IPC, through wasm-bindgen, and into a test, and it can be logged and replayed. The cost is a parse per call; at the sizes involved (a viewport of a few hundred cells, a results sheet) it is a fraction of a millisecond, measured in Performance.

Large data never cross the bridge whole. The grid asks for the cells in view (GetCells with a range), so a million-cell table costs the UI only what is on screen.

The WebAssembly build

scripts/build-wasm.sh compiles dioptra-wasm for wasm32-unknown-unknown and runs wasm-bindgen into apps/dioptra/src/engine/wasm/pkg. The UI then runs in a plain browser against the same engine. This build is how the end-to-end tests run: Playwright drives Chrome through paste, analysis, graph, export, save and reopen, with no desktop window involved. A hosted web version would use the same build; it is deferred.

Adding an analysis

Take a hypothetical sign test as the example.

1. The numerics go in dioptra-stats: a function from values to a result struct (the statistic, the p value, a confidence interval). Name the reference in its doc comment and in docs/METHODS.md.
2. The oracle. Add cases to scripts/oracle/gen_fixtures.py that compute the same quantities with SciPy (scipy.stats.binomtest for a sign test), regenerate the fixture JSON, and write a test that reads it and compares at the stated tolerance. Include the awkward cases: ties, zeros, n = 1, all values equal.
3. The specification. Add a SignTestSpec with spec_struct! in crates/dioptra-core/src/analysis.rs, a variant of AnalysisSpec, an entry in KINDS (the display name), a default in default_for, and the table kinds it accepts in accepts. The JSON form is {"kind": "sign_test", ...}.
4. The computation. Write fn sign_test(ctx: &AnalysisContext) -> Result<ResultsSheet, String> in crates/dioptra-core/src/compute/ and register it in register_all. Use extract to get clean values with notes about what was left out, checks for the assumption checks, and the helpers for the methods line, summary sentences in the project’s p-value style, and typed sections.
5. The UI. Add a one-line description to apps/dioptra/src/analysis/descriptions.ts and the options to schema.ts; the options panel is generated from the schema.
6. The documentation. An entry in docs/ANALYSES.md: when to use it, assumptions, options, outputs, reference, worked example.

Adding a graph family

1. Write a module in crates/dioptra-plot/src/families/ with pub fn plot(ctx: &Ctx) -> Plot: read the extracted data and the spec’s options, and return axis plans and layers of marks in data units. The shared layout code measures labels, places axes and legends, and maps everything to points.
2. Add the name to FAMILIES and a branch in build in families/mod.rs.
3. Give every layer an id and a target pointer so the graph editor can select it (the table of targets is in the graph reference).
4. Add a snapshot test: a golden SVG per theme in crates/dioptra-plot/tests/snapshots/. UPDATE_SNAPSHOTS=1 cargo test -p dioptra-plot writes it; look at it before committing.
5. Add the family to the UI’s list in apps/dioptra/src/graph/families.ts and document it in docs/GRAPHS.md.

The test strategy

Each layer is tested against the strongest reference available for it.

• Numerics against NIST StRD certified values and oracle fixtures from SciPy, statsmodels, lifelines and scikit-learn, plus identities and textbook examples (see Correctness). Exact quantities are compared at 10⁻¹² relative.
• The document model with unit tests per table kind, golden tests for the formula parser, recompute tests, undo/redo tests over every command, and a round-trip test: save, open, compare, field by field.
• The plot engine with golden SVGs per family and theme, PDF structure checks (header, cross-reference table, embedded fonts), PNG size checks (mm × dpi), and timing benchmarks.
• The UI with TypeScript’s type checker, vitest for pure logic (keyboard navigation, the command registry, option schemas), and Playwright end-to-end tests on the wasm build.
• The desktop build launches under a virtual display in CI to prove it starts and renders.

./verify runs all of it and is the release gate: formatting, clippy with warnings as errors, every cargo test, the wasm build, type check and unit tests, the frontend and desktop builds, and the end-to-end suite.

The complaint map

Before any code was written, the project collected what working scientists dislike about GraphPad Prism and about the spreadsheet step most people take before it. The sources were GraphPad’s own documentation and knowledge base (which documents many limits candidly), published papers on spreadsheet errors and data presentation, and review sites. Each complaint got a number, P1 to P29, and each design decision in Dioptra traces back to one or more of them. The research, with every source, is research/02-complaints.md in the repository.

This is not a list of Prism’s failures. Prism is well liked: around 4.6 to 4.7 out of 5 on the review sites. People complain about the edges of a tool they mostly value. Ten things they value (K1 to K10) are listed at the end, and Dioptra keeps all of them.

The story in five parts

Cost and platform (P1–P4). Prism is a subscription, priced per user per year, and some of the features that make statistics honest (effect sizes for ANOVA, in-table formulas) moved to higher tiers in Prism 11. There is no Linux version, and the Windows and Mac versions differ in what they can import and export. Dioptra is MIT-licensed, has no account and no licence server, builds for Linux, Windows and macOS from one codebase, and renders the same bytes on all three.

The spreadsheet step (P5–P13). Most data reach Prism through Excel, and Excel changes data on the way: gene symbols become dates (in 2016 about a fifth of papers with Excel gene lists had such errors), pasted values are the rounded display rather than the stored number, negative numbers formatted in parentheses arrive positive. Prism’s own contingency and survival tables drop decimal points on paste. Reshaping data to fit a table format is manual, and formulas, the main reason Excel stays in the loop, arrived in Prism late and only in one table kind. Dioptra’s answer is to make the spreadsheet step unnecessary: paste raw text, keep text as text, read spreadsheet files directly at full precision, reshape with stored transforms, and compute with formulas in every table.

Statistics (P14–P19). Prism documents assumptions in help pages but does not check them on the results; asterisks are the default summary; methods are under-reported in the literature; estimation graphics came late; nested data are easy to analyse as if every cell were independent. Dioptra puts the checks on the results sheet, leads with the estimate and its interval, writes a methods sentence, draws estimation plots and SuperPlots, and analyses nested tables on the experimental unit.

Records and files (P20–P24). Prism files are hard to inspect, change format between versions, and do not diff. Dioptra’s file is documented JSON in a zip, versioned, diffable after unzip, and carries the full command history.

Figures (P25–P29). Getting a Prism figure into a journal often means Illustrator: releasing clipping masks, fixing fonts. Colour-blind-safe palettes came late; bar charts remain the default; large tables are slow. Dioptra exports SVG with real text and PDF with embedded fonts, sizes figures in millimetres, ships colour-blind-safe palettes by default, shows points on every column graph, and handles a million cells interactively.

The full map

What is kept from Prism

Keyboard shortcuts

Every command is in the command palette: press Ctrl-K (⌘-K on a Mac), type a few letters of what you want, press Enter. The palette shows each command’s shortcut, so it is also the way to learn them. F1 shows this list inside the app.

On macOS read ⌘ for Ctrl and ⌥ (Option) for Alt.

File

Edit

Insert

Analyze and graph

View

Moving in the grid

While typing in a cell, the arrow keys commit the value and move, as in a spreadsheet. In the formula bar, Enter commits and Escape cancels.

FAQ

Does it run on Linux?

Yes, as a first-class platform: it is developed on Linux. Each release has an AppImage (any distribution), a .deb (Debian, Ubuntu, Mint) and an .rpm (Fedora, RHEL, openSUSE). See Getting started.

What does it cost?

Nothing. Dioptra is free and open source under the MIT licence. There is no account, no licence server, no trial period and no tier. Every analysis, effect size and export format is in the one version there is.

Can I use it at work, in a company, or in a clinical setting?

The MIT licence allows any use, commercial included, without asking. It also comes with no warranty, as all open-source licences do. For regulated work, validate it as you would any software: the correctness record and the test suite are there to make that easier.

Can I import my Excel files?

Yes. File → Import reads .xlsx, .xls and .ods directly, with no Office installation, the same way on every system. It reads the stored values at full precision, not the rounded values the sheet displays. Dates become ISO dates. You can also paste straight from Excel; then the clipboard carries what is displayed, so show enough decimals first.

Can I open my Prism files?

Prism’s XML format, .pzfx, and the Prism 10 format, .prism, can be imported: the data tables come across. Prism’s analyses and graphs are not converted; re-run the analyses in Dioptra. The old binary .pzf format is not read; if you have only that, open it in Prism and save it as .pzfx or .prism. Dioptra does not write Prism formats; it exports CSV, TSV and XLSX for anyone who needs the data elsewhere.

Where are my data? Does anything leave my computer?

Your data live in the .dioptra files you save, wherever you save them, and nowhere else. Dioptra makes no network connections: no telemetry, no analytics, no update check, no cloud. It works with the network cable unplugged.

How do I know an old analysis will give the same result next year?

The project file stores the data, every formula as text, every analysis as a specification, every graph as a specification, and the version of Dioptra that wrote it. Opening it recomputes everything from the data. The file format is versioned and newer versions read older files. And because the file is documented JSON, the data and the recipe can be read without Dioptra at all, by unzip and a text editor. See File format.

Why is Welch’s t test the default instead of Student’s?

Student’s t test assumes the two groups have the same variance. When they do, Welch’s test gives nearly the same answer. When they do not, especially with unequal group sizes, Student’s test can give a p value that is far too small or far too large. Welch costs almost nothing when the assumption holds and protects you when it does not. Student’s test is one option away. The longer argument is in Analyses.

Can I run a one-tailed test?

Yes; every test with a direction has the option. It is not the default because a one-tailed test is valid only when the direction was decided before the data were collected and an effect in the other direction would be treated as no effect. When you choose it, the methods sentence says so, so a reader knows.

Why are there no asterisks on my graphs?

Because the default p-value style is APA: brackets show p = .012, not *. Asterisks reduce a continuous measure of evidence to a grade, and readers stop at the grade. If your journal or lab needs them, set the project’s p-value style to GP (inspector, Project, P values); every sheet and bracket switches at once, and switching back costs nothing.

How large a data set can it handle?

A table of a million cells pastes in about 0.13 seconds and scrolls without lag, because the grid fetches only the cells on screen. A column formula over a million rows computes in under a tenth of a second. Graphs with more than 20,000 points are thinned for drawing (one point per 0.75 pt cell, invisible at print size) but never for analysis. The measurements are in Performance.

Are the statistics right?

They are checked against the strongest references available: the NIST Statistical Reference Datasets, whose answers are certified to 15 digits, and the established implementations in SciPy, statsmodels, lifelines and scikit-learn. All 58 NIST data sets pass, and 7,841 comparisons in 300 oracle cases agree within their stated tolerances. The whole record, including the places where a reference library turned out to be the less accurate one, is in Correctness. If you find a disagreement, please open a numerical discrepancy issue with the data and the reference value.

What is missing compared with Prism?

Mixed-effects models, three-way ANOVA, two-way ANOVA with repeated measures on both factors, multiple logistic and Cox regression, and a few smaller analyses. They are listed, with the reason each waits, in the roadmap.

How do I cite Dioptra?

The repository has a CITATION.cff file; GitHub’s Cite this repository button turns it into APA or BibTeX. Cite the version you used (it is in every methods sentence), for example:

ZahakJ. Dioptra: data, statistics and publication graphs without the spreadsheet (version 0.4.0) [Computer software]. 2026. https://github.com/ZahakJ/dioptra

How can I help?

Report bugs and numerical discrepancies as issues, with a small file that shows the problem. Contributions are welcome; read CONTRIBUTING.md in the repository first, because numerical code has rules: a named reference and a test against a known value for every change.

Roadmap

What comes next, in order, and what waits, with the reason for each. The changelog lists what each release contains.

Next: statistics for real designs

Designs that need more than one-factor repeated measures and unit means.

• Mixed-effects models (REML), so repeated measures with missing values and nested data with several levels are analysed as what they are, with a model-formula layer under the guided dialogs.
• Nested t test and nested one-way ANOVA as mixed models, replacing the analysis of unit means.
• Three-way ANOVA and two-way ANOVA with repeated measures on both factors.
• Multiple linear, logistic and Poisson regression, and Cox proportional hazards regression, on a shared iteratively reweighted least squares and Newton infrastructure.
• Interpolation from standard curves, area under the curve, and row statistics.

Then: extension and scale

• A scripting surface (Python or Lua).
• A plugin system for analyses and graph families.
• Faster rendering for very large scatter plots (more than a million points) with a canvas or WebGL renderer, if real use shows the need.
• A system font picker for figures. Arbitrary fonts can already be embedded in PDF; the missing part is the interface.

Deferred, with reasons

Suggestions are welcome as GitHub issues. A request that comes with a data set and the answer another program gives is the easiest kind to act on.

Changelog

All notable changes to Dioptra. Versions follow semantic versioning; the file format has its own version (see the manual’s File format chapter).

0.4.0 — 2026-10-14

Prism files both ways, plate readers, and Dioptra Lab.

Free

• Prism import reads .prism files (Prism 10 and later) as well as .pzfx. Nested and multiple-variables tables keep their kind; subcolumn titles are kept; CV, low–high and limits formats are converted, with a note; calendar dates become row titles. Tested on 53 real Prism files from Prism 6 to 11.
• Plate-reader import: SoftMax Pro (.txt), BMG MARS (CSV), Agilent BioTek Gen5 (.txt) and Tecan Magellan (.xlsx), endpoint and kinetic, with an optional plate map of wells to groups and doses. File → Import file… recognises them by content.
• Replace table data… loads a new file into an existing table and keeps its formulas, analyses and graphs.
• Verify records: the audit trail and signatures of a regulated project can be checked, viewed and exported without a license.
• Fixed outlines (0.4–0.6 pt) now follow the graph’s line width.

Dioptra Lab

A yearly license for labs, core facilities and regulated groups; see the pricing page. Keys are checked on the computer; nothing is sent anywhere. Help → Dioptra Lab… takes the key.

• Batch analysis: apply a project as a template to many data files, with a summary table and figures per file; a watch folder for instrument exports; dioptra batch.
• Journal figures: presets for nine journals, a figure check (text size, line width, resolution, colours colour-blind readers cannot tell apart, mismatched panels), TIFF export, layouts at final size with panel letters, a methods paragraph, and a Word or PDF report of the project.
• Prism export: File → Export to Prism… writes data tables as .pzfx; dioptra convert converts folders in either direction.
• Records for regulated labs: users and roles, a hash-chained audit trail with reasons, electronic signatures that lock a record, and a validation pack (compliance matrix, traceability, IQ/OQ protocols) with an automated OQ of 8,212 checks (Records → Run OQ…, dioptra oq).

File format

dioptra/1.2: layouts gain style; files may carry extensions/<name>. Dioptra 0.3 opens 1.2 files.

Command line

dioptra batch, dioptra convert, dioptra oq, dioptra license.

0.3.0 — 2026-10-12

Connecting lines: Prism’s before–after graphs, made an option of every bar graph.

Graphs

• Connecting lines on column, strip, box and violin graphs (options.connecting): a line per subject joining the values of each row across the bars, the means or medians joined across the bars, or both. Lines are drawn above bars, boxes and violins and beneath the points; the summary line on top. Style (solid, dashed, dotted), width, opacity and colour: one colour, by data set, per subject from a palette, or by a grouping column with a legend. A missing value leaves a gap (or the line joins across it). On grouped tables the lines run within each group across its data sets (matched subcolumns) or along each data set across the groups. With jitter on, each line ends at its own jittered point. Lines are cut where they cross an axis break. Every subject line is a target in the graph editor.
• Paired t, ratio paired t, Wilcoxon, repeated-measures ANOVA and Friedman now graph as bars with connecting lines; the results sheet’s button says Graph with connecting lines. The New graph dialog offers Bars with connecting lines and Before–after (points) as presets for column and grouped tables.
• Horizontal column, strip, box and violin graphs (options.orientation); axes.y stays the value axis, as in Prism.
• Bar options from a comparison with Prism’s Format Graph: error-bar direction (both, above, below) and cap width; bar width and slot width (the gaps between bars and between groups); bar fill (tint, solid, outline); fill patterns per data set (diagonals, crosshatch, horizontal, vertical, dots), drawn as geometry so SVG, PDF and PNG agree; strip graphs without points (mean ± error only) or without the mean line.
• Open markers (circle_open and friends) now draw open on column graphs.
• Any line now breaks where it crosses an axis break, and horizontal bars are cut at breaks of the value axis.
• New inspector sections: Connecting lines and Bars and points (orientation, summary, jitter, fill, widths, error-bar direction and caps); a pattern control per data set.

File format

• Format 1.1. Graph specs gain the fields above; defaults are not written, so graphs without them are saved as before. The before_after family is retired: opening a 1.0 file turns such graphs into the strip spec that draws the same picture (unjittered points, subject lines, the mean line when it was on). docs/FILE-FORMAT.md documents the migration.

Research and docs

• research/06-connecting-lines.md: what Prism’s column, grouped and categorical graphs offer for connecting lines, with sources, and how Dioptra maps each option.
• Manual: Connecting lines and paired graphs, with a worked example.

0.2.1 — 2026-10-12

Fixed

• macOS: the app opened as “Dioptra is damaged and can’t be opened”. The bundle is now ad-hoc signed as a whole (bundle.macOS.signingIdentity: "-"), and the release job fails unless codesign --verify --deep --strict passes on the .app inside the .dmg. The app is still not notarized: the first launch needs right-click → Open (macOS 15 and later: Privacy & Security → Open Anyway) or xattr -cr /Applications/Dioptra.app. See docs/macos-gatekeeper.md.

0.2.0 — 2026-10-12

The design release: the same engine, a redesigned instrument.

Interface

• A design system (DESIGN.md §12): warm paper neutrals in light, deep graphite in dark, one verdigris accent, Inter for the interface and JetBrains Mono with tabular figures for every number, an 8-pt spacing scale, Lucide icons, designed focus rings and thin themed scrollbars. Every text/background pair meets WCAG AA in both themes (docs/DESIGN-AUDIT.md, scripts/contrast.mjs).
• No native form control anywhere: own Select, Segmented, Toggle, Checkbox, NumberField with unit suffixes, ColorSwatch, Menu, Dialog and Tooltip.
• The in-window menu bar is gone. A slim top bar carries the mark, the project title (click to rename), the command field and the theme control; the menu tree lives in a compact Menu popover and the command palette. macOS gets a native system menu.
• Dark mode follows the operating system (and the Tauri window theme) by default, with a light/dark/system control in the top bar, View and the palette; every surface is designed for dark rather than inverted.
• The grid is a bounded sheet: rows end where the data ends plus a margin, with “+ rows” and “+ Data set” affordances; data-set headers carry a kind glyph and the colour swatch the graph will use; a designed selection with corner handles; comfortable and compact density; a first-class formula bar; human-readable provenance times.
• Results sheets in a reading column with the type system, hairline tables, mono numbers, assumption cards with designed marks and the alternative on a second line.
• The graph editor is a desk with millimetre rulers, a paper choice (white, theme, transparent), a designed zoom control, hover halos and a selection frame on targets, and collapsible inspector sections that remember their state.
• A designed first launch: paste data, open the bundled sample project, or read the manual.
• A new icon set from the dioptra mark; window size, position and panel widths are remembered.
• The paste dialog’s segmented choices sit at their own width instead of stretching across the column.
• A designed README banner (also the landing page’s Open Graph image), and a landing page whose captures follow its light or dark theme.

Engine

• SetProjectTitle command (undoable); the risk-difference Wald interval is clamped to [-1, 1].

0.1.0 — 2026-10-11

The first public release.

Data tables

• Eight table kinds: XY, Column, Grouped, Contingency, Survival, Parts of whole, Multiple variables and Nested, each explained with a sketch when a table is created.
• Subcolumn formats: replicate values, mean/SD/N, mean/SEM/N, mean/CI/N, mean/SD, mean/SEM, median/IQR, lower/upper and single values.
• A virtualised grid that holds a million cells, with the full spreadsheet keyboard set, fill down, undo and redo across every action, and a status line with n, mean, SD and sum.
• Text cells kept as text, never coerced; excluded values struck through and kept.
• Cell provenance: typed, pasted (with time), imported (file, sheet, column), formula or derived, plus a per-cell edit log.

Getting data in and out

• Paste with automatic separator, decimal-comma and header detection, and a report of what was decided; ambiguous values such as 1,234 are kept as text and reported.
• Paste as a new table with a suggested table kind.
• Import of CSV, TSV, text, XLSX, XLS, ODS (built-in reader, stored values at full precision) and Prism .pzfx data tables.
• Export of tables to CSV, TSV and XLSX.

Formulas and transforms

• Column formulas and cell formulas with fill-down, a dependency graph, pull-based recomputation and circular-reference detection.
• Arithmetic, logic, row functions, summaries, series functions (lag, lead, diff, cumsum, rank, zscore, baseline), slices, and unit conversion including mass-to-molar conversion for glucose, cholesterol, triglycerides, creatinine and urea.
• Derived tables with stored recipes: transpose, pivot long to wide and wide to long, stack, filter, sort, select rows and columns, remove baseline, fraction of total, normalise, average replicates and prune.

Command line

• dioptra info, run, import, analyze, render, export, bench and equations drive the same engine from scripts and continuous integration.

Analyses

• Twenty analyses: descriptive statistics; t tests (one-sample, Welch, Student, paired, ratio paired); Mann–Whitney; Wilcoxon signed-rank; one-way ANOVA with Welch and Brown–Forsythe; repeated-measures one-way ANOVA with Greenhouse–Geisser and Huynh–Feldt; two-way ANOVA (types I, II, III; one repeated factor); Kruskal–Wallis; Friedman; chi-square; Fisher’s exact test (2 × 2 and r × c); correlation (Pearson, Spearman, Kendall); simple linear regression with bands and diagnostics; nonlinear regression; normality tests; outlier identification (Grubbs, ROUT); survival (Kaplan–Meier, log-rank, Gehan–Breslow–Wilcoxon, hazard ratios); ROC curves; Bland–Altman; principal component analysis.
• Multiple comparisons: Tukey–Kramer, Dunnett, Šidák, Holm, Bonferroni, Dunn and Benjamini–Hochberg.
• Nonlinear regression with the equation library (4PL, 5PL, exponential, Michaelis–Menten, Hill, binding, Gaussian, polynomials and more), custom equations, weighting, robust fitting, constraints, shared parameters, profile-likelihood intervals, model comparison by extra sum of squares and AICc, and ROUT.
• Results sheets with assumption checks shown first, APA-style summary sentences, a methods sentence, effect sizes with confidence intervals, and a reporting checklist.
• P-value styles APA (default), NEJM, GP and exact, applied project-wide.
• Analyses listed by fit to the table, with the reason for each that does not fit.

Graphs

• Twenty-three families: scatter, line, column, box, violin, strip, raincloud, before–after, estimation, SuperPlot, histogram, density, heatmap, correlation matrix, Kaplan–Meier with at-risk table, ROC, Bland–Altman, volcano, forest, pie, donut, QQ and residual plots; column graphs can be grouped, stacked or percent-stacked.
• An interactive editor: click any element to edit it in the inspector, drag the legend and annotations, edit text in place; significance brackets, reference lines and labels.
• Themes Instrument, Night and Journal; palettes Okabe–Ito (default), Tol bright, muted and light, viridis, cividis, Tol sunset and grey.
• Sizes in millimetres, type and lines in points, journal presets; multi-panel layouts with panel letters.
• Export to SVG (real text), PDF (embedded subset fonts) and PNG at any resolution; identical bytes on every platform.

Files and reproducibility

• The .dioptra project file: a zip of documented, pretty-printed JSON with the data, formulas, analysis and graph specifications, and the command history.

Correctness and performance

• All 58 NIST StRD data sets used (univariate, linear regression, ANOVA, nonlinear regression) pass; 7,841 comparisons against SciPy, statsmodels, lifelines and scikit-learn agree within tolerance.
• A million-cell paste in about 0.13 s; a column formula over a million rows in under 0.11 s.

Platforms

• Linux (AppImage, deb, rpm), Windows (msi, setup exe) and macOS (Apple silicon and Intel dmg), built from one codebase.