Package 'cellreportR'

Description

Removes the cells of every unit the gate excluded, records the step in the QC log and stores the gate on the experiment so the decision remains auditable after the data have been trimmed.

Usage

cr_apply_gate(experiment, gate, units = NULL, drop_disputed = FALSE)

Arguments

Value

A modified cr_experiment. The gate is stored in metadata$qc_gate.

See Also

cr_qc_gate(), cr_qc_gate_impact(), cr_qc_report().

Other quality control: cr_balance_cells(), cr_exclude_small(), cr_qc_doublets(), cr_qc_filter(), cr_qc_gate(), cr_qc_gate_impact(), cr_qc_intensity(), cr_qc_manual(), cr_qc_report(), cr_qc_summary(), print.cr_qc_gate()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 40)
gate <- cr_qc_gate(exp, "marker_1", "Untreated", batch_vars = "replicate")
exp2 <- cr_apply_gate(exp, gate)
cr_qc_summary(exp2)

Description

Derives the identifier of the analysis unit — the spatial unit that is the unit of replication — for every row of a cell table, merging the files that belong to the same unit according to a cr_merge_rules() set.

Usage

cr_assign_units(
  x,
  key_vars,
  replicate_var = "replicate",
  rules = cr_merge_rules(),
  id_col = "well_id",
  sep = "|",
  call = rlang::caller_env()
)

Arguments

Details

The unit identifier is the combination of key_vars and the merged replicate index. Files that share it are one unit; files that do not are separate replicates. Because a unit may be assembled from more than one file, cr_unit_map() should be used afterwards to see which units were merged and from how many files.

Value

x with two columns added: replicate_merged (the replicate index after merging) and the unit identifier named by id_col. The number of units is attached as the "n_units" attribute.

See Also

cr_unit_map(), cr_merge_rules(), cr_centroid_overlap().

Other import: cr_centroid_overlap(), cr_column_map(), cr_extract_markers(), cr_filename_grammar(), cr_marker_rules(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

files <- tibble::tibble(
  compound = "CompoundA",
  plate = "Plate_1",
  mode = "treated",
  replicate = c("1", "1.1", "2", "2.2"),
  merge_unit = c(FALSE, TRUE, FALSE, FALSE),
  reacquisition = FALSE
)
units <- cr_assign_units(files, key_vars = c("compound", "plate", "mode"))
units[, c("replicate", "replicate_merged", "well_id")]

Description

Compute AUC with confidence interval from a cr_result

Usage

cr_auc(result, ci_method = c("delong", "bootstrap"), n_boot = 1000)

Arguments

Value

A tibble with auc, ci_low, ci_high, method.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
res <- cr_logistic(exp, "marker_1", "CompoundA_high", "Untreated")
cr_auc(res)

Description

Computes a per-well background estimate and subtracts it from every cell in that well. Negative values are clipped to zero.

Usage

cr_background_subtract(
  experiment,
  channel,
  method = c("percentile", "modal", "empty_wells"),
  q = 0.05,
  empty_wells = NULL
)

Arguments

Value

A modified cr_experiment.

See Also

cr_normalize(), cr_standardize_batch()

Other normalization functions: cr_normalize()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
cr_background_subtract(exp, channel = "marker_1")

Description

Randomly subsamples each analysis unit to a common cell count. A unit acquired in several passes otherwise contributes several times as many cells as its single-pass neighbour and is silently over-weighted in every pooled quantity they share — including the control statistics of their own batch.

Usage

cr_balance_cells(experiment, unit = NULL, n_max = NULL, n = NULL, seed = NULL)

Arguments

Details

Three modes:

n_max

cap each unit at n_max cells, leaving smaller units untouched. This is the usual choice for large acquisitions.

n

take exactly n cells per unit (units with fewer cells keep all of theirs).

neither

take the smallest unit's cell count from every unit, which equalises the units exactly at the cost of discarding the most data.

Subsampling is random, so pass seed for a reproducible result. The RNG state of the calling session is saved and restored, so a seeded stream outside this function is never disturbed.

Value

A modified cr_experiment. Per-unit counts before and after are stored in metadata$balance_cells.

See Also

cr_exclude_small(), which should run first.

Other quality control: cr_apply_gate(), cr_exclude_small(), cr_qc_doublets(), cr_qc_filter(), cr_qc_gate(), cr_qc_gate_impact(), cr_qc_intensity(), cr_qc_manual(), cr_qc_report(), cr_qc_summary(), print.cr_qc_gate()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 40)
exp2 <- cr_balance_cells(exp, n_max = 20, seed = 1)
max(exp2$metadata$balance_cells$n_after)

# equalise every unit at the smallest unit's count
exp3 <- cr_balance_cells(exp, seed = 1)
length(unique(exp3$metadata$balance_cells$n_after))

Description

A batch is rarely identified by a single column. Once an assay spans several plates, acquisition runs or experiment days, the analytical batch is the combination of those columns, and any analysis that standardizes against a control has to respect that combination. cr_batch_key() collapses any number of design or cell columns into one character key that can be grouped on, joined on and reported.

Usage

cr_batch_key(x, batch_vars, sep = " | ", na_label = "<NA>")

Arguments

Details

Missing values are replaced by na_label rather than propagated, so that two rows with an unrecorded plate are grouped together visibly instead of silently producing NA keys. If distinct tuples produce the same displayed key, the function refuses the collision; choose another separator or missing-value label.

Value

A character vector with one key per row of x (one key per cell when x is a cr_experiment).

See Also

cr_batch_reference(), cr_standardize_batch()

Other batch standardization functions: cr_batch_reference(), cr_correct_batch(), cr_standardize_batch()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 10)
exp$design$plate <- rep(c("P1", "P2"), length.out = nrow(exp$design))
key <- cr_batch_key(exp, c("plate", "timepoint"))
head(unique(key))

# Works on a plain data frame too
cr_batch_key(data.frame(a = c("x", "y"), b = 1:2), c("a", "b"))

Description

Summarizes the control cells of every batch: how many there are, and their mean, median and standard deviation for one channel. This table is the reference that cr_standardize_batch() divides by, and it is worth inspecting on its own – a batch with very few control cells, or none at all, is visible here before any standardized value is computed.

Usage

cr_batch_reference(
  experiment,
  channel,
  control_level,
  batch_vars,
  control_var = "treatment",
  sd_floor = 1e-08
)

Arguments

Details

Both centres are reported deliberately. A right-skewed signal has mean > median, so a downstream gate that compares a well's median against a control mean is silently stricter than the rule it states. Keeping both lets each consumer compare like with like.

Value

A tibble with one row per batch and the columns

batch_vars

The columns that define the batch.

batch_key

The collapsed batch key.

n_cells

Cells in the batch.

ctrl_n

Control cells with a finite channel value.

ctrl_mean, ctrl_median, ctrl_sd

Control statistics; NA when the batch has no control cells.

has_control

Whether the batch can be standardized.

See Also

cr_standardize_batch(), cr_batch_key()

Other batch standardization functions: cr_batch_key(), cr_correct_batch(), cr_standardize_batch()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 20)
exp$design$plate <- rep(c("P1", "P2"), length.out = nrow(exp$design))
cr_batch_reference(exp, channel = "marker_1",
                   control_level = "Untreated", batch_vars = "plate")

Description

Re-estimates each contrast within a blocking factor, typically the plate. Units on one plate share a preparation run, an imaging session and a single control denominator, so they are not independent and a pooled estimate carries the between-plate variance inside its standard deviation. Fitting value ~ group + block on unit-level data removes the additive block effect and shows whether the pooled headline estimate is conservative or inflated by pooling.

