# report pack

17 nodes, in `noodlelab` and above.

## Report

(node-report.add_compliance_matrix)=
### Add Compliance Matrix

`report.add_compliance_matrix`

Add a table of verified requirements (the ``log`` of a chain of Verify
Requirement nodes): each one's ID, statement, the required and achieved
values, the margin, the verification method and whether it was met (or,
for an uncertain value whose margin is within its uncertainty, is
inconclusive).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `verifications` | `Verifications` |  |
| `caption` | `str` | Default `'Requirements compliance'`. |
| `summary` | `bool` | Add a sentence counting what was met Default `True`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_data_sources)=
### Add Data Sources

`report.add_data_sources`

List where the report's data came from: every file read, and the
sources, licences, citations and quality notes given with Describe Data,
gathered from everything put into the report before this node.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `heading` | `str` | Default `'Data sources'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_equation)=
### Add Equation

`report.add_equation`

Add a displayed equation, numbered (1), (2), ... See the Typst math
reference: sub- and superscripts with _ and ^, fractions with /, Greek
letters by name (alpha, sigma), sqrt(x), sum_(i=1)^n.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `math` | `str` | Typst math, without the $ signs: T = 2 pi sqrt(L/g) Default `'E = m c^2'`. |
| `where` | `str` | Explains the symbols, after "where" Default `''`. |
| `numbered` | `bool` | Default `True`. |
| `markup` | `bool` | Interpret the text as Typst markup (math: $E = m c^2$, *bold*, _italic_) Default `True`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_figure)=
### Add Figure

`report.add_figure`

Add a Matplotlib figure (embedded as vector SVG).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `figure` | `Figure` |  |
| `caption` | `str` | Default `''`. |
| `width` | `int` | Default `90`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_heading)=
### Add Heading

`report.add_heading`

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `text` | `str` | Default `'Results'`. |
| `level` | `int` | Default `1`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_image)=
### Add Image

`report.add_image`

Add a PNG, JPEG, GIF or SVG image from a file, such as a photo of the
setup, a logo, or a figure saved by an earlier node.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `path` | `FileRef` |  |
| `caption` | `str` | Default `''`. |
| `width` | `int` | Default `80`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_key_values)=
### Add Key Values

`report.add_key_values`

Add a compact label / value / unit table: from a dict (such as the
``summary`` output of the analysis nodes; quantities keep their units), a
Series, or a table whose columns are label, value and optionally unit.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `data` | `Any` |  |
| `caption` | `str` | Default `''`. |
| `digits` | `int` | Significant digits Default `4`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_list)=
### Add List

`report.add_list`

Add a bulleted or numbered list, one item per line (a leading "-", "*"
or "1." is removed).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `items` | `str` | One item per line Default `''`. |
| `numbered` | `bool` | Default `False`. |
| `markup` | `bool` | Interpret the text as Typst markup (math: $E = m c^2$, *bold*, _italic_) Default `False`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_note)=
### Add Note

`report.add_note`

Add a highlighted box: a note, tip, warning or important remark.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `text` | `str` | Default `''`. |
| `style` | `Literal['note', 'tip', 'warning', 'important']` | Default `'note'`. |
| `title` | `str` | Default `''`. |
| `markup` | `bool` | Interpret the text as Typst markup (math: $E = m c^2$, *bold*, _italic_) Default `False`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_page_break)=
### Add Page Break

`report.add_page_break`

Start a new page (not at the top of an already empty page).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_requirements)=
### Add Requirements

`report.add_requirements`

Add a table of requirements: each one's ID, the quantity it constrains,
what is required, how it is verified and its statement.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `requirements` | `RequirementSet` |  |
| `caption` | `str` | Default `'Requirements'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_run_details)=
### Add Run Details

`report.add_run_details`

Add a section describing the run that made this report: when and by
whom, the software versions, the input files with their SHA-256
checksums, and every processing step with its settings. The full record
is in provenance.json, next to the PDF in the run folder. Runs every
time, so the details always describe the current run.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `title` | `str` | Default `'Reproducibility'`. |
| `appendix` | `bool` | Start the appendix (lettered sections) Default `True`. |
| `nodes` | `bool` | Default `True`. |
| `files` | `bool` | Default `True`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_table)=
### Add Table

`report.add_table`

Add a table from a DataFrame, a GeoDataFrame (without its geometry) or
a dict: of columns (``{"x": [...], "y": [...]}``), or of single values,
such as the ``summary`` output of the analysis nodes, shown as a name /
value table. Longer tables are cut at ``max_rows``, with a note saying so.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `data` | `DataFrame \| GeoDataFrame \| dict` |  |
| `caption` | `str` | Default `''`. |
| `max_rows` | `int` | Default `50`. |
| `columns` | `str` | Comma-separated columns to show, in order; empty: all Default `''`. |
| `digits` | `int` | Significant digits Default `4`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_text)=
### Add Text

`report.add_text`

Add a paragraph. Connect a Format Text or Format Values node to include
computed values.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `text` | `str` | Default `''`. |
| `markup` | `bool` | Interpret the text as Typst markup (math: $E = m c^2$, *bold*, _italic_) Default `False`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.add_value)=
### Add Value

`report.add_value`

Add a highlighted key result, e.g. "R²: 0.998". A quantity is shown in
``unit`` if one is given, otherwise in its own unit. A value with an
uncertainty is shown as "9.806 ± 0.012", rounded to its uncertainty.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `label` | `str` | Default `'Value'`. |
| `value` | `Any` | Optional. |
| `unit` | `str` | Default `''`. |
| `digits` | `int` | Significant digits (values without an uncertainty) Default `4`. |
| `coverage` | `float` | For a value with an uncertainty: show U = k·u (k = 2 for about 95 %) Default `1.0`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.new_report)=
### New Report

`report.new_report`

Start a report. Chain Add nodes after it, then Render PDF.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `title` | `str` | Default `'Analysis report'`. |
| `author` | `str` | Default `''`. |
| `subtitle` | `str` | Default `''`. |
| `abstract` | `str` | Default `''`. |
| `date` | `str` | Shown under the title; empty: the render date Default `''`. |
| `contents` | `bool` | Default `False`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `ReportDoc` |  |

(node-report.render_report)=
### Render PDF

`report.render_report`

Typeset the report with Typst into this run's output folder. With
timestamp on, each run's PDF has its own name, so copies never clash.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `report` | `ReportDoc` |  |
| `filename` | `str` | Default `'report.pdf'`. |
| `template` | `str` | Default `'default'`. |
| `timestamp` | `bool` | Add the date and time to the file name, e.g. report-2026-09-24_153012.pdf Default `True`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Path` |  |