Add genome module documentation: introduce genome statistics, feature detection, and comparative analysis tools; migrate genome-level analysis features from the sequence module.

Author: imjiaoyuan

docs/en/index.md

@@ -36,6 +36,7 @@ jsrc <module> <subcommand> --help
 | module | description |
 |---|---|
 | `seq` | Sequence extraction, renaming, translation, QC, k-mer, window |
+| `genome` | Genome statistics, feature detection, comparative/evolutionary analysis |
 | `plot` | Gene/exon/chromosome/domain and utility visualizations |
 | `analyze` | Phylogeny, motif, consensus, SNP/INDEL, QC |
 | `gs` | Genomic selection dataset build/split/train workflows |
@@ -51,6 +52,7 @@ jsrc <module> <subcommand> --help
 ## Modules
 
 - [Sequence Module](./module-seq.md)
+- [Genome Module](./module-genome.md)
 - [Analyze Module](./module-analyze.md)
 - [Plot Module](./module-plot.md)
 - [GS Module](./module-gs.md)

docs/en/module-genome.md

@@ -0,0 +1,203 @@
+# jsrc genome
+
+Genome-level analysis tools. `jsrc genome` covers genome statistics, feature detection, comparative analysis, evolutionary analysis, and annotation utilities.
+
+## cpg
+
+CpG islands are genomic regions with high CpG dinucleotide density and GC content, typically located near gene promoters and associated with gene regulation. This command predicts CpG islands using the classic sliding window method (Gardiner-Garden & Frommer 1987).
+
+A window is considered a candidate CpG island if GC% ≥ 50% and observed/expected CpG ratio ≥ 0.6. Adjacent qualifying windows are merged, and regions shorter than `--min-len` are filtered out.
+
+```bash
+jsrc genome cpg -fa genome.fa
+jsrc genome cpg -fa genome.fa --window 200 --min-len 200 --min-gc 55 --json
+```
+
+## orf
+
+ORF finding is the first step in gene prediction for unannotated sequences. Given a FASTA file, this command scans for open reading frames from ATG to stop codons, reporting coordinates, length, frame, and translated protein sequence.
+
+By default, only frame 1 is searched, reporting ORFs ≥ 100 nt. Use `--all-frames` to search all three forward frames, `--min-len` to adjust length threshold, and `--top N` to keep only the longest N ORFs per sequence.
+
+```bash
+jsrc genome orf -fa genome.fa --min-len 300 --all-frames
+jsrc genome orf -fa contigs.fa --top 5 --json
+```
+
+## promoter
+
+When studying gene regulation, you often need to examine promoter regions. For example, to check if several genes have a transcription factor binding site in their upstream 2kb region, you first need to extract these regions in batch.
+
+This command does exactly that: given a genome, GFF, and gene ID list, it automatically calculates coordinates and extracts upstream/downstream sequences.
+
+Example input (`genes.txt`):
+
+```txt
+GENE001
+GENE002
+GENE003
+```
+
+By default, it extracts 2000bp upstream and 0bp downstream. You can adjust with `-up` and `-down`.
+
+```bash
+jsrc genome promoter -fa genome.fa -gff genes.gff -ids genes.txt -o promoters.fa -up 1500 -down 500
+```
+
+If your GFF uses a different feature label than `gene` (e.g., `mRNA`), set `-feature` accordingly.
+
+## repeat
+
+Find simple sequence repeats (SSR / microsatellites / STR) in genomic sequences. Scans for tandem repeat motifs within specified unit length range and minimum repeat count.
+
+Default settings search for mono- to hexa-nucleotide repeats (unit length 1–6) with at least 3 repetitions. Commonly used for microsatellite marker development and repeat annotation.
+
+```bash
+jsrc genome repeat -fa genome.fa
+jsrc genome repeat -fa genome.fa --min-unit 2 --max-unit 4 --min-reps 5 --json
+```
+
+## island
+
+Genomic island detection identifies regions with deviant GC content that may indicate horizontal gene transfer, pathogenicity islands, or other foreign DNA. This command uses a sliding window approach to scan for GC content anomalies.
+
+Windows exceeding the GC threshold are marked as candidate islands. Adjacent candidate windows are merged into a single island. Use `--min-length` to filter out short regions.
+
+```bash
+jsrc genome island -fa genome.fa
+jsrc genome island -fa genome.fa --window 5000 --step 1000 --gc-threshold 0.6 --min-length 10000 --json
+```
+
+## palindrome
+
+Palindromic sequences (inverted repeats) are often associated with transposons, restriction enzyme recognition sites, and hairpin structures. This command finds palindromic structures in sequences.
+
+A palindrome consists of two reverse-complementary arms separated by a gap. You can set arm length range (`--min-arm`, `--max-arm`) and maximum gap length (`--max-gap`).
+
+```bash
+jsrc genome palindrome -fa genome.fa
+jsrc genome palindrome -fa genome.fa --min-arm 8 --max-arm 30 --max-gap 20 --top 100 --json
+```
+
+## stats
+
+Basic genome assembly quality metrics. This command calculates N50/L50, total length, sequence count, gap statistics, and GC content.
+
+N50 is the weighted median length—sort all sequences by length, sum from longest to shortest, and N50 is the length when cumulative sum reaches half the total. L50 is the number of sequences needed to reach N50. Higher values indicate better assembly contiguity.
+
+```bash
+jsrc genome stats -fa assembly.fa
+jsrc genome stats -fa assembly.fa --json
+```
+
+## gc-skew
+
+Cumulative GC skew analysis is used to predict replication origin (oriC) and terminus (ter) in bacterial genomes. GC skew is defined as (G-C)/(G+C), typically showing a distinct minimum near the replication origin.
+
+This command calculates sliding window cumulative GC skew, outputting position and cumulative skew for each window. Visualize with plotting tools to find the curve's lowest point.
+
+```bash
+jsrc genome gc-skew -fa genome.fa
+jsrc genome gc-skew -fa genome.fa --window 10000 --step 5000 --json
+```
+
+## window
+
+Sliding window GC and AT skew analysis. This command calculates GC content, GC skew, and AT skew for each window at specified window size and step.
+
+GC skew = (G-C)/(G+C), AT skew = (A-T)/(A+T). These metrics reveal local compositional features and replication bias.
+
+```bash
+jsrc genome window -fa genome.fa
+jsrc genome window -fa genome.fa --window 50000 --step 10000 --json
+```
+
+## codon
+
+Codon usage frequency and RSCU (Relative Synonymous Codon Usage) analysis. Input CDS sequences in FASTA format to count codon occurrences and calculate RSCU.
+
+RSCU = observed frequency / expected frequency (assuming uniform synonymous codon usage). RSCU > 1 indicates higher-than-average usage, < 1 indicates lower.
+
+Optional features:
+- `--cai`: Calculate CAI (Codon Adaptation Index), requires reference gene set (typically highly expressed genes)
+- `--enc`: Calculate ENC (Effective Number of Codons), range 20-61, lower values indicate stronger codon bias
+
+```bash
+jsrc genome codon -fa cds.fa --top 20
+jsrc genome codon -fa cds.fa --cai highly_expressed.fa --enc --json
+```
+
+## distance
+
+Calculate pairwise genetic distances in multiple sequence alignments. Supports four distance models:
+
+- **hamming**: Hamming distance, number of differing sites
+- **p**: p-distance, proportion of differing sites
+- **jc**: Jukes-Cantor distance, corrects for multiple substitutions
+- **k2p**: Kimura 2-parameter distance, distinguishes transitions and transversions
+
+Input must be aligned sequences (equal length).
+
+```bash
+jsrc genome distance -fa aligned.fa --method p
+jsrc genome distance -fa aligned.fa --method k2p --json
+```
+
+## kaks
+
+Calculate Ka/Ks ratio for two aligned CDS sequences. Ka is the nonsynonymous substitution rate, Ks is the synonymous substitution rate, and Ka/Ks (ω) reflects selection pressure:
+
+- ω < 1: purifying selection (negative selection)
+- ω = 1: neutral evolution
+- ω > 1: positive selection
+
+Input must be exactly two aligned CDS sequences with length divisible by 3.
+
+```bash
+jsrc genome kaks -fa aligned_cds.fa
+jsrc genome kaks -fa aligned_cds.fa --json
+```
+
+## density
+
+Calculate gene or feature density distribution along the genome. This command reads genome FASTA and GFF annotation, counting features in sliding windows and calculating density (features per kb) and coverage.
+
+Use `--feature-type` to specify which feature type to count (e.g., gene, CDS, exon). Useful for visualizing uneven gene distribution.
+
+```bash
+jsrc genome density -fa genome.fa -gff genes.gff
+jsrc genome density -fa genome.fa -gff genes.gff --feature-type CDS --window 20000 --step 10000 --json
+```
+
+## motif-scan
+
+Scan genomes for DNA motifs. Supports IUPAC degenerate base codes (R=A/G, Y=C/T, N=any, etc.) and allows mismatches.
+
+Commonly used for transcription factor binding site prediction, restriction enzyme site finding, etc.
+
+```bash
+jsrc genome motif-scan -fa genome.fa -m TATAAA
+jsrc genome motif-scan -fa genome.fa -m GCRWTG --mismatch 1 --top 50 --json
+```
+
+## ani
+
+k-mer-based Average Nucleotide Identity (ANI) calculation. ANI is a standard metric for measuring genome similarity, commonly used for species delineation (ANI > 95% typically indicates same species).
+
+This command uses Jaccard similarity (shared k-mers / total k-mers) as an ANI approximation, requiring no sequence alignment and running fast.
+
+```bash
+jsrc genome ani -fa genome1.fa genome2.fa
+jsrc genome ani -fa genome1.fa genome2.fa -k 21 --json
+```
+
+## compare
+
+Genome comparison and difference statistics based on global alignment. Uses the edlib library for efficient global alignment, calculating edit distance, identity, and difference sites.
+
+**Note**: This command requires edlib: `pip install edlib`
+
+```bash
+jsrc genome compare -fa genome1.fa genome2.fa
+jsrc genome compare -fa genome1.fa genome2.fa --json
+```

