Package 'dbpq'

Description

Runs vsearch --usearch_global to match query sequences against a UNITE reference database, then extracts the Species Hypothesis (SH) identifier from each best hit. The SH name is the first |-delimited field in UNITE sequence identifiers (e.g. SH123456.09FU).

This function ports the logic of the nf-core/ampliseq add_sh_to_taxonomy.py script into R, using vsearch directly instead of requiring external lookup tables.

Usage

add_sh_to_taxonomy(
  query_fasta,
  unite_db,
  vsearchpath = find_vsearch(),
  id = 0.97,
  maxaccepts = 1,
  maxrejects = 32,
  nproc = 1,
  top_hits_only = TRUE,
  keep_temporary_files = FALSE,
  verbose = FALSE
)

Arguments

Value

A data.frame with columns:

• query: Query sequence identifier.

• sh_name: Species Hypothesis name extracted from the best database hit (e.g. SH123456.09FU), or NA if no hit was found.

• target: Full identifier of the matched database sequence.

• pct_id: Percent identity of the match.

• aln_len: Alignment length.

• mismatches: Number of mismatches.

• e_value: E-value of the match.

• is_ambiguous: Logical; TRUE if multiple hits with the same top identity disagree on the SH name.

Author(s)

Adrien Taudière

See Also

download_unite_db(), is_vsearch_installed(), find_vsearch()

Examples

## Not run: 
# Download a UNITE database first
unite_file <- download_unite_db(
  version = "10.0",
  taxonomic_format = "sintax",
  taxon_group = "fungi"
)

# Annotate ASVs with SH names
sh_res <- add_sh_to_taxonomy(
  query_fasta = "asvs.fasta",
  unite_db = unite_file,
  id = 0.97
)
head(sh_res)

# Check for ambiguous assignments
sh_res[sh_res$is_ambiguous, ]

## End(Not run)

Description

Count lines (sequences if fasta file) matching a pattern. Accepts gzip files. May not work on Windows.

Usage

count_pattern_db(file, pattern = ">")

Arguments

Value

An integer, the number of matching lines.

Author(s)

Adrien Taudière

See Also

filter_db(), count_seq_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
count_pattern_db(db, "Amanita")

Description

Counts the number of sequences in a FASTA file by counting header lines (lines starting with >). Accepts gzip files.

Usage

count_seq_db(file)

Arguments

Value

An integer, the number of sequences.

Author(s)

Adrien Taudière

See Also

count_pattern_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
count_seq_db(db)

Description

Scans a taxonomy table for common problematic values such as NA-like strings, placeholder labels ("unclassified", "unknown", etc.), and empty QIIME-style rank prefixes. The input can be a phyloseq object or a FASTA reference database file.

Returns a tibble summarising, for each pattern found, how many matches occur in each taxonomic rank.

Usage

count_unwanted_tax(
  x,
  patterns = unwanted_tax_patterns_default(),
  tax_format = "auto"
)

Arguments

Details

The default patterns are:

"^[Nn][Aa][Nn]?$"

NaN, nan, NA, na

"^[Nn]/[Aa]$"

N/A, n/a

"^[Nn]one$"

None, none

"^$"

empty string

"^\\s+$"

whitespace only

"[Uu]nclassified"

unclassified, Unclassified, xxx_unclassified

"[Uu]nknown"

unknown, Unknown, xxx_unknown

"[Uu]nidentified"

unidentified, Unidentified

"[Uu]ncultured"

uncultured, Uncultured

"[Ii]ncertae[_\\s]?[Ss]edis"

incertae_sedis, Incertae sedis

"^[Mm]etagenome$"

metagenome, Metagenome

"^[Ee]nvironmental"

environmental, Environmental

"^[kpcofgs]__$"

empty QIIME-style rank prefixes

Value

A tibble with columns:

pattern

The regular expression that matched.

description

A human-readable label for the pattern.

rank

The taxonomic rank (column name) where matches were found.

n_matches

Number of values matching the pattern in that rank.

example_values

Up to 3 unique matching values (comma-separated).

Rows with zero matches are omitted.

Author(s)

Adrien Taudière

See Also

summarize_db(), list_ranks_db()

Examples

# From a FASTA file (no unwanted values in example data)
db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
count_unwanted_tax(db)

if(requireNamespace("MiscMetabar", quietly = TRUE)) {
 ref_fasta <- Biostrings::readDNAStringSet(system.file("extdata",
   "mini_UNITE_fungi.fasta.gz",
   package = "MiscMetabar", mustWork = TRUE
 ))
data("data_fungi_mini", package = "MiscMetabar")
physeq_new <- MiscMetabar::assign_mmseqs2(
   MiscMetabar::data_fungi_mini,
   ref_fasta = ref_fasta,
   behavior = "add_to_phyloseq"
 )
count_unwanted_tax(physeq_new)
}

Description

Removes pairs of primers and flanking regions from a FASTA reference database using cutadapt. Uses linked adapters to trim between forward and reverse primers.

Usage

cutadapt_rm_primers_db(
  ref_fasta,
  output = NULL,
  primer_fw = NULL,
  primer_rev = NULL,
  discard_untrimmed = TRUE,
  nproc = 1,
  verbose = TRUE,
  cmd_is_run = TRUE,
  return_file_path = FALSE,
  start_with_fw = FALSE,
  output_json = FALSE,
  error_tolerance = 0.1,
  args_before_cutadapt = paste0("source ~/miniforge3/etc/profile.d/conda.sh ",
    "&& conda activate cutadaptenv && ")
)

Arguments

Details

