API reference

Metadata registry

bolerodata.data.Metadata

DATASET_METADATA property

Misc dataset metadata.

MODEL_ZOO property

Model zoo.

QTL_COLLECTION property

QTL collection.

JASPAR_MOTIF_CLUSTER_INFO property

JASPAR motif cluster info.

JASPAR_MOTIF_CLUSTER property

JASPAR motif cluster.

DA_COLLECTION property

Differential analysis collection.

get_sample_snap_files(dataset_name)

Get the sample snap files table.

get_misc_data_path(key, path_attr)

Get the misc data path from the dictionary.

get_metacell_adata_path(key)

Get the metacell adata path from the dictionary.

get_metacell_parquet_path(key)

Get the metacell parquet path from the dictionary.

get_metacell_pseudobulk_records_path(key)

Get the metacell pseudobulk records path from the dictionary.

get_metacell_cond_pseudobulk_records_path(key)

Get the metacell condition pseudobulk records path from the dictionary.

get_reference_bigwig_path(key)

Get the reference bigwig path from the dictionary.

get_metacell_metadata_pseudobulk_records_path(key)

Get the metacell metadata pseudobulk records path from the dictionary.

get_pseudobulk_gene_and_hvg_path(key)

Get the pseudobulk gene and hvg path from the dictionary.

get_peak_motif_scan_path(dataset_name)

Get the peak motif scan path.

get_chromvar_score_path(motif='AP1', *, allow_download=True)

Get the chromVAR score file for a motif, the input of its score model.

The file is a joblib dict of DataFrames, one per dataset (or dataset+subset), holding the scaled chromVAR deviation of each pseudobulk. Only the AP-1 file is published.

Parameters:

Name	Type	Description	Default
motif	str	Motif cluster name, as in the model zoo Score Input column.	'AP1'
allow_download	bool	If False, never hit the network; raise if the file is not cached.	True

Returns:

Type	Description
Path	Local path to {motif}.chromvar_score.scale.joblib.gz, downloaded from HuggingFace if it is not on the local filesystem.

Raises:

Type	Description
ValueError	If motif is not in :data:PUBLISHED_SCORE_MOTIFS.
FileNotAvailableError	If the file is not cached and allow_download is False.

Datasets

bolerodata.dataset.Dataset

Genome property

Return a bolero.Genome object for the dataset genome.

cell_metadata property

Standard minimum cell metadata table.

Schema: - Index: cell barcode in "{sample}+{cell barcode}" format. For 10X experiments, barcode is in "GEX_BARCODE-1" format - Columns: 1. sample # link to sample metadata 2. cluster # link to cluster metadata, deepest level of clustering 3. n_fragments # From ATAC 4. tsse # From ATAC 5. n_umi # From RNA, if any 6. n_genes # From RNA, if any

n_cells property

Number of cells in the dataset.

n_samples property

Number of samples in the dataset.

sample_metadata property

Standard sample metadata table.

Schema: - Index: sample_id - This id match the sample column in all cell_metadata. - This correspond to technical sample (e.g., one 10X experiments) the same barcode within sample should come from a single cell. - For biological sample, record in donor column - Columns: 1. age # time, standard age group 2. age_int # Estimated postconceptional age in days, standard age group int 3. tissue # space, experiment tissue source information 4. DissectionRegion # space, anatomical descriptive vocabulary of the tissue 5. sex # exp design 6. donor # exp design - Additional Columns: - age_details - tissue_details - **exp_details

cluster_metadata property

Standard cluster metadata table.

Schema: - Index: cluster_id - This id match the cluster column in all cell_metadata. - This correspond to the deepest level of clustering - Columns: - Columns: 1. subclass: Most meaningful detail cell annotation level 2. class: Most meaningful major cell annotation level - Additional Columns: - **Other cluster levels

snap_file_table property

Standard snap file table.

Columns: - sample: Sample ID - EXCEPT Li2023Science, which is using cell type to group snap - dataset: Dataset Name - snap_path: Path to the snap file - Contains nan, some snap files might be missing.

