Type:	Package
Title:	Generalized Spline Mixed Effect Models for Longitudinal Breath Data
Version:	1.0
Date:	2022-03-07
Description:	Automated analysis and modeling of longitudinal 'omics' data (e.g. breath 'metabolomics') using generalized spline mixed effect models. Including automated filtering of noise parameters and determination of breakpoints.
Depends:	R (≥ 3.5.0)
LazyData:	true
License:	GPL-3
RoxygenNote:	7.1.2
Encoding:	UTF-8
Imports:	methods, lawstat, nlme, graphics, RColorBrewer, stats, base, grDevices, qpdf
Suggests:	knitr, rmarkdown
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2022-03-15 21:43:06 UTC; gittakirana
Author:	Anne-Christin Hauschild [aut, cre], Sandy P. Eckel [ths, com], Jan Baumbach [ths]
Maintainer:	Anne-Christin Hauschild <achauschild@googlemail.com>
Repository:	CRAN
Date/Publication:	2022-03-21 18:40:04 UTC

An S4 class to represent a 'Gouderman' LDO object, that was generated by the generalized gauderman algorithm.

Description

An S4 class to represent a 'Gouderman' LDO object, that was generated by the generalized gauderman algorithm.

Slots

name

character Name of the new 'generalized-Gauderman' adjusted longitudinal data

dataFrames

list List of 'generalized-Gauderman' modified data. One data.frame for each component.

peaknames

character Vector of component names contained in this object.

k

numeric Updated times for the breaks of the spline model.

times

matrix Vector of updated time values.

newTimeVars

character The names of the newly defined time variables of the generalized 'Gauderman' model.

ids

character Vector of identifiers for the experiments

labels

factor Vector of class labels for each experiment

An S4 class to represent the result of the linear mixed effect modeling on a gauderman LDO.

Description

An S4 class to represent the result of the linear mixed effect modeling on a gauderman LDO.

Slots

name

character Name of the new 'generalized-Gauderman' adjusted longitudinal model.

gaudermanLDO

GaudermanLDO 'Generalized-Gauderman' adjusted longitudinal data object.

models

list List of models generated for each component.

labels

factor Vector of class labels for each experiment

pvalues

matrix Matrix of p-values for the intercept as well as all slops of the spline model for each component.

correctedpvalues

matrix Matrix of corrected p-values for the intercept as well as all slops of the spline model for each component.

modelparameter

matrix Model parameter for each component.

An S4 class to represent a 'LoBrA' Data Object (LDO). It stores multiple time series data for muliple experiements and multiple Components. It allows repeated measurements of a component, irregular sampling, and unequal temporal spacing of the time points.

Description

An S4 class to represent a 'LoBrA' Data Object (LDO). It stores multiple time series data for muliple experiements and multiple Components. It allows repeated measurements of a component, irregular sampling, and unequal temporal spacing of the time points.

Slots

name

character Name of the 'LDO' object

dataMatrices

list List of matrices of component measurement. It contains a measurement for each time point and each experiment.

backgroundMatrices

list List of matrices of background measurements. It contains a measurement for each time point and each experiment.

peaknames

character Character vector of Component names

times

numeric Vector of times for each time point in the data

ids

character Vector of identifiers for the experiments

labels

factor Vector of class labels for each experiment

An S4 class to represent a model selection result based on an 'LDO'.

Description

An S4 class to represent a model selection result based on an 'LDO'.

Slots

ldo

LDO 'LDO' object the model selection is based on.

potentialBreaks

numeric Vector of numeric values that were considered as potential break points in the model selection.

splinetype

character Type of spline used.

qualityMeasure

character Quality measures used during the model selection ('AIC', 'BIC' or 'LogLik')

modelList

list List of all models tested.

quality

list List of quality matrices, one matrix for each quality measure used. Each matrix contains the quality for each spline tested for each component.

breaks

list For each tested spline, this list contains a vector of breaks.

An S4 class to represent the screening of metabolites in an 'LDO'.

Description

An S4 class to represent the screening of metabolites in an 'LDO'.

Slots

ldo

LDO LDO object the screening is based on.

experimentIntercept

list List of experiment intercepts.

experimentResiduals

list List of experiment Residuals.

interceptPvalues

