Laboratory-style reporting
cellreportR can construct a versioned report specification containing report identity, laboratory metadata, subject/specimen identifiers, finalized results, selected QC summaries, user-supplied interpretation, limitations, authorization metadata, custom fields, and technical provenance. The same report object is rendered programmatically or configured through the bundled Shiny application.
The reporting layer does not calculate results, supply decision limits, infer classifications, or invent interpretation. Those values and policies remain explicit caller inputs. Structured report data can be reviewed before rendering and exported with a deterministic hash and machine-readable audit record.
PDF reports use a package-owned A4 KOMA-Script template with a controlled first-page identity block, repeating page identity, Page X of Y footers, compact metadata, a prominent result panel, deliberate pagination, and a kept-together authorization block. cr_report_style() controls colour or intentional grayscale output, density, locale-aware date display, optional branding, signature lines, and an optional draft watermark. Reusable organization settings can be stored in cr_report_profile() without mixing branding policy with analytical configuration.
spec <- cellreportR::cr_report_spec(
report = list(report_id = "EXAMPLE-001", version = "1.0", status = "DRAFT"),
laboratory = list(name = "Example Laboratory"),
specimen = list(specimen_id = "SPECIMEN-001"),
examination = list(name = "Example assay"),
result = list(value = 1.42, unit = "a.u.", classification = "HIGH"),
interpretation = list(text = "User-supplied interpretation."),
authorization = list(authorized_by = "Example Authorizer")
)
report <- cellreportR::cr_lab_report(spec = spec)
cellreportR::cr_render_lab_report(report, tempfile(fileext = ".pdf"))Publication-ready visual design
Package figures use one restrained, colour-vision-conscious visual system with redundant shapes or line types for categorical distinctions. Colour and grayscale modes, standard manuscript/report dimensions, vector PDF/SVG export, and high-resolution PNG/TIFF export are available without changing plotted data.
estimates <- data.frame(
group = c("Reference", "Group A", "Group B"),
estimate = c(0.1, 0.8, 1.3),
conf_low = c(-0.2, 0.3, 0.7),
conf_high = c(0.4, 1.3, 1.9)
)
p <- cellreportR::cr_plot_estimates(estimates, reference = 0)
cellreportR::cr_save_figure(p, tempfile(fileext = ".pdf"), size = "single")cellreportR is an analysis and reporting pipeline for cell culture assays read out by microscopy. It picks up where segmentation leaves off: segmented single-cell exports flow in, and quality-controlled estimates, publication figures, machine-readable tables and a generated file of every quoted number flow out.
The organising idea is the unit of replication. Cells are not replicates. cellreportR resolves acquisitions into units, standardizes every cell against the control condition of its own batch, and reports each effect at both unit and cell level so the cost of pooling is visible rather than assumed.
Pipeline
Cell culture -> Treatment -> Staining -> Microscopy -> Segmentation
(segmantR / CellProfiler / QuPath)
|
v
+----------------------------------+
| cellreportR |
| |
| Ingest + design from paths |
| Units, exclusion, balancing |
| Per-batch standardization |
| Quality-control gate |
| Effect sizes: unit vs cell |
| Sample size from the CI bound |
| Figures / tables / macros |
| Interactive front-end |
+----------------------------------+
|
v
Report + tables + generated numbers
Installation
cellreportR is pure R — it compiles nothing — so it installs the same way on Windows, macOS, and Linux. The only hard prerequisite is R >= 4.1.0.
Install the development version from GitHub:
# install.packages("pak")
pak::pak("CTTIR/cellreportR")Platform notes
- Windows — no Rtools required: the package itself compiles nothing, and its dependencies install as pre-built binaries from CRAN.
- macOS — install XQuartz for the Cairo graphics devices used by compressed TIFF figures and laboratory PDF reports with CRAN R. Restart R after installation. Ordinary analyses do not use XQuartz.
-
Linux — several dependencies (
dplyr,readr,tidyr,ggplot2) contain C++ and build from source unless you use a binary repository such as the Posit Public Package Manager or r2u, which avoids needing a compiler. Otherwise install a build toolchain (for examplebuild-essentialon Debian/Ubuntu).
Installing the package pulls in its required imports automatically. Optional features need a few extra packages:
| Feature | Needs |
|---|---|
Interactive front-end (cr_run_app()) |
bslib, DT
|
Rendered research reports (cr_report(), cr_render_report()) |
rmarkdown, knitr, and a working pandoc |
Laboratory PDF reports (cr_render_lab_report()) |
the above plus XeLaTeX, TeX Gyre fonts (tex-gyre), and the TeX Live components checked by render preflight |
Excel export (cr_export_tables(), cr_export_results()) |
writexl |
Reading .fcs inputs |
flowCore (Bioconductor) |
Quick start
library(cellreportR)
exp <- cr_example_experiment(seed = 42)
exp <- cr_qc_filter(exp, min_area = 50, max_area = 5000)
res <- cr_test_all(exp,
channel = "marker_1",
control_group = "Untreated",
level = "replicate")
cr_plot_effect_sizes(res)Screening workflow
This runnable example uses a synthetic screen with independent experimental units, controls in every batch and source-file provenance. For actual segmented files, declare the filename grammar and design explicitly as shown in the end-to-end guide. cr_dataset() is an ingest container; convert it with cr_build_experiment() and an explicit design before applying experiment-level analysis functions.
library(cellreportR)
ds <- cr_example_screen(seed = 42, n_compounds = 2, n_cells_per_well = 20)
batch <- ds$batch_vars
# Exclude debris, balance cells, then use each batch's own control.
ds <- cr_exclude_small(ds, var = "area", probs = 0.10)
ds <- cr_balance_cells(ds, n_max = 30, seed = 42)
ds <- cr_standardize_batch(ds, channel = "target_signal",
control_level = "Vehicle", batch_vars = batch)
gate <- cr_qc_gate(ds, channel = "target_signal", control_level = "Vehicle",
batch_vars = batch)
cr_qc_gate_impact(ds, gate, group_var = "treatment",
reference_level = "Vehicle", by = "compound")
ds <- cr_apply_gate(ds, gate)
# The summarized response column is named value.
units <- cr_summarize_wells(ds, channel = "log2_fc")
eff_unit <- cr_effect_grid(units, value = "value", group_var = "treatment",
reference_level = "Vehicle", by = "compound", level = "unit")
eff_cell <- cr_effect_grid(ds, value = "log2_fc", group_var = "treatment",
reference_level = "Vehicle", by = "compound")
cr_compare_levels(eff_unit, eff_cell, by = c("compound", "contrast"))
sizes <- cr_power_grid(eff_unit)
forest <- cr_plot_forest(eff_unit, estimate = "cohens_d", ci_low = "cohens_d_ci_low",
ci_high = "cohens_d_ci_high", label = "contrast", facet_by = "compound") +
ggplot2::labs(subtitle = "Unit-level effects after QC; bars show 95% confidence intervals.")
forest
out <- tempfile("cellreportR-output-")
dir.create(out)
tables <- c(cr_tables(ds), list(unit_effects = eff_unit, cell_effects = eff_cell,
sample_sizes = sizes))
cr_export_tables(tables, file.path(out, "tables.xlsx"), format = "xlsx")
ggplot2::ggsave(file.path(out, "effects.pdf"), forest, width = 9, height = 5)
cr_macros(list(n_units = nrow(units)), file.path(out, "generated-numbers.tex"))
outCorrective development version
The single-channel cr_correct_batch(method = "combat") path now refuses an unsupported analysis. Earlier versions could return median centering after a ComBat error. Choose method = "median_center" explicitly when appropriate, or prepare a feature-by-sample matrix and a suitable design for sva::ComBat().
Version 0.3.0 corrects analysis integrity defects; it is not yet a published release. For exact reproduction of the historical manuscript software, install CTTIR/cellreportR@manuscript-anchor-2026-08-21 in a separate library. Do not replace archived results when comparing versions.
-
cr_test()andcr_test_all()now report replicate effect sizes whenlevel = "replicate"or"both". With"both", the cell effects are also available as$cell_effect_sizes. Recompute affected effect estimates, confidence intervals, plots and summary interpretations before citing them. - Fully confounded or saturated blocked models are skipped. Ambiguous batch labels and comparison joins are rejected; supply all comparison keys in
by. -
sufficientincr_power_grid()requires a usable conservative target. An interval spanning zero cannot certify sufficiency through observed sizing. - The legacy
wilcoxon_signedoption is refused because this interface has no matched-pair key. Join paired observations explicitly, verify one observation per pair and arm, retain complete pairs, and callstats::wilcox.test(x, y, paired = TRUE)on the aligned vectors. Row order or equal group size alone does not establish pairing.
Public function signatures and the API-lock snapshots remain unchanged. The manuscript anchor and historical source data remain intact.
Source-bound report evidence
cr_report_evidence() connects explicitly keyed CSV/TSV result cells to quoted values and records figure hashes with their declared source-table links. cr_lab_report_from_evidence() inserts those displays into an existing laboratory report’s custom fields. The normal renderer and audit exporter revalidate the files and bound fields before use; existing reports retain their behavior.
# Source files are relative to an existing project results directory.
evidence <- cr_report_evidence(
root = "results",
tables = list(effects = list(path = "effects.tsv", format = "tsv",
key = c("contrast", "endpoint"))),
claims = list(estimate = list(table = "effects",
key = c(contrast = "treated_vs_control", endpoint = "response"),
column = "estimate", format = "number", digits = 3)),
figures = list(effect_plot = list(path = "effect_plot.pdf", tables = "effects"))
)
spec <- cr_report_spec(report = list(report_id = "example"),
result = list(display_value = "See source-bound additional information"),
authorization = list(authorized_by = "Reviewer"))
report <- cr_lab_report_from_evidence(evidence, "results", spec = spec)
cr_export_report_audit(report, "report-audit.json")Relative paths and SHA-256 source identities allow relocation of the whole tree; reassemble the report with cr_lab_report_from_evidence(evidence, new_root, spec) using the original specification after relocation. Existing render, export and provenance function signatures remain unchanged. Source-byte changes, ambiguous or missing keys, nonfinite numeric claims, and altered bound fields fail validation. Numeric formatting performs no scaling or unit conversion. Figure-to-table links are declarations, not proof that a figure was generated from those tables. Scientific validity and other report prose or fields remain the author’s responsibility. Evidence hashes use versioned UTF-8 JSON bytes; the existing cr_report_hash() contract is unchanged.
Interactive analysis
The application provides a guided workflow covering import, quality control, normalization, statistical analysis, dose-response fitting, interactive visualisation and report export.
Output structure
cr_build_experiment() returns a list of class cr_experiment. cr_dataset() instead returns the ingest container described above:
| Slot | Description |
|---|---|
cells |
One row per segmented object, with provenance (source_file, source_path) and any derived columns added by later stages |
design |
One row per spatial unit, carrying the treatment factors recovered from the design table or from the path grammar |
channels |
Character vector of measurement channels detected or declared |
plate_info |
Plate geometry and layout metadata |
qc_log |
Append-only record of every filter, exclusion and gate applied, with the realised thresholds |
metadata |
Free-form list of user-supplied experiment metadata |
spatial_unit |
Name of the column identifying the physical acquisition location |
unit_var |
Name of the column identifying the analysis unit of replication |
batch_vars |
Character vector of design columns whose combination defines a batch |
provenance |
One row per source file, with cell counts and the unit it was assigned to |
set_aside |
Control arms split out of the sample pool and retained separately |
Function reference
Citation
Cite the exact version used. This checkout is the unpublished corrective version 0.3.0; no verified DOI is currently attached to it. For this version, the citation is:
Heller R, Schwindling L, Büchner A, Lindenberger L, Müller S, Hannemann M, Achatz G, Rothmiller S (2026). cellreportR: Cell Culture Microscopy Assay Analysis and Reporting. R package version 0.3.0, https://github.com/CTTIR/cellreportR.
BibTeX:
@Manual{cellreportR,
title = {cellreportR: Cell Culture Microscopy Assay Analysis and Reporting},
author = {Raban Heller and Leila Schwindling and Alexander B\"uchner and
Lucia Lindenberger and Steffen M\"uller and Michael Hannemann and
Gerhard Achatz and Simone Rothmiller},
year = {2026},
note = {R package version 0.3.0},
url = {https://github.com/CTTIR/cellreportR},
}You can always retrieve the up-to-date entry directly from R:
citation("cellreportR")Use of LLM tools
Where applicable, LLM tools were used for narrowly defined, non-authorial tasks: copyediting, prose refinement, Markdown/LaTeX formatting, boilerplate scaffolding (such as CI configurations and build scripts), and code refactoring. Tools included Chat AI, the KISSKI (GWDG) service, and self-hosted Mistral Small (24B, Apache-2.0) served through a local vLLM architecture on an Ubuntu Linux workstation with Intel processors and NVIDIA GPUs. Self-hosted use also includes models that were further trained (fine-tuned) or weight-edited in-house for specific tasks. All self-hosted models ran locally, with no data sent to third parties.
All scientific claims, methodological choices, analyses, interpretations and conclusions remain the authors’ own. Where applicable, LLM-generated material must be reviewed and revised before inclusion, and references must be verified against their DOI, arXiv ID or ISBN.
Local software setup: vLLM with Python/PyTorch, plus R and RStudio.
Branding
Editable R sources and regeneration instructions are in tools/branding.