Usage

cr_blocked_effect(
  data,
  value,
  group_var,
  reference_level,
  comparison_levels = NULL,
  block_var,
  by = NULL,
  unit = NULL,
  conf_level = 0.95,
  min_blocks = 2
)

Arguments

Details

The reported d_within_block is the group coefficient divided by the residual standard deviation of the blocked fit, so it is on the same scale as Cohen's d from cr_effect_grid() but conditions on the block.

Value

A tibble with the by columns, contrast, n_units, n_blocks, shift_within_block (the group coefficient), ci_low, ci_high, resid_sd, d_within_block and p_value. Contrasts that could not be fitted are returned in the skipped attribute.

See Also

cr_effect_grid(), cr_unit_variability().

Other screen statistics: cr_unit_variability()

Examples

set.seed(1)
units <- data.frame(
  compound = rep(c("CompoundA", "CompoundB"), each = 16),
  arm = rep(rep(c("reference", "interval_short"), each = 8), 2),
  plate = rep(rep(c("P1", "P2"), each = 4), 8),
  log2_fc = stats::rnorm(32)
)
units$log2_fc <- units$log2_fc +
  ifelse(units$compound == "CompoundA" & units$arm == "interval_short",
         -1.2, 0) +
  ifelse(units$plate == "P2", 0.5, 0)
cr_blocked_effect(units, value = "log2_fc", group_var = "arm",
                  reference_level = "reference",
                  block_var = "plate", by = "compound")

Description

Assembles a validated cr_experiment from its components. A cr_experiment is the central S3 object in cellreportR and holds per-cell measurements, experimental design, channel metadata, plate information, a QC log and arbitrary user metadata.

Usage

cr_build_experiment(
  cells,
  design = NULL,
  channels = NULL,
  plate_info = list(),
  metadata = list(),
  unit_var = NULL,
  batch_vars = NULL,
  provenance = NULL,
  set_aside = NULL,
  call = rlang::caller_env()
)

Arguments

Details

Three optional slots describe structure that a single design table cannot: unit_var names the analysis unit when it is neither well nor slide (a unit assembled from several files, for instance), batch_vars names the combination of columns that defines a batch, and provenance keeps the per-file record that lets any cell be traced back to its acquisition. set_aside holds arms that were split out of the analysis pool, such as a specificity control, so that they travel with the experiment instead of being lost.

Value

A cr_experiment object (an S3 list).

See Also

cr_validate_experiment(), cr_dataset(), cr_design().

Other constructors: cr_dataset(), cr_design(), cr_validate_experiment()

Examples

cells <- tibble::tibble(
  cell_id = sprintf("c%03d", 1:6),
  well = rep(c("A01", "A02"), each = 3),
  area = c(120, 130, 125, 118, 122, 131),
  target_signal = c(10, 12, 11, 30, 33, 29)
)
design <- tibble::tibble(
  well = c("A01", "A02"),
  treatment = c("Vehicle", "CompoundA"),
  plate = "Plate_1"
)
exp <- cr_build_experiment(cells, design, batch_vars = "plate")
exp

Description

Answers the question a mergeable-looking replicate suffix raises: are these two files two passes over the same physical unit, or two different units? Two passes over one unit share their segmentation centroids; two different units share essentially none.

Usage

cr_centroid_overlap(
  x,
  unit_a,
  unit_b,
  coords = c("x", "y"),
  tol = 1,
  id_col = "well_id",
  call = rlang::caller_env()
)

Arguments

Value

A single number: the fraction of cells in the smaller unit that have a centroid within tol of a centroid in the other unit. The cell counts and the number of matches are attached as the "n_a", "n_b" and "n_matched" attributes.

See Also

cr_assign_units(), cr_merge_rules().

Other import: cr_assign_units(), cr_column_map(), cr_extract_markers(), cr_filename_grammar(), cr_marker_rules(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

cells <- tibble::tibble(
  well_id = rep(c("u1", "u2"), each = 4),
  x = c(1, 2, 3, 4, 1, 2, 3, 90),
  y = c(1, 2, 3, 4, 1, 2, 3, 90)
)
# u1 and u2 share three of four centroids:
cr_centroid_overlap(cells, "u1", "u2")

Description

List channels in a cr_experiment

Usage

cr_channels(experiment)

Arguments

Value

A character vector of channel names.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 10)
cr_channels(exp)

Description

Deterministically classify numeric results using explicit boundaries

Usage

cr_classify_result(
  value,
  negative_upper,
  positive_lower,
  labels = c(negative = "NEGATIVE", indeterminate = "INDETERMINATE", positive =
    "POSITIVE")
)

Arguments

Value

Character vector with missing/non-finite inputs returned as NA.

Description

Segmented single-cell exports name their columns however the acquisition software happens to. A cr_column_map records how those raw headers translate to the analysis names used downstream, so that the mapping lives in one declarative object instead of being spread through reader code.

Usage

cr_column_map(exact = NULL, prefix = NULL, keep = NULL)

## S3 method for class 'cr_column_map'
print(x, ...)

Arguments

Details

Two matching modes are available because vendor headers are not always stable: exact matches a header verbatim, while prefix matches a regular expression. Prefix matching exists for headers that embed a unit glyph (an area column ending in a squared-micrometre symbol, for instance), where the exact spelling cannot be relied on.

Renaming is deliberately tolerant: names that do not occur in a given export are skipped silently rather than raising an error. Exports from the same instrument routinely carry different subsets of the available measurements, and a strict renamer forces a second reader to exist for every subset.

Value

An object of class cr_column_map: a list with elements exact, prefix and keep.

x, invisibly.

See Also

cr_read_export(), cr_read_exports().

