Genome & Sequence

Assembly handles and DNA utilities. Genome resolves a UCSC assembly to its FASTA / chrom.sizes, serves DNA as sequence or one-hot arrays, and exposes global coordinates and the blacklist. Sequence wraps a single DNA string with one-hot helpers, and understand_regions normalizes region specifications used throughout the package.

Genome

Genome assembly handle: sequence, coordinates, and one-hot encoding.

Resolves a UCSC assembly name (e.g. "hg38", "mm10") to its local FASTA / chrom.sizes (downloading on first use), exposes chromosome sizes, global (concatenated) coordinates and the ENCODE blacklist, and serves DNA as sequence or one-hot arrays for model input. It also lazily builds a whole-genome one-hot store in zarr (:meth:generate_genome_one_hot) for fast random-access slicing, and provides gene/GTF and protein-sequence lookups for the structural analyses.

Parameters:

Name	Type	Description	Default
genome	str or Genome	UCSC assembly name (used to locate/download the FASTA), or an existing :class:Genome (returned as-is).	required
save_dir	str or Path	Root directory for downloaded/derived data. Defaults to the package data dir.	None
user_gtf_path	str	Path to a user-supplied GTF, used instead of the default annotation for gene lookups.	None

gtf_db property

gtf_db

Return the ref id of gtf db object in ray's object store.

remote_genome_one_hot property

remote_genome_one_hot

Return the ref id of remote one-hot object in ray's object store.

genome_one_hot property

genome_one_hot

Returns the one-hot encoded representation of the genome.

If the one-hot encoded object is not already created, it generates it and saves it to a zarr file. The generated object is then stored in the _one_hot_obj attribute for future use.

Returns:

Type	Description
GenomeOneHotZarr: The one-hot encoded representation of the genome.

uniprot_records property

uniprot_records

Get the swiss-port records for this species

uniprot_idmap property

uniprot_idmap

Get the gene to protein id map for this species

download_genome_fasta

download_genome_fasta()

Download a genome fasta file from UCSC

make_windows

make_windows(window_size: int, step: int, as_df: bool = False, force_length: bool = True) -> pr.PyRanges | pd.DataFrame

Create windows across the genome, mimicking bedtools makewindows

Parameters:

Name	Type	Description	Default
window_size	int	Size of the window	required
step	int	Step size between window start positions	required
as_df	bool	If True, will return a DataFrame, else will return a PyRanges object	False
force_length	bool	If True, will force the windows to be the same length and drop the last window if it is shorter	True

Returns:

Name	Type	Description
windows	PyRanges or DataFrame	Windows across the genome

get_region_fasta

get_region_fasta(bed_path, output_path=None, compress=True)

Extract fasta sequences from a bed file.

Parameters:

Name	Type	Description	Default
bed_path	str or Path	Path to a bed file, bed file must be sorted and have chrom, start, end and name columns.	required
output_path	str or Path	Path to output fasta file. If None, will be the same as bed_path with a .fa extension	None
compress	bool	If True, will compress the fasta file with bgzip	True

Returns:

Name	Type	Description
output_path	Path	Path to output fasta file

prepare_window_bed

prepare_window_bed(bed_path, output_path=None, main_chroms=True, remove_blacklist=True, window=True, window_size=1000, window_step=50, downsample=None)

Prepare a bed file for generating one-hot matrix.

Parameters:

Name	Type	Description	Default
bed_path	str or Path	Path to a bed file.	required
output_path	str or Path	Path to output bed file. If None, will be the same as bed_path with a .prepared.bed extension	None
main_chroms	bool	If True, will only keep main chromosomes	True
remove_blacklist	bool	If True, will remove blacklist regions	True
window	bool	If True, will use genome windows with window_size and window_step to cover the entire bed file	True
window_size	int	Window size	1000
window_step	int	Window step	50
downsample	int	Number of regions to downsample to	None

Returns:

Name	Type	Description
output_path	Path	Path to output bed file

get_region_sequences

get_region_sequences(bed_path, save_fasta=False)

Extract fasta sequences from a bed file.

Parameters:

Name	Type	Description	Default
bed_path	str or Path	Path to a bed file	required
save_fasta	bool	If True, will save the fasta file to the same directory as the bed file	False

Returns:

Name	Type	Description
sequences	list of bolero.pp.seq.Sequence	List of Sequence objects

delete_genome_data

delete_genome_data()

Delete genome data files

standard_region_length

standard_region_length(regions, length, remove_blacklist=False, boarder_strategy='shift', as_df=True, keep_original=False, signal_length='given')

Adjusts the length of regions to a standard length.

Parameters:

Name	Type	Description	Default
regions	PyRanges, DataFrame, str, Path, list, or Index	The regions to be adjusted. It can be a PyRanges object, a DataFrame, a file path, a list, or an Index.	required
length	int	The desired length of the regions.	required
remove_blacklist	bool	Whether to remove regions that overlap with the blacklist. Default is False.	False
boarder_strategy	str	For regions that overlap with the chromosome boarder, the strategy to adjust the boarder. If 'shift', the region will be shifted to the left or right to fit into the chromosome. If 'drop', the region overlapping with the boarder will be dropped. The number of output regions may be less than the input regions. Default is 'shift'.	'shift'
as_df	bool	Whether to return the adjusted regions as a DataFrame. Default is True.	True
keep_original	bool	Whether to keep the original signal regions as Original_Name in the output. Default is False.	False
signal_length	str or int	If 'given', the original signal length is kept. If int, the signal length is set to the specified length. Default is 'given'.	'given'

Returns:

Name	Type	Description
regions_bed	PyRanges	The adjusted regions with the specified length.

Raises:

Type	Description
ValueError	If the regions parameter is not a PyRanges, DataFrame, str, Path, list, or Index.

