Metadata-Version: 2.5
Name: meiva
Version: 0.1.0
Summary: Caller-agnostic functional annotation of mobile element insertions (MEIs) — VEP for mobile elements.
Project-URL: Homepage, https://github.com/mlamardi/MEIVA
Project-URL: Source, https://github.com/mlamardi/MEIVA
Project-URL: Issues, https://github.com/mlamardi/MEIVA/issues
Author: Seyedmohammad Hosseinpourlamardi
License-Expression: MIT
License-File: LICENSE
Keywords: Alu,LINE-1,MEI,SVA,VCF,annotation,bioinformatics,mobile element insertion,retrotransposon,transposable element
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cyvcf2>=0.30
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# MEIVA — Mobile Element Insertion Variant Annotator

**VEP for mobile elements.** A caller-agnostic engine that turns raw MEI calls
(Alu, LINE-1, SVA) from tools like **xTEA** and **MELT** into *interpreted*,
*prioritised* variants — with element- and orientation-aware functional
consequences, population frequencies, regulatory context, and disease
knowledge.

> Status: **alpha, under active development.** The pipeline runs end to end for
> xTEA cohorts: parse, merge across samples, annotate against GENCODE, and emit a
> per-locus table with genic context and MEI-aware consequence calls (Layer 1 and
> Layer 2). A second caller (MELT), true population frequencies, and
> regulatory/lncRNA overlap are the next layers.

## Install

```bash
pip install -e .        # from a checkout; PyPI/bioconda packaging is planned
```

Requires Python 3.10 or newer. The only runtime dependency is `cyvcf2`.

## Usage

MEIVA installs a `meiva` command with two subcommands (both also work as
`python -m meiva ...`).

Annotate a cohort of caller VCFs against a GENCODE GTF, writing an annotated
per-locus table:

```bash
meiva annotate --vcf sample1.vcf sample2.vcf \
  --gencode gencode.v47.annotation.gtf.gz \
  -o cohort.annotated.tsv
```

Omit `-o` to stream the table to stdout so it composes with shell pipelines.

Optionally add FANTOM6 lncRNA functional evidence (all three files together):

```bash
meiva annotate --vcf sample1.vcf sample2.vcf \
  --gencode gencode.v47.annotation.gtf.gz \
  --fantom6-degs DESeq2_genes_ASO_signif.tsv.bz2 \
  --fantom6-samples Published_sample_summary.tsv.bz2 \
  --fantom6-cat FANTOM_CAT.lv3_robust.info_table.ID_mapping.tsv.gz \
  -o cohort.annotated.tsv
```

Add FANTOM5 regulatory context (either track may be given on its own):

```bash
meiva annotate --vcf sample1.vcf sample2.vcf \
  --gencode gencode.v47.annotation.gtf.gz \
  --fantom5-enhancers F5.hg38.enhancers.bed.gz \
  --fantom5-peaks hg38_fair+new_CAGE_peaks_phase1and2.bed.gz \
  --fantom5-peak-names human_phase1and2_CAGE_Peak_name.txt.gz \
  -o cohort.annotated.tsv
```

Inspect a single caller's output as normalized `MEISite` records, without
annotation (handy for checking that a new caller parses correctly):

```bash
meiva parse --vcf sample1.vcf | head
```

## Why this exists

MEI *calling* is a crowded, mature space (MELT, xTEA, Mobster, TEBreak, …).
What's missing is everything *downstream*: once you have calls across a cohort,
there is no standard, maintained tool to annotate and prioritise them. People
hand-roll scripts. MEIVA is that missing layer.

The intellectual core is **not** the annotation plumbing — it is the
**MEI-aware consequence model**. General annotators (VEP, SnpEff) treat a
variant as a point. An MEI is not a point: its functional impact depends on the
element family, its orientation, its length, its poly-A tail, and the genic
context it lands in. A sense-oriented full-length L1 in an intron does
something mechanistically different from an AluY in a 3′UTR. MEIVA models that.

## Design principles

- **The parser normalises; the model only validates.** A `MEISite` that exists
  is, by construction, trustworthy. Malformed input fails loudly at ingest, not
  silently three layers later.
- **Sites, not points.** Breakpoints are imprecise; everything downstream
  matches on intervals, never bare coordinates.
- **Caller-agnostic.** One canonical record; per-caller parsers behind it.
- **Reproducible references.** Reference data is versioned and built via a
  cache manager, not bundled and forgotten.

## Status by layer

- **Ingest.** xTEA parser behind a caller-agnostic parser interface. (MELT next.)
- **Cohort merge.** Interval-based merge across samples with breakpoint-jitter
  handling and discovery-based carrier frequencies.
- **Layer 1, genic context.** CDS, UTR, non-coding exon, splice, intron,
  promoter, up/downstream, intergenic; strand-aware, with sense/antisense
  orientation, MANE-Select flag, gene biotype, and nearest-gene distance,
  annotated against a pinned GENCODE release (v47).
- **Layer 2, consequence model.** VEP-style mechanistic consequence term plus an
  ordinal impact tier, derived from element family, orientation, region, length,
  and biotype.

- **Layer 4, lncRNA functional evidence.** FANTOM6 knockdown phenotypes joined onto
  the host gene by Ensembl ID, tiered by how many independent ASOs responded.
- **Layer 4, regulatory context.** FANTOM5 transcribed enhancers and CAGE-defined
  promoters, reported as both exact overlap and distance to the nearest element.

Planned:
- **MELT parser,** to exercise and lock the caller-agnostic design.
- **Layer 3, population frequency** by force-genotyping discovered sites back
  against the samples, for true allele frequencies rather than discovery counts.

## License

MIT, see [LICENSE](LICENSE).
