Regulons API reference

Contents

Regulons API reference#

cytearc.regulons builds transcription-factor regulons the way SCENIC and SCENIC+ do, and co-regulated gene programs, from RNA, ATAC, and binding data such as CUT&RUN. Every set it returns, from modules and regulons to programs, cistromes, and eRegulons, is a table with source (the set) and target (a member) columns, which ds.scores.aucell (genes) and ds.scores.chromvar (peaks) score per cell and set_overlaps compares. Regions are named by their chrom:start-end ids, as ATAC peaks are. Reading cisTarget ranking databases needs the regulons extra: pip install "cytearc[regulons]".

The cell-level steps run on a DataStore: ds.regulons.grn infers the co-expression network, ds.regulons.profiles sums groups of cells such as metacells into profiles, and the scoring methods above write enrichment_scores artifacts, which EnrichmentResult.to_pandas reads as a table. The functions on this page work on those results and on reference files, such as cisTarget databases, JASPAR motifs, a genome FASTA, a gene annotation, and peak files.

RNA regulons (SCENIC)#

GRNBoost2 importances become co-expression modules, motif enrichment keeps the targets that an enriched, annotated motif of each module’s factor recovers, and the leading edges merge into TF(+) regulons.

cytearc.regulons.infer_grn(expression, gene_names, tf_names, *, targets=None, seed, parameters=GrnParameters(learningRate=0.01, maxStages=5000, maxFeatures=0.1, subsample=0.9, earlyStopWindow=25, earlyStopping='stage'), nthreads=1, progress=None)#

Score how well each transcription factor predicts each target gene.

For every target gene, a stochastic gradient boosting regressor predicts its expression from the expression of the transcription factors, leaving the target out when it is a factor itself, and each factor’s importance is recorded. This reproduces arboreto’s GRNBoost2 as pySCENIC runs it: the same regressor settings, the same seed for every target, factors in expression column order, and importances scaled by the stages fitted. A target with constant expression has no links.

Parameters:

  • expression (ndarray) – Cells-by-genes matrix. SCENIC uses raw counts.

  • gene_names (Sequence[str]) – Names of the expression columns; must be unique.

  • tf_names (Sequence[str]) – Candidate regulators. Names absent from gene_names are ignored.

  • targets (Sequence[str] | None) – Target genes to model, by default every gene.

  • seed (int) – Random state given to every target’s regressor.

  • parameters (GrnParameters) – Regressor settings; GRNBoost2 defaults when omitted.

  • nthreads (int) – Targets fitted concurrently. scikit-learn builds trees without holding the GIL, so threads scale.

  • progress (Callable[[int, int], None] | None) – Optional callback(done, total) after each target.

Return type:

DataFrame

Returns:

A DataFrame with TF, target, importance, and correlation (Pearson, across cells) columns, one row per positive importance, sorted by decreasing importance, then by target and factor name for a deterministic order. pySCENIC splits modules into activating and repressing links by the correlation.

class cytearc.regulons.GrnParameters(learningRate=0.01, maxStages=5000, maxFeatures=0.1, subsample=0.9, earlyStopWindow=25, earlyStopping='stage')#

Settings of the per-target gradient boosting regressor.

The defaults are those of arboreto’s GRNBoost2 (SGBM_KWARGS with an out-of-bag early-stopping window of 25 rounds), the regressor that pySCENIC runs.

learningRate#

Shrinkage of each boosting stage.

maxStages#

Upper bound on boosting stages; early stopping usually ends a fit much sooner.

maxFeatures#

Fraction of the transcription factors drawn at each split.

subsample#

Fraction of cells drawn for each stage. Must be below 1, because early stopping reads the out-of-bag improvement.

earlyStopWindow#

Stop once the mean out-of-bag improvement over this many most recent stages is negative.

earlyStopping#

How a stage’s out-of-bag improvement is measured. "stage" compares the loss of the stage’s out-of-bag cells before and after the stage, as GRNBoost2 was published and as arboreto computes it with scikit-learn before 1.3, which the pySCENIC 0.12.1 container uses. "consecutive" subtracts the out-of-bag losses of consecutive stages, which are measured on different cells, as arboreto computes it with scikit-learn 1.3 and later.