matrix Matrix of experiment intercept p-values.

residualPvalues

matrix Matrix of experiment Residual p-values.

selectedPeaks

matrix Matrix of logical values. Each entry indicates whether a specific component is significant according to a specific test.

LoBrA: A package for modeling longitudinal breath data

Description

The LoBrA package provides important data objects and functions to analyze longitudinal metabolomic (breath) data.

Introduction

Novel metabolomic technologies paved the way for longitudinal analysis of exhaled air and online monitoring of fast progressing diseases. This package implements an automated analysis approach of longitudinal data from different omics technologies, such as ion mobility spectrometry of human exhaled air and demonstrates how including temporal signals increases the statistical power in biomarker identification. It can handel multiple irregular 4D time series data. More precisely, it can simultaniously handel the data of multiple experiements each observing multiple components. Therefore, it allows repeated measurements of a component, irregular sampling, and unequal temporal spacing of the time points.

LoBrA Analysis

A typical LoBrA analysis is will comprise the following steps

1. Background Screening: Using the function screening and selectComponents to select the Components that most likely do not originate from background noise.

2. Model Selection: First, a set of spline models based on different number of splits and split positions are generated by the function lobraModelSelection. Subsequently, these models are evaluated using different quality criteria, i.e. 'AIC', 'BIC' and 'LogLik'. Finally, the most appropriate model is selected.

3. Evaluation of the non-background components on the selected model, using the longitudinal 'Gouderman' linear mixed effect model in function modelGoudermanLongitudinal.

Author(s)

Maintainer: Anne-Christin Hauschild [Copyright holder]

Authors:

• Sandrah P. Eckel

• Jan Baumbach

Transformation of a single longitudinal data matrix into 'LoBrA' Data Object.

Description

Real signals and background noise originating from experimental settings or random events

Usage

as.LOBdataset(
  longData,
  name = "",
  id = "id",
  time = "time",
  type = "type",
  class = "class",
  bg = FALSE
)

Arguments

Value

'LoBrA' data object

Examples

## Not run: 
 
  data(LoBraExample)
  name="Longitudinal Test Dataset"
  ldo<-as.LOBdataset(longDataExample, name, bg=TRUE)
  

'LoBrA' Data Object (LDO) for Example data set

Description

'LoBrA' example LDO created by the function 'createExampleData' and converted to an LDO by 'as.LOBdataset' function. It consist of a single matrix for all experiments, time points, types (background, experiment), class and the intensity values of all components created. The artificial data consist of 20 experiments and 100 components with 18 measurements (3 background, 15 sample). The 10 experiments are each associated to on of 2 groups (ONE and TWO). The components comprise 70 noise components and 30 components that randomly vary in their trajectories in one of three segments. Random noise is added to all intercepts, propagated and added to each time point for all samples and components separately.

Usage

components

Format

A vector of selected components from the longitudinal example data set.

Author(s)

Anne-Christin Hauschild hauschild@uni-marburg.de

Simulate background noise peaks

Description

Simulating background noise signals originating from experimental settings or random events

Usage

createBGComponents(
  components,
  samples,
  labels,
  timepoints = 15,
  bg = 3,
  mean = 5,
  sd = 3,
  experimentSD = 2,
  randomnoise = 0.1,
  plotting = FALSE
)

Arguments

Value

matrix of background components

Simulate background measurements

Description

Simulating background noise signals originating from experimental settings or random events

Usage

createBGData(samples = 10, bg = 3, mean = 0, sd = 1, randomnoise = 0.1)

Arguments

Value

matrix of background measurements

Create example data set for 'LoBrA'

Description

Real signals and background noise originating from experimental settings or random events

Usage

createExampleData(
  components = c(70, 10, 10, 10),
  samples = 10,
  classes = 2,
  bg = 3,
  timepoints = rep(5, 3),
  myfile = NA
)

Arguments

Value

final matrix of example data.

Examples

## Not run: 
 
  components = c(21,3,3,3)
  samples = 10
  classes = 2;
  bg = 3; 
  timepoints = rep(5,3)
  p=TRUE;
  longDataExample <- createExampleData(components, samples, classes, bg, 
                                       timepoints)
  dim(longDataExample)
  

Create the Gouderman Data Arrangement.

Description