docs/en/module-seq.md

@@ -1,6 +1,8 @@
 # jsrc seq
 
-Sequence manipulation is the most routine task in bioinformatics. `jsrc seq` covers extraction, renaming, translation, promoter extraction, QC, codon usage, k-mer profiling, Entrez fetching, restriction digestion, sliding-window analysis, ORF finding, CpG island prediction, primer analysis, tandem repeat finding, sequence complexity, and MSA entropy.
+Sequence manipulation is the most routine task in bioinformatics. `jsrc seq` covers extraction, renaming, translation, QC, k-mer profiling, Entrez fetching, restriction digestion, sequence complexity, and MSA entropy.
+
+Genome-level analysis features (such as ORF finding, CpG island prediction, promoter extraction, tandem repeats, codon usage, sliding-window analysis, etc.) have been moved to the [genome module](./module-genome.md).
 
 ## extract
 
@@ -54,28 +56,6 @@ When doing cross-species comparison or looking for protein domains, what you act
 jsrc seq translate -fa genome.fa -gff genes.gff -id ID -o proteins.fa
 ```
 
-## promoter
-
-Studying gene regulation often means looking at promoter regions. Say you want to check whether a transcription factor binding site exists 2kb upstream of a set of genes — you need to extract those regions in bulk first.
-
-This command does exactly that. Given genome, GFF, and gene IDs, it automatically calculates coordinates and extracts flanking sequences.
-
-Example input (`genes.txt`):
-
-```txt
-GENE001
-GENE002
-GENE003
-```
-
-Default is 2000bp upstream, 0bp downstream. Adjust with `-up` and `-down`.
-
-```bash
-jsrc seq promoter -fa genome.fa -gff genes.gff -ids genes.txt -o promoters.fa -up 1500 -down 500
-```
-
-If your GFF uses a different feature label (some datasets use `mRNA` instead of `gene`), set `-feature` accordingly.
-
 ## qc
 
 I always check data quality before diving into large-scale analysis. This command is for a quick health check — it won't replace FastQC's deep reports, but it's fast and gives you the essentials in one go.
@@ -87,16 +67,6 @@ jsrc seq qc -fa assembly.fa
 jsrc seq qc -fq r1.fq.gz r2.fq.gz -gs 520000000 --json
 ```
 