original_cell_metadata property

Cell metadata table organized from original study, contain misc information.

cell_embedding property

Cell embedding table organized from original study, contain misc information.

peak_motif_scan_path property

Get the path to the peak motif scan table.

peak_motif_scan_table property

Peak motif scan binary table.

chromvar_adata property

Chromvar adata object.

cross_dataset_chromvar_adata property

Cross dataset chromvar adata object.

make_cell_metadata(sample_meta=True, cluster_meta=True)

Make cell metadata table with sample and cluster metadata.

get_meta_cell_adata_path(kind='metadata', subset_name=None)

Get the path to the meta cell adata file.

get_meta_cell_adata(kind='metadata', subset_name=None, backed=None)

Get the meta cell adata object.

Parameters:

Name	Type	Description	Default
kind	str	The kind of meta cell adata file to get: - "metadata": metadata and embedding only - "gene": gene expression data - "peak": peak count data - "cell": cell level metadata and embedding only	'metadata'
subset_name	str	The name of the subset to get. If None, return the full dataset.	None
backed		If not None, load the adata in backed mode. This is useful for large datasets.	None

Returns:

Type	Description
AnnData	The meta cell adata object.

get_meta_cell_parquet_path(kind, subset_name=None)

Get the path to the meta cell parquet dataset dir.

get_meta_cell_pseudobulk_records_path(target_coverage, subset_name=None, pseudobulk_type='condition')

Get the path to the meta cell pseudobulk records file.

Parameters:

Name	Type	Description	Default
target_coverage		The target_coverage of meta cell pseudobulk records file to get: - 5000000: pseudobulk records with 5000000 target coverage - 25000000: pseudobulk records with 25000000 target coverage	required
subset_name	str	The name of the subset to get. If None, return the full dataset.	None
pseudobulk_type		The type of pseudobulk to get. Must be one of ['embedding', 'condition', 'metadata']. Embedding: pseudobulk grouped based on embedding, containing embedding information only. Condition: pseudobulk grouped based on embedding, containing embedding and condition information. Metadata: pseudobulk grouped based on metadata, containing embedding and condition information.	'condition'

Returns:

Type	Description
str	The path to the meta cell pseudobulk records file.

get_reference_bigwig_path(subset_name=None)

Get the path to the reference bigwig file.

get_meta_cell_cond_pseudobulk_records_path(target_coverage, subset_name=None)

Get the path to the meta cell condition pseudobulk records file.

get_meta_cell_metadata_pseudobulk_records_path(target_coverage, subset_name=None)

Get the path to the meta cell metadata pseudobulk records file.

get_pseudobulk_gene_data_path(subset_name=None)

Get the path to the pseudobulk gene data file.

get_pseudobulk_hvg_list_path(subset_name=None)

Get the path to the pseudobulk hvg list file.

get_dataset_reference_gene_log1pcpm_path(subset_name=None)

Get the path to the dataset reference gene log1pcpm file.

bolerodata.dataset.Datasets

get_datasets(species=None, genome=None)

Get the datasets with the given species and genome.

get_datasets_and_subset_names(species=None, genome=None)

Get the datasets and subset names with the given species and genome.

Models

bolerodata.model.BoleroModel

ckpt_path property

Local checkpoint path (downloaded from HuggingFace on first access).

dataset property writable

Get the dataset for the model.

pred_batch_size property

Batch size for prediction tasks.

attr_batch_size property

Batch size for attribution tasks.

get_default_p0_meta_cells(subset_name=None, random_state=0)

Get up to 1000 meta cells for creating fixed p0 meta cells.

create_predictor(subset_name=None, pseudobulk_records_path=None, pseudobulk_ids=None, target_cov=5000000, pseudobulk_type='condition', sample_n_pseudobulks=100, peak_bed_path=None, nosignal=False, use_ref_bw=True, embedding_only_mode=False, **kwargs)

Create a predictor for the model.

Parameters:

Name	Type	Description	Default
subset_name	str	The name of the subset to create the predictor for.	None
pseudobulk_records_path	str	The path to the pseudobulk records file, if None, will use the dataset's default pseudobulk records file. If a dict, will use the pseudobulk records from the dict.	None
pseudobulk_ids	list[str]	The list of pseudobulk ids to use. If None, will use all pseudobulk ids in the pseudobulk records file.	None
peak_bed_path	str	The path to the peak bed file. If None, will use the dataset's default peak bed file.	None
pseudobulk_type	str	The type of dataset's default pseudobulk file to use. Must be one of ['condition', 'metadata'].	'condition'
sample_n_pseudobulks	int	The number of pseudobulks to sample.	100
target_cov	int	The target coverage to use for the default pseudobulk records file.	5000000
nosignal	bool	Whether to use the DNA only (no signal) model.	False
use_ref_bw	bool	Whether to use the reference bigwig file to represent the reference signal.	True
embedding_only_mode	bool	Whether to use the embedding only mode to create the predictor. If True, will skip ytrue data preparation and skip all the metrics calculation.	False

Returns:

Type	Description
GenericPredictor	The predictor for the model.

bolerodata.model.Models

__init__()

Models is a singleton class that contains all the models.

QTL collections

bolerodata.qtl

QTLCollection

qtl_path_table property

QTL path table.

tissue_list property

Tissue list.

get_qtl_path(key)

Get the QTL path (localized: downloaded from HuggingFace if off-lab).

get_qtl_table(*args, **kwargs)

Get the QTL data.

GTExQTLCollection

Bases: QTLCollection

get_qtl_path(tissue, gene_sel='protein_coding')

Get the QTL path.

get_qtl_training_path(tissue)

Get the QTL path for training QTL models.

GTExEQTLCatalogCollection

Bases: QTLCollection

get_qtl_path(tissue)

Get the QTL path for GTEx eQTL catalog data.

Parameters:

Name	Type	Description	Default
tissue	str	Tissue identifier (e.g., 'uterus', 'muscle', 'prostate').	required

Returns:

Type	Description
str	Path to the QTL data file. All GTEx eQTL catalog data uses the 'all_gene' gene selection.

Zeng2024QTLCollection

Bases: QTLCollection

get_qtl_path(cell_type, all_pair=False)

Get the QTL path.

Onek1kQTLCollection

Bases: QTLCollection

get_qtl_path(cell_type)

Get the QTL path for OneK1K eQTL catalog data.

Parameters:

Name	Type	Description	Default
cell_type	str	Cell type identifier (e.g., 'CD16+_monocyte', 'NK_cell', 'B_cell').	required

Returns:

Type	Description
str	Path to the QTL data file.

Reference annotations

Return a local path to a genome's reference annotation.

On the lab filesystem the lab copy is returned. Elsewhere the file is downloaded from the bolero-data HuggingFace repo on first use and served from the local cache afterwards.

Parameters:

Name	Type	Description	Default
genome	str	Genome name, one of :data:GTF_FILES (e.g. "hg38", "mm10").	required
db	bool	If True (default), return the prebuilt gffutils database, which bolero.pp.gtf.load_gtf opens directly. If False, return the raw .gtf.	True
allow_download	bool	If False, never hit the network; raise if the file is not local.	True

Returns:

Type	Description
Path	Path to the local file.

Raises:

Type	Description
KeyError	If genome has no registered annotation.
FileNotAvailableError	If the file is not local and allow_download is False.

Score-model inputs

Get the chromVAR score file for a motif, the input of its score model.

The file is a joblib dict of DataFrames, one per dataset (or dataset+subset), holding the scaled chromVAR deviation of each pseudobulk. Only the AP-1 file is published.

Parameters:

Name	Type	Description	Default
motif	str	Motif cluster name, as in the model zoo Score Input column.	'AP1'
allow_download	bool	If False, never hit the network; raise if the file is not cached.	True

Returns:

Type	Description
Path	Local path to {motif}.chromvar_score.scale.joblib.gz, downloaded from HuggingFace if it is not on the local filesystem.

Raises:

Type	Description
ValueError	If motif is not in :data:PUBLISHED_SCORE_MOTIFS.
FileNotAvailableError	If the file is not cached and allow_download is False.

Flashzoi backbone

Return a local path to Flashzoi weights that bolero's Borzoi loads.

On first use the public johahi/flashzoi-replicate-{fold} weights are downloaded from HuggingFace (pinned commit), their keys renamed to bolero's Borzoi module names, the output heads dropped, and the result saved to the bolerodata cache. Later calls return the cached file. On the lab filesystem the lab's own renamed checkpoint is returned instead.

Building the cached file needs torch and huggingface_hub, which the bolero environment provides.

Parameters:

Name	Type	Description	Default
fold	int	Flashzoi replicate, one of :data:FLASHZOI_FOLDS.	0
allow_download	bool	If False, never hit the network; raise if the file is not cached.	True

Returns:

Type	Description
Path	A torch.save state dict for Borzoi.load_state_dict(strict=True).

Raises:

Type	Description
ValueError	If fold is not a published fold.
FileNotAvailableError	If the file is not cached and allow_download is False, or torch or huggingface_hub is not installed.

Data resolution & caching

Resolve a bolerodata artifact to a concrete local path.

Parameters:

Name	Type	Description	Default
path	str or PathLike	An absolute lab path (as stored in the registry tables / joblib dicts) or a repo-relative logical path.	required
allow_download	bool	If False, never hit the network; raise if the artifact is not already present locally (useful for strict offline runs).	True
desc	str	Human-readable label used in error messages.	None

Returns:

Type	Description
Path	A path that exists on the local filesystem.

Raises:

Type	Description
FileNotAvailableError	If the artifact is unknown, marked not-shared, or (with allow_download=False) simply not cached.

Pre-download shared artifacts matching the given filters into the cache.

Parameters:

Name	Type	Description	Default
tier	str	Only fetch entries whose tier equals this (e.g. "core", "eval").	None
category	str	Only fetch entries whose category equals this.	None
datasets	iterable of str	Keep an entry only if one of these substrings appears in its logical path.	None
allow_download	bool	Passed through to the downloader; if False this is a no-op sanity pass.	True

Returns:

Type	Description
dict	{"downloaded": int, "errors": [(logical, message), ...]}.

Download all shared artifacts (optionally filtered). Alias of :func:prefetch.

Return the local cache directory for downloaded bolerodata artifacts.

Resolution order: $BOLERODATA_HOME → $BOLERO_HOME → :func:platformdirs.user_cache_dir → ~/.cache/bolero.

Load the bundled HuggingFace manifest.

Returns:

Type	Description
dict	Mapping logical_path -> {kind, share, category, tier, size, sha256, repo_id, repo_type, repo_path, pack}. Empty dict if the manifest has not been built/shipped yet (authors do not need it).

Bases: RuntimeError

Raised when an artifact is not available locally and cannot be fetched.

Differential analysis (optional diff extra)

bolerodata.diff_analysis.DiffRecords

A single pair-wise differential analysis record.

gene_diff_table property

Gene differential analysis table.

peak_diff_table property

Peak differential analysis table.

group1_bw_handle property

BigWig file handle for group 1.

group2_bw_handle property

BigWig file handle for group 2.

dataset_peak_scan property

Get dataset peak scan values for Group1 and Group2.

__init__(gene_rec=None, peak_rec=None, lfc_cutoff=0.2, igv_base_dir='igv')

Initialize the DiffRecords object with gene and/or peak records.

get_bw_values(region)

Get Group1 and Group2 bigwig values for a given region.

get_bw_stats(region, stat_type='mean')

Get Group1 and Group2 bigwig stats for a given region.

scan_peaks(regions)

Scan peaks on Group1 and Group2 bigwig files.

dump_sig_peak_bed(output_dir='./')

Dump significant peak bed files for IGV browser.

setup_igv_tracks()

Create IGV tracks table for IGV browser.

igv_browser(locus=None)

Open IGV browser for the differential analysis record.