Package 'coda4microbiome'

Description

Microbial signatures in survival studies The algorithm performs variable selection through an elastic-net penalized Cox regression conveniently adapted to CoDA. The result is expressed as the (weighted) balance between two groups of taxa. It allows the use of non-compositional covariates.

Usage

coda_coxnet(
  x,
  time,
  status,
  covar = NULL,
  lambda = "lambda.1se",
  nvar = NULL,
  alpha = 0.9,
  nfolds = 10,
  showPlots = TRUE,
  coef_threshold = 0
)

Arguments

Value

list with "taxa.num","taxa.name","log-contrast coefficients","risk.score","apparent Cindex","mean cv-Cindex","sd cv-Cindex","risk score plot","signature plot".

Author(s)

M. Calle, M. Pujolassos, T. Susin

Examples

data(data_survival, package = "coda4microbiome")
time <- Event_time
status <- Event
set.seed(12345)
coda_coxnet(x = x,
           time = Event_time,
           status = Event,
           covar = NULL,
           lambda = "lambda.1se", nvar = NULL,
           alpha = 0.9, nfolds = 10, showPlots = TRUE, coef_threshold = 0)

Description

Microbial signatures in cross-sectional studies. The algorithm performs variable selection through penalized regression on the set of all pairwise log-ratios. The result is expressed as the (weighted) balance between two groups of taxa. It allows the use of non-compositional covariates.

Usage

coda_glmnet(
  x,
  y,
  covar = NULL,
  lambda = "lambda.1se",
  nvar = NULL,
  alpha = 0.9,
  nfolds = 10,
  showPlots = TRUE,
  coef_threshold = 0
)

Arguments

Value

if y is binary: list with "taxa.num","taxa.name","log-contrast coefficients","predictions","apparent AUC","mean cv-AUC","sd cv-AUC","predictions plot","signature plot" if not:list with "taxa.num","taxa.name","log-contrast coefficients","predictions","apparent Rsq","mean cv-MSE","sd cv-MSE","predictions plot","signature plot"

Author(s)

M. Calle - T. Susin

Examples

data(Crohn, package = "coda4microbiome")

set.seed(123)

coda_glmnet(x_Crohn[,(1:10)],y_Crohn,showPlots= FALSE)

Description

Microbial signatures in longitudinal studies. Identification of a set of microbial taxa whose joint dynamics is associated with the phenotype of interest. The algorithm performs variable selection through penalized regression over the summary of the log-ratio trajectories (AUC). The result is expressed as the (weighted) balance between two groups of taxa.

Usage

coda_glmnet_longitudinal(
  x,
  y,
  x_time,
  subject_id,
  ini_time,
  end_time,
  covar = NULL,
  lambda = "lambda.1se",
  nvar = NULL,
  alpha = 0.9,
  nfolds = 10,
  showPlots = TRUE,
  coef_threshold = 0
)

Arguments

Value

in case of binary outcome: list with "taxa.num","taxa.name","log-contrast coefficients","predictions","apparent AUC","mean cv-AUC","sd cv-AUC","predictions plot","signature plot","trajectories plot"

Author(s)

M. Calle - T. Susin

Examples

data(ecam_filtered, package = "coda4microbiome")   # load the data

ecam_results<-coda_glmnet_longitudinal (x=x_ecam[,(1:4)],y= metadata$diet,
x_time= metadata$day_of_life, subject_id = metadata$studyid, ini_time=0,
end_time=60,lambda="lambda.min",nfolds=4, showPlots=FALSE)

ecam_results$taxa.num

Description

Performs a permutational test for the coda_glmnet_longitudinal() algorithm: It provides the distribution of results under the null hypothesis by implementing the coda_glmnet_longitudinal() on different rearrangements of the response variable.

Usage

coda_glmnet_longitudinal_null(
  x,
  y,
  x_time,
  subject_id,
  ini_time,
  end_time,
  niter = 100,
  covar = NULL,
  alpha = 0.9,
  lambda = "lambda.1se",
  nfolds = 10,
  sig = 0.05
)

Arguments

Value

list with "accuracy" and "confidence interval"

Author(s)

M. Calle - T. Susin

Examples

