obigrep(1)

NAME

obigrep – filters sequence files according to numerous conditions

SYNOPSIS

obigrep [--attribute | -a KEY=VALUE]... [--compress | -Z] [--debug] [--definition|-D PATTERN]...
[--ecopcr] [--embl] [--fasta-output] [--fastq-output] [--genbank] [--has-attribute | -A KEY]... [--help | -h | -?] [--id-list FILENAME] [--identifier | -I PATTERN]... [--ignore-taxon | -i TAXID]... [--input-OBI-header] [--input-json-header] [--inverse-match | -v] [--max-count|-C COUNT] [--max-cpu INT] [--max-length | -L LENGTH] [--min-count | -c COUNT] [--min-length | -l LENGTH] [--no-order] [--no-progressbar] [--out | -o FILENAME] [--output-OBI-header | -O] [--output-json-header] [--paired-mode forward|reverse|and|or|andnot|xor] [--paired-with FILENAME] [--predicate|-p EXPRESSION]... [--require-rank RANK_NAME]... [--restrict-to-taxon | -r TAXID]... [--save-discarded FILENAME] [--sequence|-s PATTERN]... [--solexa] [--taxdump | -t DIRECTORY] [--workers | -w INT] [FILENAMES]

DESCRIPTION

The obigrep command is somewhat analogous to the standard Unix grep command. It selects a subset of sequence records from a sequence file. A sequence record is a complex object consisting of an identifier, a set of attributes (a key, defined by its name, associated with a value), a definition, and the sequence itself. Instead of working text line by text line like the standard Unix tool, obigrep selection is done sequence record by sequence record. A large number of options allow you to refine the selection on any element of the sequence. obigrep allows you to specify multiple conditions simultaneously (which take on the value TRUE or FALSE) and only those sequence records which meet all conditions (all conditions are TRUE) are selected. obigrep is able to work on two paired read files. The selection criteria apply to one or the other of the readings in each pair depending on the mode chosen (--paired-mode option). In all cases the selection is applied in the same way to both files, thus maintaining their consistency.

OPTIONS

  General options

Helpful options

--help, -h
    Display a friendly help message.

--no-progressbar

Managing parallel execution

--max-cpu
    OBITools V4 are able to run in parallel on all the CPU cores available on the computer. It is sometime required to limit the computation to a smaller number of cores. That option specify the maximum number of cores that the OBITools command can use. This behaviour can also be set up using the OBIMAXCPU environment variable.

--workers, -w

OBITools debuging related options

--debug

  Input format options

The OBITools are centered around the [FASTA] (https://en.wikipedia.org/wiki/FASTA_format) and [FASTQ] (https://en.wikipedia.org/wiki/FASTQ_format) formats. These formats are automaticaly recognized when data are read both from files, and from standard input (stdin). Other formats (genbank, EMBL, ecopcr) are also automatically identified when data are read from files, but for stdin input, input format must be indicated using one of the following options.

  Output format options

--fasta-output

--fastq-output

--output-OBI-header, -O

--output-json-header

--out FILENAME, -o
    OBITools, as all standard UNIX tools, print their results to the standard output (stdout). To save them, stdout must be redirected to a file. That option allows to specify explicitely an output file to the command. This is especially useful when OBITools are processing paired files. In that later case, the indicated output file names is modified by adding to it the _R1 (forward file) and _R2 (reverse file) suffix just before the extensions (e.g. sequence.fasta becomes sequence_R1.fasta and sequence_R2.fasta). If that option is not specified and paired files are processed only the forward data are ouputed to the stdout.

--compress, -Z
    The ouput is compressed following the gzip (https://en.wikipedia.org/wiki/Gzip) format.

  Paired reads options

--paired-with FILENAME

--paired-mode forward|reverse|and|or|andnot|xor

  Taxonomy related options

--taxdump | -t DIRECTORY

--ignore-taxon | -i TAXID

--require-rank RANK_NAME

--restrict-to-taxon | -r TAXID

  Filtering options

--has-attribute | -A KEY...

--id-list FILENAME

--identifier | -I PATTERN

--max-count | -C COUNT
    only sequences reprensenting no more than COUNT reads will be selected. That option rely on the count attribute. If the count attribute is not defined for a sequence record, it is assumed equal to 1.

--min-count | -c COUNT
    only sequences reprensenting at least COUNT reads will be selected. That option rely on the count attribute. If the count attribute is not defined for a sequence record, it is assumed equal to 1.

--max-length | -L LENGTH
    Keeps sequence records whose sequence length is equal or shorter than LENGTH.

--min-length | -l LENGTH
    Keeps sequence records whose sequence length is equal or longer than LENGTH.

--predicate|-p EXPRESSION

--sequence|-s PATTERN
    Regular expression pattern to be tested against the sequence itself. The pattern is case insensitive. A complete description of the regular pattern grammar is available here (https://yourbasic.org/golang/regexp-cheat-sheet/#cheat-sheet).

--inverse-match | -v

--save-discarded FILENAME

ENVIRONMENT

OBICPUMAX

EXAMPLES

•   Filtering sequence file to keep only barcodes between 8 and 130 bp.

        obigrep -l 8 -L 130 data_SPER01.fasta > data_goodLength_SPER01.fasta

•   Filtering reads without anbiguity base code in its sequence.

        obigrep -s '^[acgt]+$' data_SPER01.fasta > data_onlyACGT_SPER01.fasta

•   Filtering paired files for keeping only pairs of read without ambiguity.

        obigrep  -s '^[acgt]+$' \
                 --paired-mode and --paired-with wolf_R.fastq.gz \
                 --out wolf_good.fastq \
                 wolf_F.fastq.gz

    That command produces two files wolf_good_R1.fastq and wolf_good_R1.fastq containing respectively the filtered forward and reverse reads.

SEE ALSO

obiannotate

HISTORY

BUGS

Submit bug reports online at: https://git.metabarcoding.org/obitools/obitools4/obitools4/-/issues

AUTHORS
Eric Coissac <eric.coissac@metabarcoding.org>.