Prepare experimental observations for POWERUP — prepare_powerup

Prepare measurement or barcode-count observations for posterior updating. Measurement mode selects user-supplied observation values and uncertainty; barcode-count mode processes raw guide counts through the barcode pipeline.

Usage

prepare_powerup_observations(
  mode = c("measurements", "barcode_counts"),
  observations = NULL,
  counts = NULL,
  guide_reference = NULL,
  analysis_samples = NULL,
  sample_reference_map = NULL,
  guide_negative_control_patterns = c("ONE_INTERGENIC_SITE", "NO_SITE"),
  guide_negative_control_fuzzy = c(TRUE, TRUE),
  low_count_z_cutoff = -3,
  sd_cutoff = NA_real_,
  min_guides = 2L,
  pseudogene_size = 2L,
  pseudogene_seed = 7L,
  pseudogene_control_regex = c("ONE_INTERGENIC_SITE", "NO_SITE"),
  target_pvalue_method = c("standard_normal", "empirical_null"),
  include_unexpressed = character(0),
  bootstrap_repeats = 2000L,
  bootstrap_seed = 1L,
  return_details = FALSE,
  sample_col = NULL,
  perturbation_col = NULL,
  measurement_type_col = NULL,
  measurement_type = NULL,
  measurement_value_col = NULL,
  measurement_sd_col = NULL,
  positive_controls = NULL,
  negative_controls = NULL,
  normalize_with_prefix = NULL
)

Arguments

mode: Observation input mode. One of "measurements" or "barcode_counts".
observations: Experimental measurement table for mode = "measurements". Each selected row must contain a user-prepared observation value and SD.
counts: Raw barcode-count table for mode = "barcode_counts".
guide_reference: Guide-to-perturbation reference table for mode = "barcode_counts".
analysis_samples: Optional canonical samples to analyze for mode = "barcode_counts". Replicate suffixes such as _R1 must not be supplied here.
sample_reference_map: Named character vector mapping each base sample name to its canonical reference sample for mode = "barcode_counts".
guide_negative_control_patterns: Character vector identifying guide-level negative controls used to normalize guide LFCs.
guide_negative_control_fuzzy: Logical vector indicating whether each guide negative-control pattern is matched as a pattern.
low_count_z_cutoff: Reference-sample log-normalized count z-score below which barcodes are removed.
sd_cutoff: Optional maximum replicate guide-LFC SD.
min_guides: Minimum number of guides required for a target.
pseudogene_size: Number of negative-control guides grouped into each synthetic control target.
pseudogene_seed: Random seed used for deterministic synthetic control-target grouping.
pseudogene_control_regex: Character vector identifying guide-control classes to group into synthetic control targets.
target_pvalue_method: Target-level p-value method for barcode counts. "standard_normal" uses two-sided standard-normal probabilities from Stouffer target z-scores. "empirical_null" compares target z-scores with a within-sample null built by repeatedly resampling negative-control guides and grouping them into synthetic pseudogenes.
include_unexpressed: Optional perturbations to treat as additional target-level negative controls.
bootstrap_repeats: Number of bootstrap iterations used for hierarchical observation uncertainty and, when target_pvalue_method = "empirical_null", the empirical target-z null. Defaults to 2000.
bootstrap_seed: Fixed random seed used for reproducible barcode-count bootstrap calculations.
return_details: If TRUE for mode = "barcode_counts", return the scientific intermediate tables used to produce the final observations.
sample_col: Column containing sample identifiers. Defaults to sample in measurement mode.
perturbation_col: Column containing perturbation identifiers. Defaults to perturbation in measurement mode.
measurement_type_col: Optional column containing measurement-type labels. Supply together with measurement_type when selecting one measurement type from a table containing multiple types.
measurement_type: Optional measurement type to select. Must be supplied together with measurement_type_col.
measurement_value_col: Column containing the user-prepared observation value. Defaults to value.
measurement_sd_col: Column containing the user-prepared observation SD. Defaults to sd.
positive_controls: Character vector of positive-control perturbations for mode = "barcode_counts".
negative_controls: Character vector of negative-control perturbations for mode = "barcode_counts".
normalize_with_prefix: Optional prefix used to normalize final perturbation identifiers. NULL preserves the original identifiers, "" converts them to lowercase, and a value such as "ko_" converts them to lowercase and adds that prefix.

Value

By default, a tibble with one row per sample-perturbation pair. In barcode-count mode, hierarchical-bootstrap metadata include original-scale and logit-scale uncertainty summaries, the bootstrap fraction at or above probability 0.5, and a directly estimated logit latent SD for transformed posterior updating. For mode = "barcode_counts" with return_details = TRUE, a list containing observations and the intermediate tables used to produce them.

Examples

measurements <- data.frame(
  cell_line = c("S1", "S1"),
  gene = c("CTNNB1", "FGFR1"),
  effect = c(0.25, 0.80),
  uncertainty = c(0.10, 0.15)
)

prepared_observations <- prepare_powerup_observations(
  mode = "measurements",
  observations = measurements,
  sample_col = "cell_line",
  perturbation_col = "gene",
  measurement_value_col = "effect",
  measurement_sd_col = "uncertainty",
  normalize_with_prefix = "ko_"
)
prepared_observations
#> # A tibble: 2 × 4
#>   sample perturbation observation_mean observation_sd
#>   <chr>  <chr>                   <dbl>          <dbl>
#> 1 S1     ko_ctnnb1                0.25           0.1 
#> 2 S1     ko_fgfr1                 0.8            0.15