set.seed(123) # to reproduce the results

data(ecam_filtered, package = "coda4microbiome")   # load the data

x=x_ecam # microbiome abundance
x_time = metadata$day_of_life    # observation times
subject_id = metadata$studyid   # subject id
y= metadata$diet           # diet ("bd"= breast diet, "fd"=formula diet)
ini_time = 0
end_time = 90

 coda_glmnet_longitudinal_null (x,y, x_time, subject_id, ini_time, end_time,
                                      lambda="lambda.min",nfolds=4, niter=3)

Description

internal function

Usage

coda_glmnet_longitudinal0(
  x,
  lrX,
  idlrX,
  nameslrX,
  y,
  x_time,
  subject_id,
  ini_time,
  end_time,
  covar = NULL,
  ktop = NULL,
  lambda = "lambda.1se",
  alpha = 0.9,
  nfolds = 10
)

Arguments

Value

.

Author(s)

M. Calle - T. Susin

Description

Performs a permutational test for the coda_glmnet() algorithm: It provides the distribution of results under the null hypothesis by implementing the coda_glmnet() on different rearrangements of the response variable.

Usage

coda_glmnet_null(
  x,
  y,
  niter = 100,
  covar = NULL,
  lambda = "lambda.1se",
  alpha = 0.9,
  sig = 0.05
)

Arguments

Value

a list with "accuracy" and "confidence interval"

Author(s)

M. Calle - T. Susin

Examples

data(Crohn, package = "coda4microbiome")

coda_glmnet_null(x=x_Crohn[,(1:10)], y=y_Crohn, niter=2,covar=NULL,lambda="lambda.1se",
                                                alpha=0.9,sig=0.05)

Description

Internal function for the permutational test

Usage

coda_glmnet0(
  x,
  lrX,
  idlrX,
  nameslrX,
  y,
  covar = NULL,
  lambda = "lambda.1se",
  alpha = 0.9
)

Arguments

Value

.

Author(s)

M. Calle - T. Susin

Description

This package provides a set of functions to explore and study microbiome data within the CoDA framework, with a special focus on identification of microbial signatures (variable selection).

Description

Microbiome composition at genus level from a Crohn's disease study: 48 taxa and 975 individuals (662 patients with Crohn's disease and 313 controls)

Format

The dataset contains two objects:

x_Crohn

microbiome abundance matrix for 975 individuals (rows) and 48 genera (columns)

y_Crohn

a factor, indicating if the sample corresponds to a case (CD) or a control (no).

References

doi:10.1016/j.chom.2014.02.005

Description

Microbiome composition at genus level from Early childhood and the microbiome (ECAM) study (Bokulich et al. 2016). Metadata and microbiome data were downloaded from https://github.com/caporaso-lab/longitudinal-notebooks. Filtered data contains information on 42 children and 37 taxa.

Format

The dataset contains three objects:

x_ecam

microbiome abundance matrix in long format (873 rows) and 37 genera (columns)

taxanames

vector containing the taxonomy of the 37 taxa

metadata

matrix with information on the individuals at the observation time

References

Bokulich et al. (2016). Antibiotics, birth mode, and diet shape microbiome maturation during early life. Sci Transl Med 8:343

Description

Survival Data simulated from the Crohn's disease original study: 48 taxa and 150 individuals

Format

The dataset contains three objects:

x

microbiome abundance matrix for 150 individuals (rows) and 48 genera (columns)

Event

a numeric, event occurrence. Vector (type: numeric or logical) specifying 0 or FALSE for no event occurrence, and 1 or TRUE for event occurrence.

Event_time

a numeric, time to event or follow up time for right censored data. Must be a vector (type:numeric) specifying time to event for each sample for right censored data.

References

doi:10.1016/j.chom.2014.02.005

Description

Survival Data simulated from the Crohn's disease original study: 48 taxa and 150 individuals

Format

The dataset contains three objects:

x

microbiome abundance matrix for 150 individuals (rows) and 48 genera (columns)

Event

a numeric, event occurrence. Vector (type: numeric or logical) specifying 0 or FALSE for no event occurrence, and 1 or TRUE for event occurrence.

Event_time

