Coralsnake
Coralsnake is an exon-aware RNA analysis pipeline. Its core is the
exon structure of RNA: it assembles exons into transcript references
(prepare), and then splices and joins reads between transcript and
genome coordinates (liftover), runs exon-aware
metagene profiling, and annotates sites to genes/transcripts. It also bundles a
sequence-logo plotter as a first-class subcommand.
Nucleotide-conversion (two-color / three-color) mapping is not part of
coralsnake any more: it lives in the dedicated
prismalign package (pluggable backends:
bwamem, minimap2/mappy, pure-Python), on top of the lightweight
bwamem BWA-MEM binding.
Overview
How the subcommands fit together:
coralsnake — exon-aware RNA pipeline
(read alignment is external: bwa / prismalign / ...)
reads ── external mapper ──► aligned BAM
│
▼
┌─────────────────────────────────────────────────┐
│ prepare GTF/GFF + genome.fa ► transcript.fa │
│ (exon-spliced transcript reference) │
│ │
│ liftover one command, both directions: │
│ -d t2g tx.bam ► genome.bam │
│ -d g2t genome.bam ► tx.bam │
└─────────────────────────────────────────────────┘
│
sites.tsv (chrom,pos,strand[,ref,alt])
│
┌────────────┬────────────┬────────────┬────────────┬────────────┐
▼ ▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ annotate │ │ motif │ │ coordinate │ │ metagene │ │ group │
└────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘
gene/transc motif seq chrom names metagene gene clusters
+ region + (strand- (UCSC ⇄ profile + consensus
effect aware) Ensembl) (+ plot)
┌────────────┐
│ logo │ motifs ► sequence-logo image
└────────────┘
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 |
Remap transcriptome-aligned reads to genome coordinates (default --direction t2g). |
| g -> t | liftover -d g2t |
Remap genome-aligned reads back to transcript coordinates. |
Read mapping (both directions)
prepare builds a transcript reference. The BAM-conversion commands
round-trip between transcript and genome span:
coralsnake liftover(default--direction t2g) – transcript BAM → genome BAM (splices reads at exon boundaries, inserts introns).coralsnake liftover -d g2t– genome BAM → transcript BAM (clips to exons, joins spliced reads contiguously on the transcript).
Mapping itself is out of scope: align reads with
bwamem map, withprismalign mapfor nucleotide-conversion (two/three-color) chemistry, or any other mapper, then feed the BAM into the commands above wearing a matching reference.
Command reference
| Command | Description |
|---|---|
prepare |
Extract primary transcript from a GTF/GFF file. |
liftover |
Remap reads between genome/transcript coords (--direction t2g default, g2t inverts). |
annotate |
Unified site/variant annotation (region + gene/transcript/effect). |
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]). |
motif |
Fetch a genomic motif around variant sites (strand-aware). |
coordinate |
Map chromosome names between coordinate systems (UCSC↔Ensembl). |
annotateis the single annotation tool — one command, one schema, two input modes sharing 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 and coordinate commands are a migration of the standalone
variant package — fused into the top-level CLI with the old pyfaidx /
urllib3 dependencies removed and coralsnake's pysam + ruranges stack used
instead. Naming and output format are unchanged. Variant effect annotation is
covered by annotate (--reference-gtf + a genome FASTA + ref/alt columns).
# 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 (region + codon/AA + effect)
coralsnake annotate -i variants.tsv -o effects.tsv \
--reference-gtf annotation.gtf \
--reference-transcript genome.fa -s -a
from coralsnake.motif import get_motif
from coralsnake.coordinate import run_coordinate
from coralsnake.annotate import run_annotate
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.222.tar.gz.
File metadata
- Download URL: coralsnake-0.0.222.tar.gz
- Upload date:
- Size: 101.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eeed165a56a3375ff83a83c118e6a29d1452fcd13e5254ad606f8be7a82faed1
|
|
| MD5 |
d07181da52ec6f52df58fa7abba242c9
|
|
| BLAKE2b-256 |
e016a15bba3145bc4fc83c8b2e06ffad819c44caf51b40c3cb2e1b6f43c77491
|
File details
Details for the file coralsnake-0.0.222-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: coralsnake-0.0.222-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 95.6 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 |
dca2a487d00c44c92f1a69d37c46da580da598fac819588086b549a89657abb7
|
|
| MD5 |
c5f7e68251998612a171212ee251a6d2
|
|
| BLAKE2b-256 |
098e4f5a80f82ca66059167e89f4a2a58aadfb3307d34a57e1967290494e3779
|
File details
Details for the file coralsnake-0.0.222-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: coralsnake-0.0.222-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 95.6 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 |
f37a2c445ca872731577ec53641d87a8fd6aedd7c42b9fbf867842cc556dae30
|
|
| MD5 |
64336c8f8725ead599bf673b877974c2
|
|
| BLAKE2b-256 |
893d1bbf5dc972d1db01e1bd318bab6bbf606b5168efa1998df6c510ee8d7414
|