This function is mainly a wrapper of the work of others. Please cite cutadapt (doi:10.14806/ej.17.1.200).

Value

The cutadapt command string, or the output file path if return_file_path = TRUE.

Author(s)

Adrien Taudière

Examples

## Not run: 
cutadapt_rm_primers_db(
  "database.fasta.gz",
  output = "db_cutadapted.fasta",
  primer_fw = "GCATCGATGAAGAACGCAGC",
  primer_rev = "TCCTCCGCTTATTGATATGC"
)

## End(Not run)

Description

Reads a few sequence headers from a FASTA file and guesses the taxonomy format based on characteristic patterns.

Usage

detect_tax_format(file, n_headers = 20L)

Arguments

Value

A character string: one of "unite", "sintax", "greengenes2", "pr2", or "unknown".

See Also

tax_prefixes(), list_ranks_db(), summarize_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
detect_tax_format(db)

Description

Runs format, integrity, and quality checks on one or more FASTA reference databases and returns a structured diagnosis: per-file statistics, per-rank taxonomic coverage, a table of collected warnings, a cross-file comparison (which flags problems such as a mixed taxonomy format across files), and (optionally) diagnostic plots.

The three axes checked are:

Format

Is the file valid FASTA? Which taxonomy format is detected (detect_tax_format())? Are the taxonomy prefixes consistent across all headers?

Integrity

Can the file be read to completion (a truncated gzip fails here)? Are there empty sequences or duplicated sequence IDs?

Quality

Sequence-length distribution and unusually short sequences, percentage of sequences annotated at each rank, ambiguous (non-ACGT) bases, duplicated sequences, and unwanted taxonomic values (count_unwanted_tax()).

Usage

diagnose_db(
  files,
  tax_format = "auto",
  plot = TRUE,
  min_length = 200L,
  check_duplicates = TRUE,
  verbose = TRUE
)

Arguments

Value

An object of class "dbpq_diagnosis": a list with components

stats

A tibble, one row per file, with sequence counts, length statistics, and problem counts.

coverage

A long tibble of per-rank annotation coverage (file, rank, n_annotated, pct_annotated).

warnings

A tibble of collected issues (file, check, severity, message); severity is one of "info", "warning", "error". Cross-file issues have file = NA.

cross_file

A list describing agreement across files (formats, format_agreement, n_files).

plots

A list of ggplot2 objects (length, coverage), or NULL.

Author(s)

Adrien Taudière

See Also

summarize_db(), detect_tax_format(), count_unwanted_tax()

Examples

unite <- system.file("extdata", "example_unite.fasta", package = "dbpq")
diag <- diagnose_db(unite)
diag$stats

# Several files at once: a mismatched taxonomy format is flagged
sintax <- system.file("extdata", "example_sintax.fasta", package = "dbpq")
diag2 <- diagnose_db(c(unite, sintax))
diag2$warnings

Description

Downloads reference sequences from BOLD Systems (Barcode of Life Data) for a given taxonomic group. Unlike other databases, BOLD does not provide a single pre-built reference FASTA — sequences are queried by taxon via the BOLD API.

Usage

download_bold_db(
  dest_dir = ".",
  taxon = NULL,
  marker = "COI-5P",
  tax_format = c("dada2", "sintax", "none"),
  verbose = TRUE
)

Arguments

Details

This function uses the BOLD public API hosted at v3.boldsystems.org, which remains available after the main BOLD site's migration to v5. With tax_format = "none" it queries the sequence endpoint (FASTA). With "dada2"/"sintax" it queries the combined endpoint (TSV with the full ranked taxonomy), keeps the requested marker, and writes a taxonomy-headed FASTA (gaps removed). BOLD's taxonomy starts at phylum, so the dada2 output has no kingdom level.

For very large taxa the download may be slow or hit server limits; use narrower queries, or the BOLDconnectR package for the full v5 (BCDM) data model.

Please cite: Ratnasingham S & Hebert PDN (2007) BOLD: The Barcode of Life Data System. Molecular Ecology Notes 7:355-364. doi:10.1111/j.1471-8286.2007.01678.x

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

Examples

## Not run: 
# COI reference for a genus, dada2 taxonomy headers
download_bold_db(dest_dir = "databases", taxon = "Danaus")

# ITS sequences for an order, SINTAX headers
download_bold_db(
  dest_dir = "databases",
  taxon = "Agaricales",
  marker = "ITS",
  tax_format = "sintax"
)

## End(Not run)

Description

Downloads the Diat.barcode reference database for diatom rbcL barcoding. This is a curated database for diatom identification using the rbcL marker gene. The recommended access method is through the diatbarcode R package, which provides additional tools for working with the database.

Usage

download_diatbarcode_db(
  dest_dir = ".",
  format = c("dada2", "dada2_species"),
  url = NULL,
  verbose = TRUE
)

Arguments

Details

The Diat.barcode database is maintained by INRAE and hosted on Recherche Data Gouv. For more advanced access (metadata, full taxonomy tables, custom queries), consider using the diatbarcode R package directly:

diatbarcode::download_diatbarcode(
  path = "databases",
  flavor = "rbcl312_dada2_tax"
)

Please cite: Rimet F et al. (2019) Diat.barcode, an open-access curated barcode library for diatoms. Scientific Reports 9:15116. doi:10.1038/s41598-019-51500-6

Value

The path to the downloaded file (invisibly), or a message with download instructions if no URL is provided.

Author(s)

Adrien Taudière

Examples

## Not run: 
download_diatbarcode_db(dest_dir = "databases")

## End(Not run)

Description

Downloads the Eukaryome database for eukaryotic organisms. Supports multiple markers (SSU 18S, ITS, LSU 28S) and output formats (general FASTA, dada2, mothur).