a numeric, time to event or follow up time for right censored data. Must be a vector (type:numeric) specifying time to event for each sample for right censored data.

References

doi:10.1016/j.chom.2014.02.005

Description

Explores the association of each log-ratio with the outcome. Summarizes the importance of each variable (taxa) as the aggregation of the association measures of those log-ratios involving the variable. The output includes a plot of the association of the log-ratio with the outcome where the variables (taxa) are ranked by importance

Usage

explore_logratios(
  x,
  y,
  decreasing = TRUE,
  measure = "AUC",
  covar = NULL,
  shownames = FALSE,
  maxrow = 15,
  maxcol = 15,
  showtitle = TRUE,
  mar = c(0, 0, 1, 0)
)

Arguments

Value

list with "max log-ratio","names max log-ratio", "order of importance", "name of most important variables", "association log-ratio with y" and "top log-ratios plot"

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

explore_logratios(x_HIV,y_HIV)

Description

Explores the association of summary (integral) of each log-ratio trajectory with the outcome. Summarizes the importance of each variable (taxa) as the aggregation of the association measures of those log-ratios involving the variable. The output includes a plot of the association of the log-ratio with the outcome where the variables (taxa) are ranked by importance

Usage

explore_lr_longitudinal(
  x,
  y,
  x_time,
  subject_id,
  ini_time,
  end_time,
  showPlots = FALSE,
  decreasing = TRUE,
  covar = NULL,
  shownames = FALSE,
  maxrow = 15,
  maxcol = 15,
  showtitle = TRUE,
  mar = c(0, 0, 1, 0)
)

Arguments

Value

list with "max log-ratio","names max log-ratio","order of importance","name of most important variables","association log-ratio with y","top log-ratios plot"

Author(s)

M. Calle - T. Susin

Examples

set.seed(123) # to reproduce the results

data(ecam_filtered, package = "coda4microbiome")   # load the data

x=x_ecam # microbiome abundance
x_time = metadata$day_of_life    # observation times
subject_id = metadata$studyid   # subject id
y= metadata$diet           # diet ("bd"= breast diet, "fd"=formula diet)
ini_time = 0
end_time = 90

ecam_logratios<-explore_lr_longitudinal(x,y,x_time,subject_id,ini_time,end_time)

Description

Provides the proportion of zeros for a pair of variables (taxa) in table x and the proportion of samples with zero in both variables. A bar plot with this information is also provided. Results can be stratified by a categorical variable.

Usage

explore_zeros(x, id1, id2, strata = NULL)

Arguments

Value

a list with the frequency table and the associated bar plot

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

explore_zeros(x_HIV,5,6)

explore_zeros(x_HIV,5,6, strata=y_HIV)

Description

Filters those individuals and taxa with enough longitudinal information

Usage

filter_longitudinal(
  x,
  taxanames = NULL,
  x_time,
  subject_id,
  metadata,
  ini_time = min(x_time),
  end_time = max(x_time),
  percent_indv = 0.7,
  min_obs = 3
)

Arguments

Value

list with filtered abundance table, taxanames and metadata

Author(s)

M. Calle - T. Susin

Examples

data(ecam_filtered, package = "coda4microbiome")   # load the data

x=x_ecam # microbiome abundance
x_time = metadata$day_of_life    # observation times
subject_id = metadata$studyid   # subject id
ini_time = 0
end_time = 360

data_filtered<-filter_longitudinal(x,taxanames,x_time, subject_id, metadata,
                                              ini_time, end_time, min_obs=4)

Description

Microbiome abundances (60 taxa and 155 individuals) from an HIV study (Noguera-Julian et al. 2016).

Format

The dataset contains three objects:

x_HIV

microbiome abundance matrix for 155 individuals (rows) and 60 genera (columns)

y_HIV

a factor, specifying if the individual is HIV positive or (Pos) or negative (Neg).

MSM_HIV

a factor, indicating sexual preferences: MSM (Men who have Sex with Men) or not (nonMSM).

References

doi:10.1016/j.ebiom.2016.01.032

Description

Simple imputation: When the abundance table contains zeros, a positive value is added to all the values in the table. It adds 1 when the minimum of table is larger than 1 (i.e. tables of counts) or it adds half of the minimum value of the table, otherwise.