Other import: cr_assign_units(), cr_centroid_overlap(), cr_extract_markers(), cr_filename_grammar(), cr_marker_rules(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

map <- cr_column_map(
  exact = c(
    "Event Label" = "cell_id",
    "Signal - Mean Intensity" = "target_signal"
  ),
  prefix = c("^Nuclei - Area" = "area"),
  keep = c("cell_id", "target_signal", "area")
)
map

Description

Puts the two aggregation levels of a screen side by side and quantifies how much narrower the cell-level intervals are. A ratio well above one is pseudo-replication rather than precision: cells within a unit are not independent, so the cell-level interval understates the uncertainty of the very same estimate.

Usage

cr_compare_levels(unit_effects, cell_effects, by = NULL, estimate = "cohens_d")

Arguments

Value

A tibble with the join keys, estimate_unit, estimate_cell, width_unit, width_cell and ratio (width_unit / width_cell). The median ratio is attached as the median_ratio attribute.

See Also

cr_effect_grid().

Other effect sizes: cr_effect_grid(), cr_effect_size()

Examples

set.seed(1)
cells <- data.frame(
  compound = rep(c("CompoundA", "CompoundB"), each = 240),
  arm = rep(rep(c("reference", "interval_short"), each = 120), 2),
  unit_id = rep(paste0("u", 1:8), each = 60),
  log2_fc = stats::rnorm(480)
)
cells$log2_fc <- cells$log2_fc +
  ifelse(cells$compound == "CompoundA" & cells$arm == "interval_short",
         -1, 0)
u <- cr_effect_grid(cells, "log2_fc", "arm", "reference",
                    by = "compound", unit = "unit_id")
k <- cr_effect_grid(cells, "log2_fc", "arm", "reference",
                    by = "compound", min_n = 10)
cmp <- cr_compare_levels(u, k)
cmp
attr(cmp, "median_ratio")

Description

Returns a rich set of per-unit summary statistics for a single channel: mean, median, SD, MAD, CV, cell count and percent positive above a threshold. Useful as input for QC dashboards and as the between-unit variability input of a screen.

Usage

cr_compute_metrics(experiment, channel, positive_threshold = NULL, unit = NULL)

Arguments

Value

A tibble with one row per analysis unit and the design columns appended.

See Also

cr_summarize_wells(), cr_table_disposition().

Other quantification: cr_fold_change(), cr_summarize_wells(), cr_table_disposition()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
cr_compute_metrics(exp, channel = "marker_1")
cr_compute_metrics(exp, channel = "marker_1", positive_threshold = 800)

Description

Confusion matrix for a logistic cr_result

Usage

cr_confusion_matrix(result, threshold = 0.5)

Arguments

Value

A tibble with sensitivity, specificity, ppv, npv, accuracy, and the confusion-matrix counts.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
res <- cr_logistic(exp, "marker_1", "CompoundA_high", "Untreated")
cr_confusion_matrix(res, 0.5)

Description

Returns the end of a confidence interval that lies closer to zero, which is the conservative effect a follow-up study should be powered on. When the interval spans the null there is nothing to power on and NA is returned.

Usage

cr_conservative_effect(ci_low, ci_high)

Arguments

Value

A numeric vector the length of the recycled inputs. Scalars can recycle; other lengths must agree, and lower bounds cannot exceed upper bounds.

See Also

cr_power(), cr_effect_grid().

Other power: cr_power(), cr_power_analysis(), cr_power_grid()

Examples

cr_conservative_effect(c(-1.8, -0.4), c(-0.6, 0.9))

Description

Applies a simple batch correction. "median_center" shifts each batch's median to the overall median. The legacy "combat" choice is refused: this single-channel interface cannot supply the feature-by-sample matrix required for a valid empirical-Bayes ComBat analysis. Previous versions could substitute median centering after a ComBat error. Select "median_center" explicitly if that is the intended analysis.

Usage

cr_correct_batch(
  experiment,
  batch_var,
  channel,
  method = c("median_center", "combat")
)

Arguments

Details

Batch correction removes a batch offset from the measured signal. It is not a substitute for cr_standardize_batch(), which expresses every cell relative to the control cells of its own batch and leaves the measured signal untouched.

Value

A modified cr_experiment.

See Also

cr_batch_key(), cr_standardize_batch()

Other batch standardization functions: cr_batch_key(), cr_batch_reference(), cr_standardize_batch()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
exp$design$batch <- rep(c("b1", "b2"), length.out = nrow(exp$design))
cr_correct_batch(exp, batch_var = "batch", channel = "marker_1")

# A batch defined by more than one column
exp$design$plate <- rep(c("P1", "P2"), length.out = nrow(exp$design))
cr_correct_batch(exp, batch_var = c("batch", "plate"),
                 channel = "marker_1")

Description

A cr_dataset is what comes out of ingest: the cells of every export, the per-file provenance that lets any row be traced back to the acquisition it came from, and optionally the design those files encode. It is the object to inspect before committing to an analysis, and it converts to a cr_experiment with cr_build_experiment().

Usage

cr_dataset(
  cells,
  design = NULL,
  unit_var = NULL,
  provenance = NULL,
  file_col = "source_path",
  metadata = list(),
  call = rlang::caller_env()
)

## S3 method for class 'cr_dataset'
print(x, ...)

## S3 method for class 'cr_dataset'
summary(object, ...)

Arguments

Value

An object of class cr_dataset:

cells

Tibble of per-cell measurements.

provenance

Tibble with one row per source file, or NULL.

design

A cr_design, or NULL.

unit_var

Name of the analysis unit column, or NULL.

metadata

List of user metadata.

x, invisibly.

A tibble with one row per source file, or NULL when the data set carries no provenance.

See Also

cr_read_exports(), cr_design(), cr_build_experiment().

Other constructors: cr_build_experiment(), cr_design(), cr_validate_experiment()

Examples

cells <- tibble::tibble(
  source_path = rep(c("a.csv", "b.csv"), each = 3),
  source_file = rep(c("a.csv", "b.csv"), each = 3),
  well = rep(c("A01", "A02"), each = 3),
  treatment = rep(c("Vehicle", "CompoundA"), each = 3),
  target_signal = c(10, 12, 11, 30, 33, 29)
)
ds <- cr_dataset(cells)
ds
ds$provenance

Description

A cr_design records both the design table — one row per analysis unit — and the roles its columns play: which column identifies the unit, which holds the treatment, which level of that treatment is the reference, and which columns together define a batch.

Usage

cr_design(
  data,
  unit = NULL,
  treatment = "treatment",
  control_level = NULL,
  batch_vars = NULL,
  levels = list(),
  keep = NULL,
  call = rlang::caller_env()
)

## S3 method for class 'cr_design'
print(x, ...)

Arguments

Details

Recording the roles alongside the table is what lets later stages standardise each cell against the control of its own batch rather than against one pooled reference. A batch is normally a combination of columns (compound, run, plate, experiment, pre-treatment interval), which a single batch variable cannot express.

data may be a per-unit table or a per-cell / per-file table; in the latter case it is collapsed to unique rows. If a unit maps to more than one combination of design values the collapse is ambiguous and the offending columns are named in the error, since silently keeping the first row would invent a design that was never run.

Value

An object of class cr_design:

table

Tibble with one row per analysis unit.

unit

Name of the unit column.

treatment

Name of the treatment column.

control_level

Reference level, or NULL.

batch_vars

Character vector of batch columns.

levels

The factor level orders that were applied.

x, invisibly.

See Also

cr_dataset(), cr_build_experiment(), cr_read_design().

Other constructors: cr_build_experiment(), cr_dataset(), cr_validate_experiment()

Examples

units <- tibble::tibble(
  well = sprintf("A%02d", 1:6),
  treatment = rep(c("Vehicle", "CompoundA"), each = 3),
  plate = rep(c("Plate_1", "Plate_2"), 3),
  replicate = rep(1:3, 2)
)
design <- cr_design(units, control_level = "Vehicle",
                    batch_vars = c("plate"))
design

Description

Fits a dose-response model to well-level summaries of a treatment across doses. Supports 4-parameter log-logistic ("4pl"), 3-parameter log-logistic with fixed lower asymptote at zero ("3pl"), and a simple linear model ("linear").

Usage

cr_dose_response(
  experiment,
  channel,
  treatment = NULL,
  model = c("4pl", "3pl", "linear"),
  log_dose = TRUE
)

Arguments

Details

The 4PL model fitted is:

$y = d + \frac{a - d}{1 + (x / e)^b}$

where a is the top asymptote, d the bottom asymptote, e the inflection point (EC50 / IC50), and b the Hill slope.

Value

A list with class "cr_dose_response" containing the fitted model, the data used for the fit, the estimated parameters, and helper predictions.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
# Add a synthetic dose-response sub-design
exp$design$dose <- ifelse(exp$design$treatment == "CompoundA_high",
                          500, exp$design$dose)
fit <- cr_dose_response(exp, channel = "marker_1", model = "4pl")
print(fit$params)

Description

Drives cr_effect_size() over every group in a screen: for each stratum given by by, each comparison level of group_var is contrasted against reference_level, and every requested effect size is reported with a confidence interval. The same function serves both aggregation levels: supply unit to aggregate the rows to one value per experimental unit (the unit of replication) before the contrast is computed, or leave it NULL to work on the rows as they are (typically single cells).

Usage

cr_effect_grid(
  data,
  value,
  group_var,
  reference_level,
  comparison_levels = NULL,
  by = NULL,
  unit = NULL,
  methods = c("cohens_d", "hedges_g", "cliffs_delta"),
  conf_level = 0.95,
  min_n = 3,
  test = c("t", "wilcox", "none"),
  p_adjust = c("bonferroni", "BH"),
  level = NULL
)

Arguments

Details

Cell-level intervals are anticonservative by construction, because cells within a unit are not independent. Compute both levels and pass them to cr_compare_levels() to quantify the difference; interpretation belongs to the unit level.

Multiplicity adjustment is applied across the entire returned grid and reported alongside the unadjusted p-value, never in place of it: for an exploratory screen the effect sizes and their intervals are the reportable quantity.

Value

A tibble with one row per stratum and contrast: the by columns, contrast, level, n_ref, n_cmp, mean_shift, one ⁠<method>⁠, ⁠<method>_ci_low⁠, ⁠<method>_ci_high⁠ and ⁠<method>_magnitude⁠ triplet per requested method, p_value, one ⁠p_<adjustment>⁠ column per entry of p_adjust, and ci_excludes_zero for the first method. The attributes conf_level, level, primary_method and skipped (a tibble of the contrasts that fell below min_n) are attached.

See Also

cr_effect_size(), cr_compare_levels(), cr_power_grid(), cr_blocked_effect().

Other effect sizes: cr_compare_levels(), cr_effect_size()

Examples

set.seed(1)
units <- data.frame(
  compound = rep(c("CompoundA", "CompoundB"), each = 12),
  arm = rep(rep(c("reference", "interval_short"), each = 6), 2),
  unit_id = paste0("u", 1:24),
  log2_fc = c(stats::rnorm(6, 0, 0.3), stats::rnorm(6, -1, 0.3),
              stats::rnorm(6, 0, 0.3), stats::rnorm(6, -0.1, 0.3))
)
eff <- cr_effect_grid(units, value = "log2_fc", group_var = "arm",
                      reference_level = "reference", by = "compound")
eff[, c("compound", "contrast", "cohens_d", "cohens_d_ci_low",
        "cohens_d_ci_high", "ci_excludes_zero")]

Description

Standardized effect sizes for a comparison of two independent samples, each with a confidence interval. Confidence intervals are analytic by default (deterministic and cheap on large samples); a bootstrap interval is available for cases where the analytic approximation is not wanted.

Usage

cr_effect_size(
  x,
  y,
  method = c("cohens_d", "hedges_g", "cliffs_delta", "rank_biserial", "glass_delta"),
  ci = 0.95,
  ci_method = c("analytic", "bootstrap"),
  n_boot = 200,
  seed = NULL
)

Arguments

Details

Cohen's d uses the pooled standard deviation without small-sample correction and its interval is the large-sample (Hedges-Olkin) approximation with a t quantile on n_x + n_y - 2 degrees of freedom. Hedges' g applies the bias correction $J = 1 - 3 / (4 \cdot df - 1)$ to both estimate and interval. Glass's delta standardizes by the standard deviation of y only. Cliff's delta uses the consistent variance estimator with the interval on the transformed scale, so the bounds always lie inside $[-1, 1]$. The rank-biserial correlation of two independent samples equals Cliff's delta and is reported on the same scale.

Value

A tibble with columns method, estimate, ci_low, ci_high and magnitude.

See Also

cr_effect_grid() for a whole grid of contrasts, cr_power() for the sample size implied by an effect size.

Other effect sizes: cr_compare_levels(), cr_effect_grid()

Examples

set.seed(1)
cr_effect_size(stats::rnorm(100, 1), stats::rnorm(100, 0))

# bootstrap interval with a reproducible seed
cr_effect_size(stats::rnorm(50, 1), stats::rnorm(50, 0),
               method = "cliffs_delta",
               ci_method = "bootstrap", n_boot = 50, seed = 42)

Description

Renders a character vector as "a", "a and b" or "a, b and c", with a fixed placeholder for the empty case. Sentences that enumerate results — which contrasts cleared a threshold, which arms were excluded — should be generated for the same reason the numbers are: the hand-written version is right until the analysis changes.

Usage

cr_enumerate(x, conjunction = "and", empty = "none", oxford = FALSE)

Arguments

Value

A single string.

See Also

cr_macros(), cr_format_number().

Other macros: cr_format_number(), cr_macro_name(), cr_macros(), cr_macros_from()

Examples

cr_enumerate(c("CompoundA", "CompoundB", "CompoundC"))
cr_enumerate(c("CompoundA", "CompoundB"), conjunction = "or")
cr_enumerate(character())

Description

Builds the unit-level design table used by cr_example_experiment(). Six treatment levels are crossed with two plates and two pre-treatment intervals, so that a batch is the combination of plate and interval rather than a single column and every batch still contains untreated units to standardise against.

Usage

cr_example_design(plate_format = 96, n_wells_per_replicate = 4)

Arguments

Details

Treatment names are deliberately abstract. Untreated is the vehicle level, PosControl a positive control, and CompoundA appears at a low and a high exposure level so that a dose axis exists; CompoundB and CompoundC are further compounds at the low exposure level. The four distinct values of dose are the four exposure levels of the demonstration assay.

Value

A tibble with one row per unit and the columns well, treatment, dose, dose_unit, group, replicate, plate, interval and timepoint.

See Also

cr_example_experiment(), cr_example_screen().

Other example data: cr_example_experiment(), cr_example_exports(), cr_example_files(), cr_example_path(), cr_example_screen()

Examples

design <- cr_example_design(96)
table(design$treatment, design$interval)

Description

Simulates a compact demonstration experiment: one 96-unit plate format, six treatment levels, four exposure levels, two plates and two pre-treatment intervals. It is small enough that every example in the package can build a fresh copy in well under a second, and structured enough that the batch, quality-control and effect-size functions all have something to work on.

Usage

cr_example_experiment(
  seed = 42,
  n_cells_per_well = 150,
  n_wells_per_replicate = 4
)

Arguments

Details

Use cr_example_screen() instead when a multi-compound screen with per-batch controls, merged analysis units and a specificity arm is needed.

Value

A cr_experiment whose cells table holds one row per cell (cell_id, well, x, y, area, circularity, DAPI, marker_1, marker_2, marker_3) and whose design table holds one row per unit, as described in cr_example_design().

Generating model

Values are drawn independently per cell from log-normal distributions, so that the marker channels are right-skewed the way measured intensities are:

unit intercept

Each unit draws $u \sim N(0, 0.15^2)$, added to the log mean of every channel in that unit. This is what makes the unit, and not the cell, the honest replicate.

target signal

marker_1 is $\mathrm{LogNormal}(\log 500 + u + e \log 2,\ 0.5^2)$, where $e$ is the treatment effect in log2 units: 0 untreated, 1.0 and 3.0 for the low and high exposure level of CompoundA, 3.3 for the positive control, 0.4 for CompoundB and 0.7 for CompoundC.

further channels

marker_2 moves against the target signal at $-0.4e$, marker_3 weakly with it at $0.3e$.

nuclear stain

DAPI is $\mathrm{LogNormal}(\log 500 + u,\ 0.3^2)$ and carries no treatment effect.

morphology

Nuclear area is $\mathrm{LogNormal}(\log 400,\ 0.25^2)$ and circularity is $\mathrm{Beta}(5, 2)$.

plate position

Units on the outer rows and columns get a fixed +0.07 log bump on every channel, an edge effect for the plate map to show.

debris

Five per cent of the cells of each unit are shrunk to a twentieth of their area and a tenth of their nuclear signal, so that the quality-control filters have something to remove.

artefacts

Two named units are multiplied up on marker_1 and down on area, a saturated pair for the outlier screens.

The random number generator state of the caller is restored on exit, so calling this function does not disturb a seeded analysis.

See Also

cr_example_design(), cr_example_screen(), cr_example_files().

Other example data: cr_example_design(), cr_example_exports(), cr_example_files(), cr_example_path(), cr_example_screen()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 20)
exp
head(exp$design, 3)

