Metadata-Version: 2.5
Name: genotopep
Version: 0.1.0.1
Summary: Reproducible peptide candidate generation from assemblies and predicted proteins
Project-URL: Homepage, https://github.com/ljunwon1114/GenoToPep
Project-URL: Repository, https://github.com/ljunwon1114/GenoToPep
Project-URL: Issues, https://github.com/ljunwon1114/GenoToPep/issues
Author: Jun Won Lee
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: bioinformatics,genomics,metagenomics,peptides
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: pyrodigal<4,>=3.6
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# GenoToPep

GenoToPep is a reproducible command-line package for generating peptide candidate universes from metagenome assemblies or predicted-protein FASTA files.

Candidate generation is deliberately separated from coding validation, AMP prediction, toxicity/hemolysis prediction, detection of naturally occurring peptides, and experimental activity.

## Installation

Python 3.10 or newer is required.

```bash
python -m pip install genotopep
genotopep --version
genotopep --help
```

## Input routes

- Nucleotide assembly: `--assembly sample.fna[.gz]`
- Predicted proteins: `--proteins sample.faa[.gz]`
- Predicted proteins with genomic provenance: `--proteins sample.faa --gff sample.gff3[.gz]`

`--assembly` and `--proteins` are mutually exclusive. GFF3 is optional and is only valid with FAA input.

### FNA ORF calling

Assembly input is translated with Pyrodigal metagenome mode. The default short-ORF threshold is:

```text
min_protein_aa = 10
min_gene_nt = 10 * 3 + 3 = 33 nt
closed = false
max_overlap = 0
```

Pyrodigal still applies its coding and start-site models: `33 nt` is an eligible minimum, not a guarantee that every open reading frame of that length is emitted. Contig-edge partial calls are retained and marked in the ORF provenance output. Terminal stop symbols are not written to protein FASTA.

## Generation strategies

### Intact

Emits the complete supplied or Pyrodigal-called protein when its length is within the inclusive range.

```bash
genotopep generate intact \
  --assembly assembly.fna.gz \
  --min-length 10 --max-length 100 \
  --output results/assembly-intact
```

```bash
genotopep generate intact \
  --proteins proteins.faa.gz \
  --min-length 10 --max-length 100 \
  --output results/proteins-intact
```

### Windows

Emits contiguous subsequences for every inclusive length, using stride 1 by default.

```bash
genotopep generate windows \
  --assembly assembly.fna.gz \
  --min-length 10 --max-length 50 --stride 1 \
  --output results/assembly-windows
```

```bash
genotopep generate windows \
  --proteins proteins.faa.gz \
  --min-length 10 --max-length 50 --stride 1 \
  --output results/proteins-windows
```

### Cleavage

Builds a boundary union from selected deterministic rules, creates elementary fragments, and emits every length-valid joining of adjacent fragments.

```bash
genotopep generate cleavage \
  --assembly assembly.fna.gz \
  --cleavage-mode all \
  --min-length 10 --max-length 100 \
  --output results/assembly-cleavage
```

```bash
genotopep generate cleavage \
  --proteins proteins.faa.gz \
  --cleavage-mode trypsin cnbr \
  --min-length 10 --max-length 100 \
  --output results/proteins-cleavage
```

Supported lowercase modes:

- `trypsin`: cut after K/R unless followed by P
- `chymotrypsin`: cut after F/Y unless followed by P; cut after W unless followed by M/P
- `cnbr`: boundary after M; product chemistry and methionine oxidation are not modeled
- `all`: union of trypsin, chymotrypsin, and CNBr boundaries

Omitting `--cleavage-mode` resolves to `all`. Multiple individual modes are accepted. `all` cannot be combined with an individual mode. These rules enumerate deterministic sequence candidates; they do not predict in vivo peptide release.

## Outputs

For input `sample.proteins.faa.gz` and strategy `windows`, the main outputs are:

```text
sample.proteins.windows.peptides.faa.gz
sample.proteins.windows.peptide_occurrences.tsv.gz
sample.proteins.windows.exclusions.tsv.gz
sample.proteins.command.txt
sample.proteins.run-config.yaml
sample.proteins.run.log
sample.proteins.manifest.json
sample.proteins.checksums.sha256
```

FNA runs additionally write:

```text
sample.orfs.faa.gz
sample.orfs.fna.gz
sample.orfs.gff3.gz
sample.orfs.tsv.gz
```

The peptide FASTA contains one record per exact amino-acid sequence. Its ID is `sha256:<digest>`. The occurrence TSV retains every source, protein-relative coordinate, genomic coordinate when available, strategy, window, and cleavage occurrence.

Only the canonical 20 amino acids are admitted to predictor-facing peptide FASTA. Candidates containing other symbols are written to the exclusions table with a reason.

Outputs are written through an incomplete sibling directory and renamed only after successful completion. An existing output directory is never overwritten. `--resume` accepts only an identical, complete run after configuration, input fingerprint, and output checksum verification; it does not resume a partially written stage.

## GFF3 mapping scope

The current mapper resolves a protein FASTA identifier against GFF3 `ID`, `protein_id`, `locus_tag`, or `Parent`. Missing and ambiguous mappings are errors. Single-CDS bacterial proteins are supported; multipart spliced CDS models are not yet supported.

FAA-only runs provide protein-relative coordinates and record that genomic coordinates are unavailable. Their short-ORF recall remains limited by the upstream annotation or gene-calling workflow.

## License

Copyright (C) 2026 Jun Won Lee.

GenoToPep is licensed under GPL-3.0-or-later. Pyrodigal is a GPL-3.0-or-later dependency. License compatibility should be reviewed before public redistribution; this statement is not legal advice.
