Skip to contents

Score paired pathway responses after an in-silico perturbation

AlertSystemScore.Rd

AlertSystemScore() compares each cell with itself between a baseline assay and a virtually perturbed assay. It supports two complementary channels:

Usage

AlertSystemScore(
  seurat_obj,
  gene_sets,
  perturbation_name,
  baseline_assay = "RNA",
  group.by = NULL,
  sample.by = NULL,
  layer = "data",
  min_genes = 5L,
  score_methods = c("expression", "ucell"),
  ucell_change = c("difference", "log2_ratio"),
  ucell_pseudocount = 1e-04,
  summary_fun = c("trimmed_mean", "median", "mean"),
  trim = 0.1,
  expression_response_threshold = 0.01,
  ucell_response_threshold = NULL,
  null_unit = c("auto", "sample", "cell", "none"),
  n_permutations = 1000L,
  seed = 1L,
  leading_n = 5L,
  gene_change_tolerance = 1e-08,
  misc_name = "AlertSystem",
  out_dir = NULL,
  output_prefix = NULL,
  overwrite_outputs = FALSE,
  return_details = FALSE,
  verbose = TRUE
)

Arguments

seurat_obj

Seurat object containing baseline and perturbation assays.

gene_sets

Named list of pathway gene vectors.

perturbation_name

Name of the virtually perturbed assay.

baseline_assay

Name of the baseline assay; default "RNA".

group.by

Optional metadata column defining cell groups. When NULL, all cells form the "all_cells" group.

sample.by

Optional metadata column identifying biological samples. Strongly recommended for inferential calibration.

layer

Log-normalized layer used by expression scoring.

min_genes

Minimum retained genes required for a pathway.

score_methods

Any of c("expression", "ucell").

ucell_change

UCell response transformation. "difference" computes post - pre; "log2_ratio" computes log2((post + ucell_pseudocount)/(pre + ucell_pseudocount)).

ucell_pseudocount

Positive pseudocount used only for "log2_ratio".

summary_fun

Group-level effect summary: "trimmed_mean", "median", or "mean".

trim

Fraction removed from each tail by the trimmed mean.

expression_response_threshold

Absolute expression-delta threshold.

ucell_response_threshold

Absolute UCell-response threshold. When NULL, defaults to 0.005 for differences and 0.1 for log2 ratios.

null_unit

"auto", "sample", "cell", or "none". "auto" uses samples when sample.by is supplied and otherwise disables null calibration.

n_permutations

Number of sign-flip permutations.

seed

Random seed for null calibration and temporary UCell column names.

leading_n

Number of leading genes recorded per pathway/group.

gene_change_tolerance

Numeric tolerance used to classify directly and propagation-only changed genes.

misc_name

Name used under seurat_obj@misc.

out_dir

Optional output directory. UPDATED: when supplied, the complete state is saved as RDS and metrics are exported as CSV.

output_prefix

Optional filename prefix. Defaults to a sanitized perturbation-based prefix.

overwrite_outputs

Whether existing RDS/CSV outputs may be replaced.

return_details

Return a result list instead of only the Seurat object.

verbose

Emit progress messages.

Value

A Seurat object, or a list containing seurat, per_cell, metrics, gene_sets, params, info_file, and metrics_file.

Details

  • expression: mean post-minus-pre log-normalized expression over retained pathway genes.

  • ucell: either post-minus-pre UCell score ("difference") or the legacy log2 ratio of post and pre UCell scores ("log2_ratio").

The cell-level pathway responses are summarized within cell groups. Response prevalence, directionality, leading genes, and optional sample-level sign-flip calibration are reported separately.