Usage

download_eukaryome_db(dest_dir = ".", url = NULL, verbose = TRUE)

Arguments

Details

Eukaryome does not provide a stable programmatic download API. Files are available at https://eukaryome.org/download/ in several formats:

• General FASTA: https://eukaryome.org/generalfasta/

• dada2 format: https://eukaryome.org/dada2/

• mothur format: https://eukaryome.org/mothur/

• SINTAX format: https://eukaryome.org/sintax/

• QIIME2 format: https://eukaryome.org/qiime2/

Visit one of these pages, copy the direct download link, and pass it via the url parameter.

Please cite: Vasar M et al. (2024) Eukaryome: the rRNA gene reference database for identification of all eukaryotes. Database. doi:10.1093/database/baae043

Value

The path to the downloaded file (invisibly), or a message with download instructions if no URL is provided.

Author(s)

Adrien Taudière

Examples

## Not run: 
# Download with a specific URL from the Eukaryome website
download_eukaryome_db(
  dest_dir = "databases",
  url = "https://eukaryome.org/files/eukaryome_v1.9_SSU_dada2.fasta.gz"
)

## End(Not run)

Description

Downloads the Greengenes2 16S rRNA database. By default, downloads the dada2-formatted training sets from Zenodo (maintained by Benjamin Callahan). Alternatively, downloads backbone sequences from the Greengenes2 FTP server.

Note that Greengenes2 uses d__ (domain) instead of k__ (kingdom) as the first rank prefix. Use tax_format = "greengenes2" with summarize_db() and list_ranks_db() for correct parsing.

Usage

download_greengenes2_db(
  dest_dir = ".",
  version = "2024.09",
  format = c("dada2", "dada2_species", "fasta"),
  tax_format = c("dada2", "sintax", "keep"),
  verbose = TRUE
)

Arguments

Details

The dada2-formatted files are maintained by Benjamin Callahan on Zenodo and are the same source as the SILVA dada2 training sets. See https://benjjneb.github.io/dada2/training.html for details.

The Greengenes2 trainset uses d__/p__ rank prefixes. By default (tax_format = "dada2") the prefixes are stripped so the file is directly usable by dada2::assignTaxonomy() and add_new_taxonomy_pq().

Please cite: McDonald D et al. (2024) Greengenes2 unifies microbial data in a single reference tree. Nature Biotechnology 42:715-718. doi:10.1038/s41587-023-01845-1

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

format2dada2(), tax_prefixes()

Examples

## Not run: 
# Download dada2-formatted Greengenes2
download_greengenes2_db(dest_dir = "databases")

# Download plain FASTA from FTP
download_greengenes2_db(dest_dir = "databases", format = "fasta")

## End(Not run)

Description

Downloads the KSGP (Karst, Silva, GTDB, and PR2) reference database for SSU rRNA taxonomic assignment, particularly optimized for Archaea communities. KSGP combines near full-length rRNA sequences from Karst et al. 2018, re-annotated SILVA prokaryote SSU sequences, cleaned GTDB 16S sequences, PR2 eukaryote 18S sequences, and MIDORI2 mitochondrial sequences. Taxonomy is based on GTDB, providing phylogenetically consistent classification.

Also provides access to the GTDB+ and GTDB_cleaned databases built as intermediate steps during KSGP construction.

Three annotation variants are available for database = "KSGP" and file_type = "tax":

• "sintax" (default): SINTAX-based taxonomic assignments (KSGP Sintax in the paper). Available for all versions.

• "lca": Conservative lowest common ancestor assignments (KSGP LCA). Only available for version "3.1".

• "ksgp_plus": Similarity-clustered putative taxa (KSGP+). Only available for version "3.1".

Usage

download_ksgp_db(
  dest_dir = ".",
  database = c("KSGP", "GTDB_plus", "GTDB_cleaned"),
  file_type = c("fasta", "tax", "archive"),
  annotation = c("lca", "sintax", "ksgp_plus"),
  tax_format = c("dada2", "sintax", "none"),
  version = "3.1",
  verbose = TRUE,
  timeout = Inf
)

Arguments

Details

When file_type = "fasta", the function downloads the matching ⁠KSGP_v<version>.tar.gz⁠ archive (one HTTP request) and extracts the FASTA — and, when tax_format != "none", the chosen .tax file — to dest_dir, then removes the archive. The archive is roughly 3.5x smaller than the raw FASTA (e.g. ~686 MB vs ~2.4 GB for v3.1), so this is both faster and lighter on the server than two separate requests. The KSGP FASTA and taxonomy files are otherwise separate downloads.

With tax_format = "sintax" (or "dada2"), the taxonomy is merged into the FASTA headers (one sequence ID per row, matched against the .tax file) and the .tax file is removed, so the result is a single FASTA ready for VSEARCH/dada2 — the original prefix letters from the .tax are preserved in the SINTAX output (a KSGP line starting with k__Bacteria; becomes ⁠>ID;tax=k:Bacteria,...⁠, not ⁠d:Bacteria,...⁠). To use KSGP for taxonomic assignment:

• With VSEARCH SINTAX: download the FASTA (file_type = "fasta", tax_format = "sintax").

• With dada2: download the FASTA (file_type = "fasta", tax_format = "dada2").

• With LotuS2: the KSGP database is integrated directly.

• For a complete set of all files: use file_type = "archive".

KSGP substantially improves Archaea annotation over SILVA and Greengenes2: Class and Order assignments increase by 2.7x and 4.2x respectively.

