import.external

Imports the output of the most common proteomics search/quantification tools (DIA-NN, Spectronaut, FragPipe, MaxQuant, Proteome Discoverer) and converts it into a DEprot object. The function only reads, filters and reshapes the report: the object itself is then built by load.counts2, so log2 standardization, removal of all-NA rows, boxplot generation and slot filling behave exactly as in a manual load.

import.external(
  file,
  metadata = NULL,
  source = "auto",
  quantity = "auto",
  protein.id = "auto",
  sample.id = "auto",
  summarization = "maxlfq",
  q.value = 0.01,
  pg.q.value = 0.01,
  remove.contaminants = TRUE,
  contaminant.pattern = NULL,
  clean.sample.names = TRUE,
  subset.to.metadata = TRUE,
  column.id = "column.id",
  data.type = "auto",
  id.column = NULL,
  sample.columns = NULL,
  install.missing = "ask",
  verbose = TRUE
)

Arguments

file: String, path to the report file. Delimited text (.tsv, .csv, .txt) is read with data.table::fread; .parquet requires the optional package nanoparquet (or arrow, if already installed).
metadata: A data.frame (or a path to a table) containing at least the column indicated by column.id, whose values must match the sample names extracted from the report. If NULL (default) a minimal metadata table is generated from the sample names, with a warning.
source: String indicating the tool that generated the file. One among: "auto" (default), "diann", "diann.matrix", "spectronaut", "spectronaut.pivot", "fragpipe", "maxquant", "proteome.discoverer", "generic".
quantity: String indicating the intensity column (long reports) or the column suffix/prefix (wide reports). Default "auto" uses the tool-specific recommended one, see 'Details'.
protein.id: String indicating the column to use as protein identifier (row names of the count matrix). Default "auto".
sample.id: String indicating the run/sample column of long reports. Default "auto".
summarization: String defining how precursor/fragment-level long reports are rolled up to the protein level: "maxlfq" (default, requires the optional package iq), "sum", "median", or "none" (use a protein-level column already present in the report, e.g. PG.MaxLFQ or PG.Quantity). Ignored for wide reports.
q.value: Numeric, run-specific precursor q-value cutoff applied to long reports. Default 0.01; use NULL to skip.
pg.q.value: Numeric, protein-group q-value cutoff applied to long reports. Default 0.01; use NULL to skip.
remove.contaminants: Logical, whether to drop contaminant/decoy entries. Default TRUE.
contaminant.pattern: String, regular expression identifying contaminants/decoys. Default NULL uses a tool-aware pattern.
clean.sample.names: Logical, whether to strip paths and raw-file extensions from the sample names. Default TRUE.
subset.to.metadata: Logical, whether to keep only the samples listed in the metadata. Default TRUE.
column.id: String indicating the metadata column matching the sample names. Default "column.id".
data.type: String, one among "auto" (default), "raw", "normalized", "randomized", "imputed". When "auto" it is inferred from the quantity used.
id.column: String, used only with source = "generic": the column holding the protein IDs.
sample.columns: Character vector, used only with source = "generic": the intensity columns. If named, the names are used as sample names.
install.missing: String defining the behaviour when an optional package is missing: "ask" (default, prompts in interactive sessions), "always", "never".
verbose: Logical, whether to print progress messages. Default TRUE.

Value

A DEprot object (S4 vector).

Details

No new hard dependency is introduced: all delimited reports are parsed with packages already imported by DEprot. Two optional (Suggests) packages are used, and only when needed:

iq (CRAN): MaxLFQ summarization of long precursor-level reports (summarization = "maxlfq").
nanoparquet (CRAN): reading .parquet reports (DIA-NN >= 1.9); arrow is used instead when already installed.

If a required optional package is missing, the user is prompted to install it (see install.missing). Nothing is ever installed in a non-interactive session.

Default quantity column per source:

source	default quantity	inferred data.type
`diann`	`Precursor.Normalised` (maxlfq) / `PG.MaxLFQ` (none)	normalized
`diann.matrix`	all non-annotation columns	normalized
`spectronaut`	`F.PeakArea` (maxlfq) / `PG.Quantity` (none)	normalized
`spectronaut.pivot`	`PG.Quantity`	normalized
`fragpipe`	`"MaxLFQ Intensity"`	normalized
`maxquant`	`"LFQ intensity"`	normalized
`proteome.discoverer`	`"Abundances (Normalized)"`	normalized

Intensities are kept on a linear scale (zeros converted to NA) except for summarization = "maxlfq", which returns log2 estimates from iq. The corresponding log.base is passed to load.counts2 automatically.

Author

Sebastian Gregoricchio

Examples

if (FALSE) { # \dontrun{
# DIA-NN protein-group matrix (no optional dependency required)
dpo <- import.external(file = "report.pg_matrix.tsv",
                       metadata = sample.config,
                       source = "diann.matrix")

# DIA-NN main report, MaxLFQ roll-up from precursors (uses `iq`)
dpo <- import.external(file = "report.parquet",
                       metadata = sample.config,
                       source = "diann",
                       summarization = "maxlfq")

# FragPipe
dpo <- import.external(file = "combined_protein.tsv",
                       metadata = sample.config,
                       source = "fragpipe",
                       quantity = "MaxLFQ Intensity")

# any other wide table
dpo <- import.external(file = "my_table.tsv",
                       metadata = sample.config,
                       source = "generic",
                       id.column = "Accession",
                       sample.columns = c(WT_1 = "int_1", WT_2 = "int_2"))
} # }

Arguments

Value

Details

See also

Author

Examples