scatrans.active_score

Contents

scatrans.active_score#

scatrans.active_score(adata_input, groupby='condition', target_group=None, reference_group=None, subset_col=None, subset_values=None, weight_fc=1.0, weight_unspliced=1.0, weight_pval=1.0, pval_cutoff=0.05, logfc_cutoff=0.35, unspliced_excess_fdr_cutoff=0.05, de_method='t-test_overestim_var', pseudobulk_de_backend='pydeseq2', pydeseq2_min_counts=10, use_permutation=False, perm_de_backend='same', n_perm=100, n_jobs=-1, de_preprocess='auto', gene_type_filter=None, use_pseudobulk=False, sample_col=None, min_cells=10, min_counts=1000, pb_x_layer='spliced', pb_use_total_for_x=True, min_total_counts=50, random_seed=42, show_plot=False, auto_adjust_n_perm=True, prior_weight=5.0, strict_pydeseq2_counts=True, mode='heuristic', advanced_fallback=True, advanced_n_neighbors=30, advanced_n_pcs=30, advanced_use_precomputed=False, allow_advanced_pseudobulk=False, advanced_recompute_neighbors=True, spliced_layer='spliced', unspliced_layer='unspliced', use_mixed_model=False, use_delta_variance_pval=False, delta_var_pval_cutoff=0.05, mixed_model_pval='wald', paired_replicates=False, use_memento_de=False, memento_capture_rate=0.07, memento_num_boot=5000, memento_n_cpus=-1, perm_use_memento_de=False, bias_correction='huber_length_intron', show_effective_gamma=False, gamma_method='heuristic_shrink', ranking_mode='composite', copy_input=True, **deprecated_kwargs)[source]#

Identify genes showing higher unspliced (nascent) RNA in the target group relative to reference (positive unspliced excess after reference-gamma correction), combined with upregulation (positive logFC).

The returned significant DataFrame (second return value) is strictly one-sided: it only contains genes that are upregulated in target (logFC > cutoff) AND have positive bias-corrected unspliced excess (nascent excess > 0). Downregulated genes or genes with negative excess are never included in the built-in significant list even if DE is strong. Use all_results + filter_active_genes() (with logfc_direction="down" or "both") for other directions or custom thresholds.

Required: target_group and reference_group must match values in adata.obs[groupby] (no implicit defaults). Use active_score_simple() for Disease/Control convenience defaults.

Recommended entry points (to avoid the long parameter list): - For new users: active_score_simple() - For guided configuration: recommend_workflow() then active_score(..., **rec["suggested_kwargs"]) - Presets are defined in WORKFLOW_PRESETS.

Deprecated keyword-only arguments (emit DeprecationWarning): active_fdr_cutoff, prioritize_velocity.

The full signature below is for power users and internal composition. Many parameters have inter-dependencies that are validated early; hidden interactions exist (e.g. ranking_mode affects some weight_* defaults).

The function computes: - logFC and p_adj between target and reference (via scanpy or PyDESeq2). - An unspliced (nascent) excess delta = U_target − (gamma_ref × S_target), where

gamma_ref is a shrunk U/S ratio estimated in the reference group.

  • (by default) A Huber regression correction of the delta on log(gene length) and log(intron number); the residuals become unspliced_excess_residual.

  • When use_permutation=True, independent one-sided permutation p-values and BH-FDR are computed for the bias-corrected unspliced excess residual (unspliced_excess_pval, unspliced_excess_fdr).

  • A soft-scaled, weighted combination of the three signals, scaled to 0–100.

Several extensions are available as explicit options (see the README section “Optional advanced features”): - show_effective_gamma - gamma_method=”robust_median” (heuristic variant of additive shrinkage using median per-gene ratio as base; not Bayesian) - gamma_method=”empirical_bayes” (hierarchical empirical Bayes log-ratio shrinkage; recommended for small reference groups) - bias_correction=”none” - use_mixed_model - use_permutation - prioritize_velocity (deprecated convenience; prefer ranking_mode="nascent_excess") - ranking_mode: "composite" (default) or "nascent_excess" (rank from

unspliced_excess_residual only)

