Coralsnake
Coralsnake is a transcriptome mapping toolkit. In addition to the
two-color mapping workflow (prepare, map, liftover, annot, group), it
now bundles the full metagene profiling analysis and a sequence-logo
plotter as first-class subcommands.
Installation
pip install coralsnake
Optional support for the visualization commands (metagene profile plot and
sequence logo) requires the lightweight plot extra, which only pulls in
matplotlib when you need it:
pip install "coralsnake[plot]"
Commands
| Route | Command | Description |
|---|---|---|
| t -> g | liftover / tbam2gbam |
Remap transcriptome-aligned reads to genome coordinates. |
| g -> t | gbam2tbam |
Remap genome-aligned reads back to transcript coordinates. |
Read mapping (both directions)
prepare builds a transcript reference; map aligns reads to it. The two
BAM-conversion commands round-trip between transcript and genome span:
coralsnake tbam2gbam(alias:liftover) – transcript BAM → genome BAM (splices reads at exon boundaries, inserts introns).coralsnake gbam2tbam– genome BAM → transcript BAM (clips to exons, joins spliced reads contiguously on the transcript).
Command reference
| Command | Description |
|---|---|
prepare |
Extract primary transcript from a GTF/GFF file. |
map |
Map reads to a reference genome using BWA-MEM (two-color aware). |
liftover / tbam2gbam |
Remap transcriptome-aligned reads to genome coords. |
gbam2tbam |
Remap genome-aligned reads back to transcript coordinates. |
annotate |
Unified site/variant annotation (region + gene/transcript/effect). |
annot |
Site labeling (legacy; use annotate --annotation). |
effect |
Variant effect (legacy; use annotate with GTF+FASTA). |
group |
Group genes and build a consensus sequence. |
metagene |
Metagene profiling: distribution of sites across 5'UTR/CDS/3'UTR. |
logo |
Plot a DNA/RNA sequence logo (requires coralsnake[plot]). |
variant |
Variant utilities (motif, coordinate). |
annotateis the single annotation tool (mergedannot+effect). One command, one schema. Two input modes share one engine:
--reference-gtf [--reference-transcript FASTA]– region + gene/transcript/ position + (with ref/alt + FASTA) the full variant effect.--annotation <prepare-table>– fast precomputed-table site labeling.
Metagene subcommand
coralsnake metagene is a full migration of the metagene package, built on
the high-performance polars + ruranges stack. It computes the distribution
of genomic sites relative to gene regions (5'UTR, CDS, 3'UTR) and can emit
binned statistics and a publication-ready profile plot.
# Using a built-in reference (GRCh38) or a custom GTF:
coralsnake metagene -i sites.tsv.gz -r GRCh38 -H -m 1,2,3 -w 5 \
-o output.tsv -s scores.tsv -p plot.png
coralsnake metagene -i sites.bed -g custom.gtf.gz -m 1,2,3 -w 5 \
-o output.tsv -s scores.tsv -p plot.png
List or download the built-in references:
coralsnake metagene --list
coralsnake metagene --download GRCh38
Python API
The metagene functions are also importable directly from the flat modules:
from coralsnake.io import load_sites, load_reference
from coralsnake.gtf import load_gtf
from coralsnake.annotation import map_to_transcripts, normalize_positions
from coralsnake.map_to_local import map_to_local
from coralsnake.plotting import plot_profile
sites = load_sites("sites.tsv.gz", with_header=True, meta_col_index=[0, 1, 2])
ref = load_reference("GRCh38") # or load_gtf("custom.gtf.gz")
annotated = map_to_transcripts(sites, ref)
gene_bins, gene_stats, gene_splits = normalize_positions(
annotated, split_strategy="median", bin_number=100
)
plot_profile(gene_bins, gene_splits, "metagene_plot.png")
# Map global coordinates to local transcript coordinates (strand-aware):
local = map_to_local(sites, ref, ref_id_col="transcript_id")
Performance
The metagene core is built on the vectorized polars + ruranges stack, and
uses Rust-backed ruranges primitives instead of slow per-group Python applies:
map_to_transcriptspicks the best transcript per gene with a vectorized sort +group_by().first()(wasgroup_by().map_groups()python apply) — ~20× faster on realistic inputs.map_to_localusesruranges.numpy.group_cumsumfor strand-aware cumulative transcript offsets (was a hand-rolledmap_groupsapply) — ~7× faster.Mlogo(sequence logo) builds its score matrix with vectorizednumpy(bincount+ codepoint lookup) — ~1.5× faster and fixes a0·log2(0)NaN edge case.
Logo subcommand
coralsnake logo plots a DNA/RNA sequence logo from a set of motif sequences.
The scoring engine is pure numpy; the renderer needs matplotlib (plot extra).
coralsnake logo -m ACGT -m ACGG -m CCGT -o logo.png
# or with per-motif weights from a file (seq\tcount)
coralsnake logo -i motifs.tsv -o logo.svg
from coralsnake import Mlogo
m = Mlogo(motifs=["ACGT", "ACGG", "CCGT"], to2bit=True)
m.plot(ax) # requires matplotlib (plot extra)
Variant analysis
The motif, coordinate and effect commands are a migration of the
standalone variant package — fused into the top-level CLI with the old
pyfaidx / urllib3 / pyensembl+varcode dependencies removed and
coralsnake's pysam + ruranges stack used instead. Naming and output format
are unchanged.
# Motif fetch (strand-aware, padded with N)
coralsnake motif -i sites.tsv -o motifs.tsv -f genome.fa -n 2,3 -w
# Chromosome-name mapping (UCSC ↔ Ensembl)
coralsnake coordinate -i sites.tsv -o mapped.tsv -M U2E
# Variant effect annotation (pure Python classifier on coralsnake GTF)
coralsnake effect -i variants.tsv -o effects.tsv \
--reference-gtf annotation.gtf \
--reference-transcript transcripts.fa -s -a
from coralsnake.effect import Annot, Site, reverse_base
from coralsnake.motif import get_motif
from coralsnake.coordinate import run_coordinate
from coralsnake.effect import run_effect
Documentation
- Architecture & Design — package layout and design decisions.
- Full docs site: https://coralsnake.yech.science/ (see
docs/).
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file coralsnake-0.0.217.tar.gz.
File metadata
- Download URL: coralsnake-0.0.217.tar.gz
- Upload date:
- Size: 105.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3afc7c278f065e293c784bc53072dc91a441425673563135a40b7db6428751f2
|
|
| MD5 |
7d8e6da217e3ff3c4d8ad92ca69a62ab
|
|
| BLAKE2b-256 |
c33190d7a98c8de69b66724adb050db9f4ebad7d04be30556d41854d7b0daf29
|
File details
Details for the file coralsnake-0.0.217-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: coralsnake-0.0.217-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 99.8 kB
- Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
046df7f00107f7b702fbed254752995e7de57e8e13b9b5a691a53f4e797fc641
|
|
| MD5 |
df4ffa2109f040e5a15b60561abb41e5
|
|
| BLAKE2b-256 |
7e5aa1f1f5f5cf475a1f81366419b92507889bb5f748e680f12c863a69da3643
|
File details
Details for the file coralsnake-0.0.217-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: coralsnake-0.0.217-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 99.8 kB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7b0ad5f6a6fde222f0196ce2da5ed03b9322a1aa7c4baf0a5cb9743fb0769fdc
|
|
| MD5 |
a2e655269bfb090bb5499f781b458464
|
|
| BLAKE2b-256 |
53ea995067a559b24a9173e5b9774e47157e1e7e4009997f22739726aa913fca
|