Description

Writes a nested directory of single-acquisition export files whose design information lives in the directory layout and the file names rather than inside the files. This is the input the multi-file ingest functions were written for, so that cr_read_exports(), cr_parse_paths() and cr_extract_markers() can be demonstrated on real files.

Usage

cr_example_exports(
  dir = tempdir(),
  seed = 42,
  n_cells = 20,
  format = c("csv", "xlsx")
)

Arguments

Details

The layout below dir is ⁠Run1/<compound>/<experiment>/<plate>/<file>⁠, and the file names follow the grammar ⁠<compound>_<interval>_<dose>_<mode>_<replicate>⁠ in which an absent token is meaningful: a name carrying no exposure token is a vehicle control. Parenthetical markers are attached to three files – a two-pass acquisition, a repeated read and a reagent-omitted acquisition – and one directory is marked as a partly filled plate.

Column headers are raw instrument names rather than analysis names, and one of them carries a unit glyph, so that a cr_column_map() is genuinely required to read them.

Value

A character vector of the written file paths, invisibly.

See Also

cr_read_exports(), cr_path_spec(), cr_example_screen(), cr_example_path().

Other example data: cr_example_design(), cr_example_experiment(), cr_example_files(), cr_example_path(), cr_example_screen()

Examples

d <- file.path(tempdir(), "cr_example_exports")
files <- cr_example_exports(d, seed = 1, n_cells = 5)
basename(files)

