matchValues: Matching of numeric values
In rformassspectrometry/MetaboAnnotation: Utilities for Annotation of Metabolomics Data
ValueParam R Documentation
Matching of numeric values
Description
The matchValues method matches elements from query with those in target
using different matching approaches depending on parameter param.
Generally, query is expected to contain MS experimental values
(m/z and possibly retention time) while target reference values. query
and target can be numeric, a two dimensional array (such as a
data.frame, matrix or DataFrame), a SummarizedExperiment
or a QFeatures, target can in addition be a Spectra() object.
For SummarizedExperiment, the information for the matching is expected
to be in the object's rowData. For QFeatures matching is performed
for values present in the rowData of one of the object's assays (which
needs to be specified with the assayQuery parameter - if a QFeatures
is used as target the name of the assay needs to be specified with
parameter assayTarget). If target is a Spectra matching is performed
against spectra variables of this object and the respective variable names
need to be specified e.g. with mzColname and/or rtColname.
matchMz is an alias for matchValues to allow backward compatibility.
Available param objects and corresponding matching approaches are:
-
ValueParam: generic matching between values in query and target given
acceptable differences expressed in ppm and tolerance. If query or
target are not numeric, parameter valueColname has to be used to
specify the name of the column that contains the values to be matched.
The function returns a Matched() object.
-
MzParam: match query m/z values against reference compounds for which
also m/z are known. Matching is performed similarly to the ValueParam
above. If query or target are not numeric, the column name containing
the values to be compared must be defined with matchValues' parameter
mzColname, which defaults to "mz". MzParam parameters tolerance
and ppm allow to define the maximal acceptable (constant or m/z relative)
difference between query and target m/z values.
-
MzRtParam: match m/z and retention time values between query and
target. Parameters mzColname and rtColname of the matchValues
function allow to define the columns in query and target containing
these values (defaulting to c("mz", "mz") and c("rt", "rt"),
respectively). MzRtParam parameters tolerance and
ppm have the same meaning as in MzParam; MzRtParam parameter
toleranceRt allows to specify the maximal acceptable difference between
query and target retention time values.
-
Mass2MzParam: match m/z values against reference compounds for
which only the (exact) mass is known. Before matching, m/z values are
calculated from the compounds masses in the target table using the
adducts specified via Mass2MzParam adducts parameter (defaults to
adducts = "[M+H]+"). After conversion of adduct masses to m/z values,
matching is performed similarly to MzParam (i.e. the same parameters
ppm and tolerance can be used). If query is not numeric,
parameter mzColname of matchValues can be used to specify the column
containing the query's m/z values (defaults to "mz"). If target is a
is not numeric, parameter massColname can be used to define the
column containing the reference compound's masses (defaults to
"exactmass").
-
Mass2MzRtParam: match m/z and retention time values against
reference compounds for which the (exact) mass and retention time are
known. Before matching, exact masses in target are converted to m/z
values as for Mass2MzParam. Matching is then performed similarly to
MzRtParam, i.e. m/z and retention times of entities are compared. With
matchValues' parameters mzColname, rtColname and massColname the
columns containing m/z values (in query), retention time values (in
query and target) and exact masses (in target) can be specified.
-
Mz2MassParam: input values for query and target are expected to be
m/z values but matching is performed on exact masses calculated from these
(based on the provided adduct definitions). In detail, m/z values in
query are first converted to masses with the mz2mass() function based
on the adducts defined with queryAdducts (defaults to "[M+H]+"). The
same is done for m/z values in target (adducts can be defined with
targetAdducts which defaults to "[M-H-]"). Matching is then performed on these converted values similarly to ValueParam. If queryortargetare not numeric, the column containing the m/z values can be specified withmatchValues' parameter mzColname(defaults to"mz"').
-
Mz2MassRtParam: same as Mz2MassParam but with additional comparison of
retention times between query and target. Parameters rtColname and
mzColname of matchValues allow to specify which columns contain the
retention times and m/z values, respectively.
Usage
ValueParam(tolerance = 0, ppm = 5)
MzParam(tolerance = 0, ppm = 5)
Mass2MzParam(adducts = c("[M+H]+"), tolerance = 0, ppm = 5)
Mass2MzRtParam(adducts = c("[M+H]+"), tolerance = 0, ppm = 5, toleranceRt = 0)
MzRtParam(tolerance = 0, ppm = 0, toleranceRt = 0)
Mz2MassParam(
queryAdducts = c("[M+H]+"),
targetAdducts = c("[M-H]-"),
tolerance = 0,
ppm = 5
)
Mz2MassRtParam(
queryAdducts = c("[M+H]+"),
targetAdducts = c("[M+H]+"),
tolerance = 0,
ppm = 5,
toleranceRt = 0
)
matchValues(query, target, param, ...)
## S4 method for signature 'numeric,numeric,ValueParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,numeric,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
queryAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'numeric,numeric,Mass2MzParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,Mass2MzParam'
matchValues(
query,
target,
param,
massColname = "exactmass",
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,numeric,Mass2MzParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mass2MzParam'
matchValues(
query,
target,
param,
mzColname = "mz",
massColname = "exactmass",
queryAssay = character(0),
targetAssay = character(0)
)
## S4 method for signature 'numeric,data.frameOrSimilar,MzParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'numeric,Spectra,MzParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'data.frameOrSimilar,numeric,MzParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,MzParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,Spectra,MzParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mass2MzRtParam'
matchValues(
query,
target,
param,
massColname = "exactmass",
mzColname = "mz",
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,MzRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,Spectra,MzRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'numeric,numeric,Mz2MassParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,Mz2MassParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'data.frameOrSimilar,numeric,Mz2MassParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mz2MassParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mz2MassRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
Arguments
tolerance
for any param object: numeric(1) defining the maximal
acceptable absolute difference in m/z (or in mass for Mz2MassParam)
to consider them matching.
ppm
for any param object: numeric(1) defining the maximal
acceptable m/z-dependent (or mass-dependent for Mz2MassParam)
difference (in parts-per-million) in m/z values to consider them to
be matching.
adducts
for Mass2MzParam or Mass2MzRtParam: either character
with adduct names from MetaboCoreUtils::adducts() or data.frame with
a custom adduct definition. This parameter is used to calculate m/z from
target compounds' masses. Custom adduct definitions can be passed to the
adduct parameter in form of a data.frame. This data.frame is expected
to have columns "mass_add" and "mass_multi" defining the additive
and multiplicative part of the calculation. See
MetaboCoreUtils::adducts() for the expected format or use
MetaboCoreUtils::adductNames("positive") and
MetaboCoreUtils::adductNames("negative") for valid adduct names.
toleranceRt
for Mass2MzRtParam or MzRtParam: numeric(1)
defining the maximal acceptable absolute difference in retention time
values to consider them them matching.
queryAdducts
for Mz2MassParam. Adducts used to derive mass
values from query m/z values. The expected format is the same as that
for parameter adducts.
targetAdducts
for Mz2MassParam. Adducts used to derive mass
values from target m/z values. The expected format is the same as that
for parameter adducts.
query
feature table containing information on MS1 features. Can be
a numeric, data.frame, DataFrame, matrix, SummarizedExperiment
or QFeatures. It is expected to contain m/z values and can contain also
other variables. Matchings based on both m/z and retention time can be
performed when a column with retention times is present in both query
and target.
target
compound table with metabolites to compare against. The
expected types are the same as those for query.
param
parameter object defining the matching approach and containing
the settings for that approach. See description above for details.
...
currently ignored.
valueColname
character specifying the name of the column in
query or/and the one in targetwith the desired values for the
matching. This parameter should only be used when param is
valueParam and in this case it must be provided (unless both query
and target are numeric). It can be character(1) or character(2)
in a similar way to mzColname.
targetAssay
character(1) specifying the name of the assay of the
provided QFeatures that should be used for the matching (values from
this assay's rowData will be used for matching). Only used if target
is an instance of a QFeatures object.
queryAssay
character(1) specifying the name of the assay of the
provided QFeatures that should be used for the matching (values from
this assay's rowData will be used for matching). Only used if query
is an instance of a QFeatures object.
massColname
character(1) with the name of the column in target
containing the mass of compounds. To be used when param is
Mass2MzParam or Mass2MzRtParam (and target is not already numeric
with the masses). Defaults to massColname = "exactmass".
mzColname
character specifying the name(s) of the column(s) in
query or/and targetwith the m/z values. If one among query and
target is numeric (and therefore there is no need to specify the
column name) or query is not numeric and param is Mass2MzParam
or Mass2MzRtParam (and therefore the name of the column with m/z needs
only to be specified for query) then mzColname is expected to be
character(1). If both query and target are not numeric mzColname
is expected to be character(2) (or character(1) and in this last case
the two column names are assumed to be the same). If not specified the
assumed default name for columns with m/z values is "mz". If target
is a Spectra() object, the name of the spectra variable that should be
used for the matching needs to be specified with mzColname.
rtColname
character(2) with the name of the column containing
the compounds retention times in query and the name for the one in
target. It can also be character(1) if the two names are the same.
To be used when param is MzRtParam or Mass2MzRtParam.
Defaults to rtColname = c("rt", "rt"). If target is a Spectra()
object, the name of the spectra variable that should be used for the
matching needs to be specified with mzColname.
Value
Matched object representing the result.
Depending on the param object different scores representing the quality
of the match are provided. This comprises absolute as well as relative
differences (column/variables "score" and "ppm_error" respectively).
If param is a Mz2MassParam, "score" and "ppm_error" represent
differences of the compared masses (calculated from the provided m/z values).
If param an MzParam, MzRtParam, Mass2MzParam or Mass2MzRtParam,
"score" and "ppm_error" represent absolute and relative differences of
m/z values.
Additionally, if param is either an MzRtParam or Mass2MzRtParam
differences between query and target retention times for each matched
element is available in the column/variable "score_rt" in the returned
Matched object.
Negative values of "score" (or "score_rt") indicate that the m/z or mass
(or retention time) of the query element is smaller than that of the target
element.
Author(s)
Andrea Vicini, Michael Witting
See Also
matchSpectra or CompareSpectraParam() for spectra data matching
Examples
library(MetaboCoreUtils)
## Create a simple "target/reference" compound table
target_df <- data.frame(
name = c("Tryptophan", "Leucine", "Isoleucine"),
formula = c("C11H12N2O2", "C6H13NO2", "C6H13NO2"),
exactmass = c(204.089878, 131.094629, 131.094629)
)
## Create a "feature" table with m/z of features. We calculate m/z for
## certain adducts of some of the compounds in the reference table.
fts <- data.frame(
feature_id = c("FT001", "FT002", "FT003"),
mz = c(mass2mz(204.089878, "[M+H]+"),
mass2mz(131.094629, "[M+H]+"),
mass2mz(204.089878, "[M+Na]+") + 1e-6))
## Define the parameters for the matching
parm <- Mass2MzParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20)
res <- matchValues(fts, target_df, parm)
res
## List the available variables/columns
colnames(res)
## feature_id and mz are from the query data frame, while target_name,
## target_formula and target_exactmass are from the query object (columns
## from the target object have a prefix *target_* added to the original
## column name. Columns adduct, score and ppm_error represent the results
## of the matching: adduct the adduct/ion of the original compound for which
## the m/z matches, score the absolute difference of the query and target
## m/z and ppm_error the relative difference in m/z values.
## Get the full matching result:
matchedData(res)
## We have thus matches of FT002 to two different compounds (but with the
## same mass).
## Individual columns can also be accessed with the $ operator:
res$feature_id
res$target_name
res$ppm_error
## We repeat the matching requiring an exact match
parm <- Mass2MzParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 0)
res <- matchValues(fts, target_df, parm)
res
matchedData(res)
## The last feature could thus not be matched to any compound.
## At last we use also different adduct definitions.
parm <- Mass2MzParam(
adducts = c("[M+K]+", "[M+Li]+"),
tolerance = 0,
ppm = 20)
res <- matchValues(fts, target_df, parm)
res
matchedData(res)
## No matches were found.
## We can also match a "feature" table with a target data.frame taking into
## account both m/z and retention time values.
target_df <- data.frame(
name = c("Tryptophan", "Leucine", "Isoleucine"),
formula = c("C11H12N2O2", "C6H13NO2", "C6H13NO2"),
exactmass = c(204.089878, 131.094629, 131.094629),
rt = c(150, 140, 140)
)
fts <- data.frame(
feature_id = c("FT001", "FT002", "FT003"),
mz = c(mass2mz(204.089878, "[M+H]+"),
mass2mz(131.094629, "[M+H]+"),
mass2mz(204.089878, "[M+Na]+") + 1e-6),
rt = c(150, 140, 150.1)
)
## Define the parameters for the matching
parm <- Mass2MzRtParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20,
toleranceRt = 0)
res <- matchValues(fts, target_df, parm)
res
## Get the full matching result:
matchedData(res)
## FT003 could not be matched to any compound, FT002 was matched to two
## different compounds (but with the same mass).
## We repeat the matching allowing a positive tolerance for the matches
## between rt values
## Define the parameters for the matching
parm <- Mass2MzRtParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20,
toleranceRt = 0.1)
res <- matchValues(fts, target_df, parm)
res
## Get the full matching result:
matchedData(res)
## Also FT003 was matched in this case
## It is also possible to match directly m/z values
mz1 <- c(12, 343, 23, 231)
mz2 <- mz1 + rnorm(4, sd = 0.001)
res <- matchValues(mz1, mz2, MzParam(tolerance = 0.001))
matchedData(res)
## Matching with a SummarizedExperiment or a QFeatures work analogously,
## only that the matching is performed on the object's `rowData`.
## Below we create a simple SummarizedExperiment with some random assay data.
## Note that results from a data preprocessing with the `xcms` package could
## be extracted as a `SummarizedExperiment` with the `quantify` method from
## the `xcms` package.
library(SummarizedExperiment)
se <- SummarizedExperiment(
assays = matrix(rnorm(12), nrow = 3, ncol = 4,
dimnames = list(NULL, c("A", "B", "C", "D"))),
rowData = fts)
## We can now perform the matching of this SummarizedExperiment against the
## target_df as before.
res <- matchValues(se, target_df,
param = Mass2MzParam(adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0, ppm = 20))
res
## Getting the available columns
colnames(res)
## The query columns represent the columns of the object's `rowData`
rowData(se)
## matchedData also returns the query object's rowData along with the
## matching entries in the target object.
matchedData(res)
## While `query` will return the full SummarizedExperiment.
query(res)
## To illustrate use with a QFeatures object we first create a simple
## QFeatures object with two assays, `"ions"` representing the full feature
## data.frame and `"compounds"` a subset of it.
library(QFeatures)
qf <- QFeatures(list(ions = se, compounds = se[2,]))
## We can perform the same matching as before, but need to specify which of
## the assays in the QFeatures should be used for the matching. Below we
## perform the matching using the "ions" assay.
res <- matchValues(qf, target_df, queryAssay = "ions",
param = Mass2MzParam(adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0, ppm = 20))
res
## colnames returns now the colnames of the `rowData` of the `"ions"` assay.
colnames(res)
matchedData(res)
rformassspectrometry/MetaboAnnotation documentation built on March 12, 2024, 4:09 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ValueParam | R Documentation |
Matching of numeric values
Description
The matchValues method matches elements from query with those in target
using different matching approaches depending on parameter param.
Generally, query is expected to contain MS experimental values
(m/z and possibly retention time) while target reference values. query
and target can be numeric, a two dimensional array (such as a
data.frame, matrix or DataFrame), a SummarizedExperiment
or a QFeatures, target can in addition be a Spectra() object.
For SummarizedExperiment, the information for the matching is expected
to be in the object's rowData. For QFeatures matching is performed
for values present in the rowData of one of the object's assays (which
needs to be specified with the assayQuery parameter - if a QFeatures
is used as target the name of the assay needs to be specified with
parameter assayTarget). If target is a Spectra matching is performed
against spectra variables of this object and the respective variable names
need to be specified e.g. with mzColname and/or rtColname.
matchMz is an alias for matchValues to allow backward compatibility.
Available param objects and corresponding matching approaches are:
-
ValueParam: generic matching between values inqueryandtargetgiven acceptable differences expressed inppmandtolerance. Ifqueryortargetare not numeric, parametervalueColnamehas to be used to specify the name of the column that contains the values to be matched. The function returns aMatched()object. -
MzParam: match query m/z values against reference compounds for which also m/z are known. Matching is performed similarly to theValueParamabove. Ifqueryortargetare not numeric, the column name containing the values to be compared must be defined withmatchValues' parametermzColname, which defaults to"mz".MzParamparameterstoleranceandppmallow to define the maximal acceptable (constant or m/z relative) difference between query and target m/z values. -
MzRtParam: match m/z and retention time values betweenqueryandtarget. ParametersmzColnameandrtColnameof thematchValuesfunction allow to define the columns inqueryandtargetcontaining these values (defaulting toc("mz", "mz")andc("rt", "rt"), respectively).MzRtParamparameterstoleranceandppmhave the same meaning as inMzParam;MzRtParamparametertoleranceRtallows to specify the maximal acceptable difference between query and target retention time values. -
Mass2MzParam: match m/z values against reference compounds for which only the (exact) mass is known. Before matching, m/z values are calculated from the compounds masses in the target table using the adducts specified viaMass2MzParamadductsparameter (defaults toadducts = "[M+H]+"). After conversion of adduct masses to m/z values, matching is performed similarly toMzParam(i.e. the same parametersppmandtolerancecan be used). Ifqueryis notnumeric, parametermzColnameofmatchValuescan be used to specify the column containing the query's m/z values (defaults to"mz"). Iftargetis a is notnumeric, parametermassColnamecan be used to define the column containing the reference compound's masses (defaults to"exactmass"). -
Mass2MzRtParam: match m/z and retention time values against reference compounds for which the (exact) mass and retention time are known. Before matching, exact masses intargetare converted to m/z values as forMass2MzParam. Matching is then performed similarly toMzRtParam, i.e. m/z and retention times of entities are compared. WithmatchValues' parametersmzColname,rtColnameandmassColnamethe columns containing m/z values (inquery), retention time values (inqueryandtarget) and exact masses (intarget) can be specified. -
Mz2MassParam: input values forqueryandtargetare expected to be m/z values but matching is performed on exact masses calculated from these (based on the provided adduct definitions). In detail, m/z values inqueryare first converted to masses with themz2mass()function based on the adducts defined withqueryAdducts(defaults to"[M+H]+"). The same is done for m/z values intarget(adducts can be defined withtargetAdductswhich defaults to"[M-H-]"). Matching is then performed on these converted values similarly to ValueParam. If queryortargetare not numeric, the column containing the m/z values can be specified withmatchValues' parameter mzColname(defaults to"mz"'). -
Mz2MassRtParam: same asMz2MassParambut with additional comparison of retention times betweenqueryandtarget. ParametersrtColnameandmzColnameofmatchValuesallow to specify which columns contain the retention times and m/z values, respectively.
Usage
ValueParam(tolerance = 0, ppm = 5)
MzParam(tolerance = 0, ppm = 5)
Mass2MzParam(adducts = c("[M+H]+"), tolerance = 0, ppm = 5)
Mass2MzRtParam(adducts = c("[M+H]+"), tolerance = 0, ppm = 5, toleranceRt = 0)
MzRtParam(tolerance = 0, ppm = 0, toleranceRt = 0)
Mz2MassParam(
queryAdducts = c("[M+H]+"),
targetAdducts = c("[M-H]-"),
tolerance = 0,
ppm = 5
)
Mz2MassRtParam(
queryAdducts = c("[M+H]+"),
targetAdducts = c("[M+H]+"),
tolerance = 0,
ppm = 5,
toleranceRt = 0
)
matchValues(query, target, param, ...)
## S4 method for signature 'numeric,numeric,ValueParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,numeric,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
queryAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,ValueParam'
matchValues(
query,
target,
param,
valueColname = character(),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'numeric,numeric,Mass2MzParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,Mass2MzParam'
matchValues(
query,
target,
param,
massColname = "exactmass",
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,numeric,Mass2MzParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mass2MzParam'
matchValues(
query,
target,
param,
mzColname = "mz",
massColname = "exactmass",
queryAssay = character(0),
targetAssay = character(0)
)
## S4 method for signature 'numeric,data.frameOrSimilar,MzParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'numeric,Spectra,MzParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'data.frameOrSimilar,numeric,MzParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,MzParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,Spectra,MzParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mass2MzRtParam'
matchValues(
query,
target,
param,
massColname = "exactmass",
mzColname = "mz",
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,data.frameOrSimilar,MzRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'data.frameOrSimilar,Spectra,MzRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature 'numeric,numeric,Mz2MassParam'
matchValues(query, target, param)
## S4 method for signature 'numeric,data.frameOrSimilar,Mz2MassParam'
matchValues(query, target, param, mzColname = "mz", targetAssay = character())
## S4 method for signature 'data.frameOrSimilar,numeric,Mz2MassParam'
matchValues(query, target, param, mzColname = "mz", queryAssay = character())
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mz2MassParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
queryAssay = character(),
targetAssay = character()
)
## S4 method for signature
## 'data.frameOrSimilar,data.frameOrSimilar,Mz2MassRtParam'
matchValues(
query,
target,
param,
mzColname = c("mz", "mz"),
rtColname = c("rt", "rt"),
queryAssay = character(),
targetAssay = character()
)
Arguments
tolerance |
for any |
ppm |
for any |
adducts |
for |
toleranceRt |
for |
queryAdducts |
for |
targetAdducts |
for |
query |
feature table containing information on MS1 features. Can be
a |
target |
compound table with metabolites to compare against. The
expected types are the same as those for |
param |
parameter object defining the matching approach and containing the settings for that approach. See description above for details. |
... |
currently ignored. |
valueColname |
|
targetAssay |
|
queryAssay |
|
massColname |
|
mzColname |
|
rtColname |
|
Value
Matched object representing the result.
Depending on the param object different scores representing the quality
of the match are provided. This comprises absolute as well as relative
differences (column/variables "score" and "ppm_error" respectively).
If param is a Mz2MassParam, "score" and "ppm_error" represent
differences of the compared masses (calculated from the provided m/z values).
If param an MzParam, MzRtParam, Mass2MzParam or Mass2MzRtParam,
"score" and "ppm_error" represent absolute and relative differences of
m/z values.
Additionally, if param is either an MzRtParam or Mass2MzRtParam
differences between query and target retention times for each matched
element is available in the column/variable "score_rt" in the returned
Matched object.
Negative values of "score" (or "score_rt") indicate that the m/z or mass
(or retention time) of the query element is smaller than that of the target
element.
Author(s)
Andrea Vicini, Michael Witting
See Also
matchSpectra or CompareSpectraParam() for spectra data matching
Examples
library(MetaboCoreUtils)
## Create a simple "target/reference" compound table
target_df <- data.frame(
name = c("Tryptophan", "Leucine", "Isoleucine"),
formula = c("C11H12N2O2", "C6H13NO2", "C6H13NO2"),
exactmass = c(204.089878, 131.094629, 131.094629)
)
## Create a "feature" table with m/z of features. We calculate m/z for
## certain adducts of some of the compounds in the reference table.
fts <- data.frame(
feature_id = c("FT001", "FT002", "FT003"),
mz = c(mass2mz(204.089878, "[M+H]+"),
mass2mz(131.094629, "[M+H]+"),
mass2mz(204.089878, "[M+Na]+") + 1e-6))
## Define the parameters for the matching
parm <- Mass2MzParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20)
res <- matchValues(fts, target_df, parm)
res
## List the available variables/columns
colnames(res)
## feature_id and mz are from the query data frame, while target_name,
## target_formula and target_exactmass are from the query object (columns
## from the target object have a prefix *target_* added to the original
## column name. Columns adduct, score and ppm_error represent the results
## of the matching: adduct the adduct/ion of the original compound for which
## the m/z matches, score the absolute difference of the query and target
## m/z and ppm_error the relative difference in m/z values.
## Get the full matching result:
matchedData(res)
## We have thus matches of FT002 to two different compounds (but with the
## same mass).
## Individual columns can also be accessed with the $ operator:
res$feature_id
res$target_name
res$ppm_error
## We repeat the matching requiring an exact match
parm <- Mass2MzParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 0)
res <- matchValues(fts, target_df, parm)
res
matchedData(res)
## The last feature could thus not be matched to any compound.
## At last we use also different adduct definitions.
parm <- Mass2MzParam(
adducts = c("[M+K]+", "[M+Li]+"),
tolerance = 0,
ppm = 20)
res <- matchValues(fts, target_df, parm)
res
matchedData(res)
## No matches were found.
## We can also match a "feature" table with a target data.frame taking into
## account both m/z and retention time values.
target_df <- data.frame(
name = c("Tryptophan", "Leucine", "Isoleucine"),
formula = c("C11H12N2O2", "C6H13NO2", "C6H13NO2"),
exactmass = c(204.089878, 131.094629, 131.094629),
rt = c(150, 140, 140)
)
fts <- data.frame(
feature_id = c("FT001", "FT002", "FT003"),
mz = c(mass2mz(204.089878, "[M+H]+"),
mass2mz(131.094629, "[M+H]+"),
mass2mz(204.089878, "[M+Na]+") + 1e-6),
rt = c(150, 140, 150.1)
)
## Define the parameters for the matching
parm <- Mass2MzRtParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20,
toleranceRt = 0)
res <- matchValues(fts, target_df, parm)
res
## Get the full matching result:
matchedData(res)
## FT003 could not be matched to any compound, FT002 was matched to two
## different compounds (but with the same mass).
## We repeat the matching allowing a positive tolerance for the matches
## between rt values
## Define the parameters for the matching
parm <- Mass2MzRtParam(
adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0,
ppm = 20,
toleranceRt = 0.1)
res <- matchValues(fts, target_df, parm)
res
## Get the full matching result:
matchedData(res)
## Also FT003 was matched in this case
## It is also possible to match directly m/z values
mz1 <- c(12, 343, 23, 231)
mz2 <- mz1 + rnorm(4, sd = 0.001)
res <- matchValues(mz1, mz2, MzParam(tolerance = 0.001))
matchedData(res)
## Matching with a SummarizedExperiment or a QFeatures work analogously,
## only that the matching is performed on the object's `rowData`.
## Below we create a simple SummarizedExperiment with some random assay data.
## Note that results from a data preprocessing with the `xcms` package could
## be extracted as a `SummarizedExperiment` with the `quantify` method from
## the `xcms` package.
library(SummarizedExperiment)
se <- SummarizedExperiment(
assays = matrix(rnorm(12), nrow = 3, ncol = 4,
dimnames = list(NULL, c("A", "B", "C", "D"))),
rowData = fts)
## We can now perform the matching of this SummarizedExperiment against the
## target_df as before.
res <- matchValues(se, target_df,
param = Mass2MzParam(adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0, ppm = 20))
res
## Getting the available columns
colnames(res)
## The query columns represent the columns of the object's `rowData`
rowData(se)
## matchedData also returns the query object's rowData along with the
## matching entries in the target object.
matchedData(res)
## While `query` will return the full SummarizedExperiment.
query(res)
## To illustrate use with a QFeatures object we first create a simple
## QFeatures object with two assays, `"ions"` representing the full feature
## data.frame and `"compounds"` a subset of it.
library(QFeatures)
qf <- QFeatures(list(ions = se, compounds = se[2,]))
## We can perform the same matching as before, but need to specify which of
## the assays in the QFeatures should be used for the matching. Below we
## perform the matching using the "ions" assay.
res <- matchValues(qf, target_df, queryAssay = "ions",
param = Mass2MzParam(adducts = c("[M+H]+", "[M+Na]+"),
tolerance = 0, ppm = 20))
res
## colnames returns now the colnames of the `rowData` of the `"ions"` assay.
colnames(res)
matchedData(res)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.