Digestion

digestion.py

src/precisionprodb/digestion.py is a standalone, pure-Python protein digestion utility. It accepts one or more FASTA files, including gzip-compressed FASTA, or one sequence supplied directly on the command line. Results are written to standard output as TSV, peptide-only text, or FASTA.

Quick start

Run from the PrecisionProDB repository root:

# Digest one sequence
python src/precisionprodb/digestion.py --sequence AKRPQK -l 2

# Digest one or more FASTA files
python src/precisionprodb/digestion.py proteins.fa proteins2.fa.gz \
  --enzyme Trypsin --missed-cleavages 2 -l 6 -M 40

Exactly one input mode is required: provide --sequence or at least one positional FASTA file, but not both.

Unless overridden, the CLI uses Trypsin cleavage, allows two missed cleavages, keeps peptides between 6 and 40 residues, uses full specificity, considers both initiator-methionine forms, preserves the distinction between I and L, and writes TSV output.

Input

Argument	Description
FASTA ...	One or more FASTA files. Plain text and .gz files are supported.
--sequence SEQUENCE	Digest one sequence directly instead of reading FASTA.

FASTA headers are retained for output formatting. The TSV protein ID is the first whitespace-delimited token after the leading >; for direct sequence input it is sequence.

Cleavage rules

The default preset is Trypsin. A preset can be selected with --enzyme; --enzyme2 adds a second rule. When two rules are supplied, their cleavage boundaries are merged and duplicate boundaries count once.

Preset	Position	Cleavage sites	Anti-cleavage sites
Cut_everywhere	n	A-Z	—
Trypsin	c	KR	P
Trypsin/P	c	KR	—
Lys_C	c	K	P
Lys_N	n	K	—
Arg_C	c	R	P
Asp_N	n	DN	—
CNBr	c	M	—
Asp-N_ambic	c	DE	—
PepsinA	c	FL	—
Chymotrypsin	c	FWYL	P
No_cut	c	@	@

For a preset or manual rule, c places the boundary after the cleavage site and n places it before the site. A candidate boundary is suppressed when the immediately following residue is in the anti-cleavage set. Enzyme names are case-insensitive.

Manual rules

The following options override the first enzyme preset:

Argument	Description
-c SITES, --cleavage_sites SITES	Residues at which to cleave, for example KR.
-a SITES, --anti_cleavage_sites SITES	Residues that suppress a cleavage boundary, for example P. Use -a "" to disable the preset anti-cleavage rule.
-p {c,n}, --cleavage_position {c,n}	Cleave after (c) or before (n) the site.

Manual -c/-a/-p values apply only to --enzyme. The second enzyme uses its own preset.

Custom regular expressions

--cleavage-regex and --cleavage-regex2 define custom zero-width cleavage boundaries. They may be used with lookarounds, for example:

python src/precisionprodb/digestion.py --sequence AKRPQK \
  --cleavage-regex '(?<=[KR])(?!P)' -l 1

python src/precisionprodb/digestion.py --sequence AAENLYFQG \
  --cleavage-regex '(?<=ENLYFQ)(?=[GS])' -l 1

The regex must match a boundary without consuming residues. The first regex cannot be combined with -c, -a, or -p. --cleavage-regex2 overrides --enzyme2 and can be used without --enzyme2.

Specificity and missed cleavages

--specificity controls which peptide termini must be cleavage boundaries:

Value	Behavior
full	Both termini are specific. This is the default.
n-specific	The N terminus is specific; the C terminus may be truncated.
c-specific	The C terminus is specific; the N terminus may be truncated.
semi	The de-duplicated union of n-specific and c-specific peptides.

--missed-cleavages N (or -L N) sets the maximum number of cleavage boundaries that may be skipped when combining adjacent fully cleaved fragments. The default is 2. The value is clamped to zero or greater.

--min_peptide_length N (-l, default 6) and --max_peptide_length N (-M, default 40) filter the core digested peptide. Terminal attachments are not included in this length calculation.

Cut_everywhere is special: it emits every contiguous peptide in the requested length range, ignores --missed-cleavages, and does not use the specificity mode.

Sequence handling

• Input sequences are converted to uppercase and leading/trailing * characters are removed.
• --isobaric changes I to L before digestion. Without it, I and L remain distinct.
• An internal * is a hard breakpoint. No output peptide contains *, but the marker still occupies a parent-sequence position for TSV coordinates.
• --initiator-methionine accepts retain, remove, or both (default). both digests the sequence with its N-terminal M and the form with that M removed; shared occurrences are emitted once.
• --nterm-attach STRING and --cterm-attach STRING prepend or append fixed strings after digestion. They do not affect cleavage, missed-cleavage counting, length filtering, or coordinates.

Output formats

All output is written to standard output. Use shell redirection when a file is needed.

TSV

python src/precisionprodb/digestion.py proteins.fa --output-format tsv

Each line contains four tab-separated fields, with no header:

protein_id    peptide    start    end

start and end are 1-based inclusive coordinates in the original protein sequence. Occurrences are retained, so the same peptide sequence may appear more than once.

Example for a sequence containing a stop marker:

python src/precisionprodb/digestion.py --sequence 'AK*RPQK' \
  --output-format tsv -l 1

sequence    AK      1    2
sequence    RPQK    4    7

Peptide-only output

python src/precisionprodb/digestion.py proteins.fa --output-format peptide

One peptide is written per line. Peptides are de-duplicated globally across all input records and files, keeping their first occurrence.

FASTA output

python src/precisionprodb/digestion.py proteins.fa --output-format fasta

Peptides are de-duplicated in the same way as peptide-only output. By default, headers use {protein_id}_{index}:

>sp|P12345_1
AK
>sp|P12345_2
RPQK

--header-template is used only for FASTA output. Supported placeholders are {protein_id}, {index}, and {header}:

python src/precisionprodb/digestion.py proteins.fa --output-format fasta \
  --header-template '{protein_id}|pep{index}'

Python API

The higher-level functions accept the same digestion settings as the CLI:

Function	Return value
iter_digest_sequence_occurrences(sequence, ...)	Iterator of (peptide, start, end) occurrences.
digest_sequence_occurrences(sequence, ...)	List of (peptide, start, end) occurrences.
digest_sequence(sequence, ...)	List of peptide strings.
iter_digest_records(file_path, ...)	FASTA headers paired with materialized occurrence lists.
iter_digest_records_streaming(file_path, ...)	FASTA headers paired with streaming occurrence iterators.
write_digest_results(results, handle, ...)	Writes TSV, peptide-only, or FASTA output to a file-like object.

For example:

from precisionprodb.digestion import digest_sequence, digest_sequence_occurrences

peptides = digest_sequence("AKRPQK", min_len=2)
# ['AK', 'RPQK', 'AKRPQK']

occurrences = digest_sequence_occurrences("AKRPQK", min_len=2)
# [('AK', 1, 2), ('RPQK', 3, 6), ('AKRPQK', 1, 6)]

The lower-level digest() and digest_with_missed_cleavages() helpers accept explicit sites, pos, and no values. They return peptide strings and handle internal stop markers, but do not provide the higher-level CLI features such as enzyme-name resolution, I/L normalization, initiator-methionine variants, attachments, or output formatting.