map <- cr_column_map(
  exact = c("Event Label" = "cell_id",
            "Target - Signal Mean" = "target_signal"),
  prefix = c("^Nuclei - Area" = "area")
)
cells <- cr_read_exports(d, column_map = map, progress = FALSE)
head(cells[, c("source_file", "cell_id", "target_signal", "area")], 3)

Description

Writes the tables behind cr_example_experiment() in the layouts the ⁠cr_read_*⁠ importers understand, so that the import functions can be demonstrated on real files without any being shipped.

Usage

cr_example_files(dir = tempdir(), seed = 42)

Arguments

Value

A character vector of the written file paths, invisibly.

See Also

cr_example_exports() for a nested export tree with the design encoded in the paths, cr_example_path() for the files shipped inside the package.

Other example data: cr_example_design(), cr_example_experiment(), cr_example_exports(), cr_example_path(), cr_example_screen()

Examples

d <- file.path(tempdir(), "cr_example_files")
files <- cr_example_files(d, seed = 1)
basename(files)

Description

Three tiny synthetic files are installed under extdata so that examples, tests and vignettes can read a real file without writing one first and without depending on any gated data.

Usage

cr_example_path(file = NULL)

Arguments

Details

example-export.csv

One acquisition of one unit as a vendor export: raw instrument headers, an all-blank trailing row of the kind many instruments write, and a header carrying a unit glyph, which is what the prefix matching of cr_column_map() exists for.

example-export.xlsx

The same acquisition as a workbook.

example-design.csv

The unit-level design table covering the units in the exports.

The two exports are the treated acquisition that cr_example_exports(seed = 42, n_cells = 20) writes, so the shipped files can be regenerated at any time rather than being opaque binaries.

Value

A character vector of absolute paths; length one when file is given.

See Also

cr_read_export(), cr_read_design(), cr_example_files().

Other example data: cr_example_design(), cr_example_experiment(), cr_example_exports(), cr_example_files(), cr_example_screen()

Examples

basename(cr_example_path())

cells <- cr_read_export(cr_example_path("example-export.csv"))
head(cells, 3)

Description

Simulates a screen of up to ten compounds, each acquired at four exposure levels and two pre-treatment intervals, on two plates and in two experiments. Unlike cr_example_experiment() the analysis unit is not the raw plate well: units carry file provenance, some are assembled from more than one acquisition, and one arm is set aside instead of screened.

Usage

cr_example_screen(
  seed = 42,
  n_compounds = 10,
  n_cells_per_well = 40,
  n_units_per_arm = 3,
  n_experiments = 2
)

Arguments

Details

Everything the screening functions need is present: a vehicle control inside every batch for cr_batch_reference() and cr_standardize_batch(), one unit that fails a control-referenced gate for cr_qc_gate(), enough units per arm for cr_effect_grid(), plates crossed with arms for cr_blocked_effect(), and a reagent-omitted arm in set_aside.

Value

A cr_experiment with

cells

one row per cell: cell_id, well_id, source_file, source_path, x, y, area, circularity, nuclear_signal, target_signal.

design

one row per unit: well_id, compound, experiment, plate, well, interval, dose, dose_unit, treatment, group, replicate.

provenance

one row per acquisition file, with marker flags and the number of files each unit was assembled from.

set_aside

a list whose reagent_omitted element holds the specificity arm.

unit_var is "well_id" and batch_vars is c("compound", "experiment", "plate", "interval").

Generating model

A batch is the combination of compound, experiment, plate and interval. Writing $p_c$ for the potency of compound $c$, $d$ for the exposure level and $u_w$ for the unit intercept:

potency

$p_c$ runs from 1.6 down to 0.1 in equal steps from CompoundA to the last compound, so the rank order of the screen is known in advance and the top hit is a hit by construction rather than by chance.

exposure

The response saturates in dose as $d / (d + 40)$, so the four exposure levels are not equally spaced in effect.

interval

The longer pre-treatment interval multiplies the effect by 1.15.

effect

$e = p_c \cdot d/(d + 40) \cdot g_{interval}$, in log2 units against the vehicle of the same batch.

unit intercept

$u_w \sim N(0, 0.12^2)$ on the log scale, one draw per unit.

acquisition offsets

The second experiment has a 1.35 times higher raw baseline and the second plate a 1.08 times higher one. Both act on control and treated units alike, which is what standardising against the control of a unit's own batch removes, and why raw signal is not comparable across experiments.

target signal

$\mathrm{LogNormal}(\log(400 \cdot g_{exp} \cdot g_{plate}) + u_w + e \log 2,\ 0.45^2)$.

nuclear signal

$\mathrm{LogNormal}(\log 600 + u_w,\ 0.3^2)$, with no treatment effect.

morphology

Nuclear area is $\mathrm{LogNormal}(\log 180,\ 0.3^2)$ and circularity is $\mathrm{Beta}(6, 2)$. Four per cent of objects are shrunk to an eighth of their area, the sub-threshold debris that cr_exclude_small() is meant to drop.

Planted edge cases

gate failure

One treated unit of the first compound is given a negative effect, so it sits below the control of its own batch and fails a control-referenced gate.

two-pass acquisition

One unit's cells are split across two files, the second carrying a (split) marker and a .1 replicate suffix. Left unmerged it would count twice.

repeated read

One unit's cells are split across a file and its ⁠(repeat)⁠ sibling, which has to merge into it.

look-alike suffix

One separate unit is named with a .2 replicate suffix, which must not merge with the unit named 2: it is a different physical unit on a different plate.

arm outside the screen

A reagent-omitted arm is generated and placed in set_aside rather than in the analysis pool.

The random number generator state of the caller is restored on exit.

See Also

cr_example_experiment(), cr_example_exports(), cr_batch_reference(), cr_effect_grid().

Other example data: cr_example_design(), cr_example_experiment(), cr_example_exports(), cr_example_files(), cr_example_path()