Using the Gouderman methodology to create the Gouderman-Data Arrangement.

Usage

createGoudermanData(selectedLDO, breaks, center, timeperiod = NA, range = NA)

Arguments

Value

The function returns a 'GaudermanLDO' object. For more information @seealso 'GaudermanLDO' .

Examples

## Not run: 
 
  data(LoBraExample)
  selectedLDO <- selectComponents(ldo, components)
  breaks<- c(8, 12)
  center<- 12
  timeperiod <- 2;
  gaudermanLDOexample <- createGoudermanData(selectedLDO, breaks, center, timeperiod)
  

Simulate informative peaks

Description

This function simulates signals correlated to different informative events.

Usage

createInformativeComponents(
  components,
  samples,
  labels,
  timepoints = c(5, 5, 5),
  bg = 3,
  mean = 5,
  sd = 3,
  segment = 1,
  slopeSD = 2,
  randomnoise = 0.5,
  plotting = FALSE
)

Arguments

Value

matrix of informative components

Get colors for the plotting function.

Description

Get colors for the plotting function.

Usage

getColor(label, size)

Arguments

Value

col vector of colors created

Create Peak Matrices for Generalized 'Gauderman' linear mixed effect regression (LMER) Model with parameterized Times

Description

Create Peak Matrices for Generalized 'Gauderman' linear mixed effect regression (LMER) Model with parameterized Times

Usage

getGeneralizedGaudermanDataFrame(
  peakmatrix,
  sampleIds,
  classes,
  center,
  timeperiod,
  gaudermanRange,
  k
)

Arguments

Value

Return the new peak matrix data frame for this peak.

Extract the optimal spline model parameters from the ModelSelection Object.

Description

The method calculates which spline model and parameters worked best with respect to the median of the specified quality measure. The median is calculated among all component models.

Usage

getOptimalSpline(
  lobraModelSelectionObject,
  qualityMeasure = "AIC",
  summeryfun = stats::median
)

Arguments

Value

The function returns a 'lobraModelSelectionObject' that contains the optimal model according to the specified quality measure. @seealso plot.modelSelectionEvaluation

Examples

## Not run: 
 
  data(LoBraExample)
  selectedLDO <- selectComponents(ldo, components)
  potentialBreaks=c(8, 12)
  nknots=c(1, 2)
  qualityMeasure=c("AIC", "BIC")
  ldoSelect<- lobraModelSelection(selectedLDO, potentialBreaks, nknots, qualityMeasure)
  
  optimalAIC<-getOptimalSpline(ldoSelect, qualityMeasure="AIC", summeryfun=stats::median)
  message(optimalAIC@breaks);
  
  optimalBIC<-getOptimalSpline(ldoSelect, qualityMeasure="BIC", summeryfun=base::mean)
  hist(unlist(optimalBIC@quality));

Testing differences of groups with respect to a specific value and test.

Description

Testing differences of groups with respect to a specific value and test.

Usage

getPvalue(y, group, test)

Arguments

'LoBrA' Data Object (LDO) for Example data set

Description

'LoBrA' example LDO created by the function 'createExampleData' and converted to an LDO by 'as.LOBdataset' function. It consist of a single matrix for all experiments, time points, types (background, experiment), class and the intensity values of all components created. The artificial data consist of 20 experiments and 100 components with 18 measurements (3 background, 15 sample). The 10 experiments are each associated to on of 2 groups (ONE and TWO). The components comprise 70 noise components and 30 components that randomly vary in their trajectories in one of three segments. Random noise is added to all intercepts, propagated and added to each time point for all samples and components separately.

Usage

ldo

Format

A matrix representing 20 experiments. It contains values for 100 variables at 18 time points for each experiment. Object of class LDO.

Author(s)

Anne-Christin Hauschild hauschild@uni-marburg.de

Evaluation of different spline variants.

Description

The model selection method evaluates which spline models achieve the best quality among all tested metabolites.

Usage

lobraModelSelection(
  selectedLDO,
  potentialBreaks = c(),
  nknots = c(0, 1, 2),
  splinetype = "linear",
  qualityMeasure = c("AIC", "BIC", "logLik")
)

Arguments

Value