cytearc.regulons.modules_from_adjacencies(adjacencies, *, parameters=ModuleParameters(thresholds=(0.75, 0.9), topTargets=(50,), topRegulators=(5, 10, 50), minGenes=20, rhoThreshold=0.03, keepOnlyActivating=True))#

Build pySCENIC’s co-expression modules from a TF-target network.

Each factor gets one module per rule: its targets above each importance quantile of all links (weight>75.0%), its top targets (top50), and the targets for which it is among the top factors (top5perTarget). Links are split by the sign of their correlation into activating and repressing modules, the factor joins each of its modules with weight 1, and modules smaller than minGenes are dropped.

Ties in importance are broken by row order, so pass links in the order of the network that produced them.

Parameters:

  • adjacencies (DataFrame) – TF, target, importance, and correlation columns, such as GrnResult.adjacencies.

  • parameters (ModuleParameters) – Module rules; pySCENIC defaults when omitted.

Returns:

source (a unique module name), TF, direction (activating or repressing), context (the rule), target, and weight (the link importance, 1 for the factor).

Return type:

DataFrame

class cytearc.regulons.ModuleParameters(thresholds=(0.75, 0.9), topTargets=(50,), topRegulators=(5, 10, 50), minGenes=20, rhoThreshold=0.03, keepOnlyActivating=True)#

Rules that turn importance links into candidate regulon modules.

The defaults are pySCENIC 0.12.1’s (modules_from_adjacencies and the pyscenic ctx command line).

thresholds#

Importance quantiles over all links; a module holds a factor’s targets above each quantile.

topTargets#

A module holds each factor’s top targets by importance.

topRegulators#

A target joins the modules of its top factors by importance.

minGenes#

Smallest module size, counting the factor itself.

rhoThreshold#

Links whose Pearson correlation exceeds this are activating; those below its negative are repressing; the rest are ignored.

keepOnlyActivating#

Build only activating modules.

class cytearc.regulons.RankingDatabase(path, *, name=None)#

A cisTarget rankings database read column by column.

A database is a Feather version 2 (Arrow IPC) file whose rows are motifs or tracks and whose columns are ranked features, genes or regions, plus one index column naming the rows. Each value is the zero-based rank of a feature in that motif’s ranking of all total features. Only the columns of requested features are read and decompressed, so databases far larger than memory can be queried.

Parameters:

  • path (str | PathLike[str]) – Database file, such as hg38_10kbp_up_10kbp_down_full_tx_v10_clust.genes_vs_motifs.rankings.feather.

  • name (str | None) – Display name; the file name when omitted.

ranks(features)#

Read the ranks of the features that the database ranks.

Parameters:

features (Iterable[str]) – Feature names; names the database does not rank are skipped, as ctxcore does.

Return type:

tuple[ndarray, ndarray]

Returns:

The found feature names in database column order, and their (rows, found) int32 ranks.

property total: int#

Number of ranked features.

cytearc.regulons.read_motif_annotations(path, *, motif_similarity_fdr=0.001, orthologous_identity_threshold=0.0, categories=None)#

Read a cisTarget motif-to-TF annotation table (.tbl).

Rows whose motif similarity q-value exceeds motif_similarity_fdr or whose orthologous identity is below orthologous_identity_threshold are dropped, as pySCENIC and pycistarget do.

Parameters:

  • path (str | PathLike[str]) – Annotation table, such as motifs-v10nr_clust-nr.hgnc-m0.001-o0.0.tbl.

  • motif_similarity_fdr (float) – Largest motif similarity q-value kept.

  • orthologous_identity_threshold (float) – Smallest orthologous identity kept.

  • categories (Sequence[str] | None) – Keep only these annotation categories: "direct", "similarity", "orthology", and "similarity_and_orthology".

Return type:

DataFrame

Returns:

A DataFrame with motif, TF, motif_similarity_qvalue, orthologous_identity, description, and category columns.

cytearc.regulons.prune_modules(modules, databases, annotations, *, parameters=PruningParameters(rankThreshold=5000, aucThreshold=0.05, nesThreshold=3.0, maxMissingFraction=0.2), nthreads=1, progress=None)#

Keep the module targets that an enriched motif of the module’s factor recovers.

