Package 'FastRet'

Description

The goal of this function is to train a model that predicts RT_ADJ (retention time measured on a new, adjusted column) from RT (retention time measured on the original column) and to attach this adjustment model to an existing FastRet model.

Usage

adjust_frm(
  frm,
  new_data,
  predictors = 1:6,
  nfolds = 5,
  verbose = 1,
  seed = NULL,
  do_cv = TRUE,
  adj_type = "lm",
  add_cds = NULL
)

Arguments

Details

Matching is done via "SMILES"+"INCHIKEY" if both datasets have non-missing INCHIKEYs for all rows; otherwise via "SMILES"+"NAME". If multiple rows in frm$df match the same row in new_data, their RT values are averaged first, and this average is used for training the adjustment model.

Example: if frm$df equals data.frame OLD shown below and new_data equals data.frame NEW, then the resulting, paired data.frame will look like PAIRED.

OLD <- data.frame(
    NAME   = c("A", "B",  "B",  "C"  ),
    SMILES = c("C", "CC", "CC", "CCC"),
    RT     = c(5.0,  8.0,  8.2,  9.0 )
)
NEW <- data.frame(
    NAME   = c("A", "B",  "B",  "B"),
    SMILES = c("C", "CC", "CC", "CC"),
    RT     = c(2.5,  5.5,  5.7,  5.6)
)
PAIRED <- data.frame(
    NAME   = c("A", "B",  "B",  "B"),
    SMILES = c("C", "CC", "CC", "CC"),
    RT     = c(5.0,  8.1,  8.1,  8.1), # Average of OLD$RT[2:3]
    RT_ADJ = c(2.5,  5.5,  5.7,  5.6)  # Taken from NEW
)

If do_cv is TRUE, the adjustment procedure is evaluated in cross-validation. However, care must be taken when interpreting the CV results, as the model performance depends on both the adjustment layer and the original model, which was trained on the full base dataset. Therefore, the observed CV metrics should be read as "expected performance when predicting RTs for molecules that were part of the base-model training but not part of the adjustment set" instead of "expected performance when predicting RTs for completely new molecules".

Value

An object of class frm, as returned by train_frm(), but with an additional element adj containing the adjustment model. Components of adj are:

• model: The fitted adjustment model. Class depends on adj_type and is one of lm, glmnet, or xgb.Booster.

• df: The data frame used for training the adjustment model. Including columns "NAME", "SMILES", "RT", "RT_ADJ" and optionally "INCHIKEY", as well as any additional predictors specified via the predictors argument.

• cv: A named list containing the cross validation results (see 'Details'), or NULL if do_cv = FALSE. When not NULL, elements are:

  • folds: A list of integer vectors specifying the samples in each fold.

  • models: A list of adjustment models trained on each fold.

  • stats: A list of vectors with RMSE, Rsquared, MAE, pBelow1Min per fold. Added with v1.3.0.

  • preds: Retention time predictions obtained during CV by applying the adjustment model to the hold-out data.

  • preds_adjonly: Removed (i.e. NULL) since v1.3.0.

• args: Function arguments used for adjustment (excluding frm, new_data and verbose). Added with v1.3.0.

• version: The version of the FastRet package used to train the adjustment model. Added with v1.3.0.

Examples

frm <- read_rp_lasso_model_rds()
new_data <- read_rpadj_xlsx()
frm_adj <- adjust_frm(frm, new_data, verbose = 0)

Description

Clips predicted retention times by fitting a log-normal distribution to the observed training RTs and bounding predictions to the central 99.99% interval. All observed RTs must be positive to estimate the distribution. If the estimated lower bound would be negative, it is replaced by 1% of the observed minimum RT instead.

Usage

clip_predictions(yhat, y)

Arguments

Value

Numeric vector of clipped (bounded) predictions.

Examples

# Draw only a few samples (10) and clip based on these. The allowed range will
# be much bigger than the observed range.

set.seed(42)
y <- rlnorm(n = 1000, meanlog = 2, sdlog = 0.1)
yhat <- y
yhat[1] <- -100 # way too low to be realistic
yhat[2] <- 1000 # way too high to be realistic
yhat <- clip_predictions(yhat, y)
range(y)  # [ 6.18,  8.93]
yhat[1:2] # [ 4.96, 10.61] # Limited by theoretical bounds


# Draw more samples (1000) and clip based on these. The allowed range will
# be almost identical to the observed range.

set.seed(42)
y <- rnorm(n = 100, mean = 100, sd = 5)
yhat <- y
yhat[1] <- -100
yhat[2] <- 1000
yhat <- clip_predictions(yhat, y)
range(y)  # 83.14, 117.47
yhat[1:2] # 83.14, 117.72

Description

Creates the FastRet GUI

Usage

fastret_app(port = 8080, host = "0.0.0.0", reload = FALSE, nsw = 1)