Please cite: Grant A et al. (2025) KSGP 3.1: improved taxonomic annotation of Archaea communities using LotuS2, the genome taxonomy database and RNAseq data. ISME Communications 5(1): ycaf094. doi:10.1093/ismeco/ycaf094

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

download_silva_db(), download_pr2_db(), format2sintax()

Examples

## Not run: 
# Download KSGP v3.1 FASTA
download_ksgp_db(dest_dir = "databases")

# Download KSGP v3.1 LCA taxonomy file
download_ksgp_db(
  dest_dir = "databases",
  file_type = "tax",
  annotation = "lca"
)

# Download KSGP+ taxonomy file
download_ksgp_db(
  dest_dir = "databases",
  file_type = "tax",
  annotation = "ksgp_plus"
)

# Download the complete KSGP archive (all annotation variants)
download_ksgp_db(dest_dir = "databases", file_type = "archive")

# Download GTDB+ (cleaned GTDB + PR2 + MIDORI2)
download_ksgp_db(dest_dir = "databases", database = "GTDB_plus")

## End(Not run)

Description

Downloads the LTPlus 16S rRNA gene reference FASTA for Bacteria and Archaea. LTPlus extends the All-Species Living Tree Project (LTP) type-strain collection with the best-quality non-type sequences selected from the SILVA non-redundant and GTDB databases, plus the highest-quality 16S sequences deposited at NCBI between 2019 and 2025. Sequences are clustered non-redundantly at a 98.7% identity threshold, yielding a compact database that covers most of the known prokaryotic genealogical diversity.

Usage

download_ltplus_db(
  dest_dir = ".",
  url = "https://biocom.uib.es/opucheck-backend/api/releases/02_26_06",
  tax_format = c("dada2", "sintax", "none"),
  csv_url = "https://biocom.uib.es/opucheck-backend/api/releases/02_26_02",
  to_dna = TRUE,
  verbose = TRUE
)

Arguments

Details

The file is the LTPlus 16S FASTA exported from the underlying curated alignment with gap columns removed ("compressed"), so the sequences are unaligned and vary in length (~140 MB total). It is served directly (no registration) from the LTP release backend; the file name is taken from the server's Content-Disposition header when available (e.g. ltplus_10_02_2026_compressed.fasta).

The released sequences are in the RNA alphabet (U rather than T) and the sequence lines contain whitespace. With to_dna = TRUE (default) the function transcribes U to T and rewrites a clean, whitespace-free DNA FASTA in place, ready for DNA-based classifiers such as dada2 or VSEARCH. With to_dna = FALSE the original RNA file is kept as-is.

The released FASTA headers carry only an accession (e.g. ⁠>LAJZ3046⁠); the taxonomy lives in a companion CSV. With tax_format = "dada2" (default) or "sintax" the function downloads that CSV, maps each accession to its full LTPlus lineage, and rewrites the headers with taxonomy so the file is ready for MiscMetabar::add_new_taxonomy_pq(). Use tax_format = "none" to keep the accession-only headers.

The default url points to the current release file. To list available releases and files, see the Downloads section of https://bioinfo.uib.es/ltp/ or query https://biocom.uib.es/opucheck-backend/api/releases; each file has an id appended to ⁠.../api/releases/⁠ to form its download URL. The ARB database, CSV and Newick tree files are also available there.

Please cite: Rosselló-Móra R et al. (2026) A pipeline for improved 16S rRNA gene-based phylogeny and diversity analyses of Bacteria and Archaea. Research Square. doi:10.21203/rs.3.rs-9370187/v1

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

download_silva_db(), download_greengenes2_db(), download_ksgp_db()

Examples

## Not run: 
# Download the current LTPlus 16S FASTA (DNA, dada2 taxonomy headers)
download_ltplus_db(dest_dir = "databases")

# SINTAX-formatted headers instead
download_ltplus_db(dest_dir = "databases", tax_format = "sintax")

# Keep the original RNA, accession-only FASTA without conversion
download_ltplus_db(dest_dir = "databases", to_dna = FALSE, tax_format = "none")

## End(Not run)

Description

Downloads the MaarjAM database of arbuscular mycorrhizal fungi (AMF) virtual taxa (VT) sequences, maintained at the University of Tartu. The QIIME-formatted release (a zip bundling a FASTA and a taxonomy table) is used so that the resulting FASTA carries taxonomy in its headers, ready for MiscMetabar::add_new_taxonomy_pq().

Usage

download_marjaam_db(
  dest_dir = ".",
  dataset = c("SSU", "SSU_TYPE", "LSU", "full_ITS", "onlyITS"),
  tax_format = c("dada2", "sintax", "none"),
  url = NULL,
  verbose = TRUE
)

Arguments

Details

The download links are listed at https://maarjam.ut.ee/?action=bDownload. The QIIME zip contains ⁠*.qiime.fasta⁠ and ⁠*.qiime.txt⁠ (a tab-separated ⁠id k__Fungi;p__...;s__VTX...⁠ table); taxonomy is merged into the FASTA headers by matching sequence IDs.

Please cite: Opik M et al. (2010) The online database MaarjAM reveals global and ecosystemic distribution patterns in arbuscular mycorrhizal fungi (Glomeromycota). New Phytologist 188:223-241. doi:10.1111/j.1469-8137.2010.03334.x

Value

The path to the downloaded FASTA file (invisibly).

Author(s)

Adrien Taudière

Examples

## Not run: 
# SSU (18S) AMF database with dada2 taxonomy headers
download_marjaam_db(dest_dir = "databases")

# SINTAX-formatted headers
download_marjaam_db(dest_dir = "databases", tax_format = "sintax")