Usage

impute_zeros(x)

Arguments

Value

x abundance matrix or data frame with zeros substituted by imputed positive values

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

x<-impute_zeros(x_HIV)

Description

Integral of the curve trajectory of subject_id in the interval a,b

Usage

integralFun(x, y, id, a, b)

Arguments

Value

matrix with integrals for each individual (rows) and each taxa (columns)

Author(s)

M. Calle - T. Susin

Description

Computes a large matrix with all the log-ratios between pairs of taxa (columns) in the abundance table

Usage

logratios_matrix(x)

Arguments

Value

list with matrix of log-ratios, matrix indicating the pairs of variables involved in each log-ratio, and a matrix indicating the names of the variables involved in each log-ratio.

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

lrHIV<-logratios_matrix(x_HIV[,(1:4)])

# matrix of log-ratios (first 6 rows and 6 columns):

lrHIV[[1]][1:6,1:6]

# variables involved in each log-ratio

head(lrHIV[[2]])

# names of the variables involved in each log-ratio

head(lrHIV[[3]])

Description

Microbiome composition at genus level from Early childhood and the microbiome (ECAM) study (Bokulich et al. 2016). Metadata and microbiome data were downloaded from https://github.com/caporaso-lab/longitudinal-notebooks. Filtered data contains information on 42 children and 37 taxa.

Format

The dataset contains three objects:

x_ecam

microbiome abundance matrix in long format (873 rows) and 37 genera (columns)

taxanames

vector containing the taxonomy of the 37 taxa

metadata

matrix with information on the individuals at the observation time

References

Bokulich et al. (2016). Antibiotics, birth mode, and diet shape microbiome maturation during early life. Sci Transl Med 8:343

Description

Microbiome abundances (60 taxa and 155 individuals) from an HIV study (Noguera-Julian et al. 2016).

Format

The dataset contains three objects:

x_HIV

microbiome abundance matrix for 155 individuals (rows) and 60 genera (columns)

y_HIV

a factor, specifying if the individual is HIV positive or (Pos) or negative (Neg).

MSM_HIV

a factor, indicating sexual preferences: MSM (Men who have Sex with Men) or not (nonMSM).

References

doi:10.1016/j.ebiom.2016.01.032

Description

Plot of the predictions of a fitted model: Multiple box-plot and density plots for binary outcomes and Regression plot for continuous outcome

Usage

plot_prediction(prediction, y, strata = NULL, showPlots = TRUE)

Arguments

Value

prediction plot

Author(s)

M. Calle - T. Susin

Examples

# prediction plot for the log-ratio between columns 3 and 32 on HIV status

data(HIV, package = "coda4microbiome")

x<-impute_zeros(x_HIV)

lr<-log(x[,3])-log(x[,32])

plot_prediction(lr, y_HIV)

Description

Plots samples ordered by microbial risk score values along time to event.

Usage

plot_riskscore(risk.score, x, time, status, showPlots = TRUE)

Arguments

Value

returns an object of class HeatmapList.

Author(s)

M. Calle, M. Pujolassos, T. Susin

Examples

set.seed(12345)

data(data_survival, package = "coda4microbiome")
time <- Event_time
status <- Event
crohn_cox <- coda_coxnet(x = x,
                         time = Event_time,
                         status = Event,
                         covar = NULL,
                         lambda = "lambda.1se", nvar = NULL,
                         alpha = 0.9, nfolds = 10, showPlots = TRUE, coef_threshold = 0)
plot_riskscore(risk.score = crohn_cox$risk.score,
                    x = x,
                    time = Event_time,
                    status =  Event,
                    showPlots = TRUE)


#-------------------------------------------------------------------------------

Description

Graphical representation of the variables selected and their coefficients

Usage

plot_signature(vars, coeff, showPlots = TRUE, varnames = NULL)

Arguments

Value

bar plot

Author(s)

M. Calle - T. Susin

Examples

plot_signature(c(2,10, 3, 15, 4), c(0.8, -0.1, 0.2, -0.6, -0.3))

Description

Graphical representation of the signature trajectories

Usage

