pepmatch 1.17.2

Search tool for peptides and epitopes within a proteome, while considering potential residue substitutions.

---

Author: Daniel Marrama

PEPMatch is a high-performance peptide search tool for finding short peptide sequences within a reference proteome. It handles three kinds of search out of the box: exact matches, mismatch (substitution) searches, and indel (insertion or deletion) matching. Powered by a Rust engine with Python bindings, it delivers sub-second search times across entire proteomes while maintaining a simple Python API.

Key Features

• Blazing Fast: Rust-powered search engine with automatic multi-core parallelization via Rayon. Search thousands of peptides against the entire human proteome in seconds.
• Unified Index Format: Single .pepidx binary format stores sequences, metadata, and k-mer index in one memory-mapped file. Preprocess once, search repeatedly.
• Versatile Searching: Exact matches, mismatch (substitution) searches, indel (insertion/deletion) matching, best match mode, and discontinuous epitope support.
• Counts-Only Mode: Get aggregate hit counts per peptide with O(unique queries) memory instead of O(hits) — built for massive query sets and dense reference matching.
• Simple API: Two classes — Preprocessor and Matcher — handle everything.
• Flexible I/O: Accepts queries from FASTA files, text files, or Python lists. Outputs to CSV, TSV, XLSX, JSON, or Polars DataFrame.

Requirements

• Python 3.10+
• Polars
• Biopython

Installation

pip install pepmatch

Quick Start

from pepmatch import Preprocessor, Matcher

# Preprocess a proteome (one-time step)
Preprocessor('human.fasta').preprocess(k=5)

# Search for exact matches
df = Matcher(
  query=['YLLDLHSYL', 'GLCTLVAML', 'FAKEPEPTIDE'],
  proteome_file='human.fasta',
  max_mismatches=0,
  k=5
).match()

print(df)

Preprocessing

Preprocessing builds a .pepidx index from your proteome FASTA file. This only needs to be done once per proteome and k-mer size. If a .pepidx file doesn't exist when you search, Matcher will create it automatically.

from pepmatch import Preprocessor

Preprocessor('human.fasta').preprocess(k=5)

CLI:

pepmatch-preprocess -p human.fasta -k 5

Flags

• -p, --proteome (Required): Path to the proteome FASTA file.
• -k, --kmer_size (Required): The k-mer size for indexing.
• -n, --proteome_name: Custom name for the proteome.
• -P, --preprocessed_files_path: Directory to save preprocessed files.

Matching

Exact Matching

from pepmatch import Matcher

df = Matcher(
  query='peptides.fasta',
  proteome_file='human.fasta',
  max_mismatches=0,
  k=5
).match()

Mismatch Searching

df = Matcher(
  query='neoepitopes.fasta',
  proteome_file='human.fasta',
  max_mismatches=3,
  k=3
).match()

Indel Searching

Search allowing insertions and deletions (indels) instead of substitution mismatches. The k-mer size is chosen automatically from your query lengths — no manual preprocessing needed.

df = Matcher(
  query='neoepitopes.fasta',
  proteome_file='human.fasta',
  max_indels=1
).match()

Each indel hit is annotated in an Indel Positions column with the edit type, residue, and 1-based query position — e.g. d: A[6] (deletion of A at query position 6) or i: X[6] (insertion of X before query position 6); an exact match reports []. In a repeat the exact position is ambiguous, so the inclusive range of all valid positions is reported, e.g. d: A[2,4]. When two edits fall at one site they are reported as a single chunk (d: YA[2]); when they fall apart they are reported separately (d: C[3], d: E[5]).

Supports max_indels=1 and max_indels=2; mutually exclusive with max_mismatches. At max_indels=2 the search is homogeneous — a match may use two insertions or two deletions, but never one of each (a mixed pair is a substitution, which mismatch search already covers). The two edits need not be adjacent.

Best Match