LDOmodelselection Object. For each quality measure the model list contains a list of models for each spline tested. Additionally, the output contains a matrix of qualities for each Spline Component pair. And finally there is a list of breaks for each spline tested.

Examples

## Not run: 
 
  data(LoBraExample)
  potentialBreaks <- c(8,12)
  selectedLDO <- selectComponents(ldo, components)
  ldoSelect<- lobraModelSelection(selectedLDO, potentialBreaks, nknots=c( 1, 2))
  length(ldoSelect@ldo@peaknames)
  
  

'LoBrA' Example Data Set

Description

'LoBrA' example data set created by the function 'createExampleData'. #' It consist of a single matrix for all experiments, time points, types (background, experiment), class and the intensity values of all components created. The artificial data consist of 20 experiments and 100 components with 18 measurements (3 background, 15 sample). The 10 experiments are each associated to on of 2 groups (ONE and TWO). The components comprise 70 noise components and 30 components that randomly vary in their trajectories in one of three segments. Random noise is added to all intercepts, propagated and added to each time point for all samples and components separately.

Usage

longDataExample

Format

A matrix representing 20 experiments. It contains values for 100 variables at 18 time points for each experiment.

id

Experiment identifier

time

Time Point of Measurement

type

Type of Measurement (e.g. Background, or Sample measurement for each experiment)

class

Class or Group id of the sample/ experiment

bgcomponent-x

70 random variables that represent the background noise of the experiments

components-x-x

30 components that randomly vary in their trajectories in one of three time periods, (1:4-8, 2:9-13, 3:14-18).

...

Author(s)

Anne-Christin Hauschild hauschild@uni-marburg.de

Fitting the Gouderman LME Model with using Gouderman-Data Arrangement.

Description

Uses the linear mixed effects modeling to build the final 'Gauderman' model. The 'Gauderman' modification enables the exact calculation of the significance of a specified section of the spline model.

Usage

modelGoudermanLongitudinal(mygaudermanLDO, correctionMethod = "bonferroni")

Arguments

Value

'GaudermanModelEvaluation' Results of the evaluation of the Fitted linear mixed effect models for the defined time periods.

Examples

  
  data(LoBraExample)
  selectedLDO <- selectComponents(ldo, components)
  gaudermanLDOexample <- createGoudermanData(selectedLDO, breaks=c(8, 12), center=12, timeperiod=2)
  evalResult<- modelGoudermanLongitudinal(gaudermanLDOexample)
  message(evalResult@correctedpvalues<0.005)
  

Plotting helper function to plot a single generalized gouderman Model

Description

Plotting helper function to plot a single generalized gouderman Model

Usage

plotGaudermanModel(
  data,
  labels,
  ul,
  tempmodel,
  colores,
  maincol,
  breaks,
  main,
  ylab,
  xlab
)

Arguments

Plotting the 'Gouderman' LME Model and Results.

Description

Plotting the 'Gouderman' LME Model and Results.

Usage

plotGoudermanLongitudinalResults(
  evaluationresult,
  main = "Mixed Effect Spline Model Evaluation",
  ylab = "Value",
  xlab = "Time",
  peaknames = NULL
)

Arguments

Value

No return value

Examples

  
  wd <- tempdir()
  data(LoBraExample)
  selectedLDO <- selectComponents(ldo, components)
  gaudermanLDOexample <- createGoudermanData(selectedLDO, breaks=c(8, 12), center=12, timeperiod=2)
  evalResult<- modelGoudermanLongitudinal(gaudermanLDOexample)
  # Plot all peaks
  filename<- file.path(wd, "finalModelEvaluation.pdf") ;
  oldpar <- par("mfrow")
  grDevices::pdf(filename, width=16, height=8);
    graphics::par(mfrow=c(1,1));
    plotGoudermanLongitudinalResults(evalResult);
  par(mfrow = oldpar)
  grDevices::dev.off();
  
  #Plot a selection of Peaks
  peaknames<- evalResult@gaudermanLDO@peaknames;
  filename<- file.path(wd, "finalModelEvaluation-components.pdf") ;
  oldpar <- par("mfrow")
  grDevices::pdf(filename, width=20, height=8);
    graphics::par(mfrow=c(2,5));
    plotGoudermanLongitudinalResults(evalResult, main="", peaknames=peaknames);
  par(mfrow = oldpar)
  grDevices::dev.off();
 