For every module and database, each motif’s ranking is scored by the AUC of the module’s recovery curve and standardized against all motifs of the database (NES). Enriched motifs (NES >= nesThreshold) that the annotation table assigns to the module’s factor contribute their leading edge: the module genes ranked at or before the rank where the motif’s recovery curve rises furthest above the mean plus two standard deviations of all motifs’ curves. This is pySCENIC’s prune2df with each leading edge taken from its own motif’s curve. pySCENIC 0.12.1 pairs the annotated motifs, after sorting them by annotation quality, with curves in database order, so most of its leading edges come from another enriched motif and its regulon targets differ from these.

Parameters:

  • modules (DataFrame) – Output of modules_from_adjacencies.

  • databases (Sequence[RankingDatabase]) – Gene-based ranking databases.

  • annotations (DataFrame) – Output of read_motif_annotations; every listed (factor, motif) pair counts, whatever its category.

  • parameters (PruningParameters) – cisTarget settings; pyscenic ctx defaults when omitted.

  • nthreads (int) – Modules pruned concurrently.

  • progress (Callable[[int, int], None] | None) – Optional callback(done, total) after each module and database.

Return type:

DataFrame

Returns:

One row per module, database, and enriched annotated motif, with the motif statistics, the annotation, and the leading-edge targets with their module target_weights.

class cytearc.regulons.PruningParameters(rankThreshold=5000, aucThreshold=0.05, nesThreshold=3.0, maxMissingFraction=0.2)#

cisTarget settings for pruning modules.

The defaults are those of pyscenic ctx 0.12.1.

rankThreshold#

Length of the recovery curves that define leading edges, in ranks.

aucThreshold#

Fraction of each motif’s ranking covered by the AUC.

nesThreshold#

Smallest NES of an enriched motif.

maxMissingFraction#

Skip a module once this fraction of its genes, the factor included, is missing from a database.

cytearc.regulons.regulons_from_motifs(motifs)#

Merge the leading edges of each factor and direction into one regulon.

A regulon TF(+) (activating) or TF(-) (repressing) holds the union of its factor’s leading-edge targets over all modules, databases, and enriched motifs, each with its largest weight, as pySCENIC’s df2regulons builds them. The factor is a member only when some leading edge holds it. No minimum size is applied.

Parameters:

motifs (DataFrame) – Output of prune_modules.

Return type:

DataFrame

Returns:

A network with source (the regulon), TF, direction, target, and weight columns, which ds.scores.aucell scores.

Motifs, genomes, and cistromes#

class cytearc.regulons.IndexedFasta(path, *, index_path=None)#

Read intervals of an uncompressed FASTA file without loading it.

The file is memory mapped and read through a samtools faidx index. The index is read from <path>.fai when that file exists, or from index_path; otherwise the FASTA file is scanned once to build it in memory. Nothing is written next to the FASTA file.

Coordinates are zero-based and half-open, as in BED files.

Parameters:

  • path (str | PathLike[str]) – Uncompressed FASTA file. Compressed files are not supported.

  • index_path (str | PathLike[str] | None) – Optional samtools faidx index of path.

close()#

Release the memory map and file handle.

Return type:

None

encode(name, start, end)#

Return fetch(name, start, end) as nucleotide codes (see encode_sequence).

Return type:

ndarray

fetch(name, start, end)#

Return the upper-case bases of name in [start, end).

Return type:

bytes

length(name)#

Number of bases in sequence name.

Return type:

int

property names: tuple[str, ...]#

Sequence names in index order.

cytearc.regulons.gc_content(genome, regions)#

Return the fraction of G and C among the A, C, G, and T bases of each region.

N and other ambiguity codes count in neither the numerator nor the denominator, as in chromVAR’s addGCBias. A region without any A, C, G, or T base has no defined content and gives NaN.

Parameters:

  • genome (IndexedFasta) – Genome the regions refer to.

  • regions (Iterable[str]) – Region ids chrom:start-end, such as ATAC peak ids.

Return type:

ndarray

class cytearc.regulons.Motif(motifId, name, counts)#

A DNA motif as a position frequency matrix.

motifId#

Identifier, such as a JASPAR matrix ID.

name#

Display name, usually the transcription factor.

counts#

(width, 4) non-negative counts or probabilities in A, C, G, T column order.

cytearc.regulons.read_jaspar_motifs(path)#

Read count matrices from a JASPAR-format file.

Each motif is a >ID NAME header followed by A, C, G, and T rows, with or without brackets, as in the JASPAR collection downloads.