Automatically finds the optimal match for each peptide by trying different k-mer sizes and mismatch thresholds. No manual preprocessing required.

df = Matcher(
  query='peptides.fasta',
  proteome_file='human.fasta',
  best_match=True
).match()

Discontinuous Epitope Searching

Search for non-contiguous residues defined by their positions.

df = Matcher(
  query=[
    "R377, Q408, Q432, H433, F436",
    "S2760, V2763, E2773, D2805, T2819"
  ],
  proteome_file='sars-cov-2.fasta',
  max_mismatches=1
).match()

Mixed Queries

Linear peptides and discontinuous epitopes can be searched together.

df = Matcher(
  query=[
    'YLLDLHSYL',
    'R377, Q408, Q432, H433, F436',
    'GLCTLVAML',
  ],
  proteome_file='sars-cov-2.fasta',
  max_mismatches=0
).match()

Counts-Only Mode

For large query sets where you only need how many times each peptide matches — not the full per-hit table — set counts_only=True. PEPMatch tallies hits per (peptide, mismatch level) directly, without reconstructing matched sequences, pulling metadata, or building per-hit rows. Memory scales with the number of unique queries, not the number of hits, so it stays bounded even when matching is extremely dense (e.g. searching a proteome against itself).

df = Matcher(
  query='peptides.fasta',
  proteome_file='human.fasta',
  max_mismatches=2,
  k=3,
  counts_only=True
).match()

Returns columns Query ID, Query Sequence, Mismatches, and Count — one row per peptide per mismatch level that has at least one hit. Honors output_format; not supported with best_match.

Query Input Formats

• Python list: ['YLLDLHSYL', 'GLCTLVAML']
• FASTA file: .fasta, .fas, .fa, .fna, .ffn, .faa, .mpfa, .frn
• Text file: .txt with one peptide per line

CLI:

pepmatch-match -q peptides.fasta -p human.fasta -m 0 -k 5

Flags

• -q, --query (Required): Path to the query file.
• -p, --proteome_file (Required): Path to the proteome FASTA file.
• -m, --max_mismatches: Maximum mismatches allowed (default: 0).
• -i, --max_indels: Maximum indels allowed (default: 0). Supports 1 or 2, and mutually exclusive with -m. At 2, a match uses two insertions or two deletions, never one of each.
• -k, --kmer_size: K-mer size (default: 5).
• -P, --preprocessed_files_path: Directory containing preprocessed files.
• -b, --best_match: Enable best match mode.
• -f, --output_format: Output format — csv, tsv, xlsx, json (default: csv).
• -o, --output_name: Output file name (without extension).
• -v, --sequence_version: Disable sequence versioning on protein IDs.

Output Formats

• dataframe / polars (default for API): Returns a Polars DataFrame. dataframe is kept as a backward-compatible alias for polars.
• pandas: Returns a pandas DataFrame (converts the Polars result via .to_pandas()). Requires the optional extra: pip install 'pepmatch[pandas]'.
• csv (default for CLI): CSV file.
• tsv: Tab-separated file.
• xlsx: Excel file.
• json: JSON file.

# Polars (default) — same as output_format='dataframe'
df = Matcher(query='peptides.fasta', proteome_file='human.fasta', output_format='polars').match()

# pandas
df = Matcher(query='peptides.fasta', proteome_file='human.fasta', output_format='pandas').match()

Performance

Benchmarked searching ~2,000 peptides against the human proteome (~200,000 proteins):

Mode	Time
Exact match (k=5)	~0.06s
1 mismatch (k=3)	~1.5s
2 mismatches (k=3)	~1.9s
3 mismatches (k=3)	~3.7s

Citation

If you use PEPMatch in your research, please cite:

Marrama D, Chronister WD, Westernberg L, et al. PEPMatch: a tool to identify short peptide sequence matches in large sets of proteins. BMC Bioinformatics. 2023;24(1):485. Published 2023 Dec 18. doi:10.1186/s12859-023-05606-4