plot_signature_curves(
  varNum,
  coeff,
  x,
  y,
  x_time,
  subject_id,
  ini_time,
  end_time,
  color = c("chocolate1", "slateblue2"),
  showLabel = TRUE,
  location = "bottomright",
  inset = c(0.01, 0.02),
  cex = 0.8,
  y.intersp = 0.7,
  main_title = NULL
)

Arguments

Value

trajectories plot

Author(s)

M. Calle - T. Susin

Examples

x=matrix(c(2, 3, 4, 1, 2, 5, 10, 20, 15, 30, 40, 12), ncol=2)
x_time = c(0,10,20,1,15, 25)
subject_id = c(1,1,1,2,2,2)
y=c(0,0,0,1,1,1)
plot_signature_curves(varNum=c(1,2), coeff=c(1,-1), x, y,x_time, subject_id,
                       ini_time=0, end_time=25)

Description

Plots survival curves stratifying samples based on their signature value. Signature value for stratification can be set by the user.

Usage

plot_survcurves(risk.score, time, status, strata.quantile = 0.5)

Arguments

Value

return an object of class ggsurvplot which is list containing the following: plot: the survival plot (ggplot object). table: the number of subjects at risk table per time (ggplot object). data.survplot: data used to plot the survival curves (data.frame). data.survtable: data used to plot the tables under the main survival curves (data.frame).

Author(s)

M. Calle, M. Pujolassos, T. Susin

Examples

set.seed(12345)

data(data_survival, package = "coda4microbiome")
time <- Event_time
status <- Event
crohn_cox <- coda_coxnet(x = x,
                         time = Event_time,
                         status = Event,
                         covar = NULL,
                         lambda = "lambda.1se", nvar = NULL,
                         alpha = 0.9, nfolds = 10, showPlots = TRUE, coef_threshold = 0)
plot_survcurves(risk.score = crohn_cox$risk.score,
                 time,
                 status,
                 strata.quantile = 0.5)


#-------------------------------------------------------------------------------

Description

Internal plot function

Usage

plotMedianCurve(iNum, iDen, X, Y, x_time, subject_id, ini_time, end_time)

Arguments

Value

.

Author(s)

M. Calle - T. Susin

Description

Microbiome composition (60 taxa and 151 individuals) and inflammatory parameter sCD14 from an HIV study (Noguera-Julian et al. 2016). A dataset containing the number of counts of 60 different genera in a group of 151 samples (including HIV - infected and non - infected patients).

Format

The dataset contains two objects:

x_sCD14

microbiome abundance matrix for 151 individuals (rows) and 60 genera (columns)

y_sCD14

a numeric variable with the value of the inflammation parameter sCD14 for each sample

References

Rivera-Pinto et al. (2018) Balances: a new perspective for microbiome analysis. mSystems 3 (4)

Description

Shannon information

Usage

shannon(x)

Arguments

Value

shannon information

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

shannon(x_HIV[1,])

Description

Shannon effective number of variables in a composition

Usage

shannon_effnum(x)

Arguments

Value

shannon information

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

shannon_effnum(x_HIV[1,])

Description

Shannon similarity between two compositions

Usage

shannon_sim(x, y)

Arguments

Value

shannon similarity (value between 0 and 1)

Author(s)

M. Calle - T. Susin

Examples

data(HIV, package = "coda4microbiome")

shannon_sim(x_HIV[1,],x_HIV[2,])

Description

Microbiome composition at genus level from Early childhood and the microbiome (ECAM) study (Bokulich et al. 2016). Metadata and microbiome data were downloaded from https://github.com/caporaso-lab/longitudinal-notebooks. Filtered data contains information on 42 children and 37 taxa.

Format

The dataset contains three objects:

x_ecam

microbiome abundance matrix in long format (873 rows) and 37 genera (columns)

taxanames

vector containing the taxonomy of the 37 taxa

metadata

matrix with information on the individuals at the observation time

References

Bokulich et al. (2016). Antibiotics, birth mode, and diet shape microbiome maturation during early life. Sci Transl Med 8:343

Description

Survival Data simulated from the Crohn's disease original study: 48 taxa and 150 individuals

Format

The dataset contains three objects:

x

