The Small Molecule (SML) table is mandatory in the mzTab-M format and
provides abundances along with annotations on the small molecules of an
analysis result. All columns in this table need to be tab-delimited and no
empty cells are allowed ("null" must be used for missing values, for
columns that support that).
Each row of the small molecule section is intended to report one final result
to be communicated in terms of a molecule that has been quantified. In many
cases, this may be the molecule of biological interest. In general, different
adduct forms for the same molecule would be reported in the Small Molecule
Feature (SMF) section.
A detailed description of the SML format and its columns is provided in the
respective section
of the mzTab-M specification.
The functions to create and format the SML content are:
smlCreate(): main function that creates the SML table based on the
provided abundance matrix and small molecule annotation information.
The function automatically:
Formats the abundance matrix x (renaming column names to
"abundance_assay[n]")
Adds the required "SML_ID" column with a running integer representing
the primary key (unique ID) for each molecule.
Populates missing mandatory columns with "null" strings.
Sets the line prefix column.
Orders the columns according to the mzTab-M specification.
After smlCreate(), required study variable abundance columns should
be either added manually or using the smlAddStudyVariableColumns()
function. These required columns contain the average and variation
of molecule abundances across samples for a particular study variable.
smlAddStudyVariableColumns(): completes the SML table created
with smlCreate() by adding columns with aggregated assay values
(molecule abundances) per study variable(s). Study variables have to be
listed in the MTD section provided with the mtd parameter (e.g.
"study_variable[1]") where also the aggregation functions must be
defined (e.g. "study_variable[1]-average_function"). This aggregation
and variation functions has to be defined using the respective MS CV
ontology term (e.g. "MS:1002962" for the mean and "MS:1002963" for
the coefficient of variation). See MTD-export for details on the MTD
section.
The function:
gets all study variables from the metadata section (mtd)
for each study variable:
gets the assay references from MTD
gets the summary functions (for average and variation) from MTD
(resolving the MS CV term to the respective R function)
gets the referred abundance columns in x
calculates the summary statistic and these as additional columns to
x.
smlSort(): sorts the columns of an SML table into the expected order.
optional columns to be added to the SML. The length of arguments
passed through ... has to match nrow(x) and the arguments have
to be named. The name of the argument is used for the column name,
prefixed with "opt_".
x
for smlCreate(): matrix or data.frame with the abundances
of the small molecules. Only the abundances of the molecules should be
reported (rows being molecules, columns samples).
For smlAddStudyVariableColumns(): data.frame generated by
smlCreate().
For smlSort(): a SML data.frame, such as created by smlCreate().
SMF_ID_REFS
character with the index (ID) of all features (rows in
the SMF matrix) each small molecule bases on. The length of the input
has to match nrow(x). If not provided, "null" is assigned to all
molecules. Multiple IDs for one molecule can be separated by "|".
database_identifier
character with the identifier of the molecule.
Has to be in the format : to provide the database/source
of annotation and the ID (e.g. "HMDB:HMDB0001847"). Multiple values
can be concatenated using "|".
Can be "null" or NA for molecules without annotations. The length
of database_identifier has to match the number of rows of x. If not
provided (the default) "null" is assigned to each row/molecule.
chemical_formula
character with the (possible) chemical formula(s)
of the compound. Can be "null" but, if provided, its length has to
match the number of rows of x. Multiple formulas have to be
concatenated with "|" and the number of formulas per molecule have
to match the number of reported identifiers in database_identifier.
smiles
character with the potential molecule structures in the
simplified molecular-input line-entry system (SMILES) for the small
molecule. Can be "null" but, if provided, its length has to match the
number of rows of x. The number of smiles per molecule must
match the number of reported identifiers in database_identifier and
have to be separated by "|".
inchi
character with the potential standard IUPAC International
Chemical Identifier (InChI) of the given substance. Can be "null" but,
if provided, its length has to match the number of rows of x.
The number of inchis per molecule must match the number of reported
identifiers in database_identifier and have to be separated by "|".
chemical_name
character with the possible chemical/common names for
the small molecule, or general description if a chemical name is
unavailable. Can be "null" but, if provided, its length has to match
the number of rows of x. The number of names provided must
match the number of entities reported under database_identifier and
have to be separated by "|".
uri
character with the URI pointing to the small molecule’s entry
in a reference database (e.g., the small molecule’s HMDB or KEGG entry).
Can be "null" but, if provided, its length has to match the number of
rows of x.
The number of uris per molecule must match the number of reported
identifiers in database_identifier and have to be separated by "|".
theoretical_neutral_mass
numeric() with the small molecule's
precursor's theoretical neutral mass. Can be NA but,
if provided, its length has to match the number of rows of x.
The number of masses per molecule must match the number of reported
identifiers in database_identifier and have to be separated by "|".
adduct_ions
character() with a "|" separated list of detected
adducts for this this molecule. Can be "null" (or NA) but, if
provided, its length has to match the number of rows of x.
reliability
character() or integer() of length equal to nrow(x)
with the reliability of annotation following one of the supported
schemas. Has to be of length equal to nrow(x). "null" or NA are
allowed if no reliability information is available.
best_id_confidence_measure
character() defining the approach or
database search that identified the molecule with highest confidence. Has
to be a CV parameter, but can also be "null" or NA if not available.
If provided, the length has to match nrow(x).
best_id_confidence_value
numeric() the value/score of the best
confidence measure. If provided, the length has to match nrow(x). The
type of score must be defined in the metadata section. Can also be
NA if not available.
opt_identifier
character with the identifier to be used for optional
columns passed through .... This is used to create the column names for
optional columns in the format opt_{opt_identifier}_{column_name}. If
not provided, the default is "global". Must be of length 1 or matching
the number of opt columns provided in ....
mtd
two-column matrix or data.frame with the metadata (MTD)
definition of the data set. The first column needs to contain the
metadata field names, the second the corresponding values. See
MTD-export help page for more information.
Value
For smlCreate(): a characterdata.frame ready for export. The
data.frame contains the "SMH" line prefix, the standard columns ordered
according to the mzTab-M specification, the abundance columns, the
abundance columns aggregated per study variables and any optional columns.
For smlSort(): the input data.frame with columns ordered as defined
by the mzTab-M definition.
Details
All parameters passed to the smlCreate() function must be fully named.
See also
MTD-export and SMF-export for creating and formatting the
metadata (MTD) and small molecule feature (SMF) sections.
Author
Johannes Rainer
Examples
## Define an example abundance matrixamat<-matrix(abs(rnorm(20)), ncol =4, nrow =5)colnames(amat)<-c("sample_1", "sample_2", "sample_3", "sample_4")## Define annotation information for each row (molecule). This information## should be the result of an annotation pipeline used.anns<-data.frame( hmdb_id =c("HMDB:HMDB0001847",NA,"HMDB:HMDB0000122|HMDB:HMDB0000169","HMDB:HMDB0000258","HMDB:HMDB0060475"), formula =c("C8H10N4O2",NA,"C6H12O6|C6H12O6","C12H22O11","C5H9NO4"), smiles =c("CN1C=NC2=C1C(=O)N(C)C(=O)N2C",NA,"OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O|OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O",NA,"NC(CCC(O)=O)C(O)=O"), neutral_mass =c(194.0804, NA, "180.0634|180.0634", 342.1162, 147.0531), name =c("caffeine", NA, "glucose|mannose", "sucrose", "DL-Glutamate"), adduct_ions =c("[M+H]1+", NA, "[M+Na]1+","[M+H]1+", "[M+H]1+"), uri =c("http://www.hmdb.ca/metabolites/HMDB0001847",NA,"http://www.hmdb.ca/metabolites/HMDB0000122|http://www.hmdb.ca/metabolites/HMDB0000169","http://www.hmdb.ca/metabolites/HMDB0000258","http://www.hmdb.ca/metabolites/HMDB0060475"))## Create the SML table based on this information. Note that we have to## use the **full** name for **all** function arguments (i.e., `x = amat`## etc).sml<-smlCreate( x =amat, database_identifier =anns$hmdb_id, chemical_formula =anns$formula, smiles =anns$smiles, theoretical_neutral_mass =anns$neutral_mass, uri =anns$uri, chemical_name =anns$name, adduct_ions =anns$adduct_ions)sml#> SMH SML_ID SMF_ID_REFS database_identifier chemical_formula#> 1 SML 1 null HMDB:HMDB0001847 C8H10N4O2#> 2 SML 2 null null null#> 3 SML 3 null HMDB:HMDB0000122|HMDB:HMDB0000169 C6H12O6|C6H12O6#> 4 SML 4 null HMDB:HMDB0000258 C12H22O11#> 5 SML 5 null HMDB:HMDB0060475 C5H9NO4#> smiles#> 1 CN1C=NC2=C1C(=O)N(C)C(=O)N2C#> 2 null#> 3 OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O|OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O#> 4 null#> 5 NC(CCC(O)=O)C(O)=O#> inchi chemical_name#> 1 null caffeine#> 2 null null#> 3 null|null glucose|mannose#> 4 null sucrose#> 5 null DL-Glutamate#> uri#> 1 http://www.hmdb.ca/metabolites/HMDB0001847#> 2 null#> 3 http://www.hmdb.ca/metabolites/HMDB0000122|http://www.hmdb.ca/metabolites/HMDB0000169#> 4 http://www.hmdb.ca/metabolites/HMDB0000258#> 5 http://www.hmdb.ca/metabolites/HMDB0060475#> theoretical_neutral_mass adduct_ions reliability best_id_confidence_measure#> 1 194.0804 [M+H]1+ null null#> 2 null null null null#> 3 180.0634|180.0634 [M+Na]1+ null null#> 4 342.1162 [M+H]1+ null null#> 5 147.0531 [M+H]1+ null null#> best_id_confidence_value abundance_assay[1] abundance_assay[2]#> 1 null 1.400043517 1.1484116#> 2 null 0.255317055 1.8218177#> 3 null 2.437263611 0.2473253#> 4 null 0.005571287 0.2441996#> 5 null 0.621552721 0.2827054#> abundance_assay[3] abundance_assay[4]#> 1 0.5536994 1.86301149#> 2 0.6289820 0.52201251#> 3 2.0650249 0.05260191#> 4 1.6309894 0.54299634#> 5 0.5124269 0.91407483## Update the reference between rows in SML with those in an SMF tablesml$SMF_ID_REFS<-c("3", "5", "8|23", "12", "16")## Re-order columns in the expected ordersml<-smlSort(sml)sml#> SMH SML_ID SMF_ID_REFS database_identifier chemical_formula#> 1 SML 1 3 HMDB:HMDB0001847 C8H10N4O2#> 2 SML 2 5 null null#> 3 SML 3 8|23 HMDB:HMDB0000122|HMDB:HMDB0000169 C6H12O6|C6H12O6#> 4 SML 4 12 HMDB:HMDB0000258 C12H22O11#> 5 SML 5 16 HMDB:HMDB0060475 C5H9NO4#> smiles#> 1 CN1C=NC2=C1C(=O)N(C)C(=O)N2C#> 2 null#> 3 OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O|OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O#> 4 null#> 5 NC(CCC(O)=O)C(O)=O#> inchi chemical_name#> 1 null caffeine#> 2 null null#> 3 null|null glucose|mannose#> 4 null sucrose#> 5 null DL-Glutamate#> uri#> 1 http://www.hmdb.ca/metabolites/HMDB0001847#> 2 null#> 3 http://www.hmdb.ca/metabolites/HMDB0000122|http://www.hmdb.ca/metabolites/HMDB0000169#> 4 http://www.hmdb.ca/metabolites/HMDB0000258#> 5 http://www.hmdb.ca/metabolites/HMDB0060475#> theoretical_neutral_mass adduct_ions reliability best_id_confidence_measure#> 1 194.0804 [M+H]1+ null null#> 2 null null null null#> 3 180.0634|180.0634 [M+Na]1+ null null#> 4 342.1162 [M+H]1+ null null#> 5 147.0531 [M+H]1+ null null#> best_id_confidence_value abundance_assay[1] abundance_assay[2]#> 1 null 1.400043517 1.1484116#> 2 null 0.255317055 1.8218177#> 3 null 2.437263611 0.2473253#> 4 null 0.005571287 0.2441996#> 5 null 0.621552721 0.2827054#> abundance_assay[3] abundance_assay[4]#> 1 0.5536994 1.86301149#> 2 0.6289820 0.52201251#> 3 2.0650249 0.05260191#> 4 1.6309894 0.54299634#> 5 0.5124269 0.91407483## Add study variable abundance columns based on study variable definition## in a metadata (MTD) section.## In the example below we first define a metadata section with the## minimally required information for `smlAddStudyVariableColumns()`:## the study variables, the samples (assays) that belong to each and## a average and variation function (see ?MTD-export for full help on the## metadata section).## In the example we assign sample 1 and 3 to the `"male"` category/study## variable and 2 and 4 to `"female"`. For the average and variation## function we use the mean and coefficient of variation.mtd<-cbind(c("study_variable[1]","study_variable[1]-assay_refs","study_variable[1]-average_function","study_variable[1]-variation_function","study_variable[1]-description","study_variable[2]","study_variable[2]-assay_refs","study_variable[2]-average_function","study_variable[2]-variation_function","study_variable[2]-description"),c("male","assay[1]|assay[3]","[MS, MS:1002962, mean, ]","[MS, MS:1002963, variation coefficient, ]","sex of participants, male","female","assay[2]|assay[4]","[MS, MS:1002962, mean, ]","[MS, MS:1002963, variation coefficient, ]","sex of participants, female"))## Add study variable average and variation columns and sort the columnssml<-smlAddStudyVariableColumns(sml, mtd)|>smlSort()sml#> SMH SML_ID SMF_ID_REFS database_identifier chemical_formula#> 1 SML 1 3 HMDB:HMDB0001847 C8H10N4O2#> 2 SML 2 5 null null#> 3 SML 3 8|23 HMDB:HMDB0000122|HMDB:HMDB0000169 C6H12O6|C6H12O6#> 4 SML 4 12 HMDB:HMDB0000258 C12H22O11#> 5 SML 5 16 HMDB:HMDB0060475 C5H9NO4#> smiles#> 1 CN1C=NC2=C1C(=O)N(C)C(=O)N2C#> 2 null#> 3 OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O|OC[C@H]1O[C@H](O)[C@H](O)[C@H](O)[C@H]1O#> 4 null#> 5 NC(CCC(O)=O)C(O)=O#> inchi chemical_name#> 1 null caffeine#> 2 null null#> 3 null|null glucose|mannose#> 4 null sucrose#> 5 null DL-Glutamate#> uri#> 1 http://www.hmdb.ca/metabolites/HMDB0001847#> 2 null#> 3 http://www.hmdb.ca/metabolites/HMDB0000122|http://www.hmdb.ca/metabolites/HMDB0000169#> 4 http://www.hmdb.ca/metabolites/HMDB0000258#> 5 http://www.hmdb.ca/metabolites/HMDB0060475#> theoretical_neutral_mass adduct_ions reliability best_id_confidence_measure#> 1 194.0804 [M+H]1+ null null#> 2 null null null null#> 3 180.0634|180.0634 [M+Na]1+ null null#> 4 342.1162 [M+H]1+ null null#> 5 147.0531 [M+H]1+ null null#> best_id_confidence_value abundance_assay[1] abundance_assay[2]#> 1 null 1.400043517 1.1484116#> 2 null 0.255317055 1.8218177#> 3 null 2.437263611 0.2473253#> 4 null 0.005571287 0.2441996#> 5 null 0.621552721 0.2827054#> abundance_assay[3] abundance_assay[4] abundance_study_variable[1]#> 1 0.5536994 1.86301149 0.9768715#> 2 0.6289820 0.52201251 0.4421495#> 3 2.0650249 0.05260191 2.2511443#> 4 1.6309894 0.54299634 0.8182803#> 5 0.5124269 0.91407483 0.5669898#> abundance_study_variable[2] abundance_variation_study_variable[1]#> 1 1.5057115 0.6126248#> 2 1.1719151 0.5975830#> 3 0.1499636 0.1169239#> 4 0.3935980 1.4045848#> 5 0.5983901 0.1360934#> abundance_variation_study_variable[2]#> 1 0.3355878#> 2 0.7842727#> 3 0.9181576#> 4 0.5367944#> 5 0.7460778## The average and variation for each study variable were calculated from## the assay abundances and added as additional columns to the SML.
