cisTarget

Motif enrichment, annotation-based pruning and ranking-file loading.

rustscenic.cistarget

Motif enrichment scoring (pycistarget replacement, core algorithm).

pycistarget's central operation: for each regulon (a set of target genes), compute the AUC of recovery of those genes against a motif ranking. High AUC means the motif is enriched for that regulon. The aertslab feather-format ranking databases (hg38_10kb_up_and_down_tss.feather etc.) provide the per-motif gene rankings.

We reuse rustscenic's aucell core - the algorithm is mathematically identical, just applied to motif rankings rather than per-cell expression rankings. This module is a thin wrapper that:

  1. Accepts a motif-ranking matrix (motifs × genes, where cell[m, g] = rank of gene g for motif m; lower rank = stronger association).
  2. Accepts regulons (gene sets).
  3. For each (regulon, motif) pair, computes recovery AUC.
  4. Returns enriched pairs above threshold.
  5. Optionally prunes enriched motifs through motif-to-TF annotations to produce final TF-supported regulons.

We do NOT bundle the large aertslab ranking databases. Callers can load feather files via pyarrow and pass the resulting DataFrame. Motif annotation tables are separate inputs; use prune_regulons when you need pycistarget-style motif-annotation pruning rather than candidate GRN regulons.

enrich 

enrich(
    rankings: DataFrame,
    regulons: Iterable,
    *,
    top_frac: float = 0.05,
    auc_threshold: float = 0.05,
    nes_threshold: float | None = None,
    rank_universe_size: int | None = None,
) -> pd.DataFrame

Compute motif-regulon enrichment AUCs and NES.

Parameters:

Name Type Description Default
rankings DataFrame

DataFrame with motifs as rows (index = motif names) and genes as columns. Values = rank of gene for that motif (lower rank = stronger association). Use load_aertslab_feather() to load the aertslab feather DB in the correct orientation.

 required
regulons Iterable

Iterable of (name, gene_list) tuples, or objects with .name + .genes.

 required
top_frac float

Fraction of top-ranked genes per motif used as AUC cutoff (default 0.05, matches pyscenic / ctxcore gene-mode). pycistarget region-mode uses auc_threshold=0.005 instead; pass that explicitly for region-mode parity.

 0.05
auc_threshold float

Minimum AUC to report a regulon-motif pair as enriched. Set to 0 to return all scores.

 0.05
nes_threshold float | None

Optional minimum NES to keep. None (default) returns all rows that pass auc_threshold and is backwards-compatible with v0.4.3 callers. Set to 3.0 to match the canonical pyscenic / pycistarget cutoff. When NES is undefined for a regulon (zero standard deviation across motifs, or fewer than 30 motifs), NES is recorded as NaN and a warning is emitted; NaN rows are dropped by any nes_threshold filter but preserved when nes_threshold is None.

 None
rank_universe_size int | None

Original ranking-universe width when rankings has been projected to a subset of columns. Internal HPC pipeline hook; callers normally leave this as None.

 None

Returns:

Type Description
pandas.DataFrame with columns [regulon, motif, auc, nes], sorted descending
by AUC. Only rows where auc >= auc_threshold (and, if set, nes >= nes_threshold).
NES is computed as the per-regulon population z-score of AUC across the
full motif universe (matching pyscenic ``transform.py`` and pycistarget
``motif_enrichment_cistarget.py``).

prune_enriched_motifs 

prune_enriched_motifs(
    enriched: DataFrame,
    motif_annotations: DataFrame,
    *,
    motif_col: str | None = None,
    tf_col: str | None = None,
    auc_threshold: float | None = None,
    nes_threshold: float | None = None,
    case_sensitive: bool = False,
) -> pd.DataFrame

Filter enriched motif rows through motif-to-TF annotations.

This is the pycistarget-style pruning step that turns motif enrichment evidence into TF-supported regulons: a row survives only when the motif enriched for TF_regulon is annotated to that same TF.

Parameters:

Name Type Description Default
enriched DataFrame

enrich output with columns ['regulon', 'motif', 'auc'] plus an optional nes column (present when produced by v0.4.4+ enrich).

 required
motif_annotations DataFrame

DataFrame mapping motifs to TF names. Common column names such as motif, motif_id, features and TF, gene_name are auto-detected; pass motif_col / tf_col to override.

 required
motif_col str | None

Motif identifier column in motif_annotations; auto-detected when omitted.

 None
tf_col str | None

TF symbol column in motif_annotations; auto-detected when omitted.

 None
auc_threshold float | None

Optional minimum AUC to keep before applying annotations. None preserves the rows already returned by enrich.

 None
nes_threshold float | None

Optional minimum NES to keep before applying annotations. Requires the enriched DataFrame to contain an nes column. Rows with NaN NES are dropped by this filter. 3.0 matches the canonical pyscenic / pycistarget cutoff.

 None
case_sensitive bool

Match TF names case-sensitively. Default False tolerates common upper/lower-case differences in annotation exports while preserving the candidate regulon's original TF symbol in the result.

 False

Returns:

Type Description
DataFrame containing the enriched rows that pass motif annotation support,
plus ``tf`` and ``annotation_tf`` columns.

prune_regulons 