Return type:

list[Motif]

cytearc.regulons.read_meme_motifs(path)#

Read motifs from a MEME-format file as counts.

Each letter-probability row is multiplied by its matrix’s nsites (20 when absent, the MEME format’s default), so a pseudocount weighs as much as it does for count matrices such as JASPAR’s.

Return type:

list[Motif]

cytearc.regulons.match_motifs(regions, genome, motifs, *, p_value=5e-05, background='subject', pseudocount=0.8, log_base=2.0, batch_size=4096)#

Find which regions contain a match of each motif on either strand.

Counts become log-odds scores against the background (log_odds_matrix), each strand’s threshold is the MOODS score threshold at p_value of that strand’s matrix, and a region matches when any window on either strand scores at least its strand’s threshold. Windows never span an N or other ambiguity code. These are the motifmatchr defaults that chromVAR uses, except that scores are proper log-odds against the "subject" background, and that the reverse strand has its own threshold, as in MOODS: motifmatchr reuses the forward one, which misses p_value for a background whose A and T, or C and G, frequencies differ.

Parameters:

  • regions (Sequence[str] | ndarray) – Region ids chrom:start-end (zero-based, half-open), such as ATAC peak ids.

  • genome (IndexedFasta) – Genome the regions refer to.

  • motifs (Sequence[Motif]) – Motifs to scan, for example from read_jaspar_motifs.

  • p_value (float) – Probability under the background of a window scoring at least the threshold.

  • background (Union[Literal['subject', 'even'], Sequence[float], ndarray]) – "subject" uses the pooled base frequencies of the regions, "even" uses 0.25 each, or pass four frequencies.

  • pseudocount (float) – Total pseudocount per motif position, split by the background.

  • log_base (float) – Base of the log-odds scores.

  • batch_size (int) – Regions scanned per parallel batch.

Return type:

DataFrame

Returns:

A network with source (motif ID), target (region id), and motif_name columns, one row per matching motif and region, sorted by motif then region order.

cytearc.regulons.motif_annotations(motifs)#

Annotate each motif to the factors that its name lists.

JASPAR and MEME names list one factor or a dimer such as FOS::JUN, sometimes with a variant suffix such as (var.2). Each listed factor is a direct annotation, upper-cased like human gene symbols; recase TF for other species.

Parameters:

motifs (Sequence[Motif]) – Motifs such as read_jaspar_motifs returns.

Returns:

motif (the motif ID), TF, motif_similarity_qvalue (0), orthologous_identity (1), description, and category ("direct").

Return type:

DataFrame

cytearc.regulons.cistromes_from_motifs(motif_network, annotations, *, categories=('direct',))#

Assign motif-matched regions to the factors their motifs are annotated to.

Each factor’s cistrome is the union of the regions matched by every motif the annotation table assigns to it in categories. SCENIC+ builds direct cistromes from direct annotations and extended cistromes from orthology annotations only; pass categories=("orthology",) for the latter.

Parameters:

  • motif_network (DataFrame) – source (motif ID) and target (region) columns, as match_motifs returns, or the leading-edge regions of enriched motifs.

  • annotations (DataFrame) – Output of read_motif_annotations.

  • categories (Sequence[str]) – Annotation categories that link a motif to a factor.

Return type:

DataFrame

Returns:

A network with source (factor), target (region), and motifs (sorted, comma-separated motif IDs that support the link).

cytearc.regulons.read_peak_file(path)#

Read peaks from a BED, narrowPeak, or SEACR BED file, optionally gzipped.

Coordinates are kept as zero-based half-open BED intervals. Track and browser lines and # comments are skipped.

Return type:

DataFrame

Returns:

A DataFrame with chrom, start, end, name, score, and summit columns; score is the fifth column when present and summit the narrowPeak summit offset (-1 when absent).

cytearc.regulons.binding_cistromes(peaks, regions, *, min_overlap_fraction=0.0)#

Map each factor’s binding peaks onto a set of regions.

A region joins a factor’s cistrome when one of the factor’s peaks overlaps it. With min_overlap_fraction above zero, the shared bases must also exceed that fraction of the peak or of the region, the rule pycistarget uses to map regions onto its databases (0.4).

