DOCSEARCHbyAlgolia
Submit Docs

pyensembl

repository·main·Indexed 19 days ago

https://github.com/openvax/pyensembl

A Python interface for accessing Ensembl reference genome metadata. It allows users to query genes, transcripts, exons, and protein information by ID, name, or genomic location. The library supports official Ensembl releases as well as custom local GTF/FASTA files via the Genome and Database classes.

Tokens
17.8K
Snippets
66
Records
90
Agent score
63%

What's inside pyensembl

  1. Access Gene and Transcript data

    main

    PyEnsembl provides a hierarchy of objects to navigate genomic features:

    1. Gene: Accessed via genome.gene_by_id(gene_id=...) or genome.genes_by_name(gene_name). A Gene object contains information about its location and associated transcripts.
    2. Transcript: Accessed via the .transcripts attribute of a Gene object.
    3. Protein: Transcripts provide access to protein information via .protein_id and .protein_sequence.
    # Example navigation
gene = genome.gene_by_id(gene_id='FBgn0011747')
transcript = gene.transcripts[0]
print(transcript.protein_id)
print(transcript.protein_sequence)

  2. Download and install Ensembl data

    main

    After installing the package, you must download and index the Ensembl reference data before use. You can do this via the CLI or programmatically in Python.

    Using the CLI

    Use the pyensembl install command with the --release and --species flags.

    Using Python

    Create an EnsemblRelease object, then call .download() followed by .index().

    # Example: Install human data for releases 75 and 76
pyensembl install --release 75 76 --species human

  4. Configure the PyEnsembl cache location

    main

    By default, PyEnsembl uses the platform-specific Cache folder. You can override this by setting the PYENSEMBL_CACHE_DIR environment variable.

    export PYENSEMBL_CACHE_DIR=/custom/cache/dir

  5. How SequenceData handles Ensembl version mismatches

    main

    A common issue in genomic data is the discrepancy between how Ensembl and GENCODE handle versioned IDs. Ensembl often uses bare IDs in GTFs with a separate version attribute, while GENCODE embeds the version in the ID (e.g., ENSG00000123456.1).

    SequenceData resolves this using a multi-step fallback logic in its internal lookup mechanism:

    1. Literal Lookup: Tries to find the exact identifier provided.
    2. Strip Version: If the identifier is an Ensembl ID with a version (e.g., ENS... .N), it tries the bare ID.
    3. Alias Lookup: If the identifier is a bare ID, it consults a _stripped_index to find the versioned alias actually present in the FASTA.

    This ensures that sd.get('ENS...') works regardless of whether your FASTA file uses versioned or unversioned headers.

  6. Manage species data with the Species class

    main

    The Species class is a container for biological species information, including their Latin names, synonyms, and the mapping of Ensembl releases to specific reference genome assemblies. It allows for looking up species by Latin name, common names (synonyms), or reference assembly names.

    Key attributes:

    • latin_name: The standardized lowercase name (e.g., homo_sapiens).
    • synonyms: A list of common names.
    • reference_assemblies: A dictionary mapping genome names to inclusive Ensembl release ranges, e.g., {"GRCh38": (76, 100)}.
    • division: The Ensembl division (e.g., vertebrates, plants, fungi, metazoa, protists, bacteria).
    • ensembl_genomes: A boolean indicating if the species is served from the Ensembl Genomes server instead of the main Ensembl FTP.
    from pyensembl.species import Species

