PIMENTO

A PrIMEr infereNce TOolkit to facilitate large-scale calling of metabarcoding amplicon sequence variants.

How PIMENTO works

PIMENTO’s employs a dual primer inference strategy, which are:

• Standard primer search: based on fuzzy regex search queries to a library of curated standard primer sequences.
• Primer cutoff prediction: based on the identification of the primer cutoff point from analysis of patterns of base-conservation at the beginning (and end, for single-end libraries) of reads. Consensus sequences are then generated as inferred primers using the predicted cutoff.

PIMENTO also implements an "are there primers?" function to predict the presence of primers in sequencing reads in case no standard primer was found. This method is helpful in cases where it isn't known whether primer sequences are still present in the reads, and checking manually would not be trivial, i.e. for large-scale analysis pipelines.

How to install

PIMENTO is available on PyPi. To install it from PyPi with pip just run:

pip install mi-pimento

PIMENTO is also available on bioconda and can be installed like this with conda/mamba:

conda install -c bioconda mi-pimento

How to run

You can run either PIMENTO strategy with a single command. The tool will look for primers on either end, so both strategies will work on paired-end, single-end, or merged paired-end sequencing reads (though you would have to run it twice unmerged paired-end sequencing reads, one for each end).

pimento --help
Usage: pimento [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  are_there_primers     Predict whether primers are present in the input reads
  auto                  Perform the primer cutoff strategy for primer
                        inference
  choose_primer_cutoff  Choose the optimal primer cutoff point.
  find_cutoffs          Find potential cutoffs using a BCV output.
  gen_bcv               Generate the base-conservation vector(s) (BCV)
  std                   Perform the standard primer strategy for primer
                        inference

Standard primer matching

To run the standard primer strategy:

pimento std -i <fastq/fastq.gz> -p <primers_dir> -o <output_prefix> --merged

Inputs

-i <fastq/fastq.gz>: the input FASTQ reads file.

-p <primers_dir>: the path to the standard primers library to be used, with the default being PIMENTO's library. You can use your own library, or extend PIMENTO's. If using a different library than the default, make sure the primer FASTA files have this format:

>341F
CCTACGGGNGGCWGCAG
>338F
ACTCCTACGGGAGGCAGCA
>805R
GACTACHVGGGTATCTAATCC
>785R
CTACCAGGGTATCTAATCC

Where forward strand primers have the character F as the final character, and vice versa R for reverse strand primers.

-o <output_prefix>: the prefix to be used on output files.

-m <minimum_primer_threshold>: this optional parameter sets the minimum proportion of reads a standard primer has to be present in to be considered in inference. Default value of 0.60 (60%) of reads.

-l <std_primer_read_prefix_length>: this optional parameter sets the read prefix window length that is read for inferring the presence of standard primers. Default value of 50 bases.

-c <max_read_count>: this optional parameter sets the maximum number of reads used to infer the presence of standard primers, to increase speed. Default value of 300,000 reads.

-e <std_primer_error_rate>: this optional parameter sets the maximum error rate allowed for standard primers to be considered a match. A mismatch for an ambiguous base is counted as an error only if it doesn't match any of its possible bases. The number of bases always rounds up, e.g. primer lengths of 15 and 20 with an error rate of 0.1 will be a maximum of 2 errors for both primers. Default value of 0.1 (10%) of a primer's length in bases.

--greedy_primer_length_flag [longest/shortest]: this optional parameter determines which primer to select when multiple primers are viable candidates for a strand (i.e., when their proportions differ by ≤ 0.03). Options are longest to greedily select the longer primer, or shortest to select the shorter primer. Default value is longest.

--merged: this optional flag should be used when dealing with either merged paired-end reads, or single-end reads, so that PIMENTO can correctly identify reverse-orientation primers.

-t <threads>: this optional parameter allows you to specify the number of threads to be used for the search. Default of 1.

Greedy primer length selection (--greedy_primer_length_flag)

When multiple primers of the same strand match at a high enough threshold, PIMENTO must decide which to select. All potential primers are iterated through, and a final choice is made based on two factors: the proportion of matching reads and the primer length.

1. Read proportion — If a primer's read proportion is higher than another by more than 0.03, it is selected regardless of primer length. For example, for two primers A and B with read proportions of 0.70 and 0.90 respectively, primer B is chosen. This ensures that the most commonly found primer always wins when the difference is significant.
2. Greedy length tiebreaker — When read proportions are close between two primers (within 0.03 in either direction), the --greedy_primer_length_flag setting breaks the tie:
   • longest (default): select the longer primer.
   • shortest: select the shorter primer.

For example, for two primers A and B with read proportions of 0.92 and 0.90 respectively, and primer lengths of 22 and 25 bases respectively, primer B will be chosen if the the flag is set to longest, while primer A will be chosen if the flag is set to shortest.

Outputs

<output_prefix>_std_primers.fasta: FASTA file containing the best found single or pairs of primers. Empty if none were found.

<output_prefix>_std_primer_out.txt: Text file containing the read proportions of the best found primers.

all_standard_primer_proportions.txt: Text file logging all the read proportions for every single searched primer.

Primer cutoff prediction

To run the primer cutoff strategy:

pimento auto -i <fastq/fastq.gz> -st [FR/F/R] -o <output_prefix>

NB: Running pimento auto executes the three subcommands generate_bcv, find_cutoffs, choose_primer_cutoff sequentially. You can therefore run each step of this workflow individually if you wish.

Inputs

-i <fastq/fastq.gz>: the input FASTQ reads file.

-st [FR/F/R]: the selection of strands to perform primer inference for - F for forward, R for reverse, FR for both.

-c <max_read_count>: this optional parameter sets the maximum number of reads used to infer the presence of standard primers, to increase speed. Default value of 300,000 reads.

-o <output_prefix>: the prefix to be used on output files.

Outputs

<output_prefix>_auto_primers.fasta: FASTA file containing the inferred primer sequences using the predicted optimal cutoffs.

Are there primers?

To run the "are there primers?" utility:

pimento are_there_primers -i <fastq/fastq.gz> -o <output_prefix>

Inputs

-i <fastq/fastq.gz>: the input FASTQ reads file.

-o <output_prefix>: the prefix to be used on output files.

Outputs

<output_prefix>_general_primer_out.txt: Text file containing a 1 or 0 depending on if a primer was found on the forward strand (first line) and the reverse strand (second line).

Licensing

All of the source code making up PIMENTO in this repository is licensed under the terms of the Apache 2.0 license. The standard primer library files and the unit test data files are licensed under the terms of the CC0 1.0 Universal (CC0 1.0) licence.

Citations

If you use PIMENTO in your work, please cite:

PIMENTO: A primer inference toolkit to facilitate large-scale calling of amplicon sequence variants

Christian Atallah, Lorna Richardson, Martin Beracochea, Robert D. Finn

GigaScience 2026; doi: https://doi.org/10.1093/gigascience/giag083