Metadata-Version: 2.2
Name: coralsnake
Version: 0.0.215
Summary: Transcriptome mapping in two colors
Author-email: Chang Ye <yech1990@gmail.com>
License: GPL-3.0-only
Project-URL: Repository, https://github.com/y9c/coralsnake
Project-URL: Changelog, https://github.com/y9c/coralsnake/blob/main/CHANGELOG.md
Project-URL: Documentation, https://coralsnake.yech.science/
Keywords: transcriptome,mapping,metagene,genomics,variant,rna,polars
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: bwamem>=0.0.52
Requires-Dist: ruranges>=0.0.14
Requires-Dist: numpy>=1.26
Requires-Dist: polars>=1.30.0
Requires-Dist: pyfamsa>=0.4
Requires-Dist: pysam>=0.22
Requires-Dist: rich>=13.0.0
Requires-Dist: rich-click>=1.8.3
Requires-Dist: scipy>=1.14
Requires-Dist: xopen>=1.9.0
Provides-Extra: plot
Requires-Dist: matplotlib<4,>=3.8; extra == "plot"

# Coralsnake

[![Pypi Releases](https://img.shields.io/pypi/v/coralsnake.svg)](https://pypi.python.org/pypi/coralsnake)
[![Downloads](https://pepy.tech/badge/coralsnake)](https://pepy.tech/project/coralsnake)

<p align="center">
    <picture>
        <img alt="coralsnake logo" src="https://coralsnake.yech.science/coralsnake_DNA.png" style="width: 50%">
    </picture>
</p>

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

```bash
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:

```bash
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`).                         |

> **`annotate` is the single annotation tool** (merged `annot` + `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.

```bash
# 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:

```bash
coralsnake metagene --list
coralsnake metagene --download GRCh38
```

### Python API

The metagene functions are also importable directly from the flat modules:

```python
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).

```bash
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
```

```python
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.

```bash
# 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
```

```python
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](DESIGN.md) — package layout and design decisions.
- Full docs site: <https://coralsnake.yech.science/> (see `docs/`).
