Metadata-Version: 2.4
Name: lncnova
Version: 0.1.1
Summary: LncNova: an integrated RNA-seq pipeline for novel lncRNA discovery and characterization
License-Expression: MIT
Keywords: lncRNA,RNA-seq,novel transcripts,bioinformatics,StringTie
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: openpyxl
Requires-Dist: pysam
Requires-Dist: pydeseq2>=0.4
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# LncNova

| | |
|---|---|
| **Package** | [![PyPI](https://img.shields.io/pypi/v/lncnova?label=PyPI)](https://pypi.org/project/lncnova/) [![Downloads](https://img.shields.io/pypi/dm/lncnova)](https://pypi.org/project/lncnova/) [![Wheel](https://img.shields.io/pypi/wheel/lncnova)](https://pypi.org/project/lncnova/#files) [![PyPI status](https://img.shields.io/pypi/status/lncnova)](https://pypi.org/project/lncnova/) |
| **Meta** | [![License: MIT](https://img.shields.io/pypi/l/lncnova)](LICENSE.txt) [![Python versions](https://img.shields.io/pypi/pyversions/lncnova)](https://pypi.org/project/lncnova/) |
| **Author** | AIIMS New Delhi |
<!--
Add these rows once the identifiers exist (replace the <...> parts):
| **CI**        | [![CI](https://github.com/<owner>/<repo>/actions/workflows/<workflow>.yml/badge.svg)](https://github.com/<owner>/<repo>/actions) |
| **Container** | [![Docker Pulls](https://img.shields.io/docker/pulls/<namespace>/lncnova)](https://hub.docker.com/r/<namespace>/lncnova) [![Docker Image Size](https://img.shields.io/docker/image-size/<namespace>/lncnova)](https://hub.docker.com/r/<namespace>/lncnova) |
| **Meta**      | [![DOI](https://zenodo.org/badge/DOI/<doi>.svg)](https://doi.org/<doi>) [![bio.tools](https://img.shields.io/badge/bio.tools-<tool_id>-blue)](https://bio.tools/<tool_id>) [![OpenEBench](https://img.shields.io/badge/OpenEBench-<id>-blue)](https://openebench.bsc.es/tool/<id>) |
| **Author**    | [![ORCID](https://img.shields.io/badge/ORCID-<0000--0000--0000--0000>-a6ce39?logo=orcid&logoColor=white)](https://orcid.org/<0000-0000-0000-0000>) |
-->

**An integrated RNA-seq pipeline for novel lncRNA discovery and characterization.**

LncNova takes raw RNA-seq FASTQ files and returns a curated set of **novel lncRNAs**
(transcripts absent from GENCODE and LNCipedia), then characterizes them. It runs on a
**single sample** or on a **case/control cohort**. All tools and reference databases ship in a
container image, so nothing else needs to be installed.

```
FASTQ ─ fastp ─ HISAT2 ─ strandedness check ─ StringTie (per sample) ─ merge + gffcompare
      ─ novelty / length / exon-count / TPM filters ─ CPC2 + CPAT consensus ─► novel lncRNAs
      ─ featureCounts (known genes vs GENCODE, novel genes vs the novel set)

cohort only:  PyDESeq2 ─ cis / trans targets ─ GO / KEGG ─ IntaRNA (lncRNA + mRNA 3'UTR) ─ ceRNA triads
all modes:    cis targets ─ IntaRNA miRNA sites ─ disease precedent (RNADisease)
```

| Mode | Triggered by | Result |
|------|--------------|--------|
| single | one sample, or several with no `condition` column | novel lncRNA set, TPM, cis targets, miRNA sites, disease precedent |
| cohort | `condition` column with `case`/`control`, ≥ 2 samples per group | the above plus differential expression, condition-adjusted co-expression, GO/KEGG, ceRNA triads |

## Install

LncNova is a thin Python launcher plus a container image. You need Python ≥ 3.9 and one of
Docker, Apptainer or Singularity.

```bash
pip install lncnova                                        # the `lncnova` command (launcher only)
```

The PyPI package does not contain the tools or databases. They live in the container image,
which you build once from the `Dockerfile` in the source repository:

```bash
git clone <this-repository> && cd LncNova
docker build -t lncnova:0.1.0 --build-arg THREADS=16 .    # downloads and bakes in all data (~20 GB image)
lncnova check                                              # verifies every tool and database in the image
```

The image build downloads GENCODE v49, builds a HISAT2 index, and fetches LNCipedia 5.2, miRBase,
the CPAT human models, Enrichr GO-BP/KEGG gene sets and RNADisease v4.0. It needs a good
connection and roughly an hour. `docker/README.md` in the repository explains running the image
directly, on HPC with Apptainer, or offline.

## Run

```bash
lncnova template > samples.tsv        # edit the paths
lncnova run -s samples.tsv -o results -t 16
```

`samples.tsv` (TSV or CSV), one row per sample:

| column | required | meaning |
|--------|----------|---------|
| `sample` | yes | unique sample name |
| `fastq_1` | yes | read 1 (`.fastq.gz`) |
| `fastq_2` | no | read 2 for paired-end data |
| `condition` | no | `case` or `control` (change with `--case/--control`) |
| `batch` | no | added to the differential-expression design |

Paths are bind-mounted into the container automatically. Re-running resumes: finished per-sample
steps are skipped, and merge/quantification are recomputed if the sample set changes.

### Options

| Option | Default | Meaning |
|--------|---------|---------|
| `--strandedness` | `auto` | inferred from the alignments (`rf`, `fr`, `unstranded`) |
| `--classes` | `u,x,i` | gffcompare class codes treated as novel |
| `--min-length`, `--min-exons` | 200, 2 | structural filters (`--min-exons 1` keeps single-exon transcripts) |
| `--min-tpm`, `--min-samples` | 0.5, auto | expression filter (auto: 1 sample for single mode, otherwise the smallest group size, ≥ 2) |
| `--coding-tools`, `--consensus` | `cpc2,cpat`, `all` | non-coding only if every tool agrees; `any` is permissive |
| `--keep-lncipedia` | off | keep transcripts that already exist in LNCipedia |
| `--padj`, `--lfc` | 0.05, 1 | differential-expression thresholds |
| `--mirna-max-energy` | -20 | IntaRNA interaction-energy cutoff (kcal/mol) |
| `--max-mrna-per-lncrna` | 50 | co-expressed mRNAs per lncRNA tested for shared miRNAs |
| `--no-mirna`, `--no-disease` | | skip those layers |

## Output

```
results/
├── lncnova_report.xlsx        summary + every table below
├── 06_novel_lncrna/           novel_lncrna.gtf, novel_lncrna.fa, novel_lncrna_transcripts.tsv
├── 05_quant/                  transcript_tpm.csv, gene_counts.csv
├── 07_de/                     DESeq2-style tables for all, novel, known-lncRNA and coding genes (cohort)
├── 08_targets/                cis_targets.csv, trans_targets.csv (cohort)
├── 09_mirna/                  IntaRNA hits and ceRNA triads
├── 10_disease_precedent.csv
└── 01_trim … 04_merge/        per-step files and logs
```

## How the calls are made

- **Novel:** gffcompare class `u` (intergenic), `x` (antisense) or `i` (intronic) against GENCODE v49,
  length ≥ 200 nt, ≥ 2 exons, no overlap with a same-strand LNCipedia 5.2 exon, and TPM ≥ 0.5 in enough samples.
- **Non-coding:** CPC2 and CPAT must both call the transcript non-coding (CPAT human cutoff 0.364).
- **Counts:** known genes are counted against GENCODE and novel genes against the final novel set.
  StringTie's merged annotation relabels many known genes as `MSTRG`, so it cannot supply both.
- **Co-expression:** Pearson on log-normalized counts after removing group means, Benjamini-Hochberg
  adjusted, `|r| ≥ 0.6`. It is skipped with fewer than 6 samples.
- **miRNA sites:** IntaRNA, seed of 7 bp enforced, energy ≤ cutoff. lncRNAs are tested as whole
  transcripts; mRNAs by their 3′UTR, and only against miRNAs that bind a lncRNA.
- **Disease precedent:** each cis or trans target gene is looked up in RNADisease v4.0.

## Limits

- Human GRCh38 / GENCODE v49 only; paired- or single-end FASTQ.
- Differential expression uses PyDESeq2, which is close to but not identical to R DESeq2.
- HISAT2 uses a plain genome index plus the known splice sites at alignment time. The
  splice-graph index needs far more memory than most machines have.
- Co-expression and ceRNA results are hypothesis-generating and are only convincing with roughly
  10 or more samples. The ceRNA and disease layers are computational associations, not evidence
  for a specific lncRNA. Validate candidates experimentally.
- Tested end to end on subsampled data (4 and 6 samples, 2 million read pairs each). Runtime and
  results on a full-depth cohort have not been benchmarked.

## Development

```bash
pip install -e ".[test]" && pytest
python -m build            # wheel and sdist in dist/
```

## License

LncNova's code is MIT-licensed (see `LICENSE.txt`). The image bundles third-party tools
and data under their own terms: HISAT2, Subread and CPAT are GPL; gffcompare is Artistic 2.0;
IntaRNA is MIT but uses ViennaRNA, whose license should be checked before commercial
redistribution of the image; GENCODE, LNCipedia, miRBase, Enrichr and RNADisease data follow
their providers' terms.