Diagnostics (including global unspliced fraction and bias fit details) are stored under adata.uns[“scatrans”][“diagnostics”]. The full ranked table (all_results) is the main output; the built-in significant list uses the same default thresholds as filter_active_genes() with preset="heuristic" (logFC > 0.35, unspliced_excess_residual > 1.0, active_score >= 55, etc.) and may still be small on low-signal data.

A separate function diagnose_design is available to summarize the experimental design and surface relevant warnings before analysis.

Important statistical note (reporting boundaries): - active_score is a heuristic ranking score only. It is NOT a p-value,

effect size with calibrated uncertainty, or evidence of causal transcriptional activation.

  • unspliced_excess_* columns are group-contrast proxies (reference-gamma excess), not outputs of a stochastic/dynamical RNA velocity model. Do not treat them as literal nascent transcription rates without independent validation.

  • For significance claims use DE p_adj and/or permutation unspliced_excess_fdr (when use_permutation=True). Cross-check with orthogonal methods when possible.

  • The built-in significant list is a strict conjunction and is frequently empty — this is intentional. Use all_results + filter_active_genes for exploration.

Full usage, recommended workflow, and result interpretation are documented in the package README (“Statistical interpretation and reporting boundaries”).

copy_inputbool, default True

If True (default), deep-copy the input once after combining obs filters (subset_col + target/reference groups) so the caller’s object is not mutated. If False, reuse the input in-place when no obs filtering is required; otherwise subset without calling AnnData.copy() (lower memory on large objects). The returned AnnData is always the working object and may be mutated (new .var columns, layer remapping, etc.).

Parameters:

  • adata_input (Any)

  • groupby (str)

  • target_group (str | None)

  • reference_group (str | None)

  • subset_col (str | None)

  • subset_values (str | list[str] | tuple[str, ...] | None)

  • weight_fc (float)

  • weight_unspliced (float)

  • weight_pval (float)

  • pval_cutoff (float)

  • logfc_cutoff (float)

  • unspliced_excess_fdr_cutoff (float)

  • de_method (str)

  • pseudobulk_de_backend (str)

  • pydeseq2_min_counts (int)

  • use_permutation (bool)

  • perm_de_backend (str)

  • n_perm (int)

  • n_jobs (int)

  • de_preprocess (str)

  • gene_type_filter (str | None)

  • use_pseudobulk (bool)

  • sample_col (str | None)

  • min_cells (int)

  • min_counts (int)

  • pb_x_layer (str)

  • pb_use_total_for_x (bool)

  • min_total_counts (int)

  • random_seed (int)

  • show_plot (bool)

  • auto_adjust_n_perm (bool)

  • prior_weight (float)

  • strict_pydeseq2_counts (bool)

  • mode (str)

  • advanced_fallback (bool)

  • advanced_n_neighbors (int)

  • advanced_n_pcs (int)

  • advanced_use_precomputed (bool)

  • allow_advanced_pseudobulk (bool)

  • advanced_recompute_neighbors (bool)

  • spliced_layer (str)

  • unspliced_layer (str)

  • use_mixed_model (bool)

  • use_delta_variance_pval (bool)

  • delta_var_pval_cutoff (float)

  • mixed_model_pval (str)

  • paired_replicates (bool)

  • use_memento_de (bool)

  • memento_capture_rate (float)

  • memento_num_boot (int)

  • memento_n_cpus (int)

  • perm_use_memento_de (bool)

  • bias_correction (str)

  • show_effective_gamma (bool)

  • gamma_method (str)

  • ranking_mode (str)

  • copy_input (bool)

  • deprecated_kwargs (Any)

Return type:

tuple[AnnData, DataFrame, DataFrame]

Contents