## End(Not run)

Description

Downloads the MIDORI2 reference database for eukaryotic mitochondrial genes (COI, 12S, 16S, Cytb, etc.). MIDORI2 provides pre-formatted FASTA files for multiple classifiers (dada2, SINTAX, RDP, BLAST).

Usage

download_midori2_db(
  dest_dir = ".",
  gene = "CO1",
  format = c("dada2", "dada2_species", "SINTAX", "RDP", "BLAST"),
  seq_type = c("UNIQ", "LONGEST"),
  url = NULL,
  verbose = TRUE
)

Arguments

Details

MIDORI2 download URLs include a date-stamped directory path that changes with each GenBank release, making fully programmatic access fragile. Visit https://www.reference-midori.info/download.php to find the current download URL for your desired gene and format, then pass it via the url parameter.

Files are typically named following this pattern: ⁠MIDORI2_{TYPE}_NUC_SP_GB{VERSION}_{GENE}_{FORMAT}.fasta.gz⁠

Please cite: Leray M et al. (2022) MIDORI2: A collection of quality controlled, preformatted, and regularly updated reference databases for taxonomic assignment of eukaryotic mitochondrial sequences. Environmental DNA 4:894-907. doi:10.1002/edn3.303

Value

The path to the downloaded file (invisibly), or a message with download instructions if no URL is provided.

Author(s)

Adrien Taudière

See Also

format2sintax(), format2dada2()

Examples

## Not run: 
# Get instructions for downloading MIDORI2
download_midori2_db()

# Download with a specific URL
download_midori2_db(
  dest_dir = "databases",
  url = "https://reference-midori.info/download/Databases/..."
)

## End(Not run)

Description

Downloads the PR2 protist ribosomal reference database from GitHub releases. PR2 provides 18S rRNA gene sequences for protists and other eukaryotes.

For more advanced access to PR2 data (e.g., full taxonomy tables, metadata, or custom queries), see the pr2database R package.

Usage

download_pr2_db(
  dest_dir = ".",
  version = NULL,
  format = c("dada2", "mothur", "UTAX", "sintax"),
  marker = c("SSU", "plastid"),
  verbose = TRUE
)

Arguments

Details

PR2 releases are hosted on GitHub at https://github.com/pr2database/pr2database/releases.

Taxonomic ranks

PR2 uses 9 taxonomic ranks. The "dada2" file keeps all nine as a positional, semicolon-delimited lineage (no rank prefixes); pass them to dada2::assignTaxonomy() (via MiscMetabar::add_new_taxonomy_pq() with method = "dada2") through taxLevels:

c("Domain", "Supergroup", "Division", "Subdivision", "Class", "Order", "Family", "Genus", "Species")

The "UTAX"/"sintax" file targets VSEARCH/USEARCH SINTAX and uses the 8 standard single-letter rank prefixes (⁠k, d, p, c, o, f, g, s⁠). To fit PR2's nine ranks onto them, PR2 merges Division and Subdivision into the ⁠p:⁠ rank (joined by -). The 9 → 8 mapping is:

Mind the per-method argument when calling MiscMetabar::add_new_taxonomy_pq():

• method = "dada2" (the "dada2" download) keeps all 9 ranks — pass the 9 names above as taxLevels (forwarded to dada2::assignTaxonomy()).

• method = "sintax" (the "sintax"/"UTAX" download) has 8 ranks — pass 8 names as taxa_ranks, e.g. c("Domain", "Supergroup", "Division_Subdivision", "Class", "Order", "Family", "Genus", "Species"). The dada2 taxLevels argument is ignored by the SINTAX path, so the default 7 ranks would be used and parsing the 8-rank output fails.

Please cite: Guillou L et al. (2013) The Protist Ribosomal Reference database (PR2). Nucleic Acids Research 41:D1108-D1113. doi:10.1093/nar/gks1160

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

format2dada2(), format2sintax(), pr2database R package

Examples

## Not run: 
# Download latest PR2 in dada2 format
download_pr2_db(dest_dir = "databases")

# Download specific version in UTAX format
download_pr2_db(dest_dir = "databases", version = "5.0.0", format = "UTAX")

## End(Not run)

Description

Downloads the Ribosomal Database Project (RDP) 16S rRNA database. By default, downloads the dada2-formatted training sets from Zenodo (maintained by Benjamin Callahan).

Usage

download_rdp_db(
  dest_dir = ".",
  trainset = "19",
  format = c("dada2", "dada2_species"),
  verbose = TRUE
)

Arguments

Details

The dada2-formatted files are maintained by Benjamin Callahan on Zenodo. See https://benjjneb.github.io/dada2/training.html for details.

Please cite: Cole JR et al. (2014) Ribosomal Database Project: data and tools for high throughput rRNA analysis. Nucleic Acids Research 42:D633-D642. doi:10.1093/nar/gkt1244

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

format2dada2(), download_silva_db()

Examples

## Not run: 
# Download RDP trainset 19 for assignTaxonomy()
download_rdp_db(dest_dir = "databases")

# Download species assignment file
download_rdp_db(dest_dir = "databases", format = "dada2_species")

## End(Not run)

Description

Downloads the SILVA ribosomal RNA database (16S/18S/23S/28S). By default, downloads the dada2-formatted training sets from the official arb-silva.de DADA2 release (available for both SSU and LSU). Can also produce a SINTAX-formatted database (converted locally from the dada2 trainset) or download the raw SILVA NR99 export.

For the PARC version (all sequences, not clustered like NR99), see dada2:::makeSpeciesFasta_Silva() on the manually downloaded FASTA file.

Usage