Parameters:

  • peaks (Mapping[str, DataFrame | str | PathLike[str]]) – Factor name to binding peaks, as a read_peak_file table or a path such as a CUT&RUN narrowPeak file.

  • regions (Sequence[str] | ndarray) – Region names chrom:start-end, such as ATAC peak names.

  • min_overlap_fraction (float) – Required overlap fraction in [0, 1).

Return type:

DataFrame

Returns:

A network with source (factor), target (region), and n_peaks (binding peaks overlapping the region).

Enhancer-driven regulons (SCENIC+)#

cytearc.regulons.read_gene_annotation(path, *, feature='gene', gene_types=None)#

Read gene intervals and strands from a GTF, GFF3, or BED file.

GTF and GFF3 files (optionally gzipped) contribute their feature records, converted to zero-based half-open coordinates. BED files need at least six columns: chrom, start, end, gene name, score, and strand; a file of exactly seven columns gives the gene identifier in the seventh (in BED12, the seventh column is thickStart).

Parameters:

  • path (str | PathLike[str]) – Annotation file. The format follows the extension: .gtf, .gff3/.gff, or .bed, each optionally .gz.

  • feature (str | Iterable[str]) – GTF/GFF3 feature type, or types, to read. Ensembl GFF3 types non-coding genes ncRNA_gene.

  • gene_types (set[str] | frozenset[str] | None) – Keep only these gene types (GTF gene_type or gene_biotype, GFF3 biotype), such as {"protein_coding"}. BED files carry no type, so they reject this filter.

Return type:

DataFrame

Returns:

A DataFrame with chrom, start, end, strand, gene_id, gene_name, and gene_type columns.

Link regions to genes whose window they overlap.

With anchor="tss" each gene’s window spans upstream bases before and downstream bases after its TSS in the direction of transcription, so the window of a minus-strand gene extends to higher coordinates upstream. With anchor="gene_body" the window is the gene body extended by upstream bases before its 5’ end and downstream bases after its 3’ end, the SCENIC+ search space (150 kb each way by default there).

Parameters:

  • regions (Iterable[str]) – Region ids chrom:start-end (zero-based, half-open), such as ATAC peak ids.

  • genes (DataFrame) – Annotation from read_gene_annotation.

  • upstream (int) – Window extent in bases.

  • downstream (int) – Window extent in bases.

  • anchor (Literal['tss', 'gene_body']) – "tss" or "gene_body".

Returns:

region (the region id), gene (the gene name), gene_id, and distance, the signed distance from the anchor to the nearest base of the region, negative upstream, positive downstream, and zero when the region overlaps the TSS (or the gene body). Rows follow the order of the regions, then of the gene ids, and are the candidates that region_gene_links scores.

Return type:

DataFrame

Score candidate region-to-gene links over matched samples.

For each gene, the accessibility of its candidate regions is compared with its expression over the same samples, such as metacells that aggregate both modalities of a multiome experiment. rho is Spearman’s rank correlation of each region with the gene. With importance="gbm", a gradient boosting regressor with SCENIC+’s settings (500 stages, learning rate 0.01, a tenth of the regions per split, no subsampling) predicts the gene from all its candidate regions, and each region’s normalized impurity importance is reported, as SCENIC+’s region-to-gene step does.

Parameters:

  • accessibility (DataFrame) – Samples-by-regions accessibility named by region, such as the ATAC metacell profiles of ds.regulons.profiles.

  • expression (DataFrame) – Samples-by-genes expression named by gene, over the same samples in the same order.

  • candidates (DataFrame) – region and gene columns, such as link_regions_to_genes returns.

  • importance (Literal['gbm', 'none']) – "gbm" fits the regressor; "none" reports rho only.

  • seed (int) – Random state of each gene’s regressor.

  • nthreads (int) – Genes fitted concurrently.

  • progress (Callable[[int, int], None] | None) – Optional callback(done, total) after each gene.

Return type:

DataFrame

Returns:

region, gene, importance, and rho for every candidate whose region and gene are both measured. Constant vectors give NaN rho.

cytearc.regulons.build_eregulons(cistromes, region_to_gene, tf_to_gene, *, label='direct', parameters=EregulonParameters(rhoThreshold=0.05, quantiles=(0.85, 0.9, 0.95), topRegionsPerGene=(5, 10, 15), minTargetGenes=10, adjustedPThreshold=1.0, nesThreshold=0.0, nPermutations=1000, seed=666), nthreads=1)#