microbiome abundance matrix for 150 individuals (rows) and 48 genera (columns)

Event

a numeric, event occurrence. Vector (type: numeric or logical) specifying 0 or FALSE for no event occurrence, and 1 or TRUE for event occurrence.

Event_time

a numeric, time to event or follow up time for right censored data. Must be a vector (type:numeric) specifying time to event for each sample for right censored data.

References

doi:10.1016/j.chom.2014.02.005

Description

Microbiome composition at genus level from a Crohn's disease study: 48 taxa and 975 individuals (662 patients with Crohn's disease and 313 controls)

Format

The dataset contains two objects:

x_Crohn

microbiome abundance matrix for 975 individuals (rows) and 48 genera (columns)

y_Crohn

a factor, indicating if the sample corresponds to a case (CD) or a control (no).

References

doi:10.1016/j.chom.2014.02.005

Description

Microbiome composition at genus level from Early childhood and the microbiome (ECAM) study (Bokulich et al. 2016). Metadata and microbiome data were downloaded from https://github.com/caporaso-lab/longitudinal-notebooks. Filtered data contains information on 42 children and 37 taxa.

Format

The dataset contains three objects:

x_ecam

microbiome abundance matrix in long format (873 rows) and 37 genera (columns)

taxanames

vector containing the taxonomy of the 37 taxa

metadata

matrix with information on the individuals at the observation time

References

Bokulich et al. (2016). Antibiotics, birth mode, and diet shape microbiome maturation during early life. Sci Transl Med 8:343

Description

Microbiome abundances (60 taxa and 155 individuals) from an HIV study (Noguera-Julian et al. 2016).

Format

The dataset contains three objects:

x_HIV

microbiome abundance matrix for 155 individuals (rows) and 60 genera (columns)

y_HIV

a factor, specifying if the individual is HIV positive or (Pos) or negative (Neg).

MSM_HIV

a factor, indicating sexual preferences: MSM (Men who have Sex with Men) or not (nonMSM).

References

doi:10.1016/j.ebiom.2016.01.032

Description

Microbiome composition (60 taxa and 151 individuals) and inflammatory parameter sCD14 from an HIV study (Noguera-Julian et al. 2016). A dataset containing the number of counts of 60 different genera in a group of 151 samples (including HIV - infected and non - infected patients).

Format

The dataset contains two objects:

x_sCD14

microbiome abundance matrix for 151 individuals (rows) and 60 genera (columns)

y_sCD14

a numeric variable with the value of the inflammation parameter sCD14 for each sample

References

Rivera-Pinto et al. (2018) Balances: a new perspective for microbiome analysis. mSystems 3 (4)

Description

Microbiome composition at genus level from a Crohn's disease study: 48 taxa and 975 individuals (662 patients with Crohn's disease and 313 controls)

Format

The dataset contains two objects:

x_Crohn

microbiome abundance matrix for 975 individuals (rows) and 48 genera (columns)

y_Crohn

a factor, indicating if the sample corresponds to a case (CD) or a control (no).

References

doi:10.1016/j.chom.2014.02.005

Description

Microbiome abundances (60 taxa and 155 individuals) from an HIV study (Noguera-Julian et al. 2016).

Format

The dataset contains three objects:

x_HIV

microbiome abundance matrix for 155 individuals (rows) and 60 genera (columns)

y_HIV

a factor, specifying if the individual is HIV positive or (Pos) or negative (Neg).

MSM_HIV

a factor, indicating sexual preferences: MSM (Men who have Sex with Men) or not (nonMSM).

References

doi:10.1016/j.ebiom.2016.01.032

Description

Microbiome composition (60 taxa and 151 individuals) and inflammatory parameter sCD14 from an HIV study (Noguera-Julian et al. 2016). A dataset containing the number of counts of 60 different genera in a group of 151 samples (including HIV - infected and non - infected patients).

Format

The dataset contains two objects:

x_sCD14

microbiome abundance matrix for 151 individuals (rows) and 60 genera (columns)

y_sCD14

a numeric variable with the value of the inflammation parameter sCD14 for each sample

References

Rivera-Pinto et al. (2018) Balances: a new perspective for microbiome analysis. mSystems 3 (4)