Data

Bundled TF lists and cached motif-ranking and gene-coordinate resources.

rustscenic.data

Bundled reference data and download helpers.

Everything in this module eliminates a step between pip install rustscenic and running the full pipeline. TF lists ship with the wheel (small text files). Motif-ranking databases are fetched on first use with local caching.

Public API:

rustscenic.data.tfs(species="hs") -> list[str]
    Bundled TF names. "hs" = human (1,839 TFs, HGNC), "mm" = mouse
    (1,721 TFs, MGI). Lists are from aertslab/pySCENIC resources/.

rustscenic.data.motif_rankings_path(species="hs", cache_dir=None) -> Path
    Fetch + cache an aertslab motif ranking database (feather). Returns
    the local file path without loading the ranking table into memory.

rustscenic.data.download_motif_rankings(species, genome, version, cache_dir=None)
    Fetch + cache an aertslab motif ranking database (feather). Returns
    a pandas DataFrame with motifs as index, genes as columns.

tfs 

tfs(species: Literal['hs', 'mm'] = 'hs') -> list[str]

Return the bundled transcription-factor list for species.

Parameters:

Name Type Description Default
species Literal['hs', 'mm']

"hs" for human (HGNC, 1,839 TFs, hg38) or "mm" for mouse (MGI, 1,721 TFs, mm10). Sourced from aertslab/pySCENIC resources.

 'hs'

Returns:

Type Description
Plain Python list of TF gene symbols, suitable to pass directly as
the ``tf_names`` argument to ``rustscenic.grn.infer``.

motif_rankings_cache_path 

motif_rankings_cache_path(
    species: Literal["hs", "mm", "human", "mouse", "hg38", "mm10"] = "hs",
    genome: str | None = None,
    motif_collection: str = "mc_v10_clust",
    refseq_release: str = "refseq_r80",
    region: str = "gene_based",
    window: str = "10kbp_up_10kbp_down",
    score_type: str = "rankings",
    cache_dir: Path | None = None,
    filename: str | None = None,
    url: str | None = None,
) -> Path

Return the expected local motif-ranking cache path without IO.

Parameters:

Name Type Description Default
species Literal['hs', 'mm', 'human', 'mouse', 'hg38', 'mm10']

Human (hs, human, hg38) or mouse (mm, mouse, mm10) species alias used to select the default assembly.

 'hs'
genome str | None

Assembly token used in a generated filename. None chooses hg38 for human or mm10 for mouse.

 None
motif_collection str

Motif-collection token. The leading mc_ is removed when constructing the filename.

 'mc_v10_clust'
refseq_release str

Accepted for interface compatibility; unused in the local cache key.

 'refseq_r80'
region str

Database mode: gene_based or region_based. Selects the generated filename layout.

 'gene_based'
window str

Regulatory-window token in generated gene-based filenames. Unused for region-based filenames.

 '10kbp_up_10kbp_down'
score_type str

Filename suffix token, normally rankings.

 'rankings'
cache_dir Path | None

Cache directory; defaults to ~/.cache/rustscenic/cistarget. This path-only helper does not create it.

 None
filename str | None

Explicit local filename. None constructs one from the other filename tokens; it is not derived from url.

 None
url str | None

Accepted for interface compatibility; ignored in the local path.

 None

Returns:

Type Description
Path

Expected cache file, which need not exist. No download, directory creation or Feather loading is performed.

motif_rankings_path 

motif_rankings_path(
    species: Literal["hs", "mm", "human", "mouse", "hg38", "mm10"] = "hs",
    genome: str | None = None,
    motif_collection: str = "mc_v10_clust",
    refseq_release: str = "refseq_r80",
    region: str = "gene_based",
    window: str = "10kbp_up_10kbp_down",
    score_type: str = "rankings",
    cache_dir: Path | None = None,
    filename: str | None = None,
    url: str | None = None,
    verbose: bool = True,
) -> Path

Fetch/cache motif rankings and return the local path without loading it.

Parameters:

Name Type Description Default
species Literal['hs', 'mm', 'human', 'mouse', 'hg38', 'mm10']

Human (hs, human, hg38) or mouse (mm, mouse, mm10) alias selecting the remote species directory.

 'hs'
genome str | None

Assembly token in the database filename and URL. None chooses hg38 for human or mm10 for mouse.

 None
motif_collection str

Motif-collection directory token; a leading mc_ is removed when constructing the filename.

 'mc_v10_clust'
refseq_release str

Annotation directory in generated gene-based URLs. Unused by region-based URLs and not part of the local cache key.

 'refseq_r80'
region str

gene_based for genes-versus-motifs or region_based for screen regions-versus-motifs filename and URL layouts. Names are constructed without checking that a remote database exists.

 'gene_based'
window str

Regulatory-window token in generated gene-based filenames. Unused for region-based filenames.

 '10kbp_up_10kbp_down'
score_type str

Filename suffix token, normally rankings.

 'rankings'
