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.

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

For local development:

python -m pip install -e ".[dev]"
pytest

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:

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.

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

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.

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

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.

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

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:

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:

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.

Scientific scope

GenoToPep candidate generation does not establish:

• that a candidate is a true coding gene;
• that a candidate is an AMP;
• that a candidate is non-toxic or non-hemolytic;
• that a peptide naturally exists in the sample;
• that a peptide is biologically active.

Those questions require downstream computational evidence and, where appropriate, experimental validation.

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.