Notes

• The method adjusts the length of the regions to the specified length.
• It ensures that all regions have the same size by centering them around their midpoint.
• It also ensures that the start and end positions of each region are within the range of the chromosome.
• The method updates the 'Name' column of the regions to reflect the adjusted positions.

generate_genome_one_hot

generate_genome_one_hot(zarr_path: str | Path | None = None)

Generate genome one-hot encoding.

Parameters:

Name	Type	Description	Default
zarr_path	str or Path	Path to save the Zarr file. If not provided, a default path will be used.	None

Returns:

Type	Description
None

dump_region_bigwig_zarr

dump_region_bigwig_zarr(bw_table, bed_path, partition_dir, region_id=None, partition_size=50000000, cpu=None)

Dump bigwig values from a bed file into zarr files.

split_genome_fasta

split_genome_fasta(fasta_chunk_dir, chunk_size=10000000, slop_size=10000)

Split genome fasta into chunks.

Parameters:

Name	Type	Description	Default
fasta_chunk_dir	str or Path	Path to directory to save the fasta chunks	required
chunk_size	int	Size of each chunk in base pairs	10000000
slop_size	int	Size of slop for each chunk	10000

scan_motif_with_cbust

scan_motif_with_cbust(output_dir, motif_table, cpu=None, min_cluster_score=0, r=10000, b=0, save_motif_scan=False)

Scan motifs with cbust.

Parameters:

Name	Type	Description	Default
output_dir	str or Path	Path to directory to save the output bigwig files	required
motif_table	str or Path	Path to a table of motif names and paths	required
cpu	int	Number of cpus to use, if None, will use all available cpus	None
min_cluster_score	int	Minimum cluster score	0
r	int	cbust -r parameter. Range in bp for counting local nucleotide abundances.	10000
b	int	cbust -b parameter. Background padding in bp.	0
save_motif_scan	bool	If True, will save the motif scan table file, which has exact motif locations and scores.	False

get_region_one_hot

get_region_one_hot(*args)

Returns the one-hot encoding of a genomic region.

Parameters:

Name	Type	Description	Default
*args			()

Returns:

Type	Description
numpy.ndarray: The one-hot encoding of the specified genomic region.

Raises:

Type	Description
ValueError: If the genome one-hot encoding is not created. Please run `genome.get_genome_one_hot` first.

get_region_sequence

get_region_sequence(*args)

Returns the sequence of a genomic region.

Parameters:

Name	Type	Description	Default
*args			()

Returns:

Name	Type	Description
str	The sequence of the specified genomic region.

fetch_seq

fetch_seq(*args, **kwargs)

Alias of get_region_sequence

get_regions_one_hot

get_regions_one_hot(regions: DataFrame | list[str]) -> torch.Tensor

Get the one-hot encoding for the given regions.

Parameters:

Name	Type	Description	Default
regions	pd.DataFrame or list of str	The regions for which to retrieve the one-hot encoding.	required

Returns:

Type	Description
Tensor	The one-hot encoding for the given regions.

Raises:

Type	Description
ValueError	If the genome one-hot encoding is not created. Please run genome.get_genome_one_hot first.

get_global_coords

get_global_coords(region_bed, chrom_offsets=None)

Convert the coordinates in the given region bed file to global coordinates.

Parameters:

Name	Type	Description	Default
region_bed	str	The path to the region bed file.	required
chrom_offsets	DataFrame	A DataFrame containing the global start offsets for each chromosome. Default is None.	None

Returns:

Type	Description
ndarray	An array of global coordinates corresponding to the coordinates in the region bed file.

Notes

This method assumes that the chrom_offsets attribute has been properly set.

The region_bed file should be in BED format, with columns for chromosome, start position, and end position.

Examples:

>>> genome = Genome()
>>> genome.chrom_offsets = {"chr1": 0, "chr2": 1000}
>>> coords = genome.get_global_coords("regions.bed")
>>> print(coords)
[100 200 300 1100 1200 1300]

parse_global_coords

parse_global_coords(global_coords)

Return the global coords in to regions.

get_motif_db

get_motif_db(motif_db_name='JASPAR2024_CORE_vertebrates', max_length=None)

Get JASPAR motif database object.

get_gene_protein_sequence

get_gene_protein_sequence(gene_name, sel_longest=True)

Get the protein sequence for a gene.

Sequence

Bases: Seq

Utility class for DNA sequence manipulation. Inherits from Bio.Seq.Seq.

sequence property

sequence

Returns the sequence as a string.

one_hot_encoding

one_hot_encoding(order=DEFAULT_ONE_HOT_ORDER, dtype=np.int8) -> np.ndarray

One-hot encoding of a DNA sequence string. Output is a numpy array of shape (len(seq), 4).

Parameters:

Name	Type	Description	Default
order	str	Order of the one-hot encoding base axis. Default is 'ACGT' so reverse the base axis will be equal to make a compelment conversion.	DEFAULT_ONE_HOT_ORDER
dtype	dtype	Data type of the output array. Default is np.int8.	int8

Returns:

Name	Type	Description
one_hot	ndarray	One-hot encoding of the sequence

reverse_complement

reverse_complement()

Returns the reverse complement of the sequence.

understand_regions

understand_regions(regions, as_df=True) -> pr.PyRanges | pd.DataFrame

From various inputs, return a clear output. Return pyranges by default.

Parameters:

Name	Type	Description	Default
regions	(PyRanges, DataFrame, str, Path, list, tuple, Index, ndarray, Series)	The input regions to parse.	required
as_df	bool	If True, return the output as a DataFrame. Default is True.	True

Returns:

Type	Description
PyRanges or DataFrame	A PyRanges object representing the parsed regions, or a DataFrame if as_df is True.