# 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:

    library(BiocManager)
    BiocManager::install("combi", update = FALSE)

    library(devtools)
    install_github("CenterForStatistics-UGent/combi")

    suppressPackageStartupMessages(library(combi))
    cat("combi package version", as.character(packageVersion("combi")), "\n")

    ## combi package version 1.6.0

    data(Zhang)

## Unconstrained 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

    microMetaboInt

    ## 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 117 and 44.9

A simple plot function is available for the result, for samples and shapes, a data frame should also be supplied

    plot(microMetaboInt)

    plot(microMetaboInt, samDf = zhangMetavars, samCol = "ABX")

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:

    plot(microMetaboInt, samDf = zhangMetavars, samCol = "ABX", featurePlot = "points")

    plot(microMetaboInt, samDf = zhangMetavars, samCol = "ABX", featurePlot = "density")

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

    coords = extractCoords(microMetaboInt, Dim = c(1, 2))

## 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

    microMetaboIntConstr

    ## 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.2 and 21.4

and plot the ordination

    plot(microMetaboIntConstr, samDf = zhangMetavars, samCol = "ABX")

## Diagnostics

Convergence of the iterative algorithm can be assessed as follows:

    convPlot(microMetaboInt)

Influence of the different views can be investigated through

    inflPlot(microMetaboInt, samples = 1:20, plotType = "boxplot")

# Session info

This vignette was generated with following version of R:

    sessionInfo()

    ## R version 4.1.1 (2021-08-10)
    ## Platform: x86_64-w64-mingw32/x64 (64-bit)
    ## Running under: Windows Server x64 (build 17763)
    ##
    ## Matrix products: default
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.1252
    ## [3] LC_MONETARY=English_United States.1252
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.1252
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] combi_1.6.0
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] nlme_3.1-153                bitops_1.0-7
    ##   [3] matrixStats_0.61.0          phyloseq_1.38.0
    ##   [5] GenomeInfoDb_1.30.0         numDeriv_2016.8-1.1
    ##   [7] tools_4.1.1                 bslib_0.3.1
    ##   [9] utf8_1.2.2                  R6_2.5.1
    ##  [11] vegan_2.5-7                 mgcv_1.8-38
    ##  [13] DBI_1.1.1                   BiocGenerics_0.40.0
    ##  [15] colorspace_2.0-2            permute_0.9-5
    ##  [17] rhdf5filters_1.6.0          ade4_1.7-18
    ##  [19] tidyselect_1.1.1            compiler_4.1.1
    ##  [21] quantreg_5.86               Biobase_2.54.0
    ##  [23] formatR_1.11                SparseM_1.81
    ##  [25] alabama_2015.3-1            isoband_0.2.5
    ##  [27] DelayedArray_0.20.0         labeling_0.4.2
    ##  [29] sass_0.4.0                  scales_1.1.1
    ##  [31] quadprog_1.5-8              stringr_1.4.0
    ##  [33] digest_0.6.28               rmarkdown_2.11
    ##  [35] XVector_0.34.0              pkgconfig_2.0.3
    ##  [37] htmltools_0.5.2             MatrixGenerics_1.6.0
    ##  [39] highr_0.9                   fastmap_1.1.0
    ##  [41] limma_3.50.0                rlang_0.4.12
    ##  [43] farver_2.1.0                jquerylib_0.1.4
    ##  [45] generics_0.1.1              jsonlite_1.7.2
    ##  [47] dplyr_1.0.7                 RCurl_1.98-1.5
    ##  [49] magrittr_2.0.1              GenomeInfoDbData_1.2.7
    ##  [51] biomformat_1.22.0           Matrix_1.3-4
    ##  [53] Rcpp_1.0.7                  munsell_0.5.0
    ##  [55] S4Vectors_0.32.0            Rhdf5lib_1.16.0
    ##  [57] fansi_0.5.0                 ape_5.5
    ##  [59] lifecycle_1.0.1             stringi_1.7.5
    ##  [61] yaml_2.2.1                  nleqslv_3.3.2
    ##  [63] MASS_7.3-54                 SummarizedExperiment_1.24.0
    ##  [65] zlibbioc_1.40.0             BB_2019.10-1
    ##  [67] rhdf5_2.38.0                plyr_1.8.6
    ##  [69] grid_4.1.1                  parallel_4.1.1
    ##  [71] crayon_1.4.1                lattice_0.20-45
    ##  [73] Biostrings_2.62.0           splines_4.1.1
    ##  [75] tensor_1.5                  multtest_2.50.0
    ##  [77] knitr_1.36                  pillar_1.6.4
    ##  [79] igraph_1.2.7                GenomicRanges_1.46.0
    ##  [81] reshape2_1.4.4              codetools_0.2-18
    ##  [83] stats4_4.1.1                glue_1.4.2
    ##  [85] evaluate_0.14               cobs_1.3-4
    ##  [87] data.table_1.14.2           vctrs_0.3.8
    ##  [89] foreach_1.5.1               MatrixModels_0.5-0
    ##  [91] gtable_0.3.0                purrr_0.3.4
    ##  [93] assertthat_0.2.1            ggplot2_3.3.5
    ##  [95] xfun_0.27                   survival_3.2-13
    ##  [97] tibble_3.1.5                conquer_1.0.2
    ##  [99] iterators_1.0.13            IRanges_2.28.0
    ## [101] cluster_2.1.2               ellipsis_0.3.2