download_silva_db(
  dest_dir = ".",
  version = "138.2",
  target = c("SSU", "LSU"),
  format = c("dada2", "dada2_species", "sintax", "raw"),
  verbose = TRUE
)

Arguments

Details

The dada2-formatted files are provided by arb-silva.de and are the recommended format for dada2::assignTaxonomy() and dada2::addSpecies(). See https://benjjneb.github.io/dada2/training.html for details.

SILVA data is free for academic use. Commercial use requires a license. See https://www.arb-silva.de/silva-license-information/.

Please cite: Quast C et al. (2013) The SILVA ribosomal RNA gene database project. Nucleic Acids Research 41:D590-D596. doi:10.1093/nar/gks1219

Value

The path to the resulting file (invisibly). For "sintax" this is the converted ⁠*_sintax.fasta.gz⁠; the intermediate trainset is also kept in dest_dir.

Author(s)

Adrien Taudière

See Also

format2dada2(), format2sintax()

Examples

## Not run: 
# Download dada2-formatted SILVA for assignTaxonomy()
download_silva_db(dest_dir = "databases")

# Download species assignment file
download_silva_db(dest_dir = "databases", format = "dada2_species")

# Download a SINTAX database for SSU (converted from the dada2 trainset)
download_silva_db(dest_dir = "databases", format = "sintax")

# SINTAX database for LSU
download_silva_db(dest_dir = "databases", target = "LSU", format = "sintax")

# Download raw SILVA NR99 FASTA
download_silva_db(dest_dir = "databases", format = "raw")

## End(Not run)

Description

Downloads the UNITE fungal ITS database for taxonomic assignment from the UNITE DOI repository (PlutoF/Zenodo). Provides both "dynamic" (including singletons) and "static" versions, for fungi or all eukaryotes.

UNITE general FASTA releases use the k__/p__ taxonomy format and are compatible with dada2, VSEARCH, and other classifiers after reformatting with format2dada2() or format2sintax().

Usage

download_unite_db(
  dest_dir = ".",
  type = c("dynamic", "static"),
  taxon_group = c("fungi", "eukaryotes"),
  version = "10.0",
  taxonomic_format = c("default", "sintax"),
  doi = NULL,
  verbose = TRUE
)

Arguments

Details

When taxonomic_format = "default": since UNITE v10.0, the .tgz archive contains all clustering variants (dynamic, 97%, 99%) bundled together. After downloading, extract the archive and select the appropriate FASTA file.

When taxonomic_format = "sintax": the downloaded .gz file is a single FASTA with SINTAX-ready taxonomy headers. This file can be used directly with vsearch --sintax.

The S3 download URLs use opaque UUIDs that change between releases. If the automatic URL fails, visit https://unite.ut.ee/repository.php to find the current DOI and pass it via the doi parameter, or download manually.

Please cite UNITE: Abarenkov K et al. (2024) UNITE general FASTA release for Fungi. UNITE Community. doi:10.15156/BIO/2959336

Value

The path to the downloaded file (invisibly).

Author(s)

Adrien Taudière

See Also

format2dada2(), format2sintax()

Examples

## Not run: 
# Download UNITE v10.0 default (general FASTA archive) for fungi
download_unite_db(dest_dir = "databases")

# Download UNITE v10.0 SINTAX-formatted for fungi
download_unite_db(dest_dir = "databases", taxonomic_format = "sintax")

# Download for all eukaryotes in SINTAX format
download_unite_db(
  dest_dir = "databases",
  taxon_group = "eukaryotes",
  taxonomic_format = "sintax"
)

## End(Not run)

Description

Filters sequences from a FASTA database whose header lines match a given pattern. Accepts gzip files. May not work on Windows.

Usage

filter_db(
  ref_fasta,
  pattern,
  output = NULL,
  force_two_lines_per_seq = TRUE,
  keep_temporary_files = FALSE
)

Arguments

Value

The path to the output file (invisibly).

Author(s)

Adrien Taudière

See Also

count_pattern_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
out <- tempfile(fileext = ".fasta")
filter_db(db, "Amanita", output = out)
count_seq_db(out)

Description

Locates the vsearch executable on the system PATH, or verifies a user-supplied path. This is a lightweight standalone version of the helper found in MiscMetabar, so that dbpq does not need to depend on MiscMetabar for vsearch operations.

Usage

find_vsearch(path = NULL)

Arguments

Value

A character string with the path to vsearch, or NA if not found.

See Also

is_vsearch_installed(), add_sh_to_taxonomy()

Examples

find_vsearch()

Description

Detects (or uses) the input taxonomy format and rewrites sequence headers to the requested output format. This is the primary conversion function; format2sintax(), format2dada2(), and format2dada2_species() are convenience wrappers around it.

Supported input formats (prefix-based, with detectable rank labels): "sintax", "unite", "greengenes2".

Supported output formats:

• "sintax" — VSEARCH/USEARCH SINTAX (⁠>ID;tax=k:Kingdom,p:Phylum,...⁠)

• "unite" — UNITE default (⁠>ID;k__Kingdom;p__Phylum;...⁠)

• "greengenes2" — Greengenes2 (⁠>ID d__Domain;p__Phylum;...⁠)

• "dada2" — Unprefixed semicolon-delimited (⁠>Kingdom;Phylum;...;⁠)

• "dada2_species" — For dada2::addSpecies() (⁠>ID Genus Species⁠)

Positional formats ("pr2", "dada2") can be detected by detect_tax_format() but cannot be used as input for conversion because they lack rank labels.

Usage

