Package 'metaboprep'

Description

This function adds an additional layer of data along the third dimension to an existing 3D array (or 2D matrix/vector) by stacking a new layer of data. It ensures that the dimensions of the new layer match the first two dimensions of the existing array or matrix. If there is a mismatch in row or column names and the 'force' parameter is set to 'TRUE', the function will align the data by filling missing values with 'NA'. It is used internally and not intended for routine user use.

Usage

add_layer(current, layer, layer_name, force = FALSE)

Arguments

Value

A 3D array with the added layer in the third dimension.

Description

Scans the package source files for functions starting with "read_" to determine supported data formats.

Usage

available_data_formats()

Value

A named character vector of available data formats.

Description

Scans the package source files for available report templates to write to.

Usage

available_report_templates()

Value

A character vector of available report templates

Description

Run batch normalisation based on the platform flag in the features data

Usage

batch_normalise(
  metaboprep,
  run_mode_col,
  run_mode_colmap,
  source_layer = "input",
  dest_layer = "batch_normalised"
)

Arguments

Description

A 'Metaboprep' object is a container for matrices of metabolite data, along with associated metadata. It allows for efficient storage and manipulation of data, supporting quality control, transformations, and various analyses. This object facilitates easy access to data layers, sample and feature summaries, outlier treatment, and more.

Usage

Metaboprep(
  data,
  samples,
  features,
  exclusions = list(samples = list(user_excluded = character(),
    extreme_sample_missingness = character(), user_defined_sample_missingness =
    character(), user_defined_sample_totalpeakarea = character(),
    user_defined_sample_pca_outlier = character()), features = list(user_excluded =
    character(), extreme_feature_missingness = character(),
    user_defined_feature_missingness = character())),
  feature_summary = array(data = NA_real_, dim = c(0, 0, 0)),
  sample_summary = array(data = NA_real_, dim = c(0, 0, 0))
)

Arguments

Value

An object of class Metaboprep, an S7 class.

Slots

data

numeric matrix, the metabolite data.

samples

data.frame, the samples data frame

features

data.frame, the features data frame

exclusions

list, exclusion codes (mask for data).

feature_summary

numeric matrix, feature summary statistics.

sample_summary

numeric matrix, sample summary statistics.

Description

Cleans a character vector of names by replacing spaces with underscores, removing special characters ('-', '.'), replacing ' and converting to lowercase.

Usage

clean_names(names)

Arguments

Value

'character vector' A standardized version of the input names.

Examples

clean_names(c("Sample ID", "Feature-Name.1", "Concentration %"))
# Returns: c("sample_id", "featurename1", "concentration_pct")

Description

This function (1) identifies an informative distribution of effect and power estimates given your datas total sample size and (2) returns a summary plot.

Usage

continuous_power_plot(mydata)

Arguments

Value

a ggplot2 object

Examples

ex_data = matrix(NA, 1000, 2)
continuous_power_plot( ex_data )

Description

Calculates Cramer's V for a table of nominal variables; confidence intervals by bootstrap. Function taken from the rcompanion Rpackage.

Usage