cache_dir Path | None

Cache directory; defaults to ~/.cache/rustscenic/cistarget. Created when needed.

 None
filename str | None

Override the local filename and the final component of a generated URL. None builds a name from the other filename tokens.

 None
url str | None

Full download-URL override. It does not determine the local filename. An existing local file is reused without fetching this URL; use a distinct filename or cache_dir for a different resource.

 None
verbose bool

Print a download message when an uncached file is fetched.

 True

Returns:

Type Description
Path

Cached or newly downloaded database file. The Feather table is not loaded, and existing files are reused without checksum verification.

Raises:

Type Description
RuntimeError

If downloading fails. A partially written local file is removed.

download_motif_rankings 

download_motif_rankings(
    species: Literal["hs", "mm", "human", "mouse", "hg38", "mm10"] = "hs",
    genome: str | None = None,
    motif_collection: str = "mc_v10_clust",
    refseq_release: str = "refseq_r80",
    region: str = "gene_based",
    window: str = "10kbp_up_10kbp_down",
    score_type: str = "rankings",
    cache_dir: Path | None = None,
    filename: str | None = None,
    url: str | None = None,
    verbose: bool = True,
)

Download (and cache) an aertslab motif-ranking database.

On first use this downloads a large feather file (hundreds of MB to tens of GB depending on the DB). Subsequent calls read from the local cache at cache_dir (default: ~/.cache/rustscenic/cistarget/).

Resolves to URLs of the form::

https://resources.aertslab.org/cistarget/databases/
    <species_dir>/<genome>/<refseq_release>/<motif_collection>/<region>/
    <genome>_<window>_full_tx_<motif_collection_short>.
    <region>s_vs_motifs.<score_type>.feather

e.g. homo_sapiens/hg38/refseq_r80/mc_v10_clust/gene_based/ hg38_10kbp_up_10kbp_down_full_tx_v10_clust.genes_vs_motifs.rankings.feather.

Parameters:

Name Type Description Default
species Literal['hs', 'mm', 'human', 'mouse', 'hg38', 'mm10']

"hs" / "human" / "hg38" for human, or "mm" / "mouse" / "mm10" for mouse.

 'hs'
genome str | None

Defaults to "hg38" for human, "mm10" for mouse.

 None
motif_collection str

aertslab motif collection slug. Default "mc_v10_clust".

 'mc_v10_clust'
refseq_release str

RefSeq release directory. Default "refseq_r80".

 'refseq_r80'
region str

"gene_based" (recommended for rustscenic.cistarget) or "region_based".

 'gene_based'
window str

Region window slug. "10kbp_up_10kbp_down" (default, broad 20kb total) or "500bp_up_100bp_down" (promoter-only).

 '10kbp_up_10kbp_down'
score_type str

"rankings" for cistarget; "scores" for alternate analyses.

 'rankings'
cache_dir Path | None

Override the default cache directory.

 None
filename str | None

Escape hatch - pass an aertslab feather filename directly to bypass the auto-built name. Combined with the auto-built dir.

 None
url str | None

Full download-URL override. The local cache name still comes from filename or the generated filename tokens, not from this URL.

 None
verbose bool

Print a download message when an uncached file is fetched.

 True

Returns:

Type Description
DataFrame

Motif × gene ranking matrix suitable for rustscenic.cistarget.enrich.
Notes

aertslab hosts rankings at resources.aertslab.org/cistarget/databases/. Browse https://resources.aertslab.org/cistarget/databases/ for the authoritative directory.

download_gene_coords 

download_gene_coords(
    species: Literal["hs", "mm", "human", "mouse", "hg38", "mm10"] = "hs",
    cache_dir: Path | None = None,
    url: str | None = None,
    verbose: bool = True,
)

Download and cache GENCODE gene TSS coordinates as (gene, chrom, tss).

The end-to-end pipeline's enhancer→gene linking step needs real gene-TSS coordinates for biological interpretation. This helper fetches a GENCODE basic-annotation GTF on first use, parses it to a TSS-per-gene table (TSS = start on + strand, end on - strand), and caches the result as parquet for fast reuse.

Returns a DataFrame with columns ["gene", "chrom", "tss"] suitable for rustscenic.enhancer.link_peaks_to_genes and rustscenic.pipeline.run(gene_coords=...).

Parameters:

Name Type Description Default
species Literal['hs', 'mm', 'human', 'mouse', 'hg38', 'mm10']

"hs" / "human" / "hg38" (GENCODE release 46) or "mm" / "mouse" / "mm10" (GENCODE release M35).

 'hs'
cache_dir Path | None

Override the default cache directory (~/.cache/rustscenic/gene_coords/).

 None
url str | None

Escape hatch for an alternate GENCODE GTF URL.

 None
verbose bool

Print a message when the annotation GTF must be downloaded.

 True

Returns:

Type Description
DataFrame

Columns gene, chrom, tss. One row per gene; gene symbols come from the GTF's gene_name attribute.