-## codon
-
-Codon bias is an interesting angle. Different species, and even different genes within the same genome, display distinct codon usage patterns — shaped by selection pressure, mutation bias, and tRNA abundance.
-
-This command calculates codon usage frequencies from CDS FASTA. It counts each codon and computes RSCU (Relative Synonymous Codon Usage). Shows the top 20 by default; increase with `--top`.
-
-```bash
-jsrc seq codon -fa cds.fa --top 20 --json
-```
-
 ## kmer
 
 k-mer is one of the most fundamental yet powerful features in sequence analysis. It's useful for assessing sequence complexity, generating genomic fingerprints, and quickly comparing similarity between samples.
@@ -130,60 +100,6 @@ jsrc seq digest -fa plasmid.fa -e EcoRI,HindIII --circular --json
 jsrc seq digest -fa seq.fa -e EcoRI --min-size 50
 ```
 
-## window
-
-Sliding-window analysis solves a common problem: global GC content is an average, but genomic GC distribution is uneven — high near CpG islands, low near centromeres. This command looks at these variations window by window.
-
-Specify window size and step, and the program slides along the sequence, computing GC content and GC skew ((G-C)/(G+C)) in each window. By default it uses the longest sequence in the FASTA; target a specific sequence with `-id`. `--head` limits output to the first N windows.
-
-```bash
-jsrc seq window -fa genome.fa -w 100000 -s 20000 --head 20
-jsrc seq window -fa genome.fa -id chr1 -w 1000 -s 200 --json
-```
-
-## orf
-
-ORF finding is the first step in gene prediction from unannotated sequences. Given a FASTA file, this command scans for ATG-to-stop codon open reading frames and reports their coordinates, length, frame, and translated protein sequence.
-
-By default it searches frame 1 only and reports ORFs ≥ 100 nt. Use `--all-frames` to search all three forward frames, and `--min-len` to adjust the length cutoff. `--top N` keeps only the N longest ORFs per sequence.
-
-```bash
-jsrc seq orf -fa genome.fa --min-len 300 --all-frames
-jsrc seq orf -fa contigs.fa --top 5 --json
-```
-
-## cpg
-
-CpG islands are genomic regions with elevated CpG dinucleotide density and GC content, typically found near gene promoters and associated with gene regulation. This command predicts them using the classical sliding-window approach (Gardiner-Garden & Frommer 1987).
-
-A window is considered a CpG island candidate if GC% ≥ 50% and observed/expected CpG ratio ≥ 0.6. Adjacent qualifying windows are merged; merged regions shorter than `--min-len` are dropped.
-
-```bash
-jsrc seq cpg -fa genome.fa
-jsrc seq cpg -fa genome.fa --window 200 --min-len 200 --min-gc 55 --json
-```
-
-## primer
-
-Evaluates primer sequences for Tm, GC content, GC clamp, and hairpin risk. Two Tm models are provided: Wallace rule (fast estimate for short oligos) and the nearest-neighbor thermodynamic model (SantaLucia 1998, more accurate).
-
-Input is a FASTA file where each record is one primer sequence. `--conc` sets the primer concentration for the nearest-neighbor calculation (default 250 nM).
-
-```bash
-jsrc seq primer -fa primers.fa
-jsrc seq primer -fa primers.fa --conc 500 --json
-```
-
-## repeat
-
-Finds simple sequence repeats (SSRs / microsatellites / STRs) in genomic sequences. Scans for tandemly repeated motifs of specified unit length range with a minimum number of repeat copies.
-
-Default settings find mono- through hexanucleotide repeats (unit length 1–6) with at least 3 copies. Useful for microsatellite marker development and repeat annotation.
-
-```bash
-jsrc seq repeat -fa genome.fa
-jsrc seq repeat -fa genome.fa --min-unit 2 --max-unit 4 --min-reps 5 --json
-```
 
 ## complexity
 

docs/zh/index.md

@@ -36,6 +36,7 @@ jsrc <module> <subcommand> --help
 | 模块 | 说明 |
 |---|---|
 | `seq` | 序列提取、重命名、翻译、QC、k-mer、滑窗分析 |
+| `genome` | 基因组统计、特征检测、比较分析、进化分析 |
 | `plot` | 基因/外显子/染色体/结构域等可视化 |
 | `analyze` | 系统发育、motif、一致序列、SNP/INDEL、QC |
 | `gs` | 基因组选择数据构建、划分与训练流程 |
@@ -51,6 +52,7 @@ jsrc <module> <subcommand> --help
 ## 模块文档
 
 - [序列模块](./module-seq.md)
+- [基因组模块](./module-genome.md)
 - [分析模块](./module-analyze.md)
 - [绘图模块](./module-plot.md)
 - [GS 模块](./module-gs.md)