Reference and species helpers

These helpers normalize known species/reference names or select a matching dataset. For reproducible analysis, prefer an explicit assembly and annotation version. See assembly selection.

cached_release

cached_release(release, species='human')

Create an EnsemblRelease instance only if it's hasn't already been made, otherwise returns the old instance. Keeping this function for backwards compatibility but this functionality has been moving into the cached method of EnsemblRelease.

available_dated_releases

available_dated_releases(species='human', refresh=False)

Annotation dates of the species' registered dated assembly, oldest first.

Parameters:

Name	Type	Description	Default
species	str or Species	Species name, e.g. "human" or "mus_musculus".	'human'
refresh	bool	Fetch the dates again. Otherwise cached dates are used without network access; dates are fetched and cached on first use.	False

Returns:

Type	Description
list of str	Dates in YYYY_MM form, each usable as EnsemblRelease(date).

Raises:

Type	Description
ValueError	If the species has no dated releases.
OSError	If the dates must be fetched and the server can't be reached or returns a page that lists no dates.

available_annotation_dates

available_annotation_dates(assembly_accession, provider='ensembl', refresh=False)

Annotation dates published for one assembly accession and provider on the new Ensembl platform, oldest first; use with EnsemblRelease.

Parameters:

Name	Type	Description	Default
assembly_accession	str	Versioned GCA or GCF accession, e.g. "GCA_000001405.29".	required
provider	str	Provider directory, e.g. "ensembl" or "community".	'ensembl'
refresh	bool	Fetch the dates again rather than using cached dates.	False

Raises:

Type	Description
OSError	If the dates must be fetched and the server can't be reached or returns a page that lists no dates.

UnpublishedDateError

Ensembl doesn't publish an annotation with this date; the message lists the dates it does publish.

find_species_by_name

find_species_by_name(species_name)

find_species_by_reference

find_species_by_reference(reference_name)

genome_for_reference_name

genome_for_reference_name(reference_name, allow_older_downloaded_release=True)

Given a genome reference name, such as "GRCh38", returns the corresponding Ensembl Release object.

If allow_older_downloaded_release is True, return the newest release that is installed (see Genome.installed), else the newest whose files are downloaded. Choosing only reads the cache; nothing is downloaded.

Otherwise, or when no release is available locally, return the newest release of Ensembl for the reference.

which_reference

which_reference(species_name, ensembl_release)

check_species_object

check_species_object(species_name_or_object)

Helper for validating user supplied species names or objects.

normalize_reference_name

normalize_reference_name(name)

Search the dictionary of species-specific references to find a reference name that matches aside from capitalization.

If no matching reference is found, raise an exception.

normalize_species_name

normalize_species_name(name)

If species name was "Homo sapiens" then replace spaces with underscores and return "homo_sapiens". Also replace common names like "human" with "homo_sapiens".

Species

Species(latin_name, synonyms=[], reference_assemblies={}, division='vertebrates', ensembl_genomes=False, ensembl_names=None, dated_releases=None, dated_reference_name=None, assemblies_without_ncrna=())

Container for combined information about a species name, its synonyn names and which reference to use for this species in each Ensembl release.

Parameters:

Name	Type	Description	Default
latin_name	str		required
synonyms	list of strings		[]
reference_assemblies	dict	Mapping of names of reference genomes onto inclusive ranges of Ensembl releases Example: {"GRCh37": (54, 75)}	{}
division	str	Ensembl division this species belongs to. One of "vertebrates", "plants", "fungi", "metazoa", "protists", "bacteria". Defaults to "vertebrates".	'vertebrates'
ensembl_genomes	bool	If True, the species' annotation and FASTA files live on the Ensembl Genomes server (ftp.ensemblgenomes.ebi.ac.uk) under the /{division}/... subtree, with their own release numbering (1..MAX_ENSEMBL_GENOMES_RELEASE). If False (default) the species is served from the main Ensembl FTP at ftp.ensembl.org.	False
ensembl_names	dict	Names Ensembl publishes the species under from a given release on, when it renamed it, e.g. {100: "canis_lupus_familiaris"}.	None
dated_releases	tuple of (str, str)	Assembly accession and provider under which the new Ensembl platform publishes dated releases (e.g. "2026_04") of the registered default assembly, e.g. ("GCA_000001405.29", "ensembl").	None
dated_reference_name	str	Stable label of that dated assembly when it differs from the latest numbered assembly. Existing dated cache paths retain it.	None
assemblies_without_ncrna	iterable of str	Numbered assemblies with no separately published ncRNA FASTA. Their transcript sources contain only cDNA. Other missing files remain installation errors.	()

VALID_DIVISIONS class-attribute instance-attribute

VALID_DIVISIONS = frozenset({'vertebrates', 'plants', 'fungi', 'metazoa', 'protists', 'bacteria'})

latin_name instance-attribute

latin_name = latin_name.lower().replace(' ', '_')

synonyms instance-attribute

synonyms = synonyms

reference_assemblies instance-attribute

reference_assemblies = reference_assemblies

division instance-attribute

division = division

ensembl_genomes instance-attribute

ensembl_genomes = ensembl_genomes

ensembl_names instance-attribute

ensembl_names = dict(ensembl_names or {})

dated_releases instance-attribute

dated_releases = tuple(dated_releases) if dated_releases else None

assemblies_without_ncrna instance-attribute

assemblies_without_ncrna = frozenset(assemblies_without_ncrna)

is_plant property

is_plant

is_fungus property

is_fungus

is_vertebrate property

is_vertebrate

is_invertebrate property

is_invertebrate

is_animal property

is_animal

is_protist property

is_protist

is_bacterium property

is_bacterium

dated_reference_name property

dated_reference_name

Stable label of the registered dated dataset, independent of new releases.

current_reference_name property

current_reference_name

Assembly of the last numbered release.

register classmethod

register(latin_name, synonyms, reference_assemblies, division='vertebrates', ensembl_genomes=False, ensembl_names=None, dated_releases=None, dated_reference_name=None, assemblies_without_ncrna=())

Create a Species object from the given arguments and enter into all the dicts used to look the species up by its fields.

all_registered_latin_names classmethod

all_registered_latin_names()

Returns latin name of every registered species.

all_species_release_pairs classmethod

all_species_release_pairs()

Generator which yields (species, release) pairs for all possible combinations.

ensembl_name

ensembl_name(release)

The name of this species' directories and files in an Ensembl release.

transcript_sequence_types

transcript_sequence_types(release)

Published transcript FASTAs; missing required files still fail.

which_reference

which_reference(ensembl_release)

to_dict

to_dict()

from_dict classmethod

from_dict(state_dict)

Package values and convenience genomes

MAX_ENSEMBL_RELEASE is the newest numbered release supported by this package. __version__ is its package version. ensembl_grch36, ensembl_grch37 and ensembl_grch38 are convenience EnsemblRelease objects selected when the package imports, using genome_for_reference_name. Their selections depend on installed/downloaded data and the supported release range. Use an explicit EnsemblRelease for reproducibility. They do not represent the new platform's dated annotations.