1- System requirements:

1.1- Operating systems: Windows, or Mac, or Linux, any versions which can run R (version >= 3.5)

1.2- Dependencis: R (version >=3.5; https://www.r-project.org/), R packages: vegan, parallel, permute, ape, bigmemory, nortest, minpack.lm, Hmisc, stats4. R package NST is necessary to run the funciton tNST and pNST in the demo, but not required for running package iCAMP.

1.3- iCAMP current version 1.2.4 has been tested on the current development version of R (4.1.0, 2020-8-18 r79041), R 4.0.2, and R 3.5.3.

1.4- Any required non-standard hardware: No. However, if you are dealing with a large dataset (e.g. >20,000 taxa), a server with enough CPU threads (e.g. >=20) is preferred to finish the calculation in reasonable time.


2- Installation guide

2.1- downlaod and install R (https://www.r-project.org/). Then, open R.

2.2- iCAMP will be available from CRAN soon. Then, you can install it directly in R with following code.

install.packages("iCAMP")

2.3- Or you can install iCAMP directly from file, 

2.3.1- you may use following code to install or update following packages. The package 'parallel' and 'stats4' are base packages, thus usually do not need to update.

install.packages(c("vegan", "permute", "ape", "bigmemory", "nortest", "minpack.lm", "Hmisc"))

2.3.2- In R, click Packages/install package from local file, then select the iCAMP source code file provided in this zip folder. For windows, select the .zip file. For Mac/Linux, select the .gz file.

       Alternatively, in Linux sytem, if you open R in a terminal, use following command to install from the .gz file (revise "/Path/to/the/folder" to the real path of this folder on your computer):

install.packages(pkgs="/Path/to/the/folder/iCAMP_1.2.4.tar.gz", repos = NULL, type="source")

2.4- The whole installation typically takes several minutes. Usually, <5 min for R installation, <1 min for the iCAMP package, <5 min for installation of other packages.


3- Demo

3.1- Please check the icamp.test.r in the example folder, and follow the detailed instruction in the file to run iCAMP analysis for the example data.

3.2- Expected output: example output files have been saved in the subfolder "TestOutputs16". Detailed explanation can also be found in the file "icamp.test.r".

Output files:
(1) path.rda: a R object to list all the nodes and  edge lengthes from root to every tip. saved in R data format. It is an intermediate output when claculating phylogenetic distance matrix.

(2) pd.bin: BIN file (backingfile) generated by function big.matrix in R package bigmemory. This is the big matrix storing pairwise phylogenetic distance values. By using this bigmemory format file, we will not need memory but hard disk when calling big matrix for calculation.

(3) pd.desc: the DESC file (descriptorfile) to hold the backingfile (pd.bin) description.

(4) pd.taxon.name.csv: comma delimited csv file storing the IDs of tree tips (OTUs), serving as the row/column names of the big phylogenetic distance matrix.

(5) ND.res.rda: a R object to save all the output of function "dniche" (niche differences among taxa). 

(6) nd.names.csv: comma delimited csv file storing the IDs of species (OTUs), serving as the row/column names of the big niche difference matrix.

(7) pH.ND.bin: BIN file (backingfile) generated from "dniche" by funciton big.matrix in R package bigmemory. This is the big matrix storing pairwise niche difference values based on pH values in environment.txt.

(8) pH.ND.desc: the DESC file (descriptorfile) to hold the backingfile (pH.ND.bin) description.

(9) temperature.ND.bin: BIN file (backingfile) generated from "dniche", storing pairwise niche difference values based on temperature values in environment.txt.

(10) temperature.ND.desc: the DESC file (descriptorfile) to hold the backingfile (temperature.ND.bin) description.

(11) Test.PhyloSignalSummary.csv: a table to summarize within-bin phylogenetic signal test results from "ps.bin". The indexes include relative abundance of bins with significant phylogenetic signal in all bins (RAsig) or in bins with species number larger than min.spn (RAsig.adj), average correlation coefficient in significant bins (MeanR.sig) or in all bins (MeanR).

(12) Test.PhyloSignalDetail.csv: a table to list all the correlation coefficient (r) and p value in each bin.

(13) Test.OmitBinInform.csv: a table about relative abundances of species in the small bins which have too few members and will be omitted if setting omit.option as omit.

(14) Test.iCAMP.Confidence.detail.rda: the object "icres" saved in R data format. it is a list object. The first element named CbMPDiCBraya is the result of relative importance of each assembly process in each pairwise comparison (each turnover), using Confidence for null model significance test. The second element "detail" including binning information (named taxabin), phylogenetic and taxonomic metrics results in each bin (named like SigbMPDi, SigBCa, etc.), relative abundance of each bin (bin.weight), relative importance of each process in each turnover between communities (processes), input settings (setting), and input community data matrix (comm). See help document of the function icamp.big for more details.

(15) Test.iCAMP.SES.RC.detail.rda: the object "icres2" saved in R data format. It is very similar to the file "Test.iCAMP.Confidence.detail.rda". The main difference is that the null model significance test used betaNRI and RCbray instead of Confidence. It also includes all the null model values.

(16)Test.MetaCrct.iCAMP.Confidence.detail.rda: the object "icres.meta" saved in R data format. It is a list object, where the meaning of each element is the same as in the file "Test.iCAMP.Confidence.detail.rda". It is calculated by specifying the relative abundance of each taxon in the regional pool, instead of using the average relative abundance from the community matrix as regional relative abundance.

(17) Test.iCAMP.Summary.rda: the object "icbin" saved in R data format. see help document of the function icamp.bins for description of each element in the object.

(18) Test.ProcessImportance_EachGroup.csv: Relative importance of each process in governing the turnovers in a group of samples.

(19) Test.ProcessImportance_EachBin_EachGroup.csv: Relative importance of each process in governing the turnovers of each bin among a group of samples.

(20) Test.ProcessImportance_EachTurnover.csv: Relative importance of each process in governing the turnovers between each pair of communities (samples).

(21) Test.BinContributeToProcess_EachGroup.csv: Bin contribution to each process, measuring the contribution of each bin to the relative importance of each process in the assembly of a group of communities.

(22) Test.iCAMP.Boot.Management.rda: the object "icboot" saved in R data format. see help document of the function icamp.boot for description of each element in the object.

(23) Test.iCAMP.BootSummary.Management.csv: a table to summarize bootstrapping results. see help document of the function icamp.boot for description of the output element "summary".

(24) Test.iCAMP.Compare.Management.csv: a table to summarize comparison index, effect size, and significance between each two groups. see help document of the function icamp.boot for description of the output element "compare".

(25) Test.QPEN.detail.csv: a table to show betaMNTD, Bray-Curtis dissimilarity, betaNTI, RC, and governing assembly process for each turnover between communities, calculated by QPEN (quantifying community assembly processes based on entire-community null model analysis). Please find details in the help document of function 'qpen' in package 'iCAMP'.

(26) Test.NeutralModel.Stats.csv: Neutral taxa percentage results, showing estimated dispersal rate and model fitting statistics. Please find details in the help document of function 'snm' in package 'iCAMP'.

(27) Test.NeutralModel.TypeRatio.csv: Neutral taxa percentage results, showing unweighted and abundance-weighted percentage of taxa within, above, and below the confidence interval of occurrence frequencies estimated by neutral theory model. Please find details in the help document of function 'snm' in package 'iCAMP'.

(28) Test.tNST.summary.Management.csv: taxonomic normalized stochasticity ratio (tNST) results, showing the estimated tNST in each group (treatment). Please find details in the help document of function 'tNST' in package 'NST'.

(29) Test.tNST.pairwise.Management.csv: tNST results, showing standardized similarity, null expectation of the similarity, stochasticity ratio, normalized stochasticity ratio, and modeified normalized stochasticity ratio for each pairwise comparison between communities. Please find details in the help document of function 'tNST' in package 'NST'.

(30) Test.tNST.bootstr.Management.csv: tNST bootstrapping test results, showing the variation (mean, standard deviation, quartiles, outliers, etc.) of tNST in each group (treatment). Please find details in the help document of function 'nst.boot' in package 'NST'.

(31) Test.tNST.compare.Management.csv: tNST bootstrapping test results, showing the significance of tNST difference between groups (treatments). Please find details in the help document of function 'nst.boot' in package 'NST'.

(32-35) Test.pNST.summary.Management.csv, Test.pNST.pairwise.Management.csv, Test.pNST.bootstr.Management.csv, and Test.pNST.compare.Management.csv: phylogenetic normalized stochasticity ratio (pNST) results, the same as those for tNST. Please find details in the help document of function 'pNST' and 'nst.boot' in package 'NST'.

3.3- Expected run time: 6 to 12 min in a normal desktop computer.


4- Instractions for use

To analyze your own data with iCAMP, 

(1) Check the format of the example data files (otu.txt, tree.nwk, treat2col.txt, and environment.txt) in the folder "Example". Revise your data files to the same format. It is fine if you do not have environment factor information, just pay attention to the notes specific to no env.file situation in the "icamp.test.r".

(2) Change the folder paths and file names in the "icamp.test.r" as indicated. 

(3) Change the thread number for parallel computing, memory limitation, and other parameter setting according to your need. You may check the help document of each function for detailed explanation.

(4) Run the codes, skip some steps if not applicable, and check the output files in the output folder you've specified.




