Dataset constructors

EnsemblRelease selects numbered and dated Ensembl datasets, infers assemblies, and supports explicit assembly/provider choices. See assembly selection for examples, metadata, API discovery, and cache compatibility. Both it and custom Genome objects provide the shared Genome methods.

EnsemblRelease

EnsemblRelease(release=MAX_ENSEMBL_RELEASE, species=None, server=ENSEMBL_FTP_SERVER, *, genome_fasta=None, genome_fasta_type='toplevel', genome_fasta_mask='none', download_genome_fasta=None, genome_fasta_path=None, assembly=None, assembly_accession=None, provider=None, include_alt=None, reference_name=None, cache_directory_path=None, reference_metadata=None, _resolved=None, _preserve_legacy=False)

Bundles together the genomic annotation and sequence data associated with a particular release of the Ensembl database.

A release is either numbered or an annotation date, e.g. EnsemblRelease("2026_04", species="human"). Assembly identity is inferred from verified metadata; assembly= can select or check a particular build, full name, or versioned accession. Existing reference labels and cache layouts remain independent of the new assembly metadata.

release : int or str Numbered Ensembl release, e.g. 116, or an annotation date on the new Ensembl platform in YYYY_MM form, e.g. "2026_04".

genome_fasta : True or path, optional Reference DNA for sequence(): True for Ensembl's DNA for this release (see genome_fasta_type and genome_fasta_mask), or a local plain or gzip FASTA. Nothing is downloaded until download_genome_fasta(), download(), or pyensembl install.

release instance-attribute

release = release

species instance-attribute

species = normalize_species(species, assembly, assembly_accession)

server instance-attribute

server = server

include_alt instance-attribute

include_alt = self._resolved['include_alt']

annotation_date instance-attribute

annotation_date = release if dated else None

reference_name instance-attribute

reference_name = self._resolved['reference_name']

genome_fasta_type instance-attribute

genome_fasta_type = genome_fasta_type

genome_fasta_mask instance-attribute

genome_fasta_mask = genome_fasta_mask

download_url instance-attribute

download_url = urls.directory

gtf_url instance-attribute

gtf_url = urls.gtf

transcript_fasta_urls instance-attribute

transcript_fasta_urls = [urls.cdna]

protein_fasta_urls instance-attribute

protein_fasta_urls = [urls.pep]

genome_fasta_urls instance-attribute

genome_fasta_urls = [genome_fasta_url] if genome_fasta is True else []

assembly property

assembly

Canonical build/coordinate-system identifier, or None if unknown.

assembly_name property

assembly_name

Complete official assembly name, including any patch suffix.

assembly_accession property

assembly_accession

Versioned GCA/GCF accession, or None when upstream does not supply it.

provider property

provider

Dated FTP annotation provider (not its human-readable API label).

annotation_label property

annotation_label

Provider's API annotation label, e.g. GENCODE 50; not release.

annotation_is_subset property

annotation_is_subset

Whether upstream metadata or verified comparisons identify a subset.

genome_id property

genome_id

Pinned genome UUID for an explicit new-API selection, otherwise None.

website_release property

website_release

Website release label from API discovery, distinct from release.

normalize_init_values classmethod

normalize_init_values(release, species, server)

Normalizes the arguments which uniquely specify an EnsemblRelease genome.

cached classmethod

cached(release=MAX_ENSEMBL_RELEASE, species=None, server=ENSEMBL_FTP_SERVER, *, genome_fasta=None, genome_fasta_type='toplevel', genome_fasta_mask='none', download_genome_fasta=None, genome_fasta_path=None, **selection)

Construct EnsemblRelease if it's never been made before, otherwise return an old instance.

verify_sources

verify_sources(check_remote=False)

Check recorded annotation MD5s; optionally read upstream manifests.

Returns one report per GTF/sequence source. Existing files without a checksum are unrecorded, not corrupt. This never repairs data or writes receipts. MD5 checks accidental changes, not authenticity.

with_mirror

with_mirror(mirror, *, genome_fasta_path_or_url=None)

Return a Genome using this release's filenames at a flat mirror.

Use the same mirror when installing and reopening data. New mirror downloads have their own source identities and do not populate the canonical EnsemblRelease cache. This is also the constructor used by the CLI's --custom-mirror option.

Parameters:

Name	Type	Description	Default
mirror	str or Path	URL or directory containing the Ensembl filenames for this release.	required
genome_fasta_path_or_url	str or Path	Explicit reference DNA source. Otherwise mirror requested Ensembl DNA, or preserve a local DNA file attached to this release.	None

Returns:

Type	Description
Genome	A source-explicit genome, usable across processes and in Varcode.

install_string

install_string()

genome_fasta_install_string

genome_fasta_install_string()

to_dict

to_dict()

from_dict classmethod

from_dict(state_dict)

Deserialize EnsemblRelease without creating duplicate instances.

from_ensembl classmethod

from_ensembl(genome_id_or_accession, **options)

Resolve a genome using the new Ensembl metadata API (network access).

The returned object pins its annotation date and assembly metadata. Ordinary construction and loading serialized objects remain offline.

available_releases

available_releases(species=None, *, assembly=None, assembly_accession=None, provider=None, include_alt=None, refresh=False)

List metadata for the selected assembly's numbered and dated releases.

Uses bundled metadata and existing directory listings without network or cache writes unless refresh=True. With no assembly selection, use the species' latest numbered assembly. Entries are grouped by kind for display; their list order does not imply a cross-platform chronology. latest marks the conservative, verified choice used by EnsemblRelease("latest"). Explicit provider/coverage options select the dated platform only.