# Example of a species object structure
species = Species(
    latin_name="homo_sapiens",
    synonyms=["human"],
    reference_assemblies={"GRCh38": (76, 100)},
    division="vertebrates",
    ensembl_genomes=False
)

  7. Determine protein coding status using biotype tiers

    main

    PyEnsembl uses a three-tier ontology to classify whether a transcript's biotype produces a polypeptide. You can check these statuses using the following properties on a LocusWithGenome object:

    1. is_protein_coding (Strict): Returns True only if the biotype is exactly "protein_coding". This is the most conservative definition, used by downstream effect predictors like varcode to identify canonical protein-coding transcripts.

    2. is_protein_coding_extended (Extended): Returns True for biotypes that produce stable, functional polypeptides. This includes the strict "protein_coding" set plus:

      • Immunoglobulin gene segments ("IG_C_gene", "IG_D_gene", "IG_J_gene", "IG_V_gene")
      • T-cell receptor gene segments ("TR_C_gene", "TR_D_gene", "TR_J_gene", "TR_V_gene")
      • "polymorphic_pseudogene"
      • "translated_processed_pseudogene" and "translated_unprocessed_pseudogene"

    3. is_translated (Widest): Returns True for any biotype that is translated on a ribosome, even if the product is transiently expressed and targeted for degradation. This includes everything in the extended set plus:

      • "nonsense_mediated_decay"
      • "non_stop_decay"

    Use is_translated when you need to know if a variant lands in a translated frame (e.g., for RNA-seq peptide analysis), regardless of whether the protein product is stable.

  8. Use DownloadCache to manage genome data files

    main

    The DownloadCache class manages the downloading of remote files or the copying of local files into a centralized cache directory. It handles path resolution, decompression, and error reporting when data is missing.

    Key Features

    • Automatic Path Resolution: Determines cache locations based on reference and annotation names.
    • Remote Downloads: Fetches files from URLs and optionally decompresses them (e.g., .fa.gz to .fa).
    • Local File Integration: Copies local files into the cache if copy_local_files_to_cache is enabled.
    • Custom Error Messages: Can use an install_string_function to provide actionable installation instructions when files are missing.
    • Cache Cleanup: Provides methods to delete specific files by prefix/suffix or to wipe the entire cache directory.
    from pyensembl.download_cache import DownloadCache

cache = DownloadCache(
    reference_name="GRCh38",
    annotation_name="ensembl",
    annotation_version=104,
    decompress_on_download=True,
    copy_local_files_to_cache=True
)

# Get a path to a remote file (downloads if missing and download_if_missing=True)
path = cache.download_or_copy_if_necessary(
    "https://example.com/data.fa.gz",
    download_if_missing=True
)

  9. Download and index genome data

    main

    Before accessing genomic features, you must ensure the data files are downloaded and the database is indexed.

    1. Use .download() to fetch the GTF and FASTA files from the provided paths/URLs to the local cache.
    2. Use .index() to generate the SQLite database from the GTF and create efficient representations of the FASTA sequence files.
    genome = Genome(reference_name='GRCh38', annotation_name='Ensembl', ...)
genome.download()
genome.index()

  10. Load an Ensembl genome in Python

    main

    To load a specific Ensembl release for a species, instantiate the EnsemblRelease class.

    from pyensembl import EnsemblRelease
# Load fly genome data from Ensembl release v100
data = EnsemblRelease(release=100, species='drosophila_melanogaster')

  11. Retrieve Exon information via Genome API

    main

    The Genome object provides methods to query and retrieve Exon objects or their identifiers:

    Querying Exons

    • exon_by_id(exon_id): Constructs an Exon object for a specific Ensembl exon ID (e.g., "ENSE00001209410").
    • exon_ids(contig=None, strand=None): Returns a list of exon IDs, optionally filtered by chromosome (contig) and strand.
    • exon_ids_of_gene_id(gene_id): Returns a list of exon IDs associated with a specific gene ID.
    • exon_ids_of_gene_name(gene_name): Returns a list of exon IDs associated with a specific gene name.
    • exon_ids_of_transcript_id(transcript_id): Returns a list of exon IDs associated with a specific transcript ID.
    • exon_ids_of_transcript_name(transcript_name): Returns a list of exon IDs associated with a specific transcript name.

  12. Use custom (non-Ensembl) genome data

    main

    You can use the Genome class to work with arbitrary reference data by providing paths or URLs to GTF and FASTA files. Note that handling of non-Ensembl GTF formats is still in development.

    After initializing the Genome object, you must call .index() to parse the GTF and construct the database.

    from pyensembl import Genome
data = Genome(
    reference_name='GRCh38',
    annotation_name='my_genome_features',
    gtf_path_or_url='/My/local/gtf/path_to_my_genome_features.gtf',
)
data.index()
# Now you can use methods like data.gene_names_at_locus(...)