format_fasta_db(
  fasta_db = NULL,
  taxnames = NULL,
  output_format = c("sintax", "unite", "greengenes2", "dada2", "dada2_species"),
  input_format = "auto",
  output_path = NULL,
  id_prefix = "seq"
)

Arguments

Value

If taxnames is used, a character vector of reformatted headers. If fasta_db is used, a DNAStringSet with reformatted names (invisibly when output_path is given).

Author(s)

Adrien Taudière

See Also

detect_tax_format(), format2sintax(), format2dada2(), format2dada2_species()

Examples

# UNITE → SINTAX
format_fasta_db(
  taxnames = "AB123;k__Fungi;p__Ascomycota;c__Sordariomycetes",
  output_format = "sintax"
)

# SINTAX → UNITE
format_fasta_db(
  taxnames = "AB123;tax=k:Fungi,p:Ascomycota,c:Sordariomycetes",
  output_format = "unite"
)

# Greengenes2 → dada2
format_fasta_db(
  taxnames = "abc123 d__Bacteria;p__Pseudomonadota;g__Escherichia",
  output_format = "dada2"
)

Description

Converts taxonomy headers to the format expected by dada2::assignTaxonomy(): unprefixed semicolon-delimited taxonomy (⁠>Kingdom;Phylum;Class;Order;Family;Genus;⁠). Wrapper around format_fasta_db().

Usage

format2dada2(
  fasta_db = NULL,
  taxnames = NULL,
  input_format = "auto",
  output_path = NULL,
  pattern_to_remove = NULL
)

Arguments

Value

If taxnames is used, a character vector. If fasta_db is used, a DNAStringSet with reformatted names. When output_path is provided, returned invisibly.

Author(s)

Adrien Taudière

See Also

format_fasta_db(), format2sintax(), format2dada2_species()

Examples

# SINTAX format → dada2
format2dada2(
  taxnames = "AB123;tax=k:Fungi,p:Ascomycota,c:Sordariomycetes"
)

# UNITE format → dada2
format2dada2(
  taxnames = "AB123;k__Fungi;p__Ascomycota;c__Sordariomycetes",
  input_format = "unite"
)

Description

Converts taxonomy headers to the format expected by dada2::addSpecies(): ⁠ID Genus Species⁠. Wrapper around format_fasta_db().

Usage

format2dada2_species(
  fasta_db = NULL,
  taxnames = NULL,
  input_format = "auto",
  output_path = NULL
)

Arguments

Value

If taxnames is used, a character vector. If fasta_db is used, a DNAStringSet with reformatted names.

Author(s)

Adrien Taudière

See Also

format_fasta_db(), format2sintax(), format2dada2()

Examples

# UNITE format → dada2_species
format2dada2_species(
  taxnames = "AB123;k__Fungi;g__Aspergillus;s__fumigatus"
)

# SINTAX format → dada2_species
format2dada2_species(
  taxnames = "AB123;tax=k:Fungi,g:Aspergillus,s:fumigatus",
  input_format = "sintax"
)

Description

Converts taxonomy headers to the VSEARCH SINTAX format (⁠>ID;tax=k:Kingdom,p:Phylum,...⁠). Wrapper around format_fasta_db().

Usage

format2sintax(
  fasta_db = NULL,
  taxnames = NULL,
  input_format = "auto",
  output_path = NULL,
  id_prefix = "seq"
)

Arguments

Value

If taxnames is used, a character vector of reformatted names. If fasta_db is used, a DNAStringSet with reformatted names.

Author(s)

Adrien Taudière

See Also

format_fasta_db(), format2dada2(), format2dada2_species()

Examples

# UNITE format → SINTAX
format2sintax(taxnames = "AB123;k__Fungi;p__Ascomycota;c__Sordariomycetes")

# Greengenes2 format → SINTAX
format2sintax(
  taxnames = "abc123 d__Bacteria;p__Pseudomonadota",
  input_format = "greengenes2"
)

# dada2 trainset (taxonomy-only, positional) → SINTAX with synthetic IDs
format2sintax(
  taxnames = "Bacteria;Pseudomonadota;Gammaproteobacteria;Vibrio;",
  input_format = "dada2",
  id_prefix = "SILVA_"
)

Description

Returns all extensions from a file name. Double extensions such as .fasta.gz are treated as a first-class case and returned as a two-element vector (e.g. c("fasta", "gz")).

Usage

get_file_extension(file_path)

Arguments

Value

A character vector of file extensions (one element per extension).

Examples

get_file_extension("my_database.fasta")
get_file_extension("my_database.fasta.gz")

Description

Tests whether the vsearch executable is available on the system.

Usage

is_vsearch_installed(path = find_vsearch())

Arguments

Value

TRUE if vsearch is available, FALSE otherwise.

See Also

find_vsearch(), add_sh_to_taxonomy()

Examples

is_vsearch_installed()

Description

Extracts and counts occurrences of a given taxonomic rank from FASTA sequence headers. Supports both prefix-based formats (unite, sintax, greengenes2) and positional formats (dada2, pr2).

Usage

list_ranks_db(
  file,
  rank_prefix = "k__",
  tax_format = NULL,
  rank_position = NULL
)

Arguments

Value

A named integer vector of counts, sorted in decreasing order. Names are the taxonomic rank values.

Author(s)

Adrien Taudière

See Also

tax_prefixes(), detect_tax_format(), summarize_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
list_ranks_db(db, rank_prefix = "p__")
list_ranks_db(db, tax_format = "unite")

Description

Builds a taxonomic profile of one or more FASTA reference databases. It first runs diagnose_db() (format/integrity/quality checks) and then adds:

