Coralsnake

coralsnake logo

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

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`	Remap transcriptome-aligned reads back to genome coordinates.
`annotate`	Unified site/variant annotation (region + gene/transcript/effect).
`annot`	Site labeling with transcript positions (legacy; see `annotate`).
`effect`	Variant effect classification (legacy; see `annotate`).
`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`).

annotate is the merged successor of annot + effect. One command, one GTF-based engine, one output schema: it labels a site with its gene/transcript/position and region, and (with a genome FASTA + ref/alt) classifies the variant effect (codon/AA). annot and effect are retained for backward compatibility.

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_transcripts picks the best transcript per gene with a vectorized sort + group_by().first() (was group_by().map_groups() python apply) — ~20× faster on realistic inputs.
map_to_local uses ruranges.numpy.group_cumsum for strand-aware cumulative transcript offsets (was a hand-rolled map_groups apply) — ~7× faster.
Mlogo (sequence logo) builds its score matrix with vectorized numpy (bincount + codepoint lookup) — ~1.5× faster and fixes a 0·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/).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coralsnake-0.0.214.tar.gz (94.9 kB view details)

Uploaded Aug 26, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

coralsnake-0.0.214-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (93.7 kB view details)

Uploaded Aug 26, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

coralsnake-0.0.214-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (93.7 kB view details)

Uploaded Aug 26, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

File details

Details for the file coralsnake-0.0.214.tar.gz.

File metadata

Download URL: coralsnake-0.0.214.tar.gz
Upload date: Aug 26, 2026
Size: 94.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for coralsnake-0.0.214.tar.gz
Algorithm	Hash digest
SHA256	`17417cbcc5b1bab6114827d13453e82533db0cf55a64ae4f7356a98e63cc72bb`
MD5	`956cba7e08485afede10b33d77a29781`
BLAKE2b-256	`87a2421628a66d08975eec0377a21c12afd1b36f3dde62c7e5dc894c31cacc93`

See more details on using hashes here.

File details

Details for the file coralsnake-0.0.214-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: coralsnake-0.0.214-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 26, 2026
Size: 93.7 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

Hashes for coralsnake-0.0.214-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`d8f34082b4d1fb2c271996dc7dcfb384b050c18e8ef5fe103546448d1c00a5ce`
MD5	`6d27bb43376721559577ae284b199bba`
BLAKE2b-256	`22b4ab3eacaa703ac894b71c9ca7218a4b0ec7ed4fcb8e4f441f157ae90c578a`

See more details on using hashes here.

File details

Details for the file coralsnake-0.0.214-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: coralsnake-0.0.214-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 26, 2026
Size: 93.7 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

Hashes for coralsnake-0.0.214-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`d81776d09be865510e1707b64000d02c624a1c5009c7754140d3a086f97e563d`
MD5	`4230dfb800bdf18683e1892a67e0b7c2`
BLAKE2b-256	`4d2a6cec7d51cccafcb1c269d726ea2055a033dcc97759a58bd07dde932e1183`