Quickstart¶
Installation of ensembl-tui creates a command line tool eti which contains a number of subcommands that allow you to acquire and then sample from Ensembl genomic datasets. The general workflow is:
- Create a demo config file
- Download raw data from Ensembl
- Make the local installation
- Show summaries of the installation
- Export gene meta-data
- Export homology data
Create A Demo Config¶
You specify the genomic resources that you want from Ensembl using a config file. ensembl-tui comes with an example file with comments describing what each of the components of that file are.
$ eti demo-config -o demo
Contents written to demo
Note
The config specifies download the genomes and annotations from Ensembl release 115 of Saccharomyces cerevisiae and Caenorhabditis elegans and gene homology data. It also specifies the path to write the downloaded files and where to install them.
Warning
Edit this file before using! It also specifies primate whole genome alignments -- which are large!
Download The Specified Data¶
We use a custom config file which specifies just "yeast" and "worm". (You can do this yourself by downloading the small.cfg and executing the following command
$ eti download -c <path to>/small.cfg
The data will be downloaded to staging_path specified in small.cfg, which is interpreted relative to the directory in which you executed the command.
Note
If a download is interrupted and restarted, eti resumes downloads from where it stopped.
Make The Local Installation¶
$ eti install -d data/small-download
Installing features 📚 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 0:02:17
Installing 🧬🧬 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 0:00:01
Installing homologies ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 0:00:42
Contents installed to
'/home/runner/work/ensembl_tui/ensembl_tui/docs/data/small-install'
Show Summaries Of The Installation¶
The Top Level¶
$ eti installed -i data/small-install
Ensembl release: 115
Installed genomes:
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ abbrev ┃ genome ┃ common name ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ cae-eleg │ caenorhabditis_elegans │ caenorhabditis elegans (nematode, n2) │
│ sac-cere │ saccharomyces_cerevisiae │ saccharomyces cerevisiae │
└──────────┴──────────────────────────┴───────────────────────────────────────┘
Installed homologies: ✅
Installed alignments: ❌
Installation software versions:
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ package ┃ version ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ click │ 8.3.1 │
│ cogent3 │ 2026.1.12a1 │
│ cogent3_h5seqs │ 0.7.3 │
│ duckdb │ 1.4.3 │
│ ensembl_tui │ 0.7.5 │
│ numba │ 0.63.1 │
│ numpy │ 2.3.5 │
│ polars │ 1.37.1 │
│ pyarrow │ 23.0.0 │
│ rich │ 14.2.0 │
│ scitrack │ 2024.10.8 │
│ trogon │ 0.6.0 │
│ typing_extensions │ 4.15.0 │
│ unsync │ 1.4.0 │
└───────────────────┴─────────────┘
Summary Of A Species¶
$ eti species-summary -i data/small-install --species sac-cere
Saccharomyces cerevisiae
features
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ biotype ┃ count ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ ncRNA │ 18 │
│ snoRNA │ 77 │
│ tRNA │ 299 │
│ protein_coding │ 6,600 │
│ rRNA │ 24 │
│ snRNA │ 6 │
│ transposable_element │ 91 │
│ pseudogene │ 12 │
└──────────────────────┴───────┘
Saccharomyces cerevisiae repeat
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ repeat_type ┃ repeat_class ┃ count ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Dust │ dust │ 8,662 │
│ LTRs │ LTR/Gypsy │ 63 │
│ LTRs │ LTR/Copia │ 464 │
│ Low complexity regions │ Low_complexity │ 2 │
│ Other repeats │ Other/subtelomeric │ 35 │
│ RNA repeats │ rRNA │ 7 │
│ Simple repeats │ Simple_repeat │ 149 │
│ Tandem repeats │ trf │ 3,210 │
│ Type II Transposons │ DNA │ 2 │
└────────────────────────┴────────────────────┴───────┘
Note
We can use the abbrev listed above to identify the species.
Summary Of Compara¶
$ eti compara-summary -i data/small-install
Homology types
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ homology_type ┃ count ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ gene_split │ 44 │
│ within_species_paralog │ 11,998 │
│ ortholog_one2one │ 2,878 │
│ other_paralog │ 6,476 │
│ ortholog_one2many │ 1,509 │
│ ortholog_many2many │ 1,344 │
└────────────────────────┴────────┘
This shows the relationships between the species installed.
Export Gene meta-data¶
$ eti dump-genes -i data/small-install --species sac-cere --outdir yeast
Finished: wrote 'yeast/saccharomyces_cerevisiae-115-gene_metadata.tsv'!
Show the first five lines of the output file.
$ head -n 5 yeast/saccharomyces_cerevisiae*.tsv
species seqid source biotype transcript_biotypes num_transcripts start stop strand symbol description
saccharomyces_cerevisiae XV protein_coding protein_coding 1 234939 238185 1 GAL11 Subunit of the RNA polymerase II mediator complex; associates with core polymerase subunits to form the RNA polymerase II holoenzyme; affects transcription by acting as target of activators and repressors; forms part of the tail domain of mediator [Source:SGD;Acc:S000005411]
saccharomyces_cerevisiae XV protein_coding protein_coding 1 231569 231755 -1 DDR2 Multi-stress response protein; expression is activated by a variety of xenobiotic agents and environmental or physiological stresses; DDR2 has a paralog, HOR7, that arose from the whole genome duplication [Source:SGD;Acc:S000005413]
saccharomyces_cerevisiae XV protein_coding protein_coding 1 219210 220473 1 ARG1 Arginosuccinate synthetase; catalyzes the formation of L-argininosuccinate from citrulline and L-aspartate in the arginine biosynthesis pathway; potential Cdc28p substrate [Source:SGD;Acc:S000005419]
saccharomyces_cerevisiae VII protein_coding protein_coding 1 903473 904748 -1 PCT1 Cholinephosphate cytidylyltransferase; a rate-determining enzyme of the CDP-choline pathway for phosphatidylcholine synthesis, inhibited by Sec14p, activated upon lipid-binding; contains an element within the regulatory domain involved in both silencing and activation of enzymatic activity [Source:SGD;Acc:S000003434]
Export Homology Data¶
$ eti homologs -i data/small-install --ref cae-eleg --outdir worm_yeast --homology_type ortholog_one2one --limit 5
Homolog search ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 0:00:00
Extracting 🧬 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 0:00:00
Listing the files that are written into the specified worm_yeast directory.
$ ls worm_yeast
WBGene00016623.fa
WBGene00017749.fa
WBGene00018723.fa
WBGene00020113.fa
WBGene00194707.fa
logs
md5
not_completed
Note
The not_completed directory will contain any errors that occurred during the homolog command.