prune_regulons(
    enriched: DataFrame,
    regulons: Iterable,
    motif_annotations: DataFrame,
    *,
    rankings: DataFrame | None = None,
    top_frac: float = 0.05,
    auc_threshold: float | None = None,
    nes_threshold: float | None = None,
    min_genes: int = 1,
    motif_col: str | None = None,
    tf_col: str | None = None,
    case_sensitive: bool = False,
    rank_universe_size: int | None = None,
) -> dict[str, list[str]]

Create final motif-annotation-pruned regulons.

Candidate regulons are first filtered to rows whose enriched motifs are annotated back to the source TF. When rankings is provided, each surviving regulon's targets are further restricted to genes recovered in the enriched motif's top-ranked window, matching the usual cistarget pruning semantics more closely than keeping the whole GRN top-N list. nes_threshold adds the canonical pyscenic / pycistarget NES filter on top of motif annotation matching; pass 3.0 for the standard cutoff.

Parameters:

Name Type Description Default
enriched DataFrame

Motif enrichment rows containing regulon, motif and auc. An nes column is required when nes_threshold is set.

 required
regulons Iterable

Candidate regulons as a name-to-genes mapping, (name, genes) pairs or accepted regulon objects.

 required
motif_annotations DataFrame

DataFrame mapping motif identifiers to TF symbols.

 required
rankings DataFrame | None

Optional motifs-by-genes rank DataFrame. When provided, restrict surviving targets to the supported motifs' top-ranked window.

 None
top_frac float

Fraction of the ranking universe used for target recovery when rankings is provided.

 0.05
auc_threshold float | None

Optional minimum motif AUC applied before annotation matching.

 None
nes_threshold float | None

Optional minimum motif NES applied before annotation matching.

 None
min_genes int

Minimum retained target count for a final regulon.

 1
motif_col str | None

Motif identifier column in motif_annotations; auto-detected when omitted.

 None
tf_col str | None

TF symbol column in motif_annotations; auto-detected when omitted.

 None
case_sensitive bool

Match annotation TF symbols case-sensitively when true.

 False
rank_universe_size int | None

Original feature count for projected rankings. Leave unset when columns cover the full ranking universe.

 None

Returns:

Type Description
dict[str, list[str]]

Surviving regulon names mapped to their retained target genes.

load_aertslab_feather 

load_aertslab_feather(path) -> pd.DataFrame

Load an aertslab motif-ranking feather file.

The feather file typically has motifs or features as one column and the rest as genes. Returns a DataFrame indexed by motif name.

Parameters:

Name Type Description Default
path

Feather-file path accepted by pyarrow.feather.read_feather.

 required

Returns:

Type Description
DataFrame

Ranking table with features or motifs moved to the index when such a column exists.

Reexported helpers

These names are also available from this module. They share the underlying implementation and source documentation of their original definitions.

rustscenic.cistarget.iter_regulon_pairs 

iter_regulon_pairs(regulons: Iterable) -> Iterator[tuple[str, list[str]]]

Yield (name, genes) pairs from dicts, tuples, or Regulon objects.

Parameters:

Name Type Description Default
regulons Iterable

Name-to-genes mapping, iterable of (name, genes) pairs, mappings with name/genes keys, or objects exposing a name and genes.

 required

rustscenic.cistarget.prepare_regulon_indices 

prepare_regulon_indices(
    gene_names: Iterable[str], regulons: Iterable
) -> tuple[list[str], list[list[int]], list[tuple[str, list[str]]], int]

Map regulon genes onto a feature axis once, preserving coverage inputs.

Parameters:

Name Type Description Default
gene_names Iterable[str]

Feature names in expression-matrix column order.

 required
regulons Iterable

Regulons accepted by iter_regulon_pairs.

 required

Returns:

Type Description
tuple

Retained names, feature-index lists, original regulon pairs and number of regulons dropped because no features matched.

rustscenic.cistarget.prepare_regulon_indices_with_coverage 

prepare_regulon_indices_with_coverage(
    gene_names: Iterable[str], regulons: Iterable
) -> tuple[
    list[str],
    list[list[int]],
    list[tuple[str, list[str]]],
    dict[str, tuple[int, int]],
    int,
]

Map regulon genes and coverage in one Rust call.

Parameters:

Name Type Description Default
gene_names Iterable[str]

Feature names in expression-matrix column order.

 required
regulons Iterable

Regulons accepted by iter_regulon_pairs.

 required

Returns:

Type Description
tuple

Retained names, feature-index lists, original regulon pairs, per-regulon (matched, total) coverage and dropped-empty count.

rustscenic.cistarget.string_list 

string_list(values: Iterable) -> list[str]

Return Python strings with minimal pandas boundary overhead.

Parameters:

Name Type Description Default
values Iterable

Iterable, pandas Series or Index, or NumPy array of values to convert to strings in input order.

 required

rustscenic.cistarget.string_list_missing_empty 

string_list_missing_empty(values: Iterable) -> list[str]

Return strings, mapping pandas-style missing scalar values to "".

Parameters:

Name Type Description Default
values Iterable

Iterable, pandas Series or Index, or NumPy array. Missing scalars become empty strings; other values are converted with str.

 required

rustscenic.cistarget.tf_from_regulon_name 

tf_from_regulon_name(name: str) -> str

Reduce common SCENIC regulon-name variants to the bare TF symbol.

Parameters:

Name Type Description Default
name str

Regulon name whose _regulon, _extended, _activator, _repressor, (+) and (-) suffixes should be stripped.

 required