scatrans.filter_active_genes

scatrans.filter_active_genes#

scatrans.filter_active_genes(results, *, preset=None, active_score_cutoff=<object object>, pval_cutoff=<object object>, unspliced_excess_residual_cutoff=<object object>, logfc_cutoff=<object object>, logfc_direction='up', active_score_fdr_cutoff=<object object>, unspliced_excess_fdr_cutoff=<object object>, effective_gamma_min=<object object>, effective_gamma_max=<object object>, delta_variance_min=<object object>, return_mask=False, inplace=False, **deprecated_kwargs)[source]#

Apply custom post-filtering to a results DataFrame (from active_score or differential_expression).

This helper works for both: - Full active_score output (has active_score + unspliced_excess_residual). - Pure DE results from differential_expression (only logFC / p_adj + optional memento columns).

It standardizes the common workflow: 1. Run active_score(…) or differential_expression(…). 2. Use this function on the returned table to derive a final gene list.

The function supports preset to automatically select reasonable default thresholds for different analysis modes:

  • preset=”heuristic”: stricter defaults suitable for typical single-cell data with default weights (active_score >= 55, unspliced_excess_residual > 1.0, etc.).

  • preset=”pseudobulk”: more lenient defaults that account for the much smaller magnitude of unspliced_excess_residual and active_score after sample-level aggregation (active_score >= 5, unspliced_excess_residual > 0.05, logFC > 0.2, etc.).

  • preset=”significant” (aliases: “builtin”, “active_score_significant”): exactly reproduces the built-in significant list from active_score() using metadata stored in all_results.attrs['scatrans_filter_context']. Requires use_permutation=True on the upstream run.

  • preset=None (or “permissive”/”none”): apply only explicitly provided cutoffs; this is the most permissive / backward-compatible mode and returns nearly the full table (subject to any user-supplied thresholds).

When all_results carries scatrans_filter_context with use_fdr_for_significance=False (common for pseudobulk with few samples), preset-based FDR cutoffs are skipped automatically unless you pass explicit unspliced_excess_fdr_cutoff / active_score_fdr_cutoff.

Presets are oriented toward target-group “activated” / upregulated signals (positive logFC + positive unspliced_excess_residual; direction defaults to “up”). For downregulated or two-sided selection from differential_expression() results, pass preset=None + logfc_direction=”down” or “both” (with your desired logfc_cutoff).

If you explicitly pass any cutoff parameter, it takes precedence over the preset.

Calling with no arguments (or only the DataFrame) and no preset returns the full all_results (fully permissive).

Only filters corresponding to columns present in the DataFrame are applied. This is safe whether or not use_permutation=True or use_mixed_model=True was used.

New options for power users: - return_mask=True: return the boolean mask (pd.Series) instead of the filtered DataFrame.

Useful to combine with other logic or apply yourself.

  • inplace=True: mutate the input results DataFrame in-place (keeps only passing rows and re-sorts). Returns the (mutated) DataFrame. Use with caution; the input reference will be modified. Ignored when return_mask=True.

Parameters:

  • results (pd.DataFrame) – The all_results table returned as the third element of active_score.

  • preset (str or None) – One of “heuristic”, “pseudobulk”, “significant”, “permissive”, “none”. When provided, supplies recommended cutoff values for that analysis style for any parameters you did not explicitly pass.

  • active_score_cutoff (float) – Minimum composite active transcription score (0-100).

  • pval_cutoff (float) – Maximum adjusted p-value if a “p_adj” column is present in the results DataFrame; otherwise falls back to the nominal “p_val” column. This matches the behavior of the internal significant mask in active_score() and common user expectations (FDR control when available).

  • unspliced_excess_residual_cutoff (float) – Minimum bias-corrected unspliced (nascent) excess residual.

  • logfc_cutoff (float) – Magnitude threshold for logFC (treated as non-negative). See logfc_direction.

  • logfc_direction ({"up", "down", "both"}) – Direction filter applied when a “logFC” column is present: - “up” (default): keep if logFC > logfc_cutoff (upregulated in target) - “down”: keep if logFC < -logfc_cutoff (downregulated in target) - “both”: keep if |logFC| > logfc_cutoff (differentially expressed either way) Presets and this helper’s design are “active”/up-biased by default. Use direction=”down” or “both” with preset=None for standalone DE results.

  • active_score_fdr_cutoff (float or None) – If the column exists, max permutation FDR on the composite active_score (ranking aid).

  • unspliced_excess_fdr_cutoff (float or None) – If the column exists (use_permutation=True), max permutation FDR on unspliced_excess_residual (recommended for final gene lists).

  • effective_gamma_min (float) – Minimum reference-group effective gamma. See README section on effective_gamma.

  • effective_gamma_max (float or None) – Optional upper bound on effective_gamma.

  • delta_variance_min (float or None) – If the column exists (use_mixed_model=True), minimum variance fraction explained by condition.

  • return_mask (bool)

  • inplace (bool)

  • deprecated_kwargs (Any)

Returns:

Subset of the input. Sorted by active_score (desc) when present; otherwise by p_adj then logFC (direction-aware for pure DE tables).

Return type:

pd.DataFrame