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.

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)

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 assembly of the last numbered release, e.g. ("GCA_000001405.29", "ensembl").	None

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

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

register classmethod

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

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.

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.