Examples

screen <- cr_example_screen(seed = 1, n_compounds = 3,
                            n_cells_per_well = 12)
screen
table(screen$design$compound, screen$design$treatment)

# Units assembled from more than one acquisition file
prov <- screen$provenance
unique(prov$well_id[prov$n_files > 1])

Description

Removes objects whose segmentation size falls below a quantile of the observed size distribution. Unlike cr_qc_filter(), which applies an absolute threshold, the cut-off here is derived from the data, so it adapts to magnification and segmentation settings. The realised threshold is recorded, because a data-derived cut-off is only reproducible if the value it resolved to is reported.

Usage

cr_exclude_small(
  experiment,
  var = "area",
  probs = 0.1,
  threshold = NULL,
  scope = c("pooled", "batch"),
  batch_vars = NULL
)

Arguments

Details

Cells with a non-finite value in var are always removed: they cannot be placed on either side of the threshold.

scope = "pooled" computes one threshold from all cells. That is the right choice when the segmentation settings were shared across the whole study. scope = "batch" computes one threshold per combination of batch_vars, which protects a batch acquired at a different magnification from being trimmed against a pool it does not belong to — at the cost of a threshold that is no longer comparable between batches.

Run this step before cr_balance_cells(): balancing changes how many cells each unit contributes to the pool, so a threshold computed afterwards is taken on a differently weighted distribution.

Value

A modified cr_experiment. The realised threshold(s) are stored in metadata$exclude_small as a tibble and summarised in the QC log.

See Also

cr_balance_cells(), cr_qc_filter(), cr_qc_report().

Other quality control: cr_apply_gate(), cr_balance_cells(), cr_qc_doublets(), cr_qc_filter(), cr_qc_gate(), cr_qc_gate_impact(), cr_qc_intensity(), cr_qc_manual(), cr_qc_report(), cr_qc_summary(), print.cr_qc_gate()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 40)
exp2 <- cr_exclude_small(exp, var = "area", probs = 0.10)
exp2$metadata$exclude_small

# one threshold per replicate block
exp3 <- cr_exclude_small(exp, scope = "batch", batch_vars = "replicate")
exp3$metadata$exclude_small

Description

Export plots to PNG, PDF or SVG in batch

Usage

cr_export_plots(
  plots,
  path,
  format = c("png", "pdf", "svg"),
  width = 6,
  height = 4,
  dpi = 300,
  ...
)

Arguments

Value

A character vector of written file paths (invisibly).

See Also

cr_export_tables().

Other reporting: cr_export_results(), cr_export_tables(), cr_render_report(), cr_report(), cr_table_qc(), cr_tables()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 20)
p1 <- cr_plot_intensity(exp, "marker_1")
out <- tempfile("plots_")
cr_export_plots(list(intensity = p1), out, width = 4, height = 3)

Description

Export report audit provenance as JSON

Usage

cr_export_report_audit(report, path, output_file = NULL)

Arguments

Description

Named field labels are encoded as a JSON object. Date-time export retains its existing whole-second representation; fractional precision is not preserved by this format.

Usage

cr_export_report_spec(spec, path, pretty = TRUE)

Arguments

Description

Writes a single flat table of results. Anything the reporting layer produces is accepted: a cr_report, a cr_result, the list returned by cr_test_all(), a named list of tables, or a plain data frame.

Usage

cr_export_results(results, path, format = NULL)

Arguments

Value

The output path (invisibly).

See Also

cr_export_tables() to write several tables at once and cr_macros() to emit individual numbers.

Other reporting: cr_export_plots(), cr_export_tables(), cr_render_report(), cr_report(), cr_table_qc(), cr_tables()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 20)
rep <- cr_report(exp)
f <- tempfile(fileext = ".csv")
cr_export_results(rep$tables$disposition, f)
utils::read.csv(f)

Description

Writes the named list produced by cr_tables(). Excel output can go into one workbook with a sheet per table; CSV always writes one file per table into a directory, because a CSV file holds exactly one table.

Usage

cr_export_tables(tables, path, format = c("csv", "xlsx"), one_file = TRUE)

Arguments

Value

A character vector of written paths (invisibly).

See Also

cr_tables(), cr_export_results().

Other reporting: cr_export_plots(), cr_export_results(), cr_render_report(), cr_report(), cr_table_qc(), cr_tables()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 20)
tabs <- cr_tables(exp)
out <- tempfile("tables_")
paths <- cr_export_tables(tabs, out)
basename(paths)

Description

Applies a cr_marker_rules() set to a table that carries a file-name column, adding one logical column per rule plus a character variant column holding any unmatched trailing parenthetical.

Usage

cr_extract_markers(
  x,
  name_col = "source_file",
  container_col = NULL,
  rules = cr_marker_rules(),
  stem_col = NULL,
  strip_ext = TRUE,
  call = rlang::caller_env()
)

Arguments

Value

x with the columns merge_unit, partial_plate, omitted_reagent, reacquisition, lot (all logical) and variant (character) added. Columns for rules that were not supplied are FALSE throughout.

See Also

cr_marker_rules(), cr_parse_paths().

