combi package: vignette
Introduction
This package implements a novel data integration model for sample-wise integration of different views. It accounts for compositionality and employs a non-parametric mean-variance trend for sequence count data. The resulting model can be conveniently plotted to allow for explorative visualization of variability shared over different views.
Installation
The package can be installed and loaded using the following commands:
suppressPackageStartupMessages(library(combi))
cat("combi package version",
as.character(packageVersion("combi")), "\n")## combi package version 1.19.0Unconstrained integration
For an unconstrained ordination, a named list of datasets with overlapping samples must be supplied. The datasets can currently be supplied as a raw data matrix (with features in the columns), or as a phyloseq, SummarizedExperiment or ExpressionSet object. In addition, information on the required distribution (“quasi” for quasi-likelihood fitting, “gaussian” for normal data) and compositional nature (TRUE/FALSE) should be supplied
microMetaboInt = combi(
list("microbiome" = zhangMicrobio, "metabolomics" = zhangMetabo),
distributions = c("quasi", "gaussian"), compositional = c(TRUE, FALSE),
logTransformGaussian = FALSE)One can print basic infor about the ordination
## Unconstrained combi ordination of 2 dimensions on 2 views with 42 samples.
## Views and number of features were:
## microbiome: 130
## metabolomics: 174
## Importance parameters of dimensions 1 to 2 are 115 and 46.3A simple plot function is available for the result, for samples and shapes, a data frame should also be supplied
By default, only the most important features (furthest away from the origin) are shown. To show all features, one can resort to point cloud plots or density plots as follows:
The drawback is that now no feature labels are shown.
Adding projections
As an aid to interpretation of compositional views, links between features can be plotted and projected onto samples by providing their names or approximate coordinates
#First define the plot, and return the coordinates
mmPlot = plot(microMetaboInt, samDf = zhangMetavars, samCol = "ABX", returnCoords = TRUE, featNum = 10)
#Providing feature names, and sample coordinates, but any combination is allowed
addLink(mmPlot, links = cbind("Staphylococcus_819c11","OTU929ffc"), Views = 1, samples = c(0,1))
Coordinates
Finally, one can extract the coordinates for use in third-party software
Constrained integration
For a constrained ordination also a data frame of sample variables should be supplied
microMetaboIntConstr = combi(
list("microbiome" = zhangMicrobio, "metabolomics" = zhangMetabo),
distributions = c("quasi", "gaussian"), compositional = c(TRUE, FALSE),
logTransformGaussian = FALSE, covariates = zhangMetavars)Also here we can get a quick overview
## Constrained combi ordination of 2 dimensions on 2 views with 42 samples.
## Views and number of features were:
## microbiome: 130
## metabolomics: 174
## Number of sample variables included was 4,
## for which 6 parameters were estimated per dimension.
## Importance parameters of dimensions 1 to 2 are 34.3 and 21.4and plot the ordination
FAQ
Why are not all my samples shown in the constrained ordination?
Confusion often arises as to why less distinct sample dots are shown than there are samples in the constrained ordination. This occurs when few, categorical constraining variables are supplied as below.
#Linear with only 2 variables
microMetaboIntConstr2Vars = combi(
list("microbiome" = zhangMicrobio, "metabolomics" = zhangMetabo),
distributions = c("quasi", "gaussian"), compositional = c(TRUE, FALSE),
logTransformGaussian = FALSE, covariates = zhangMetavars[, c("Sex", "ABX")])Every constrained sample score is a linear combination of constraining variables, and in this case there are only 2x2=4 distinct sample scores possible, leading to the sample dots from the same gender and treatment to be plotted on top of each other.
In general, it is best to include all measured sample variables in a constrained analysis, and let the combi-algorithm find out which ones are the most important drivers of variability.
The combi function crashes, what should I do
The combi method works by iteratively solving systems of non-linear equations through Newton-Raphson. This can lead to numerical instability, with errors like “infinite values returned by jacobian” in the nleqslv function. This class of problems has no general solution, but is mainly a matter of trial and error. Following two things can be tried:
- Tweaking the prevCutOff and minFraction parameters to remove more sparse features.
- Tweaking the initPower parameter, which will lead to different starting values, and hopefully a solution path that is numerically more stable.
Session info
This vignette was generated with following version of R:
## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] combi_1.19.0 DBI_1.2.3 rmarkdown_2.28
##
## loaded via a namespace (and not attached):
## [1] ade4_1.7-22 farver_2.1.2
## [3] Biostrings_2.75.0 fastmap_1.2.0
## [5] phyloseq_1.49.0 digest_0.6.37
## [7] lifecycle_1.0.4 cluster_2.1.6
## [9] survival_3.7-0 statmod_1.5.0
## [11] magrittr_2.0.3 compiler_4.4.1
## [13] rlang_1.1.4 sass_0.4.9
## [15] tools_4.4.1 igraph_2.1.1
## [17] utf8_1.2.4 yaml_2.3.10
## [19] data.table_1.16.2 knitr_1.48
## [21] BB_2019.10-1 labeling_0.4.3
## [23] S4Arrays_1.5.11 DelayedArray_0.31.14
## [25] alabama_2023.1.0 plyr_1.8.9
## [27] abind_1.4-8 withr_3.0.2
## [29] nleqslv_3.3.5 numDeriv_2016.8-1.1
## [31] BiocGenerics_0.53.0 sys_3.4.3
## [33] grid_4.4.1 stats4_4.4.1
## [35] fansi_1.0.6 multtest_2.61.0
## [37] biomformat_1.35.0 colorspace_2.1-1
## [39] Rhdf5lib_1.27.0 ggplot2_3.5.1
## [41] scales_1.3.0 iterators_1.0.14
## [43] MASS_7.3-61 isoband_0.2.7
## [45] SummarizedExperiment_1.35.5 cli_3.6.3
## [47] vegan_2.6-8 crayon_1.5.3
## [49] httr_1.4.7 reshape2_1.4.4
## [51] ape_5.8 cachem_1.1.0
## [53] rhdf5_2.49.0 stringr_1.5.1
## [55] zlibbioc_1.51.2 splines_4.4.1
## [57] parallel_4.4.1 XVector_0.45.0
## [59] matrixStats_1.4.1 vctrs_0.6.5
## [61] Matrix_1.7-1 jsonlite_1.8.9
## [63] SparseM_1.84-2 IRanges_2.39.2
## [65] S4Vectors_0.43.2 tensor_1.5
## [67] maketools_1.3.1 foreach_1.5.2
## [69] limma_3.61.12 jquerylib_0.1.4
## [71] glue_1.8.0 codetools_0.2-20
## [73] stringi_1.8.4 gtable_0.3.6
## [75] GenomeInfoDb_1.41.2 GenomicRanges_1.57.2
## [77] UCSC.utils_1.1.0 quadprog_1.5-8
## [79] munsell_0.5.1 tibble_3.2.1
## [81] pillar_1.9.0 cobs_1.3-8
## [83] htmltools_0.5.8.1 quantreg_5.99
## [85] rhdf5filters_1.17.0 GenomeInfoDbData_1.2.13
## [87] R6_2.5.1 evaluate_1.0.1
## [89] lattice_0.22-6 Biobase_2.67.0
## [91] highr_0.11 bslib_0.8.0
## [93] MatrixModels_0.5-3 Rcpp_1.0.13
## [95] permute_0.9-7 SparseArray_1.5.45
## [97] nlme_3.1-166 mgcv_1.9-1
## [99] xfun_0.48 MatrixGenerics_1.17.1
## [101] buildtools_1.0.0 pkgconfig_2.0.3