Plotting the screening results.

Description

For each peak two box plots are created. The first plot shows a boxplot of the Sample Intercept Comparison of the sample and the background, and the corresponding p-values. The second plot shows a boxplot of the Residual Comparison of the sample and the background, and the corresponding p-values.

Usage

plotLDOScreening(
  ldoscreen,
  plotAll = FALSE,
  correctionmethod = "levene",
  decs = 3,
  ask = FALSE,
  peaknames = rownames(ldoscreen@selectedPeaks)
)

Arguments

Value

No return value

Examples

## Not run: 
 

  wd <- tempdir()
  data(LoBraExample)
  ldos<-screening(ldo, method= c('levene'), alpha =0.05, criteria=c(1,1))
  filename<- file.path(wd, "screeningresults.pdf") 
  grDevices::pdf(filename, width=16, height=8)
  plotLDOScreening(ldos)
  grDevices::dev.off();

Plotting function for a longitudinal data matrix (Internal Function)

Description

Plotting function for a longitudinal data matrix (Internal Function)

Usage

plotTimeSeries(
  myMatrix,
  main = "",
  labels = NA,
  ylab = "Expression",
  xlab = "Time Point",
  legend = "",
  col = 1:dim(myMatrix)[1]
)

Arguments

Value

No return value

Plotting results of Model Evaluation and Selection.

Description

Plotting the results of Model Evaluation and Selection. The plot shows a vertical boxplot for each spline tested starting with the best average fit according to the selected quality measure. The label of each spline can be found on the left, the median quality measure on the right. The x-axis denotes the selected quality measure.

Usage

plotmodelSelectionEvaluation(
  lobraModelSelectionObject,
  qualityMeasure,
  title = NULL
)

Arguments

Value

No return value

Examples

## Not run: 
 

wd <- tempdir()
data(LoBraExample)
selectedLDO <- selectComponents(ldo, components)
ldoSelect<- lobraModelSelection(selectedLDO, potentialBreaks=c(8, 12), nknots=c(1, 2))

filename<- file.path(wd, "evaluateBestSplineAIC.pdf") ;
grDevices::pdf(filename, width=16, height=8);
  plotmodelSelectionEvaluation(ldoSelect, "AIC", "Best Spline Models");
grDevices::dev.off();
  
qualityMeasure=c("AIC", "BIC", "logLik")
filename<- file.path(wd, "evaluateBestSplineAllMeasures.pdf") ;
grDevices::pdf(filename, width=16, height=8);
oldpar <- par("mfrow")
par(mfrow=c(3,1))
  plotmodelSelectionEvaluation(ldoSelect, qualityMeasure);
par(mfrow = oldpar)
grDevices::dev.off();

Creating the power set of a set.

Description

Creating the power set of a set.

Usage

powerSet(set)

Arguments

Value

Returns power set of the given set.

Screening of background or confounding components

Description

Background noise signals originating from experimental settings or random events can hugely influence the signal pattern of the breath. Background data enables the detailed evaluation and differentiation of the compounds originating primarily from the background or confounding factors as compared to those from the sample itself. The method assumes that all compounds of interest show a larger variation in the sample as compared to the background noise.

Usage

screening(
  ldo,
  method = c("bf", "levene", "bartlett"),
  alpha = 0.05,
  criteria = c(1, 1)
)

Arguments

Value

Returns an object of type 'LDOscreening' containing the original 'ldo' object and the results of the screening. The variable 'selectedPeaks' contains a matrix including the results (TRUE = Significant, FALSE = not Significant) of the specified tests ('bf', 'levene', 'bartlett').

Examples

## Not run: 
 

  data(LoBraExample)
  method= c('bf', 'levene', 'bartlett')
  alpha =0.05
  criteria=c(1,1)
  ldos<-screening(ldo, method, alpha, criteria)
  components <- ldos@selectedPeaks[,"levene"]
  components <- names(components)[components]
  selectedLDO <- selectComponents(ldo, components)

Create a new 'LDO' Object that only contains the selected components.

Description

Create a new 'LDO' Object that only contains the selected components.

Usage

selectComponents(ldo, components, name = paste(ldo@name, " selected"))

Arguments

Value

new ldo object only containing the selected components.