Other import: cr_assign_units(), cr_centroid_overlap(), cr_column_map(), cr_filename_grammar(), cr_marker_rules(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

files <- tibble::tibble(
  source_file = c("CompoundA_10uM_treated_1.csv",
                  "CompoundA_10uM_treated_1.1 (split).csv",
                  "CompoundA_vehicle_1 (no reagent).csv",
                  "CompoundA_vehicle_2 (weekend).csv"),
  plate = c("Plate_1", "Plate_1", "Plate_1", "Plate_2 (partial)")
)
cr_extract_markers(
  files,
  container_col = "plate",
  rules = cr_marker_rules(merge_unit = "\\(split\\)",
                          partial_plate = "\\(partial\\)",
                          omitted_reagent = "\\(no reagent\\)")
)

Description

Build a descriptive figure caption

Usage

cr_figure_caption(
  title = NULL,
  description = NULL,
  n = NULL,
  unit = NULL,
  qc_note = NULL
)

Arguments

Description

Standard deterministic figure dimensions

Usage

cr_figure_size(
  size = c("single", "double", "report", "square"),
  units = c("mm", "in")
)

Arguments

Description

A cr_filename_grammar states how one export file name decomposes into design facts: which trailing token is the replicate index, which leading labels are stripped, which substrings are tokens, and which whole-name shapes are legal at all.

Usage

cr_filename_grammar(
  tokens = list(),
  defaults = list(),
  core_patterns = character(),
  typo_fixes = character(),
  prefix_strip = character(),
  replicate = "[0-9]+(?:\\.[0-9]+)?",
  sep = "_",
  normalise_space = TRUE
)

## S3 method for class 'cr_filename_grammar'
print(x, ...)

Arguments

Details

The core_patterns whitelist exists because the absence of a token is itself meaningful — a name with no interval token is the untreated reference arm, a name with no concentration token is a vehicle control. A mistyped token therefore matches nothing, falls through to the defaults, and silently reclassifies a treated unit as a vehicle control, pulling it into the control denominator of its own batch. With a whitelist in place such a name is a hard error instead.

prefix_strip entries are removed longest-first, so a short label cannot consume a longer one that starts with the same characters.

Value

An object of class cr_filename_grammar (a list).

x, invisibly.

See Also

cr_parse_paths(), cr_path_spec().

Other import: cr_assign_units(), cr_centroid_overlap(), cr_column_map(), cr_extract_markers(), cr_marker_rules(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

g <- cr_filename_grammar(
  tokens = list(interval = "[0-9]+min", dose = "[0-9]+uM",
                mode = "treated|vehicle"),
  defaults = list(interval = "none", dose = "vehicle"),
  core_patterns = c("^vehicle$",
                    "^[0-9]+min_vehicle$",
                    "^[0-9]+uM_treated$",
                    "^[0-9]+min_[0-9]+uM_treated$"),
  prefix_strip = c("CompoundA", "CompoundB")
)
g

Description

A thin wrapper around dplyr::filter() applied to the cells slot. Filtering is additive: rows excluded here are removed from the returned experiment and logged in qc_log.

Usage

cr_filter_cells(experiment, ...)

Arguments

Value

A modified cr_experiment.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 10)
cr_filter_cells(exp, area > 50)

Description

Apply a caller-selected QC finalization rule

Usage

cr_finalize_result(
  classification,
  qc_status,
  failed_statuses = "FAIL",
  invalid_label = "INVALID",
  invalidate = TRUE
)

Arguments

Description

Returns log2 fold changes at the cell and unit levels, relative to one pooled reference computed from the control group.

Usage

cr_fold_change(
  experiment,
  channel,
  control_group,
  method = c("median", "mean"),
  eps = 0,
  unit = NULL
)

Arguments

Details

The reference is pooled across the whole experiment. When controls differ systematically between plates, runs or acquisition days, standardize each cell against the control of its own batch instead — a pooled reference silently mixes those batches together.

Value

A list with components cell (tibble, one row per cell with log2_fc), well (one row per analysis unit) and summary (per treatment: number of units, median, mean and SD of the unit-level log2 fold change).

See Also

cr_summarize_wells().

Other quantification: cr_compute_metrics(), cr_summarize_wells(), cr_table_disposition()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
fc <- cr_fold_change(exp, channel = "marker_1",
                     control_group = "Untreated")
fc$summary

# additive offset instead of a floor
fc2 <- cr_fold_change(exp, channel = "marker_1",
                      control_group = "Untreated", eps = 1)
fc2$summary

Description

Format an estimate and confidence interval

Usage

cr_format_interval(estimate, lower, upper, digits = 2)

Arguments

Description

Fixed-decimal formatting with the conventions a manuscript needs: a placeholder rather than NaN for non-finite values, an optional explicit sign — never printed on an exact zero, where a sign would claim a direction the data does not support — and thousands separators for counts.

Usage

cr_format_number(x, digits = 3, signed = FALSE, big_mark = ",", na = "--")

Arguments

Value

A character vector of the same length as x.

See Also

cr_macros(), cr_enumerate().

Other macros: cr_enumerate(), cr_macro_name(), cr_macros(), cr_macros_from()

Examples

cr_format_number(c(1.2345, -0.5, 0, NA))
cr_format_number(c(1.2345, -0.5, 0), signed = TRUE)
cr_format_number(128400, digits = 0)

Description

Format proportions as percentages

Usage

cr_format_percent(x, digits = 1)

Arguments

Description

Format p-values without displaying calculated zero

Usage

cr_format_pvalue(x, digits = 3)

Arguments

Description

Extract IC50 / EC50 from a dose-response fit

Usage

cr_ic50(fit, level = 0.95)

Arguments

Value

A tibble with estimate, ci_low, ci_high, parameter (IC50 or EC50) and units.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
exp$design$dose <- ifelse(exp$design$treatment == "CompoundA_high",
                          500, exp$design$dose)
fit <- cr_dose_response(exp, channel = "marker_1", model = "4pl")
cr_ic50(fit)

Description

Date-only timestamps retain Date class; ISO timestamps with Z or numeric offsets are restored as UTC date-times. Legacy space-separated UTC times with minutes or seconds (optionally ending in UTC) are also accepted. Custom-section lists and named field-label objects retain their structure. This cannot recover names or fractional seconds lost in older exports and does not guarantee equality of whole-report hashes after a JSON round trip.

Usage

cr_import_report_spec(path, validate = TRUE)

Arguments

Description

Look up explicit interpretation text

Usage

cr_interpretation_lookup(classification, dictionary, default = NA_character_)

Arguments

Description

Assemble a laboratory report without recalculating analytical values

Usage

cr_lab_report(
  experiment = NULL,
  spec = cr_report_spec(),
  qc = NULL,
  result_graphic = FALSE,
  include_audit_appendix = NULL,
  strict = TRUE,
  style = NULL,
  profile = NULL
)

Arguments

Description

Claim identifiers become custom-field names and their displays become field values. Existing custom fields with the same names are rejected. The existing report renderer and audit exporter revalidate source files and bound fields. Other report fields and free text are not verified by this contract.

Usage

cr_lab_report_from_evidence(evidence, root, spec = cr_report_spec(), ...)

Arguments

Value

A cr_lab_report with additional evidence and local root fields.

Description

Stable line types for categorical figures

Usage

cr_linetypes(n = NULL, names = NULL)

Arguments

Description

Fits a univariate logistic regression on a single fluorescence channel for the binary outcome treatment == treatment (vs. treatment == control). Returns a cr_result with the fitted model, ROC curve and AUC.

Usage

cr_logistic(
  experiment,
  channel,
  treatment,
  control,
  level = c("cell", "replicate")
)

Arguments

Value

A cr_result.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
res <- cr_logistic(exp,
                   channel = "marker_1",
                   treatment = "CompoundA_high",
                   control = "Untreated")
print(res)

Description

Turns a label into an identifier that a LaTeX control sequence accepts: letters only, with digits spelled out and every other character dropped. "CompoundA_5min" becomes "CompoundAfivemin".

Usage

cr_macro_name(x, prefix = NULL)

Arguments

Value

A character vector of the same length as x.

See Also

cr_macros().

Other macros: cr_enumerate(), cr_format_number(), cr_macros(), cr_macros_from()

Examples

cr_macro_name(c("CompoundA_5min", "interval-2", "n cells"))
cr_macro_name("estimate", prefix = "screen")

Description

Writes every number a write-up quotes into one machine-generated file, so the text can reference the value by name instead of repeating the digits. A number that lives in exactly one place cannot disagree with itself: re-run the analysis, re-emit the file, and the document is current. Splicing an estimate from one run beside an interval from another stops being possible.

Usage

cr_macros(
  values,
  file,
  format = c("tex", "json", "yaml"),
  prefix = NULL,
  header = NULL,
  digits = 3,
  big_mark = ",",
  na = "--"
)

Arguments

Details

LaTeX control sequences may contain letters only, so names are transliterated by cr_macro_name() — "CompoundA_5min" becomes ⁠\CompoundAfivemin⁠. Two source names that transliterate to the same macro are an error rather than a silent overwrite.

Value

The output path (invisibly), or a character vector of lines when file is NULL.

See Also

cr_macros_from() to derive the values from a report, cr_macro_name(), cr_format_number(), cr_enumerate().

Other macros: cr_enumerate(), cr_format_number(), cr_macro_name(), cr_macros_from()

Examples

vals <- list(cells_analyzed = 128400L, units_analyzed = 96L,
             top_estimate = 1.42, top_ci_low = 0.55)
cat(cr_macros(vals, file = NULL), sep = "\n")

f <- tempfile(fileext = ".tex")
cr_macros(vals, f, prefix = "screen")
cat(readLines(f)[1:2], sep = "\n")

Description

Walks an assembled report (or any table of contrasts) and turns it into the named values cr_macros() emits: the disposition counts, one entry per contrast and numeric column, and the enumerations that a sentence would otherwise state by hand — which intervals exclude the null, and how many. Enumerations are the entries most worth generating, because a hand-typed list is wrong as soon as one row of the analysis changes.

Usage

cr_macros_from(x, file, label_cols = NULL, ci = c("ci_low", "ci_high"), ...)

Arguments

Value

The output path (invisibly), or a character vector of lines when file is NULL.

See Also

cr_macros().

Other macros: cr_enumerate(), cr_format_number(), cr_macro_name(), cr_macros()

Examples

eff <- data.frame(
  group = c("CompoundA", "CompoundB", "CompoundC"),
  estimate = c(1.42, 0.31, -0.88),
  ci_low = c(0.55, -0.10, -1.60),
  ci_high = c(2.29, 0.72, -0.16)
)
cat(cr_macros_from(eff, file = NULL), sep = "\n")

Description

Acquisition software and operators annotate exports with short markers, and those markers change the analysis. A cr_marker_rules object states which regular expression means what, so that a marker becomes a typed flag instead of a string somebody has to remember.

Usage

cr_marker_rules(
  merge_unit = NULL,
  partial_plate = NULL,
  omitted_reagent = NULL,
  reacquisition = NULL,
  lot = NULL,
  capture_unknown = TRUE,
  ignore_case = TRUE
)

Arguments

Details

The distinctions the rules encode are deliberate:

• merge_unit sits on a file and means one spatial unit was acquired in two passes. The two files are one unit and must be merged before any per-unit balancing, or the unit contributes twice the cells of its neighbours.

• partial_plate sits on a container (the plate directory) and means a partly filled plate. It has no downstream consequence. Collapsing the two into one flag hides the one that matters, so they are matched against different strings.

• omitted_reagent marks the specificity arm, where the detection reagent was left out. These acquisitions are never samples.

• reacquisition marks a repeated read of a unit that already has a plain sibling file.

• lot marks a different reagent lot. A lot marker is not an omitted-reagent control; pooling the two inverts the meaning of the arm.

Any trailing parenthetical that matches none of the rules is captured verbatim into a variant column when capture_unknown = TRUE, rather than being guessed at or silently dropped.

Value

An object of class cr_marker_rules (a list).

See Also

cr_extract_markers(), cr_parse_paths(), cr_merge_rules().

Other import: cr_assign_units(), cr_centroid_overlap(), cr_column_map(), cr_extract_markers(), cr_filename_grammar(), cr_merge_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

rules <- cr_marker_rules(
  merge_unit = "\\(split\\)",
  partial_plate = "\\(partial\\)",
  omitted_reagent = "\\(no reagent\\)",
  reacquisition = "\\(repeat\\)",
  lot = "\\(lot[A-Z]\\)"
)
rules

Description

Combines two or more cr_experiment objects that share the same schema (channel panel, spatial unit). Useful for multi-plate studies. Well/slide names must be unique across inputs (prefix them with a plate identifier if necessary).

Usage

cr_merge_experiments(...)

Arguments

Value

A single merged cr_experiment.

Examples

e1 <- cr_example_experiment(seed = 1, n_cells_per_well = 10)
e2 <- cr_example_experiment(seed = 2, n_cells_per_well = 10)
e2$cells$well <- paste0("p2_", e2$cells$well)
e2$design$well <- paste0("p2_", e2$design$well)
merged <- cr_merge_experiments(e1, e2)

Description

States which replicate suffixes and marker flags mean "these files are one unit" and which mean "these files are different units". Getting this wrong is silent in both directions, so each rule is explicit.

Usage

cr_merge_rules(
  merge_suffix = "\\.1$",
  merge_marker = "merge_unit",
  keep_separate = "\\.2$",
  reacquisition = "reacquisition",
  merge_reacquisition = TRUE,
  separate_suffix = "re"
)

## S3 method for class 'cr_merge_rules'
print(x, ...)

Arguments

Details

• merge_suffix matches the replicate index of a file that is the second pass over a unit that already exists. Left unmerged, such a unit draws a full cell allocation twice and is double-weighted in its own batch.

• merge_marker names a logical column (typically produced by cr_extract_markers()) that must also be TRUE before a suffix match is merged. Requiring the marker is the conservative default: a suffix on its own is not evidence.

• keep_separate matches replicate indices that look mergeable but are a different physical unit. It always wins over merge_suffix. cr_centroid_overlap() is the evidence test for deciding which of the two a given suffix is.

• reacquisition names the logical column marking a repeated read. With merge_reacquisition = TRUE such a file folds into its plain sibling; otherwise separate_suffix is appended so it stays a unit of its own.

Value

An object of class cr_merge_rules (a list).

x, invisibly.

See Also

cr_assign_units(), cr_extract_markers(), cr_centroid_overlap().

Other import: cr_assign_units(), cr_centroid_overlap(), cr_column_map(), cr_extract_markers(), cr_filename_grammar(), cr_marker_rules(), cr_parse_paths(), cr_path_spec(), cr_read_cellprofiler(), cr_read_cells(), cr_read_design(), cr_read_export(), cr_read_exports(), cr_read_qupath(), cr_read_segmantr(), cr_unit_map()

Examples

cr_merge_rules()
cr_merge_rules(merge_marker = NULL, keep_separate = NULL)

Description

Count cells in a cr_experiment

Usage

cr_n_cells(experiment, by = NULL)

Arguments

Value

Either a scalar integer (no grouping) or a tibble with cell counts per group.

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 10)
cr_n_cells(exp)
cr_n_cells(exp, by = "treatment")