Build eRegulons from cistromes, region-to-gene links, and a co-expression network.

Each factor’s cistrome selects, from every binarization of the region-to-gene links, a module of links. A module is kept when the preranked GSEA of its genes against the factor’s co-expression ranking has a Benjamini-Hochberg adjusted p-value below adjustedPThreshold and an NES above nesThreshold, and when the leading edge holds at least minTargetGenes genes. An eRegulon is the union of its kept modules’ leading-edge links.

Parameters:

  • cistromes (DataFrame) – source (factor) and target (region) columns, from cistromes_from_motifs or binding_cistromes.

  • region_to_gene (DataFrame) – region, gene, importance, and rho columns, from region_gene_links.

  • tf_to_gene (DataFrame) – TF, target, importance, and correlation columns, such as GrnResult.adjacencies.

  • label (str) – Cistrome label in eRegulon names, such as direct, extended, or the experiment that measured binding.

  • parameters (EregulonParameters) – Construction settings; SCENIC+ pipeline settings when omitted.

  • nthreads (int) – Factors tested concurrently.

Returns:

source (the eRegulon, named {TF}_{label}_{TF-to-gene sign}/{region-to-gene sign}), TF, the two signs, the module’s context (its binarization) with its NES, p_value, and adjusted_p, region, target (the gene), the link’s importance_R2G and rho_R2G, and the target’s factor-to-gene importance_TF2G and rho_TF2G. A link kept by several modules, or a gene linked by several regions, repeats: filter by the module statistics, then score the unique source and target pairs.

Return type:

DataFrame

class cytearc.regulons.EregulonParameters(rhoThreshold=0.05, quantiles=(0.85, 0.9, 0.95), topRegionsPerGene=(5, 10, 15), minTargetGenes=10, adjustedPThreshold=1.0, nesThreshold=0.0, nPermutations=1000, seed=666)#

Settings of eRegulon construction.

The defaults are those that the SCENIC+ 1.0 pipeline passes to build_grn (without BASC binarization, which CyteArc does not run).

rhoThreshold#

Region-to-gene and factor-to-gene links with a correlation above this are positive, below its negative negative.

quantiles#

Per-gene importance quantiles that threshold region links.

topRegionsPerGene#

Each gene’s most important region links.

minTargetGenes#

Smallest leading edge of a kept module, and smallest co-expression ranking.

adjustedPThreshold#

Kept modules have a Benjamini-Hochberg adjusted GSEA p-value below this; SCENIC+ keeps every tested module (1).

nesThreshold#

Kept modules have a GSEA NES above this.

nPermutations#

GSEA gene-set permutations.

seed#

GSEA random seed, the same for every module.

Gene programs and specificity#

cytearc.regulons.gene_programs(profiles, *, parameters=GeneProgramParameters(nNeighbors=15, minCorrelation=0.2, resolution=1.0, minMembership=0.3, alpha=0.05, minSize=10, seed=0), block_size=2048)#

Partition genes into co-regulated programs.

Parameters:

  • profiles (DataFrame) – Samples-by-genes expression named by gene, over independent samples such as the metacell or pseudobulk profiles of ds.regulons.profiles. Smoothed or overlapping cells share their counts, which inflates every correlation and admits chance programs. Constant genes are skipped.

  • parameters (GeneProgramParameters) – Discovery settings.

  • block_size (int) – Genes whose correlations are computed at once.

Return type:

DataFrame

Returns:

One row per assigned gene with source (the program, P1 the largest), target (the gene), and membership, the gene’s Pearson correlation with the mean standardized profile of its program’s other genes; rows sort by program, then decreasing membership.

class cytearc.regulons.GeneProgramParameters(nNeighbors=15, minCorrelation=0.2, resolution=1.0, minMembership=0.3, alpha=0.05, minSize=10, seed=0)#

Settings of gene-program discovery.

nNeighbors#

Most correlated genes linked to each gene.

minCorrelation#

Links need at least this Pearson correlation.

resolution#

Leiden resolution of the gene graph.

minMembership#

Genes correlating less than this with the mean profile of their program’s other genes are left unassigned.

alpha#