Arguments

Value

An object of class shiny.appobj.

Examples

x <- fastret_app()
if (interactive()) shiny::runApp(x)

Description

Calculate Chemical Descriptors (CDs) for a list of molecules. Molecules can appear multiple times in the list.

Usage

getCDs(df, verbose = 1, nw = 1, keepdf = TRUE)

Arguments

Value

A dataframe with all input columns (if keepdf is TRUE) and chemical descriptors as remaining columns.

Examples

cds <- getCDs(head(RP, 3), verbose = 1, nw = 1)

Description

Creates scatter plots of measured vs. predicted retention times (RT) for a FastRet Model (FRM). Supports plotting cross-validation (CV) predictions and fitted predictions on the training set, as well as their adjusted variants when the model has been adjusted via adjust_frm(). Coloring highlights points within 1 minute of the identity line and simple outliers.

Usage

plot_frm(frm = train_frm(verbose = 1), type = "scatter.cv", trafo = "identity")

Arguments

Value

NULL, called for its side effect of plotting.

Examples

frm <- read_rp_lasso_model_rds()
plot_frm(frm, type = "scatter.cv")

Description

Predict retention times for new data using a FastRet Model (FRM).

Usage

## S3 method for class 'frm'
predict(
  object = train_frm(),
  df = object$df,
  adjust = NULL,
  verbose = 0,
  clip = TRUE,
  impute = TRUE,
  ...
)

Arguments

Value

A numeric vector with the predicted retention times.

See Also

train_frm(), adjust_frm()

Examples

object <- read_rp_lasso_model_rds()
df <- head(RP)
yhat <- predict(object, df)

Description

Preprocess data so they can be used as input for train_frm().

Usage

preprocess_data(
  data,
  degree_polynomial = 1,
  interaction_terms = FALSE,
  verbose = 1,
  nw = 1,
  rm_near_zero_var = TRUE,
  rm_na = TRUE,
  add_cds = TRUE,
  rm_ucs = TRUE,
  rt_terms = 1,
  mandatory = c("NAME", "RT", "SMILES")
)

Arguments

Details

If add_cds = TRUE, chemical descriptors are added using getCDs(). If all chemical descriptors listed in CDFeatures are already present in the input data object, getCDs() will leave them unchanged. If one or more chemical descriptors are missing, all chemical descriptors will be recalculated and existing ones will be overwritten.

Value

A dataframe with the preprocessed data.

Examples

data <- head(RP, 3)
pre <- preprocess_data(data, verbose = 0)

Description

Reads the Retip::HILIC dataset (CC BY 4.0) from the Retip package or, if Retip is not installed, downloads the dataset directly from the Retip GitHub repository. Before returning the dataset, SMILES strings are canonicalized and the original tibble object is converted to a base R data.frame.

Usage

read_retip_hilic_data(verbose = 1)

Arguments

Details

Attribution as required by CC BY 4.0:

• Original dataset by: Paolo Bonini, Tobias Kind, Hiroshi Tsugawa, Dinesh Kumar Barupal, and Oliver Fiehn as part of the Retip project.
  

• Source repository: https://github.com/oloBion/Retip
  

• Original file: https://github.com/oloBion/Retip/raw/master/data/HILIC.RData
  

• License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
  

• Modifications in FastRet:

  • converted tibble to data.frame

  • canonicalized SMILES using as_canonical()

  • renamed column 'INCHKEY' to 'INCHIKEY'

Value

A data frame with 970 rows and the following columns:

• NAME: Molecule name

• INCHIKEY: InChIKey

• SMILES: Canonical SMILES string

• RT: Retention time in Minutes

Source

https://github.com/oloBion/Retip/raw/master/data/HILIC.RData

References

Retip: Retention Time Prediction for Compound Annotation in Untargeted Metabolomics
Paolo Bonini, Tobias Kind, Hiroshi Tsugawa, Dinesh Kumar Barupal, and Oliver Fiehn
Analytical Chemistry 2020 92 (11), 7515-7522 DOI: 10.1021/acs.analchem.9b05765

Examples

df <- read_retip_hilic_data(verbose = 0)

Description

Read a LASSO model trained on the RP dataset using train_frm().

Usage

read_rp_lasso_model_rds()

Value

A frm object.

Examples

frm <- read_rp_lasso_model_rds()

Description

Reads retention times from a reverse phase liquid chromatography experiment, performed at 35$^\circ$C and a flow rate of 0.3 mL/min. The data is also available as a dataframe in the package; to access it directly, use RP.

Usage

read_rp_xlsx()

Value

A dataframe of 442 metabolites with columns RT, SMILES and NAME.

Source

Measured by the Institute of Functional Genomics at the University of Regensburg.

See Also

RP

Examples

x <- read_rp_xlsx()
all.equal(x, RP)