• a richness table and bar plot giving the number of distinct taxa (levels) annotated at each taxonomic rank, and

• when several databases are supplied, a cross-database comparison of the taxa present at each rank, drawn as a Venn diagram (ggVennDiagram, up to venn_max databases) or an UpSet plot (ComplexUpset), with one plot per rank.

By default the comparison overlaps the sets of distinct taxon names at each rank (presence/absence). With weight_by_seqs = TRUE the UpSet bars instead show the total number of sequences backing the taxa in each intersection (summed across the databases that contain each taxon).

Usage

profile_db(
  files,
  tax_format = "auto",
  weight_by_seqs = FALSE,
  plot = TRUE,
  venn_max = 7L,
  verbose = TRUE,
  ...
)

Arguments

Value

An object of class "dbpq_profile": a list with components

diagnosis

The diagnose_db() result (a dbpq_diagnosis).

taxa

A long tibble (file, rank, taxon, n_seqs) of every taxon found at every rank.

richness

A tibble (file, rank, n_levels, n_seqs_annotated) of per-rank taxonomic richness.

comparison

NULL for a single file; otherwise a list with per_db and signatures tibbles, per-rank membership data frames, and per-rank plots.

plots

A list with richness (a ggplot) and comparison (a named list of per-rank Venn/UpSet plots, or NULL).

Author(s)

Adrien Taudière

See Also

diagnose_db(), summarize_db(), list_ranks_db()

Examples

unite <- system.file("extdata", "example_unite.fasta", package = "dbpq")
prof <- profile_db(unite, verbose = FALSE)
prof$richness

# Compare two databases (needs ggVennDiagram / ComplexUpset for the plots)

sintax <- system.file("extdata", "example_sintax.fasta", package = "dbpq")
prof2 <- profile_db(c(unite, sintax), verbose = FALSE)
prof2$comparison$signatures

Description

Searches a FASTA database (plain or gzip) for sequences whose header matches a set of taxonomic name parts. This is useful to retrieve all sequences assigned to a given taxon across databases that use different header formats (e.g. UNITE ⁠g__Apiotrichum;s__akiyoshidainum⁠ vs SINTAX ⁠k:Fungi,...,g:Apiotrichum,s:akiyoshidainum⁠).

Matching is case-insensitive by default and based on substrings, so the rank prefixes and separators used by a given format do not matter. Provide multiple name parts in taxa to narrow the search: by default a header matches only when all parts are present (match = "all"); use match = "any" to match when at least one part is present.

On Linux/macOS, filtering is done with awk in a single streaming pass over the file, so memory usage stays low even for multi-GB reference databases — only the matched records are loaded into R. On Windows (or whenever awk is unavailable), the function automatically falls back to an in-memory Biostrings::readDNAStringSet() filter, which is slower and more memory-hungry for large databases but produces the same result.

Usage

search_taxa_db(
  file,
  taxa,
  match = c("all", "any"),
  case_sensitive = FALSE,
  output_path = NULL
)

Arguments

Value

A Biostrings::DNAStringSet of the matching sequences, with original headers preserved (including all taxonomy information). An empty DNAStringSet (length 0) is returned when nothing matches.

Author(s)

Adrien Taudière

See Also

filter_db() for a shell-based header filter that writes to a file; format_fasta_db() to reformat the retrieved sequences.

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")

# Retrieve all Amanita sequences (single name part)
search_taxa_db(db, "Amanita")

# Narrow to a species with two name parts (AND logic)
search_taxa_db(db, c("Amanita", "muscaria"))

# Match any of several genera (OR logic)
search_taxa_db(db, c("Amanita", "Fusarium"), match = "any")

# Write the result to a gzipped FASTA file and read it back
out <- tempfile(fileext = ".fasta.gz")
search_taxa_db(db, "Boletus", output_path = out)
Biostrings::readDNAStringSet(out)

Description

Provides an overview of a FASTA reference database: number of sequences, sequence length distribution, and taxonomic coverage at each rank. Supports both prefix-based formats (unite, sintax, greengenes2) and positional formats (dada2, pr2).

Usage

summarize_db(
  file,
  rank_prefixes = c("k__", "p__", "c__", "o__", "f__", "g__", "s__"),
  tax_format = NULL
)

Arguments

Value

A list with components:

• n_sequences: total number of sequences

• length_summary: summary statistics of sequence lengths

• ranks: a named integer vector of annotated counts per rank

Author(s)

Adrien Taudière

See Also

tax_prefixes(), detect_tax_format(), list_ranks_db()

Examples

db <- system.file("extdata", "example_unite.fasta", package = "dbpq")
summarize_db(db)
summarize_db(db, tax_format = "unite")

Description

Returns the taxonomic rank information for common reference database formats. For prefix-based formats (unite, sintax, greengenes2), returns a named character vector of prefixes. For positional formats (pr2), returns a named integer vector of rank positions.

Use the result with list_ranks_db() and summarize_db() via their tax_format parameter.

Note: dada2::assignTaxonomy() is a classifier, not a taxonomy format. It accepts any semicolon-separated taxonomy with any number of levels, regardless of whether prefixes are present or not. Use the taxLevels argument in dada2::assignTaxonomy() to specify the rank names.

Usage

tax_prefixes(tax_format = c("unite", "sintax", "greengenes2", "pr2"))

Arguments

Value

For prefix-based formats: a named character vector of rank prefixes. For positional formats: a named integer vector of rank positions.

See Also

list_ranks_db(), summarize_db(), detect_tax_format()

Examples

tax_prefixes("unite")
tax_prefixes("sintax")
tax_prefixes("greengenes2")
tax_prefixes("pr2")