Description

Applies a channel-wise normalization. The normalized channel values replace the original column in cells.

Usage

cr_normalize(
  experiment,
  channel,
  method = c("background", "control", "zscore", "robust_zscore", "quantile"),
  control_group = NULL,
  ...
)

Arguments

Details

• "background" subtracts per-well background via cr_background_subtract() (percentile method, 5th percentile).

• "control" divides each cell's intensity by the median intensity of cells assigned to control_group, then takes the log2 ratio.

• "zscore" applies a global Z-score across all cells.

• "robust_zscore" uses the median and MAD.

• "quantile" maps the per-well empirical distributions onto the global quantile distribution.

All five methods use a single, pooled reference for the whole experiment and overwrite the channel in place. When the reference has to be the control of each cell's own batch – the usual situation once several plates, runs or acquisition days are involved – use cr_standardize_batch() instead, which adds new columns rather than overwriting the measured signal.

Value

A modified cr_experiment.

See Also

cr_standardize_batch() for per-batch standardization, cr_background_subtract(), cr_correct_batch().

Other normalization functions: cr_background_subtract()

Examples

exp <- cr_example_experiment(seed = 1, n_cells_per_well = 30)
cr_normalize(exp, channel = "marker_1", method = "robust_zscore")

Description

Returns hex colours from the palette every ⁠cr_plot_*⁠ function uses for discrete groupings. The qualitative set is Okabe-Ito, the standard colour-vision-safe qualitative palette; it deliberately contains no red/green pair, so hue never encodes an opposition that a large minority of readers cannot separate.

Usage

cr_palette(
  n = NULL,
  type = c("qualitative", "sequential", "diverging"),
  names = NULL,
  mode = c("colour", "grayscale")
)

Arguments

Details

Hue alone is not treated as a sufficient encoding: use cr_shapes() (or cr_scale_group(), which wires both at once) so that every grouping is carried by shape as well as colour.

Value

A character vector of hex colour strings, named when names is supplied or when the whole qualitative palette is returned.

See Also

cr_shapes(), cr_scale_group(), cr_theme()

Other plot design: cr_scale_group(), cr_shapes(), cr_theme()

Examples

cr_palette()
cr_palette(3)
cr_palette(5, names = c("a", "b", "c", "d", "e"))
cr_palette(7, type = "diverging")