spacr.methods_export¶

Workflow inputs and outputs¶

Methods & Results¶

Draft methods/results text from recorded settings and results; review every claim before publication.

Open: Regression → Methods & Results.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

Run history and artifacts — Project run records, settings, output paths, artifact provenance, status and logs.
Regression results and hits — Selected run results folder: coefficient/result CSVs, hit tables, settings and diagnostic figures.

Outputs

Shareable reports — Exported HTML/PDF or methods/results documents derived from recorded analysis outputs.

Before this module

Regression: Review exported prose and every traced result.

API reference.

Module tutorial.

Write Methods and Results text from a run digest and verify its numbers.

The output is two paragraphs of a paper: a methods section that states what was done, and a results section that states what came out. A language model asked to write about an experiment can produce plausible numbers that did not come from the run, and a reader cannot tell which ones did.

The model therefore never sees the data. It sees a run digest: a structured record of the modules that ran, the parameters they ran with, the counts, the versions, the QC verdicts and the statistics already computed by the rest of spaCR. It writes prose around those numbers, and then:

verify_numbers() extracts every number from what came back and checks each one against the digest. A number that is not in the digest — not as a value, not as a correct rounding of one, not as a verbatim quote of a digest string — is unsupported, and
check_draft() rejects a draft that carries one, so a draft with an invented figure is never returned as a draft.

Two consequences follow. First, the digest is the contract: anything the prose may quote has to be in it, which is why the digest carries the alpha, the confidence level and the seed as numbers rather than leaving the model to supply the obvious ones. Second, there is a deterministic renderer — render_methods() and render_results() — that writes the same sections from the same digest with no model at all. It is what runs when no AI provider is configured, it is what a rejected draft falls back to, and it is what the number-provenance tests assert against, because a test that plants a number in the digest and requires it in the output must not be testing a stub.

Caveats are required. A methods section that omits a QC failure, or the fact that illumination correction did not run, or the on_error=skip that dropped eleven fields, is incorrect. build_digest() collects those into DIGEST_CAVEATS and both renderers, and the prompt, are required to state every one.

Public API:

from spacr.methods_export import build_digest, render_methods

digest = build_digest(project="/data/plate7", run_dir=run.dir,
                      results_folder=".../results/pred/ols")
print(render_methods(digest))
print(render_results(digest))

The AI half lives in spacr.qt.ai.manuscript, which reuses the console’s existing provider plumbing rather than opening a second client.

Classes¶

Verification

The verdict on one generated section's numbers.

Functions¶

`build_digest`(, regression_type, hits, model_path, ...)	Assemble everything a methods and results section may quote.
`caveats_for`(→ List[str])	Return the caveat sentences that a methods section must include.
`check_draft`(→ Tuple[Verification, Verification])	Verify both sections. `(methods verdict, results verdict)`.
`digest_numbers`(→ Set[float])	Return every number the digest asserts, as floats.
`digest_strings`(→ List[str])	Every non-trivial string the digest carries, longest first.
`extract_numbers`() → List[str])	Every number a paragraph asserts, as it was written.
`render_methods`(→ str)	Write the methods section from the digest, with no model involved.
`render_prompt`(→ Tuple[str, str])	`(system prompt, user message)` for one digest.
`render_results`(→ str)	Write the results section from the digest, with no model involved.
`system_prompt`(→ str)	Return the system prompt; it requires every number to be in the digest.
`verify_numbers`(→ Verification)	Check that every number in `text` came from `digest`.

Module Contents¶

class spacr.methods_export.Verification[source]¶

The verdict on one generated section’s numbers.

Parameters:

ok – no unsupported number was found.
checked – how many number tokens were examined.
supported – the tokens that trace to the digest.
unsupported – the tokens that do not.
missing_caveats – caveats the digest carries that the text omits.

__bool__() → bool[source]¶: True when the text is clean.

problem() → str[source]¶: One sentence naming what is wrong, or "".

to_dict() → Dict[str, Any][source]¶: A JSON-serializable copy.

Assemble everything a methods and results section may quote.

Every source is optional and every one of them is read defensively: a subsystem that cannot answer contributes a note rather than an exception, because a digest is written at the end of a long run and should not be lost to, for example, a missing model card.

Parameters:

project – the project root. Supplies the provenance summary from spacr.pipeline_graph and the segmentation QC from spacr.seg_qc.
run_dir – a spacr.run_journal run folder. Supplies the manifest: versions, timings, seeds, warnings, status.
macro_path – the emitted macro.py; defaults to the one inside run_dir. Supplies the per-module steps, the settings each ran with and which of them the user actually chose.
settings – settings to read directly, when there is no journal.
results_folder – a regression results folder, for the statistics.
metadata_files – annotation CSVs to join into the hit list.
regression_type – the backend, for how the hit list is ranked.
hits – an already-built spacr.hits.HitList, instead of reading results_folder.
model_path – a classifier checkpoint whose model card carries the held-out metrics.
title – what to call the experiment in the prose.
top_hits – how many hits to carry into the digest.
extra – anything else to record, under "extra".

Returns:

the digest, JSON-serializable throughout.

spacr.methods_export.caveats_for(digest: Mapping[str, Any]) → List[str][source]¶

Return the caveat sentences that a methods section must include.

Every limitation the pipeline records about the run, stated as prose the paragraph has to carry: which QC flags fired, whether illumination correction ran, the seed, the on_error policy and what it dropped, the classifier’s held-out metrics, and whether any artifact the numbers rest on is stale.

Parameters:: digest – a digest under construction.
Returns:: one sentence per caveat, in the order a methods section would state them.

spacr.methods_export.check_draft(methods: str, results: str, digest: Mapping[str, Any]) → Tuple[Verification, Verification][source]¶

Verify both sections. (methods verdict, results verdict).

The methods section additionally has to state the run’s caveats.

Parameters:

methods – generated methods-section text to verify.
results – generated results-section text to verify.
digest – source digest against which numbers and caveats are checked.

spacr.methods_export.digest_numbers(digest: Mapping[str, Any]) → Set[float][source]¶

Return every number the digest asserts, as floats.

Numeric leaves, plus strings that are entirely a number (a gene id such as "233460" is a string in the tables and a number in prose). Digits embedded in a longer string — a path, a run id, a version — are not harvested here: those are handled by digest_strings(), which lets the prose quote them verbatim without also licensing every digit inside them as a free-standing figure.

Parameters:: digest – a digest as build_digest() returns.
Returns:: the numbers, as floats.

spacr.methods_export.digest_strings(digest: Mapping[str, Any]) → List[str][source]¶

Every non-trivial string the digest carries, longest first.

Quoting one of these verbatim — a path, a run id, a settings digest, a package version, a gene name — is not inventing a number, so verify_numbers() removes them from the text before it looks for figures. Longest first so a version is removed whole rather than having its prefix eaten by a shorter match.

Parameters:: digest – a digest.
Returns:: the strings, longest first.

spacr.methods_export.extract_numbers(text: str, strings: Sequence[str] = ()) → List[str][source]¶

Every number a paragraph asserts, as it was written.

strings — usually digest_strings() — are removed first, so a sentence that quotes run 8f21c0a3 or /data/plate7 is not accused of asserting 8 and 7. Structural tokens (list markers, dotted versions, ISO dates, long hex ids) go next. What is left is a claim.

Parameters:

text – the prose to check.
strings – substrings that may be quoted verbatim.

Returns:

the number tokens, in the order they appear.

spacr.methods_export.render_methods(digest: Mapping[str, Any]) → str[source]¶

Write the methods section from the digest, with no model involved.

What runs when no AI provider is configured, what a rejected draft falls back to, and what the number-provenance tests assert against. Every number in the output comes from digest; every caveat in the digest is stated. No trailing newline.

Parameters:: digest – collected run facts from which to render the section.

spacr.methods_export.render_prompt(digest: Mapping[str, Any]) → Tuple[str, str][source]¶

(system prompt, user message) for one digest.

A pure function of the digest. The model receives this and nothing else, so there is no path by which raw data could reach it, and a test can assert that a number planted in the digest is the only place a number in the prompt can have come from.

Parameters:: digest – the digest to write about.
Returns:: the two prompt halves.

spacr.methods_export.render_results(digest: Mapping[str, Any]) → str[source]¶

Write the results section from the digest, with no model involved.

Every number comes from digest. No trailing newline.

Parameters:: digest – collected run facts from which to render the section.

spacr.methods_export.system_prompt() → str[source]¶: Return the system prompt; it requires every number to be in the digest.

spacr.methods_export.verify_numbers(text: str, digest: Mapping[str, Any], *, require_caveats: bool = False) → Verification[source]¶

Check that every number in text came from digest.

It is applied to what a model returns, and a draft that fails it is not returned as a draft — see check_draft().

Parameters:

text – the generated prose.
digest – the digest it was generated from.
require_caveats – also require every sentence in the digest’s caveats to be represented. Applied to the methods section, which is where the caveats belong.

Returns:

a Verification.