docs: update documentation

.Rbuildignore

@@ -6,3 +6,4 @@
 ^docs$
 ^pkgdown$
 ^\.github$
+pkgdown/

.gitignore

@@ -6,3 +6,4 @@ NetCoMi.Rproj
 .Renviron
 .Rprofile
 docs
+inst/doc

DESCRIPTION

@@ -2,6 +2,7 @@ Package: NetCoMi
 Type: Package
 Title: Network Construction and Comparison for Microbiome Data
 Version: 1.1.0
+Date: 2022-11-20
 Authors@R: c(
     person("Stefanie", "Peschel", email = "[email protected]", 
     role = c("aut", "cre"), comment = c(ORCID = "0000-0002-7936-7627")),
@@ -57,14 +58,17 @@ Suggests:
     ccrepe,
     DESeq2,
     discordant,
+    knitr,
     LaplacesDemon,
     limma,
     metagenomeSeq,
     metagMisc,
     propr,
+    rmarkdown,
     testthat,
     zCompositions
 RdMacros: Rdpack
 Encoding: UTF-8
 RoxygenNote: 7.3.2
 URL: https://stefpeschel.github.io/NetCoMi/
+VignetteBuilder: knitr

_pkgdown.yml

@@ -2,3 +2,16 @@ url: https://stefpeschel.github.io/NetCoMi/
 template:
   bootstrap: 5
 
+articles:
+- title: Main functionality
+  navbar: ~
+  contents:
+  - netcompare
+  - diffnet
+  - dissimilarity_networks
+
+- title: More examples
+  navbar: More examples
+  contents:
+  - asso_as_input
+  - soil_example

index.Rmd

@@ -0,0 +1,202 @@
+---
+output: github_document
+bibliography: references.bib
+---
+
+```{r setup, echo = FALSE}
+knitr::opts_chunk$set(fig.path="man/figures/readme/")
+```
+
+
+<!-- badges: start -->
+[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
+[![DOI](https://zenodo.org/badge/259906607.svg)](https://zenodo.org/badge/latestdoi/259906607)
+[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](https://anaconda.org/bioconda/r-netcomi)
+<!-- badges: end -->
+
+# NetCoMi <a href="https://stefpeschel.github.io/NetCoMi/"><img src="man/figures/logo.png" align="right" height="100" alt="NetCoMi website" /></a>
+
+NetCoMi (**Net**work **Co**nstruction and Comparison for **Mi**crobiome Data) 
+is an R package designed to facilitate the construction, analysis, and comparison of networks tailored to microbial compositional data. It implements a comprehensive workflow introduced in [Peschel et al. (2020)](https://academic.oup.com/bib/advance-article/doi/10.1093/bib/bbaa290/6017455), which guides users through each step of network generation and analysis with a strong emphasis on reproducibility and computational efficiency.
+
+With NetCoMi, users can construct microbial association or dissimilarity networks directly from sequencing data, typically provided as a read count matrix. The package includes a broad selection of methods for handling zeros, normalizing data, computing associations between microbial taxa, and sparsifying the resulting matrices. By offering these components in a modular format, NetCoMi allows users to tailor the workflow to their specific research needs, creating highly customizable microbial networks.
+
+The package supports both the construction, analysis, and visualization of single networks and the comparison of two networks through graphical and quantitative approaches, including statistical testing. Additionally, NetCoMi offers the capability of constructing differential networks, where only differentially associated taxa are connected.
+
+<img src="man/figures/networkplot_soil.png" width="800" />
+
+```{r networkplot, eval=FALSE, echo=FALSE, message=FALSE, warning=FALSE, fig.height=16, fig.width=29}
+library(phyloseq)
+library(NetCoMi)
+data("soilrep")
+
+soil_warm_yes <- phyloseq::subset_samples(soilrep, warmed == "yes")
+soil_warm_no  <- phyloseq::subset_samples(soilrep, warmed == "no")
+
+net_seas_p <- netConstruct(soil_warm_yes, soil_warm_no,
+                           filtTax = "highestVar",
+                           filtTaxPar = list(highestVar = 500),
+                           zeroMethod = "pseudo",
+                           normMethod = "clr",
+                           measure = "pearson",
+                           verbose = 0)
+
+netprops1 <- netAnalyze(net_seas_p, clustMethod = "cluster_fast_greedy",
+                        gcmHeat = FALSE)
+
+nclust <- as.numeric(max(names(table(netprops1$clustering$clust1))))
+
+col <- c(topo.colors(nclust), rainbow(6))
+
+plot(netprops1, 
+     sameLayout = TRUE, 
+     layoutGroup = "union", 
+     colorVec = col,
+     borderCol = "gray40", 
+     nodeSize = "degree", 
+     cexNodes = 0.9, 
+     nodeSizeSpread = 3, 
+     edgeTranspLow = 80, 
+     edgeTranspHigh = 50,
+     groupNames = c("Warming", "Non-warming"), 
+     showTitle = TRUE, 
+     cexTitle = 2.8,
+     mar = c(1,1,3,1), 
+     repulsion = 0.9, 
+     labels = FALSE, 
+     rmSingles = "inboth",
+     nodeFilter = "clustMin", 
+     nodeFilterPar = 10, 
+     nodeTransp = 50, 
+     hubTransp = 30)
+```
+
+> Exemplary network comparison using soil microbiome data (['soilrep' data from 
+phyloseq package](https://github.com/joey711/phyloseq/blob/master/data/soilrep.RData)). 
+Microbial associations are compared between the two experimantal settings 
+'warming' and 'non-warming' using the same layout in both groups. 
+
+### Methods included in NetCoMi
+
+Here is an overview of methods available for network construction, together with
+some information on their implementation in R:
+
+**Association measures:**
+
+- Pearson coefficient ([`cor()`](https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/cor) from `stats` package)
+- Spearman coefficient ([`cor()`](https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/cor) from `stats` package)
+- Biweight Midcorrelation [`bicor()`](https://rdrr.io/cran/WGCNA/man/bicor.html) from `WGCNA` package
+- SparCC ([`sparcc()`](https://rdrr.io/github/zdk123/SpiecEasi/man/sparcc.html) from `SpiecEasi` package)
+- CCLasso ([R code on GitHub](https://github.com/huayingfang/CCLasso))
+- CCREPE ([`ccrepe`](https://bioconductor.org/packages/release/bioc/html/ccrepe.html) package)
+- SpiecEasi ([`SpiecEasi`](https://github.com/zdk123/SpiecEasi) package)
+- SPRING ([`SPRING`](https://github.com/GraceYoon/SPRING) package)
+- gCoda ([R code on GitHub](https://github.com/huayingfang/gCoda))
+- propr ([`propr`](https://cran.r-project.org/web/packages/propr/index.html) package)
+
+**Dissimilarity measures:**
+
+- Euclidean distance ([`vegdist()`](https://www.rdocumentation.org/packages/vegan/versions/2.4-2/topics/vegdist) from `vegan` package)
+- Bray-Curtis dissimilarity ([`vegdist()`](https://www.rdocumentation.org/packages/vegan/versions/2.4-2/topics/vegdist) 
+from `vegan` package)
+- Kullback-Leibler divergence (KLD) ([`KLD()`](https://rdrr.io/cran/LaplacesDemon/man/KLD.html) 
+from `LaplacesDemon` package)
+- Jeffrey divergence (own code using [`KLD()`](https://rdrr.io/cran/LaplacesDemon/man/KLD.html) 
+from `LaplacesDemon` package)
+- Jensen-Shannon divergence (own code using [`KLD()`](https://rdrr.io/cran/LaplacesDemon/man/KLD.html) from `LaplacesDemon` package)
+- Compositional KLD (own implementation following @martin1999measure)
+- Aitchison distance ([`vegdist()`](https://www.rdocumentation.org/packages/vegan/versions/2.4-2/topics/vegdist) and [`clr()`](https://rdrr.io/github/zdk123/SpiecEasi/man/clr.html) from `SpiecEasi` package)
+
+**Methods for zero replacement:**
+
+- Add a predefined pseudo count to the count table
+- Replace only zeros in the count table by a predefined pseudo count (ratios between non-zero values are preserved)
+- Multiplicative replacement ([`multRepl`](https://rdrr.io/cran/zCompositions/man/multRepl.html) 
+from `zCompositions` package)
+- Modified EM alr-algorithm ([`lrEM`](https://rdrr.io/cran/zCompositions/man/lrEM.html) 
+from `zCompositions` package)
+- Bayesian-multiplicative replacement ([`cmultRepl`](https://rdrr.io/cran/zCompositions/man/cmultRepl.html) 
+from `zCompositions` package)
+
+**Normalization methods:**
+
+- Total Sum Scaling (TSS) (own implementation)
+- Cumulative Sum Scaling (CSS) ([`cumNormMat`]() from `metagenomeSeq` package)
+- Common Sum Scaling (COM) (own implementation)
+- Rarefying ([`rrarefy`]() from `vegan` package)
+- Variance Stabilizing Transformation (VST) ([`varianceStabilizingTransformation`]() from `DESeq2` package)
+- Centered log-ratio (clr) transformation ([`clr()`](https://rdrr.io/github/zdk123/SpiecEasi/man/clr.html) from 
+`SpiecEasi` package))
+
+TSS, CSS, COM, VST, and the clr transformation are described in [@badri2020shrinkage]. 
+
+## Installation
+
+```{r install, eval=FALSE}
+# Required packages
+install.packages("devtools")
+install.packages("BiocManager")
+
+# Install NetCoMi
+devtools::install_github("stefpeschel/NetCoMi", 
+                         dependencies = c("Depends", "Imports", "LinkingTo"),
+                         repos = c("https://cloud.r-project.org/",
+                                   BiocManager::repositories()))
+```
+
+If there are any errors during installation, please install the missing 
+dependencies manually.
+
+In particular the automatic installation of 
+[`SPRING`](https://github.com/GraceYoon/SPRING) and  [`SpiecEasi`](https://github.com/zdk123/SpiecEasi) (only available on 
+GitHub) does sometimes not work. These packages can be installed as follows 
+(the order is important because SPRING depends on SpiecEasi):
+
+```{r install2, eval=FALSE}
+devtools::install_github("zdk123/SpiecEasi")
+devtools::install_github("GraceYoon/SPRING")
+```
+
+Packages that are optionally required in certain settings are not installed 
+together with NetCoMi. These can be installed automatically using:
+
+```{r install3, eval=FALSE}
+installNetCoMiPacks()
+
+# Please check:
+?installNetCoMiPacks()
+```
+
+If not installed via `installNetCoMiPacks()`, the required package is installed
+by the respective NetCoMi function when needed.
+
+### Bioconda
+
+Thanks to [daydream-boost](https://github.com/daydream-boost), NetCoMi can also
+be installed from conda bioconda channel with
+
+```bash
+# You can install an individual environment firstly with
+# conda create -n NetCoMi
+# conda activate NetCoMi
+conda install -c bioconda -c conda-forge r-netcomi
+```
+
+## Development version
+
+Everyone who wants to use new features not included in any releases 
+is invited to install NetCoMi's development version:
+
+```{r install4, eval=FALSE}
+devtools::install_github("stefpeschel/NetCoMi", 
+                         ref = "develop",
+                         dependencies = c("Depends", "Imports", "LinkingTo"),
+                         repos = c("https://cloud.r-project.org/",
+                                   BiocManager::repositories()))
+```
+
+Please check the [NEWS](https://github.com/stefpeschel/NetCoMi/blob/develop/NEWS.md) 
+document for features implemented on develop branch.
+
+### References
+