cramerV(
  x,
  y = NULL,
  ci = FALSE,
  conf = 0.95,
  type = "perc",
  R = 1000,
  digits = 4,
  bias.correct = FALSE,
  reportIncomplete = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

Cramer's V is used as a measure of association between two nominal variables, or as an effect size for a chi-square test of association. For a 2 x 2 table, the absolute value of the phi statistic is the same as Cramer's V.

Because V is always positive, if type="perc", the confidence interval will never cross zero. In this case, the confidence interval range should not be used for statistical inference. However, if type="norm", the confidence interval may cross zero.

When V is close to 0 or very large, or with small counts, the confidence intervals determined by this method may not be reliable, or the procedure may fail.

Value

A single statistic, Cramer's V. Or a small data frame consisting of Cramer's V, and the lower and upper confidence limits.

Author(s)

Salvatore Mangiafico, [email protected]

References

http://rcompanion.org/handbook/H_10.html

Description

This function allows you estimate power for a binary variable given a defined number of case samples, control samples, effect size, and significance threshold.

Usage

eval.power.binary.imbalanced(N_case, N_control, effect, alpha)

Arguments

Value

a matrix of paramater inputs and power estimates are returned as a matrix

Examples

eval.power.binary.imbalanced( N_case = 1000,
 N_control = 1000,
 effect = 0.01,
 alpha = 0.05 )

eval.power.binary.imbalanced( N_case = c(1000, 2000),
 N_control = c(1000, 2000),
 effect = 0.01,
 alpha = 0.05 )

Description

This function estimates power for a continuous variable given the sample size, effect size, significance threshold, and the degrees of freedom.

Usage

eval.power.cont(N, n_coeff, effect, alpha)

Arguments

Examples

eval.power.cont(N = 1000, n_coeff = 1, effect = 0.0025, alpha = 0.05)

Description

Exports all data from a 'Metaboprep' object to a structured directory format. For each data layer, the function creates a subdirectory containing: - the primary data matrix ('data.tsv'), - associated feature and sample metadata ('features.tsv', 'samples.tsv'), - feature and sample summaries (if present, 'feature_summary.tsv', 'sample_summary.tsv'), - a serialized feature tree (if present), - and a 'config.yml' file with additional metadata and processing parameters.

Usage

export(metaboprep, directory, format = "metaboprep", ...)

Arguments

Value

the 'Metaboprep' object, invisibly, for use in pipes

Description

Export Data to 'COMETS' format

Usage

export_comets(metaboprep, directory, layer = NULL)

Arguments

Value

the 'Metaboprep' object, invisibly, for use in pipes

Description

Export Data to 'MetaboAnalyst' format

Usage

export_metaboanalyst(metaboprep, directory, layer = NULL, group_col = NULL)

Arguments

Value

the 'Metaboprep' object, invisibly, for use in pipes

Description

Export Data to 'Metaboprep' format

Usage

export_metaboprep(metaboprep, directory, ...)

Arguments

Value

the 'Metaboprep' object, invisibly, for use in pipes

Description

This function allows you to 'describe' metabolite features using the describe() function from the psych package, as well as estimate variance, a dispersion index, the coeficent of variation, and shapiro's W-statistic.

Usage

feature_describe(data)

Arguments

Value

a data frame of summary statistics for features (columns) of a matrix

Description

This function estimates feature statistics for samples in a matrix of metabolite features.

Usage

feature_summary(
  metaboprep,
  source_layer = "input",
  outlier_udist = 5,
  tree_cut_height = 0.5,
  feature_selection = "max_var_exp",
  sample_ids = NULL,
  feature_ids = NULL,
  features_exclude = NULL,
  output = "data.frame"
)

Arguments

Description

This function estimates an appropriate distribution of effect sizes to simulate in a continuous trait power analysis.

Usage

find.cont.effect.sizes.2.sim(mydata)

Arguments

Value

a vector of effect sizes

Examples

ex_data = sapply(1:10, function(x){ rnorm(250, 40, 5) })
find.cont.effect.sizes.2.sim(ex_data)

Description

This function estimates an appropriate distribution of effect sizes to simulate in a power analysis.

Usage

find.PA.effect.sizes.2.sim(mydata)

Arguments

Value

a vector of effect sizes

Examples

ex_data = sapply(1:10, function(x){ rnorm(250, 40, 5) })
find.PA.effect.sizes.2.sim(ex_data)

Description

This function writes an output report

Usage

generate_report(
  metaboprep,
  output_dir,
  output_filename = NULL,
  project = "Project",
  format = "pdf",
  template = "qc_report"
)

Arguments

Description

This function (1) estimates an informative distribution of effect and power estimates given your datas total sample size, over a distribution of imbalanced sample sizes and (2) returns a summary plot.

Usage

imbalanced_power_plot(mydata)

Arguments

Value

a ggplot2 object

Examples

ex_data = matrix(NA, 1000, 2)
imbalanced_power_plot( ex_data )

Description

This function estimates missingness in a matrix of data and provides an option to exclude certain columns or features from the analysis, such as xenobiotics (with high missingness rates) in metabolomics data sets.

Usage

missingness(data, by = "row")

Arguments

Value

data.frame, a data frame of missingness estimates for each sample/feature.

Description

This function performs a multivariate analysis over a dependent|response and numerous independent|explanatory variable

Usage

multivariate_anova(dep, indep_df)

Arguments

Value

ggplot2 table figure of

Examples

## simulate some correlated data
set.seed(1110)
n <- 250
mu <- c(5, 45, 25)
cmat <- matrix(c(1, 0.5, 0.3,
                 0.5, 1, 0.25,
                 0.3, 0.25, 1), nrow = 3, byrow = TRUE)
L <- chol(cmat)
Z <- matrix(rnorm(n * 3), nrow = n)
ex_data <- Z %*% L
ex_data <- sweep(ex_data, 2, mu, "+")
colnames(ex_data) = c("outcome","age","bmi")
multivariate_anova(dep = ex_data[,1], indep_df = ex_data[, 2:3])

Description

Given a vector or matrix, this function returns a vector or matrix of 0|1, of the same structure with 1 values indicating outliers.

Usage

outlier_detection(data, nsd = 5, meansd = FALSE, by = "column")

Arguments

Value

a matrix of 0 (not a sample outlier) and 1 (outlier)

Description

This function identifies outliers from a vector of data at SD units from the mean.

Usage

outliers(x, nsd = 3)

Arguments

Value

a list object of length three. (1) a vector of sample indexes indicating the outliers, (2) the lower outlier cuttoff value, (3) the upper outlier cuttoff value.

Examples

ex_data = rnbinom(500, mu = 40, size = 5)
outliers(ex_data)

Description

This function performs principal component analysis. In the first, missing data is imputed to the median. Subsequent to the derivation of the PC, the median imputed PC data is used to identify the number of informative or "significant" PC by (1) an acceleration analysis, and (2) a parrallel analysis. Finally the number of sample outliers are determined at 3, 4, and 5 standard deviations from the mean on the top PCs as determined by the acceleration factor analysis.

Usage

pc_and_outliers(
  metaboprep,
  source_layer = "input",
  sample_ids = NULL,
  feature_ids = NULL
)

Arguments

Value

a data.frame

Description

This function is a wrapper function that performs the key quality controls steps on a metabolomics data set. Key principles: 1. keep the source underlying data as it is 2. copy the source data to a new data layer called qcing for processing 3. build an exclusion list, accumulating codes for exclusion reasons 4. make any adjustments needed in the destination copy of the data, flag these in the exclusion list 5. copy the final result to a data layer called post_qc 6. return the Metabolites object with the newly populated data layers

Usage

quality_control(
  metaboprep,
  source_layer = "input",
  sample_missingness = 0.2,
  feature_missingness = 0.2,
  total_peak_area_sd = 5,
  outlier_udist = 5,
  outlier_treatment = "leave_be",
  winsorize_quantile = 1,
  tree_cut_height = 0.5,
  feature_selection = "max_var_exp",
  pc_outlier_sd = 5,
  max_num_pcs = 10,
  sample_ids = NULL,
  feature_ids = NULL,
  features_exclude_but_keep = NULL
)

Arguments

Description

Read Metabolon Data

Usage

read_metabolon(
  filepath,
  sheet = NULL,
  feature_sheet = NULL,
  feature_id_col = NULL,
  sample_sheet = NULL,
  sample_id_col = NULL,
  return_Metaboprep = TRUE
)

Arguments

Value

list or Metaboprep object, list(data = matrix, samples = samples data.frame, features = features data.frame)

Examples

# version 1.1 data format
filepath1 <- system.file("extdata", "metabolon_v1.1_example.xlsx", package = "metaboprep")
m <- read_metabolon(filepath1, sheet = 2)

# version 1.2 data format (different column names)
filepath2 <- system.file("extdata", "metabolon_v1.2_example.xlsx", package = "metaboprep")
m <- read_metabolon(filepath2, sheet = 'OrigScale')


# version 2 data format
filepath3 <- system.file("extdata", "metabolon_v2_example.xlsx", package = "metaboprep")
m <- read_metabolon(filepath3, 
                    sheet = 'Batch-normalized Data', 
                    feature_sheet = 'Chemical Annotation', 
                    feature_id_col = 'CHEM_ID', 
                    sample_sheet = 'Sample Meta Data', 
                    sample_id_col = 'PARENT_SAMPLE_NAME')

Description

Read Nightingale Data (format 1)

Usage

read_nightingale(filepath, return_Metaboprep = TRUE)

Arguments

Value

list or Metaboprep object, list(data = matrix, samples = samples data.frame, features = features data.frame)

Examples

# version 1 data format
filepath1 <- system.file("extdata", "nightingale_v1_example.xlsx", package = "metaboprep")
m <- read_nightingale(filepath1)

# version 2 data format
filepath2 <- system.file("extdata", "nightingale_v2_example.xlsx", package = "metaboprep")
m <- read_nightingale(filepath2)

Description

This function reads and processes an Olink NPX file in long format. It supports ‘.csv', '.xls', '.xlsx', '.txt', '.zip', and '.parquet' formats, using Olink’s own OlinkAnalyze::read_NPX() function, and returns a metaboprep object or a list of matrices and metadata frames for further analysis.

Usage

read_olink(filepath, return_Metaboprep = FALSE)

Arguments

Details

The function checks whether the input data is in long format by verifying the presence of duplicate 'SampleID' values. It also accommodates two variants of Olink files:

• Files that include a 'Sample_Type' column with values '"SAMPLE"' and '"CONTROL"'.

• Files that use the 'SampleID' column to label control samples (e.g., entries containing '"CONTROL"').

If neither format is detected, the function stops with an error indicating that the data is likely not from Olink.

Value

Metaboprep object or a named list with the following elements:

data

A matrix of NPX values with 'SampleID' as rows and 'OlinkID' as columns, containing only sample data.

samples

A 'data.frame' containing metadata for samples.

features

A 'data.frame' containing feature-level metadata for samples.

controls

A matrix of NPX values for control samples.

control_metadata

A 'data.frame' containing metadata for control samples.

Examples

## Not run: 
  filepath <- system.file("extdata", "example_olink_data.txt", package = "metaboprep")
  olink_data <- read_olink(filepath)

## End(Not run)

Description

This function reads and processes a commercial SomaLogic '.adat' file. It extracts RFU (Relative Florecent Units) data for samples and controls, along with their respective metadata and feature (protein) metadata. The function returns a structured list suitable for further analysis.

Usage

read_somalogic(filepath, return_Metaboprep = FALSE)

Arguments

Details

The function performs several validation steps and data transformations:

• It first checks if the provided 'filepath' points to an '.adat' file.

• It uses 'SomaDataIO::read_adat()' to import the raw data and 'SomaDataIO::is.soma_adat()' to verify its integrity as a SomaLogic object.

• It confirms the presence of the crucial 'SampleId' column.

• Data is separated into experimental "Sample" and "Calibrator" control groups based on the 'SampleType' column.

• For both sample and control data, RFU values corresponding to "seq" columns are extracted and reshaped into wide matrices with 'SampleId' as row names.

• Feature metadata is extracted from 'attr(df, "Col.Meta")', and a new 'feature_id' column is created (prefixed with "seq." and hyphens replaced by periods).

• Sample and control metadata are extracted from 'attr(df, "row_meta")', converted to 'tibble's, renamed, and 'sample_id' is relocated to the front. Explicit 'tibble::as_tibble()' and 'tibble::remove_rownames()' are used to handle potential 'SomaDataIO' object intricacies.

Value

A metaboprep object or a named list with the following elements:

data

A matrix of RFU values for experimental samples, with 'SampleId' as row names and 'SeqId' (from columns containing "seq") as column names.

samples

A 'tibble' containing metadata for experimental samples, with 'sample_id' (renamed from 'SampleId') as the first column.

features

A 'tibble' containing feature-level metadata (e.g., protein details), including a newly created 'feature_id' column derived from 'SeqId'.

controls

A matrix of RFU values for control samples (specifically "Calibrator" samples), with 'SampleId' as row names and 'SeqId' as column names.

control_metadata

A 'tibble' containing metadata for control samples (specifically "Calibrator" samples), with 'sample_id' as the first column.

Examples

## Not run: 
  filepath <- system.file("extdata", "example_data10.adat", package = "SomaDataIO")
  somalogic_data <- read_somalogic(filepath)

## End(Not run)

Description

This function runs the original metaboprep1 pipeline using the old parameter file input format. The function requires access to the internet as the old package (default github commit 'bbe1f85') will be dynamically downloaded and used to process the data.

Usage

run_metaboprep1(parameter_file, gitcommit = "bbe1f85", attempt_report = FALSE)

Arguments

Description

Summarise the sample data

Usage

sample_summary(
  metaboprep,
  source_layer = "input",
  outlier_udist = 5,
  sample_ids = NULL,
  feature_ids = NULL,
  output = "data.frame"
)

Arguments

Description

Launch a Shiny app to explore the Metaboprep object

Usage

shiny_app(metaboprep)

Arguments

Value

Runs a Shiny app

Description

Summarise the sample and feature data

Usage

summarise(
  metaboprep,
  source_layer = "input",
  outlier_udist = 5,
  tree_cut_height = 0.5,
  feature_selection = "max_var_exp",
  sample_ids = NULL,
  feature_ids = NULL,
  features_exclude = NULL,
  output = "data.frame"
)

Arguments

Description

Provides a concise, human-readable summary of a 'Metaboprep' object. It reports key dimensions of the data, the presence of metadata columns, the number of data layers, and the status of quality control summaries and exclusions.

Arguments

Value

Invisibly returns NULL. Prints a formatted summary to the console.

See Also

class_metaboprep

Description

This function estimates total peak abundance|area for numeric data in a matrix, for (1) all features and (2) all features with complete data.

Usage

total_peak_area(data, ztransform = TRUE)

Arguments

Value

a data frame of estimates for (1) total peak abundance and (2) total peak abundance at complete features for each samples

Description

This function identifies independent features using Spearman's rho correlation distances, and a dendrogram tree cut step.

Usage

tree_and_independent_features(
  data,
  tree_cut_height = 0.5,
  features_exclude = NULL,
  feature_selection = "max_var_exp"
)

Arguments

Value

A list with the following components:

data

A 'data.frame' with:

• 'feature_id': Feature (column) names from the input matrix.

• 'k': The cluster index assigned to each feature after tree cutting.

• 'independent_features': Logical indicator of whether the feature was selected as an independent (representative) feature.

tree

A ‘hclust' object representing the hierarchical clustering of the features based on 1 - |Spearman’s rho| distance.

Description

This function performs univariate linear analysis of a dependent and an independent variable and generates a viloin or box plot to illustrate the associated structure.

Usage

variable_by_factor(
  dep,
  indep,
  dep_name = "dependent",
  indep_name = "independent",
  orderfactor = TRUE,
  violin = TRUE
)

Arguments

Value

a ggplot2 object

Examples

x = c( rnorm(20, 10, 2), rnorm(20, 20, 2) )
y = as.factor( c( rep("A", 20), rep("B", 20)  ) )
variable_by_factor(dep = x , indep = y, dep_name = "expression", indep_name = "species" )