A screen against chance groupings: a gene’s membership must also exceed the correlation that is significantly positive at this family-wise level over all genes (one-sided Fisher z, Bonferroni) for that many independent samples. It assumes independent samples and ignores that each program was chosen from the same correlations, so it is a filter, not a calibrated test of the programs.

minSize#

Programs with fewer genes are left unassigned.

seed#

Leiden random seed.

cytearc.regulons.program_scores(profiles, programs)#

Mean standardized profile of each program’s genes in each sample.

Parameters:

  • profiles (DataFrame) – Samples-by-genes values named by gene.

  • programs (DataFrame) – Output of gene_programs.

Return type:

DataFrame

Returns:

A samples-by-programs DataFrame indexed like profiles.

cytearc.regulons.program_regulators(programs, database, annotations, *, rank_threshold=5000, auc_threshold=0.05, nes_threshold=3.0, categories=None, profiles=None)#

Nominate the transcription factors whose motifs explain each program.

Each program’s genes are tested with cisTarget against a gene-based ranking database, as pySCENIC tests modules, and enriched motifs are assigned to factors by the annotation table. A large program enriches many weak motifs, so pass profiles to check that each factor’s own expression follows its program.

Parameters:

  • programs (DataFrame) – Output of gene_programs (any source/target table).

  • database (RankingDatabase) – Gene-based ranking database.

  • annotations (DataFrame) – Output of read_motif_annotations.

  • rank_threshold (int) – cisTarget settings.

  • auc_threshold (float) – cisTarget settings.

  • nes_threshold (float) – cisTarget settings.

  • categories (Sequence[str] | None) – Annotation categories to accept; all when omitted.

  • profiles (DataFrame | None) – Samples-by-genes expression named by gene, such as metacell profiles.

Returns:

program, TF, motif, NES, AUC, n_targets (leading-edge genes), and category, sorted by program and decreasing NES. With profiles, correlation is the Pearson correlation of the factor’s expression with the program’s program_scores across samples, NaN for a factor without a varying profile.

Return type:

DataFrame

cytearc.regulons.set_overlaps(queries, references, universe)#

Test every query set for overlap with every reference set.

Parameters:

  • queries (DataFrame) – source (set) and target (gene) columns, such as programs.

  • references (DataFrame) – source and target columns, such as regulons.

  • universe (Sequence[str] | ndarray) – Genes that could have been in any set.

Return type:

DataFrame

Returns:

query, reference, overlap, expected, odds_ratio, one-sided hypergeometric p_value, and Benjamini-Hochberg q_value across all tests.

cytearc.regulons.regulon_specificity(activity, labels)#

Regulon specificity scores (RSS) of each regulon for each group.

RSS = 1 - JSD(p, q) ** 0.5 where p is the regulon’s activity over cells normalized to sum to one, q the group’s indicator normalized the same way, and JSD the Jensen-Shannon divergence with natural logarithms, as pySCENIC’s regulon_specificity_scores computes it. The score is 1 when the regulon is active only, and uniformly, in the group.

Parameters:

  • activity (DataFrame) – Cells-by-regulons non-negative activity, such as AUCell AUCs.

  • labels (Sequence[object] | ndarray | Series) – Group of each cell, aligned by position with activity.

Return type:

DataFrame

Returns:

A groups-by-regulons DataFrame, groups in order of first appearance.

cytearc.regulons.connection_specificity(activity, *, margin=0.05)#

Connection specificity index (CSI) of every pair of regulons.

For regulons a and b with activity correlation r, the CSI is the fraction of all regulons whose correlation with a and with b are both below r - margin (Fuxman Bass et al. 2013). Regulons that co-vary with each other but not with the rest score near 1, which SCENIC analyses use to group regulons into modules.

Parameters:

  • activity (DataFrame) – Cells-by-regulons activity.

  • margin (float) – Correlation margin.

Return type:

DataFrame

Returns:

A symmetric regulons-by-regulons DataFrame.

cytearc.regulons.regulon_modules(csi, n_modules)#

Group regulons into co-activity modules by clustering their CSI profiles.

Rows of the CSI matrix are clustered with Ward linkage and the tree is cut into n_modules clusters, numbered by decreasing size.

Parameters:

  • csi (DataFrame) – Output of connection_specificity.

  • n_modules (int) – Number of modules.

Return type:

Series

Returns:

Module number of each regulon, indexed by regulon.

Contents