Description

Subset of the data from read_rp_xlsx() with some slight modifications to simulate changes in temperature and/or flowrate.

Usage

read_rpadj_xlsx()

Value

A dataframe with 25 rows (metabolites) and 3 columns: RT, SMILES and NAME.

Examples

x <- read_rpadj_xlsx()

Description

Retention time data from a reverse phase liquid chromatography measured with a temperature of 35$^\circ$C and a flowrate of 0.3ml/min. The same data is available as an xlsx file in the package. To read it into R use read_rp_xlsx(). @format A dataframe of 442 metabolites with the following columns:

RT

Retention time

SMILES

SMILES notation of the metabolite

NAME

Name of the metabolite

Usage

RP

Format

An object of class data.frame with 442 rows and 3 columns.

Source

Measured by the Institute of Functional Genomics at the University of Regensburg.

See Also

read_rp_xlsx

Description

The function adjust_frm() is used to modify existing FastRet models based on changes in chromatographic conditions. It requires a set of molecules with measured retention times on both the original and new column. This function selects a sensible subset of molecules from the original dataset for re-measurement. The selection process includes:

1. Generating chemical descriptors from the SMILES strings of the molecules. These are the features used by train_frm() and adjust_frm().

2. Standardizing chemical descriptors to have zero mean and unit variance.

3. Training a Ridge Regression model with the standardized chemical descriptors as features and the retention times as the target variable.

4. Scaling the chemical descriptors by coefficients of the Ridge Regression model.

5. Clustering the entire dataset, which includes the scaled chemical descriptors and the retention times.

6. Returning the clustering results, which include the cluster assignments, the medoid indicators, and the raw data.

Usage

selective_measuring(
  raw_data,
  k_cluster = 25,
  verbose = 1,
  seed = NULL,
  rt_coef = "max_ridge_coef"
)

Arguments

Value

A list containing the following elements:

• clustering: A data frame with columns RT, SMILES, NAME, CLUSTER and IS_MEDOID.

• clobj: The clustering object. The object returned by the clustering function. Depends on the method parameter.

• coefs: The coefficients from the Ridge Regression model.

• model: The Ridge Regression model.

• df: The preprocessed data.

• dfz: The standardized features.

• dfzb: The features scaled by the coefficients (betas) of the Ridge Regression model.

Examples

x <- selective_measuring(RP[1:50, ], k = 5, verbose = 0)
# For the sake of a short runtime, only the first 50 rows of the RP dataset
# were used in this example. In practice, you should always use the entire
# dataset to find the optimal subset for re-measurement.

Description

Starts the FastRet GUI

Usage

start_gui(port = 8080, host = "0.0.0.0", reload = FALSE, nw = 2, nsw = 1)

Arguments

Details

If you set nw = 3 and nsw = 4, you should have at least 16 cores, one core for the shiny main process. Three cores for the three worker processes and 12 cores (3 * 4) for the subworkers. For the default case, nworkers = 2 and nsw = 1, you only need 3 cores, as nsw = 1 means that all subprocesses will run sequentially.

Value

A shiny app. This function returns a shiny app that can be run to interact with the model.

Examples

if (interactive()) start_gui()

Description

Trains a new model from molecule SMILES to predict retention times (RT) using the specified method.

Usage

train_frm(
  df,
  method = "lasso",
  verbose = 1,
  nfolds = 5,
  nw = 1,
  degree_polynomial = 1,
  interaction_terms = FALSE,
  rm_near_zero_var = TRUE,
  rm_na = TRUE,
  rm_ns = FALSE,
  seed = NULL,
  do_cv = TRUE
)

Arguments

Value

A 'FastRet Model', i.e., an object of class frm. Components are:

• model: The fitted base model. This can be an object of class glmnet (for Lasso or Ridge regression) or xgb.Booster (for GBTree models).

• df: The data frame used for training the model. The data frame contains all user-provided columns (including mandatory columns RT, SMILES and NAME) as well the calculated chemical descriptors. (But no interaction terms or polynomial features, as these can be recreated within a few milliseconds).

• cv: A named list containing the cross validation results, or NULL if do_cv = FALSE. When not NULL, elements are:

  • folds: A list of integer vectors specifying the samples in each fold.

  • models: A list of models trained on each fold.

  • stats: A list of vectors with RMSE, Rsquared, MAE, pBelow1Min per fold.

  • preds: Retention time predictions obtained in CV as numeric vector.

• seed: The seed used for random number generation.

• version: The version of the FastRet package used to train the model.

• args: The value of function arguments besides df as named list.

Examples

m <- train_frm(df = RP[1:40, ], method = "lasso", nfolds = 2, verbose = 0)
# For the sake of a short runtime, only the first 40 rows of the RP dataset
# are used in this example. In practice, you should always use the entire
# training dataset for model training.