PRINSEQ-LITE(1)

📦
version 0.20.4 · 3 versions
, in ubuntu jammy, ubuntu noble

PRINSEQ-LITE 💅✨

okay bestie, welcome to the prinseq-lite manual page — this is PRINSEQ, which stands for PReprocessing and INformation of SEQuence data. yes, it's an acronym, yes it's a mouthful, we love her anyway 🫶

✨ VERSION ✨

PRINSEQ-lite 0.20.4 🌸

📜 SYNOPSIS 📜

like, here's how you actually call her:

perl prinseq-lite.pl [-h] [-help] [-version] [-man] [-verbose] [-fastq
input_fastq_file] [-fasta input_fasta_file] [-fastq2 input_fastq_file_2]
[-fasta2 input_fasta_file_2] [-qual input_quality_file] [-min_len
int_value] [-max_len int_value] [-range_len ranges] [-min_gc int_value]
[-max_gc int_value] [-range_gc ranges] [-min_qual_score int_value]
[-max_qual_score int_value] [-min_qual_mean int_value] [-max_qual_mean
int_value] [-ns_max_p int_value] [-ns_max_n int_value] [-noniupac]
[-seq_num int_value] [-derep int_value] [-derep_min int_value]
[-lc_method method_name] [-lc_threshold int_value] [-trim_to_len
int_value] [-trim_left int_value] [-trim_right int_value] [-trim_left_p
int_value] [-trim_right_p int_value] [-trim_ns_left int_value]
[-trim_ns_right int_value] [-trim_tail_left int_value] [-trim_tail_right
int_value] [-trim_qual_left int_value] [-trim_qual_right int_value]
[-trim_qual_type type] [-trim_qual_rule rule] [-trim_qual_window
int_value] [-trim_qual_step int_value] [-seq_case case] [-dna_rna type]
[-line_width int_value] [-rm_header] [-seq_id id_string] [-out_format
int_value] [-out_good filename_prefix] [-out_bad filename_prefix]
[-phred64] [-stats_info] [-stats_len] [-stats_dinuc] [-stats_tag]
[-stats_dupl] [-stats_ns] [-stats_assembly] [-stats_all] [-aa]
[-graph_data file] [-graph_stats string] [-qual_noscale]
[-no_qual_header] [-exact_only] [-log file] [-custom_params string]
[-params file] [-seq_id_mappings file]

it's giving a lot but every single one of those flags gets explained below, no cap 💖

🦋 DESCRIPTION 🦋

PRINSEQ is here to help you preprocess your genomic or metagenomic sequence data in FASTA (and QUAL) or FASTQ format. 🧬

and the tea? the lite version needs zero non-core perl modules to do its processing. no dependencies, no drama, just vibes ✨

💅 OPTIONS 💅

🎀 housekeeping first 🎀

  • -help | -h — prints the help message. that's it, that's the whole job. everything else you passed gets ignored. 🙈
  • -man — prints the full documentation. also ignores every other argument you threw at her. 💁‍♀️
  • -version — prints the program version. yep, other arguments? ignored. 👑
  • -verbose — prints status and info messages while processing, so you actually know what's going on instead of staring at a blank terminal. 🔥

