Metadata-Version: 2.4
Name: jsrc
Version: 0.4.1
Summary: Bioinformatics CLI toolkit: sequence, genome, plotting, analysis and GRN utilities
Author-email: Jiaoyuan <imjiaoyuan@gmail.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# jsrc

Python library for bioinformatics and scientific computing.

## Installation

Install from PyPI:
```bash
pip install jsrc
```

From source (development):
```bash
git clone https://github.com/imjiaoyuan/jsrc.git
cd jsrc
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Run `jsrc --help` to get started.

For detailed usage, see the [Documentation](docs/en/index.md). 中文文档请参阅 [文档](docs/zh/index.md)。

## Quick Start

```bash
jsrc --help
jsrc <module> --help
jsrc <module> <subcommand> --help
```

Examples:

```bash
jsrc seq --help
jsrc analyze phylo --help
jsrc genome stats --help
```

> Paths like `test/...` in the examples below are illustrative — substitute your own input files.

## Module Overview

| module | focus | typical use |
|---|---|---|
| `seq` | Sequence extraction, translation, k-mer, sliding window | `jsrc seq extract ...` |
| `genome` | Genome statistics, feature detection, comparative/evolutionary analysis | `jsrc genome stats ...` |
| `plot` | Gene/exon/chromosome/domain and other plots | `jsrc plot gene ...` |
| `analyze` | Phylogeny, motif, consensus, SNP/INDEL, QC | `jsrc analyze phylo ...` |
| `grn` | GRN conversion, centrality, build packaging, local serve | `jsrc grn build ...` |

## Error Output Conventions

- Input and validation failures are reported in unified format: `Error: <message>`.
- Missing files, invalid parameters, and incompatible inputs follow the same style across subcommands.
- Use `--help` on the target module/subcommand first when argument combinations are unclear.

## A Glance of jsrc's Functions

**grn module**

Generate and launch a 1000-gene random network viewer:

```bash
jsrc grn net2json -i test/grn/network.tsv -o test/grn/grn.json
jsrc grn anno2json -i test/grn/annotation.tsv -o test/grn/annotation.json
jsrc grn build -d test/grn/public -g test/grn/grn.json -n test/grn/annotation.json -z test/grn/grn-viewer.zip -a -t 200
jsrc grn serve -d test/grn/public -g test/grn/public/json/grn.json -n test/grn/public/json/annotation.json -p 8000 -a -t 200
```

![](assets/grn.jpg)

Centrality ranking (top 5):

```bash
jsrc grn centrality -i test/grn/network.tsv --top 5
```

| rank | node | in_degree | out_degree | total_degree |
|------|------|-----------|------------|-------------|
| 1 | GENE_0504 | 24.14 | 34.97 | 59.12 |
| 2 | GENE_0785 | 26.37 | 29.51 | 55.88 |
| 3 | GENE_0165 | 42.81 | 12.21 | 55.01 |
| 4 | GENE_0394 | 14.82 | 33.04 | 47.86 |
| 5 | GENE_0427 | 36.50 | 10.60 | 47.10 |

---

**genome module**

```bash
jsrc genome stats -fa genome.fa
jsrc genome cpg -fa genome.fa --window 200 --min-len 500
jsrc genome ani -fa1 genome1.fa -fa2 genome2.fa -k 21
jsrc genome codon -fa cds.fa --cai reference.fa --enc
```

Genome statistics: N50 2,450,000 bp, L50 3, GC 45.2%, 15 gaps.

CpG islands: 42 islands found, longest 1,250 bp.

ANI: 96.8% (Jaccard 0.85, Mash distance 0.032).

Codon usage: CAI 0.78, ENC 52.3, top codon CTG (RSCU 1.85).

---

**seq module**

```bash
jsrc seq extract -fa test/seq/test.fa -gff test/seq/test.gff -ids test/seq/ids.txt -o test/seq/extracted.fa -feature gene -match ID
```

Extract sequences by gene ID from FASTA+GFF, rename via CSV map, run QC stats, k-mer counting, and sliding-window analysis.

QC: 2 sequences, 268 bp total, GC 56.7%, N50 160.

k-mer (k=3): top `ATC` (40), `TCG` (40), `CGA` (39).

---

**analyze module**

```bash
jsrc analyze msa_consensus -fa test/analyze/aln.fa --json
jsrc analyze snpindel -fa test/analyze/aln.fa
jsrc analyze motif -fa test/analyze/aln.fa -o test/analyze/motif_out -minw 3 -maxw 5 -nmotifs 3
jsrc analyze phylo -fa test/analyze/aln.fa -o test/analyze/tree.nwk
```

- Consensus: `ATGCTAGCTAGCTAGCTAGC`, mean conservation 0.983
- SNP: seq1 vs seq3 has 1 SNP (alignment score 19/20)
- Motif (top): `GCT` (12), `CTA` (12), `TAG` (12)
- Phylogeny: `(seq1:0.00000,seq2:0.00000,seq3:0.05000)Inner1:0.00000;`

---