✨💖 INPUT OPTIONS 💖✨

  • -fastq <file> — input file in FASTQ format holding the sequence and quality data. use stdin instead of a file name to read from STDIN (-fasta stdin). this is lowkey iconic for processing compressed files through Unix pipes. 🍓
  • -fasta <file> — input file in FASTA format holding the sequence data. use stdin instead of a file name to read from STDIN (-fastq stdin). again: compressed files + Unix pipes = a moment. 🌸
  • -qual <file> — input file in QUAL format that contains the quality data.
  • -fastq2 <file> — paired-end data only, bestie. input file in FASTQ format containing the sequence and quality data. the sequence identifiers for two matching paired-end sequences in separate files can be marked by /1 and /2, or _L and _R, or _left and _right, or they must have the exact same identifier in both input files. the input sequences must be sorted by their sequence identifiers. singletons are allowed in the input files. 🧚
  • -fasta2 <file> — paired-end data only. input file in FASTA format containing the sequence data. same rules as above: matching pairs can be marked by /1 and /2, or _L and _R, or _left and _right, or they must have the exact same identifier in both files. sequences must be sorted by their sequence identifiers. singletons are allowed. 🦋
  • -params <file> — input file in text format that contains PRINSEQ parameters. every parameter goes on a new line, and arguments should be separated by spaces or tabs. comments? start a line with the # sign. 💬 can be combined with command line parameters — and heads up, parameters specified on the command line will overwrite the arguments in the file (if any). 💅
  • -si13 — this option was replaced by option -phred64. rip to her, she's legacy 💀
  • -phred64 — quality data in the FASTQ file is in Phred+64 format (http://en.wikipedia.org/wiki/FASTQ_format#Encoding). not required for Illumina 1.8+, Sanger, Roche/454, Ion Torrent, or PacBio data. ✨
  • -aa — input is amino acid (protein) sequences instead of nucleic acid (DNA or RNA) sequences. allowed amino acid characters:

ABCDEFGHIKLMNOPQRSTUVWYZXabcdefghiklmmopqrstuvwyzx*-

and allowed nucleic acid characters:

ACGTURYKMSWBDHVNXacgturykmswbdhvnx-

the following options get ignored for -aa: stats_dinuc,stats_tag,stats_ns,dna_rna 🙈

🌈💖 OUTPUT OPTIONS 💖🌈

  • -out_format <integer> — to change the output format, pick one of these. if you don't define it, the output format will just match the input format, easy.
    1. 1 (FASTA only)
    2. 2 (FASTA and QUAL)
    3. 3 (FASTQ)
    4. 4 (FASTQ and FASTA)
    5. 5 (FASTQ, FASTA and QUAL)
  • -out_good <string> — by default, output files are created in the same directory as the input file containing the sequence data, with an extra "_prinseq_good_XXXX" in their name (where XXXX is replaced by random characters so you don't overwrite your previous files, we're thoughtful like that 💅). to change the output filename and location, just specify the filename with this option. the file extension gets added automatically (either .fasta, .qual, or .fastq). for paired-end data, filenames additionally contain "_1", "_1_singletons", "_2", and "_2_singletons" before the file extension. use "-out_good null" to stop the program from generating output file(s) for data passing all filters. use "-out_good stdout" to write data passing all filters to STDOUT (only for FASTA or FASTQ output files). 🫶

example: use "file_passed" to generate the output file file_passed.fasta in the current directory ✨

  • -out_bad <string> — by default, output files are created in the same directory as the input file containing the sequence data, with an extra "_prinseq_bad_XXXX" in their name (where XXXX is replaced by random characters to prevent overwriting previous files). to change the output filename and location, specify the filename with this option. the file extension is added automatically (either .fasta, .qual, or .fastq). for paired-end data, filenames additionally contain "_1" and "_2" before the file extension. use "-out_bad null" to prevent the program from generating output file(s) for data not passing any filter. use "-out_bad stdout" to write data not passing any filter to STDOUT (only for FASTA or FASTQ output files). 💀

example: use "file_filtered" to generate the output file file_filtered.fasta in the current directory 🌸

example: "-out_good stdout -out_bad null" will write data passing filters to STDOUT, and data not passing any filter will be ignored 👑

  • -log <file> — log file to keep track of parameters, errors, etc. the log file name is optional — if you don't give one, the log file name will be "inputname.log". if the log file already exists, new content will be added to the file. 📝
  • -graph_data <file> — file that contains the necessary information to generate graphs similar to the ones in the web version. the file name is optional — if you don't give one, the file name will be "inputname.gd". if the file already exists, new content will overwrite the file. use "-out_good null -out_bad null" to prevent generating any additional outputs. (see below for more options related to the graph data. 👀)

the graph data can be used as input for the prinseq-graphs.pl file to generate the PNG graph files or an HTML report file. if you have trouble installing the required prinseq-graphs.pl modules, or you just wanna see an output example report, upload the graph data file at: http://edwards.sdsu.edu/prinseq/ → choose "Get Report" 🎀

  • -graph_stats <string> — use this option to select what statistics should be calculated and included in the graph_data file. super useful if, say, you don't need sequence complexity info, because that one requires a lot of computation. requires graph_data to be specified. default is all selected. ✨

allowed options are (separate multiple by comma with no spaces):

  • ld (Length distribution)
  • gc (GC content distribution)
  • qd (Base quality distribution)
  • ns (Occurrence of N)
  • pt (Poly-A/T tails)
  • ts (Tag sequence check)
  • aq (Assembly quality measure)
  • de (Sequence duplication - exact only)
  • da (Sequence duplication - exact + 5'/3')
  • sc (Sequence complexity)
  • dn (Dinucleotide odds ratios, includes the PCA plots)

example use: -graph_stats ld,gc,qd,de 💖

  • -qual_noscale — use this option if all your sequences are shorter than 100bp, because then they don't need quality data scaled to 100 data points in the graph. by default, quality scores of sequences shorter than 100bp or longer than 100bp are fit to 100 data points. (to retrieve this info and calculate the graph data would otherwise require parsing the data two times or storing all the quality data in memory.) 🧠
  • -no_qual_header — to reduce the file size, this option generates an empty header line for the quality data in FASTQ files. instead of +header, only the + sign gets output. the header of the sequence data is left unchanged. this option applies to FASTQ output files only. 🍓
  • -exact_only — use this option to check for exact (forward and reverse) duplicates only when generating the graph data. this keeps memory requirements low for large input files and it's faster, slay. this option is automatically applied when using -derep options 1 and/or 4 only. specify option -derep 1 or -derep 4 if you do not want to apply both at the same time. 🌈
💖 part 1 done, bestie — the rest of the flags are coming right up, don't go anywhere 🫶
  • -seq_id_mappings <file> — a lil text file holding the old and the new identifiers (the new one being whatever you set with -seq_id), saved for later so you can look stuff up. super handy if, say, you renamed a sequence and now need to track it down by its new ID. The filename is optional bestie — if you don't give one, it just calls itself inputname_prinseq_good.ids (and heads up: only the good sequences get renamed, so only those show up). If a file with that same name is already sitting there, the new content will straight-up overwrite the old file, no warning. The file has one identifier pair per line, separated by tabs (old-tab-new). Requires option -seq_id or it does nothing. 💅

✨ FILTER OPTIONS ✨

  • -min_len <integer> — filters out any sequence shorter than min_len. bye bye shorties 🦋
  • -max_len <integer> — filters out any sequence longer than max_len.
  • -range_len <string> — filter by a length range. Multiple ranges go in separated by commas, no spaces allowed (the comma-spacing is a vibe check, don't fail it). Example:
-range_len 50-100,250-300
  • -min_gc <integer> — filters sequences whose GC content is below min_gc.
  • -max_gc <integer> — filters sequences whose GC content is above max_gc.
  • -range_gc <string> — filter by GC content range. Same deal: multiple ranges, comma-separated, no spaces. Example:
-range_gc 50-60,75-90
  • -min_qual_score <integer> — filters any sequence that has at least one quality score below min_qual_score. one bad base and it's out, no cap 😭
  • -max_qual_score <integer> — filters any sequence that has at least one quality score above max_qual_score.
  • -min_qual_mean <integer> — filters sequences whose quality score mean is below min_qual_mean.
  • -max_qual_mean <integer> — filters sequences whose quality score mean is above max_qual_mean.
  • -ns_max_p <integer> — filters sequences with more than ns_max_p percentage of Ns.
  • -ns_max_n <integer> — filters sequences with more than ns_max_n Ns (absolute count, not a percentage, iykyk).
  • -noniupac — filters out any sequence with characters other than A, C, G, T or N. strict queen behavior 👑
  • -seq_num <integer> — only keeps the first seq_num number of sequences — and yes, only the ones that passed all the other filters.
  • -derep <integer> — the type(s) of duplicates to filter. Allowed values are 1, 2, 3, 4 and 5. Want multiple at once? Use integers glued together (e.g. 124 to use type 1, 2 and 4) — order genuinely does not matter. Heads up on the math: option 2 and 3 will set 1, and option 5 will set 4, because those are subsets of the other option.
    • 1 (exact duplicate), 2 (5' duplicate), 3 (3' duplicate), 4 (reverse complement exact duplicate), 5 (reverse complement 5'/3' duplicate)
  • -derep_min <integer> — how many duplicates are allowed to stick around. So if you wanna yeet sequences that occur more than x times, you pass x+1 as the -derep_min value. Example bestie: to remove sequences that occur more than 5 times, you'd specify -derep_min 6. This one only works in combination with -derep 1 and/or 4 (forward and/or reverse exact duplicates). [default : 2]
  • -lc_method <string> — which method to use for filtering low complexity sequences. Current options are "dust" and "entropy". Use "-lc_method dust" to calculate the complexity with the dust method.
  • -lc_threshold <integer> — the threshold value (between 0 and 100) used to filter sequences by sequence complexity. The dust method treats it as a maximum allowed score, and the entropy method treats it as a minimum allowed value. 👀 different direction, same number
  • -custom_params <string> — for specifying additional filters. The current set of possible rules is limited and has to follow the specs below. The custom parameters have to be wrapped in quotes (either ' or ").

Separate parameter values with a space, and separate new parameter sets with a semicolon (;). Each parameter is defined by two values:

  1. the pattern (any combination of the letters "ACGTN"),
  2. the number of repeats or percentage of occurrence.

Percentage values are a number followed by the %-sign (no space between them, ever). If there's no %-sign, it's assumed the number you gave specifies the number of repeats of the pattern.

Examples: "AAT 10" (filters out sequences containing AATAATAATAATAATAATAATAATAATAAT anywhere in the sequence), "T 70%" (filters out sequences with more than 70% Ts in the sequence), "A 15" (filters out sequences containing AAAAAAAAAAAAAAA anywhere in the sequence), "AAT 10;T 70%;A 15" (apply all three filters)

🎀 TRIM OPTIONS 🎀

  • -trim_to_len <integer> — trims everything from the 3'-end so the sequence ends up exactly this length.
  • -trim_left <integer> — trims the sequence at the 5'-end by trim_left positions.
  • -trim_right <integer> — trims the sequence at the 3'-end by trim_right positions.
  • -trim_left_p <integer> — trims the sequence at the 5'-end by trim_left_p percentage of the read length. The trim length gets rounded towards the lower integer (e.g. 143.6 rounds to 143 positions). Use an integer between 1 and 100 for the percentage value.
  • -trim_right_p <integer> — trims the sequence at the 3'-end by trim_right_p percentage of the read length. Same rounding tea: rounded towards the lower integer (e.g. 143.6 → 143 positions). Use an integer between 1 and 100 for the percentage value.
  • -trim_tail_left <integer> — trims a poly-A/T tail with a minimum length of trim_tail_left at the 5'-end.
  • -trim_tail_right <integer> — trims a poly-A/T tail with a minimum length of trim_tail_right at the 3'-end.
  • -trim_ns_left <integer> — trims a poly-N tail with a minimum length of trim_ns_left at the 5'-end.
  • -trim_ns_right <integer> — trims a poly-N tail with a minimum length of trim_ns_right at the 3'-end.
  • -trim_qual_left <integer> — trims the sequence by quality score from the 5'-end, using this threshold score.
  • -trim_qual_right <integer> — trims the sequence by quality score from the 3'-end, using this threshold score.
  • -trim_qual_type <string> — the type of quality score calculation to use. Allowed options are min, mean, max and sum. [default: min]
  • -trim_qual_rule <string> — the rule used to compare the quality score against the calculated value. Allowed options are lt (less than), gt (greater than) and et (equal to). [default: lt]
  • -trim_qual_window <integer> — the sliding window size used to calculate the quality score by type. If you want it to stop at the first base that fails the rule you defined, use a window size of 1. [default: 1]
  • -trim_qual_step <integer> — the step size used to move the sliding window. To glide the window over all quality scores without missing any, the step size should be less than or equal to the window size. [default: 1]

🌈 REFORMAT OPTIONS 🌈

  • -seq_case <string> — changes sequence character case to upper or lower. Allowed options are "upper" and "lower". Use this to remove soft-masking from your sequences ✨
  • -dna_rna <string> — converts the sequence between DNA and RNA. Allowed options are "dna" (convert from RNA to DNA) and "rna" (convert from DNA to RNA).
  • -line_width <integer> — sequence characters per line. Use 0 if you want each sequence on a single line. Use 80 for line breaks every 80 characters. Note bestie: this only applies to FASTA output files, since FASTQ files store sequences without additional line breaks. [default: 60]
  • -rm_header — removes the sequence header. That means everything after the sequence identifier — and the identifier itself stays unchanged. ✂️
  • -seq_id <string> — renames the sequence identifier. A counter is added to each identifier to keep it unique. Use -seq_id_mappings to generate a file with the old and new identifiers for later reference.

Example: "mySeq_10" will generate the IDs (in FASTA format) >mySeq_101, >mySeq_102, >mySeq_103, ...

👑 SUMMARY STATISTIC OPTIONS 👑

The summary statistic values get written to STDOUT in this form: "parameter_name statistic_name value" (without the quotes). So like, "stats_info reads 10000" or "stats_len max 500". Only one statistic per line, and the values are separated by tabs.

⚠️ If you specify any statistic option, no other output will be generated. So if you actually want to preprocess data, do not specify a statistics option. it's giving all-or-nothing 💀
  • -stats_info — outputs basic info like number of reads (reads) and total bases (bases).
  • -stats_len — outputs minimum (min), maximum (max), range (range), mean (mean), standard deviation (stddev), mode (mode) and mode value (modeval), and median (median) for read length. the whole squad fr fr 📊
  • -stats_dinuc — outputs the dinucleotide odds ratio for AA/TT (aatt), AC/GT (acgt), AG/CT (agct), AT (at), CA/TG (catg), CC/GG (ccgg), CG (cg), GA/TC (gatc), GC (gc) and TA (ta).
  • -stats_tag — outputs the probability of a tag sequence at the 5'-end (prob5) and 3'-end (prob3) in percentage (0..100). Also provides the number of predefined MIDs (midnum) and the MID sequences (midseq, separated by comma, only provided if midnum > 0) that occur in more than 34/100 (approx. 3%) of the reads.
  • -stats_dupl — outputs the number of exact duplicates (exact), 5' duplicates (5), 3' duplicates (3), exact duplicates with reverse complements (exactrevcom) and 5'/3' duplicates with reverse complements (revcomp), plus the total number of duplicates (total). The maximum number of duplicates shows up under the value name with an additional "maxd" tacked on (e.g. exactmaxd or 5maxd).
  • -stats_ns — outputs the number of reads with ambiguous base N (seqswithn), the maximum number of Ns per read (maxn) and the maximum percentage of Ns per read (maxp). Note: the maxn and maxp values are not necessarily from the same sequence 👀
  • -stats_assembly — drops the N50, N90, etc. contig sizes on you. ✨ And what even is an Nxx contig size, bestie? It's a weighted median, okay: picture every contig sorted from biggest to smallest, and it's the length of the smallest contig C where the cumulative length from that top contig all the way down to C is at least xx% of the total length (aka the sum of all contig lengths). Math but make it slay 💅
  • -stats_all — literally all the summary statistics. Every single one. No crumbs left. 👑

🔥 ORDER OF PROCESSING 🔥

Okay so here's the tea, bestie — the options don't just run in whatever order your chaotic little heart wants. They get processed in this exact order, and you're gonna want to know it:

seq_num, trim_left, trim_right, trim_left_p, trim_right_p,
trim_qual_left, trim_qual_right, trim_tail_left,
trim_tail_right, trim_ns_left, trim_ns_right, trim_to_len,
min_len, max_len, range_len, min_qual_score, max_qual_score,
min_qual_mean, max_qual_mean, min_gc, max_gc, range_gc,
ns_max_p, ns_max_n, noniupac, lc_method, derep, seq_id,
seq_case, dna_rna, out_format
Pro tip from your girl: if you're stacking a bunch of these, the order above is the order they hit. Chain responsibly. 🫶

💖 AUTHOR 💖

Robert SCHMIEDER, <rschmieder_at_gmail_dot_com> — the icon, the legend, the main character who made all of this. 👑

😭 BUGS 😭

Found a bug? Not the vibe, but also please tell him. Email <rschmieder_at_gmail_dot_com> or hit up http://sourceforge.net/tracker/?group_id=315449 so he can make PRINSEQ better. Reporting bugs is self-care, fr fr. 🦋

Copyright (C) 2010-2012 Robert SCHMIEDER

📜 LICENSE 📜

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

And that's the whole page, bestie!! 🎀 Big shoutout to perl v5.32.0 and the date stamp 2020-11-09 riding along at the bottom — that's the source and the moment this manual got its little glow-up. Go forth and sequence, you gorgeous genius. 💅✨💜
📦 where this page comes from