Merge pull request #87 from TheoreticalEcology/Change-PhyloSim-packag…

…e.RD-to-R-file-with-Roxygen

Changed main package documentation from .Rd file to .R file

Fixes #86

.gitignore

@@ -12,7 +12,6 @@ workspace/
 .Rproj.user
 PhylGeo.Rcheck/00_pkg_src
 00check.log
-phylosim.Rproj
 RcppExports.cpp
 
 .Rhistory

PhyloSim/DESCRIPTION

@@ -2,8 +2,8 @@ Package: PhyloSim
 Type: Package
 Title: Analysis of Phylogenetic and Biogeographic patterns, inferring species
     community assembly
-Version: 0.3
-Date: 2015-02-12
+Version: 0.3.0.1
+Date: 2024-01-19
 Authors: c(person("Paul", "Bauche", role = c("aut","cre")),
     person("Florian", "Hartig", role = "aut"),
     person("Christian", "Buschbeck", role = "ctb"),
@@ -34,7 +34,8 @@ Imports:
 Suggests:
     knitr
 LinkingTo: Rcpp
+RoxygenNote: 7.3.0
+Roxygen: list(old_usage = TRUE, markdown = TRUE)
 LazyData: true
 VignetteBuilder: knitr
-LinkingTo: Rcpp
-RoxygenNote: 6.0.1
+Encoding: UTF-8

PhyloSim/R/PhyloSim-package.R

@@ -0,0 +1,28 @@
+#' @keywords internal
+#' @title Analysing phylogenetic and biogeographic patterns and inferring species community assembly 
+#' @name PhyloSim
+#' @useDynLib PhyloSim, .registration = TRUE
+#' @description
+#' This package is designed to simulate and analyse species community assembly processes. It allows the user to implement different mechanisms of community assembly such as environmental filtering, competitive exclusion or dispersal limitation. These mechanisms can be combined or activated seprately, which allows the user to identify biogeographic or phylogenetic patterns exclusively correlated with a certain mechanism or combination of mechanisms.
+#' @details
+#' The core of this package is basically a community assembly model, which can be run with \code{\link{runSimulation}} or \code{\link{runSimulationBatch}}. All other functions help analize and visualize the model outcome. For visualization the following functions can be useful:
+#'\tabular{ll}{
+#'  \code{\link{plotSpatialPhylo}} \tab Plots the phylogeny tree ,the spatially abundance of the evolved species and their traits.\cr
+#'  \code{\link{rac}} \tab Plots the Rank Abundance Curve for a given community\cr
+#'  \code{\link{sac}} \tab Plots the species area curve for a given community\cr
+#'  \code{\link{plotclades}} \tab Visualises the phylogenetic clades of a local community within a metacommunity.\cr
+#'  \code{\link{plotTraitDistribution}} \tab Plots trait-histograms, trait ~ Environment relationship and the spatial distribution of the different traits\cr
+#'}
+#'
+#'
+#'The function \code{\link{phyloReconstruct}} creates a phylogeny from given neutral traits of a community in order to compare them with the existing phylogeny. The observed patterns in the simulation output can be tested against null models using the function \code{\link{nullModel}}.
+#'
+#'
+#' @author Paul Bauche, Florian Hartig
+#' 
+#' @example /inst/examples/phylosim-help.R
+#'  
+"_PACKAGE"
+## usethis namespace: start
+## usethis namespace: end
+NULL

PhyloSim/R/createPhylosimList.R

@@ -3,21 +3,7 @@
 #' @param simu List of objects of type Phylosim as created by \code{\link{runSimulation}}
 #' @return An object of type PhylosimList
 #' @details The function is used to make functions for objets of type "PhylosimList" usable for objects of class "Phylosim". The function needs at least two objets to work.  
-#' @examples 
-#' ## Create two objects of type Phylosim
-#' par1 <- createCompletePar(x = 50, y = 50, dispersal = "global" , runs = 500,
-#'         density = 1, environment = 0.5, specRate = 1)
-#' par2 <- createCompletePar(x = 50, y = 50, dispersal = "global" , runs = 500,
-#'         density = 1, environment = 0.5, specRate = 2)
-#'         
-#' simu1 <- runSimulation(par1)
-#' simu2 <- runSimulation(par2)
-#' 
-#' ## Use the function
-#' simuList <- createPhylosimList(list(simu1,simu2))
-#' 
-#' ## The object can now be handed to functions designed for objects of type "PhylosimList".
-#'  
+#' @example /inst/examples/createPhylosimList-help.R
 #' @export
 
 

PhyloSim/R/localPlots.R

@@ -9,7 +9,7 @@
 #' @param nested Logical, determining whether the subplots should be nested (see Details).
 #' @return A list of subplots and (if coomunity = T) a community table with plots in rows and species in collumns
 #' @details If nested == TRUE the subplots are poduced in a sequential order. That means if your 'size' argument has the length 5 and your 'n' argument has the size 2 you will get ten subplots. The first five will be one group of nested plots and the last five the second group of nested plots.
-#' @example inst/examples/localPlots.R
+#' @example inst/examples/localPlots-help.R
 #' @export
 localPlots <- function(simu, which.result=NULL,size, n, community = FALSE, plot = FALSE, nested = FALSE){
 

PhyloSim/R/neutralModelR.R

@@ -7,22 +7,8 @@
 #' @param runs The number of generations the model runs through
 #' @references Hubbell, Stephen P. The unified neutral theory of biodiversity and biogeography (MPB-32). Vol. 32. Princeton University Press, 2001.
 #' @details This model is to be seen only for test and teaching purpose. However, if you want to use the results for further analysis please call the model with \code{\link{runSimulation}}. \cr\cr  Be careful with the dimensions you choose. Large grids and many generations may take very long to compute. You can assume to have reached the equilibrium state of the model after dim^2/2.  
-#' @examples
-#' # Run the model
-#' metaCom <- NeutralMod(xdim=50, ydim=50, specRate=2, seed=1500, runs=500)
-#' image(metaCom)
-#' 
-#' # Usually the function is called by the runSimualtion function
-#' # Define a parameter set
-#' parNeut <- createCompletePar(x = 50, y = 50, dispersal = FALSE , runs = 500,
-#'         density = 1, environment = 0.5, specRate = 1, type="Rneutral")
-#'
-#' # Run the model
-#' simuNeut <- runSimulation(parNeut)
-#' 
-#' # Visualize the grid
-#' image(simuNeut$Output[[1]]$specMat)
-#' 
+#' @example /inst/examples/neutralModelR-help.R
+
 #' @export
 NeutralMod <- function(  xdim = 100, ydim=100, specRate = 2,  seed = NULL, runs = 500 ){
 
@@ -49,4 +35,4 @@ NeutralMod <- function(  xdim = 100, ydim=100, specRate = 2,  seed = NULL, runs
   }
   print (paste("Finished after",floor(((proc.time() - ptm)[3])/60), "minute(s) and", ((proc.time() - ptm)[3])%%60, "second(s)."))
   return (mat)
-}
+}

PhyloSim/R/nullModel.R

@@ -8,36 +8,8 @@
 #' @param repetitions number of generated null model plots
 #' @param fun String, phylogenetic measure that is used. Possible inputs are "mpd" (\code{\link[picante]{mpd}}) and "pd" (\code{\link[picante]{pd}}). Only used if abundance = FALSE.  
 #' @return A numeric vector with pValues for each plot in the observed metacommunity
-#' @examples 
-#' 
-#' ### Usage with runSimulation
-#' ## Define a parameter set
-#' par <- createCompletePar(x = 50, y = 50, dispersal = 0 , runs = c(500,1000), density = 1, environment = 0.5, specRate = 1)
-#' 
-#' ## Run Model
-#' simu <- runSimulation(par)
-#' 
-#' ## Compare to null model
-#' nullModel(simu, abundance= FALSE, localPlotSize = 100, numberOfPlots = 10, repetitions = 10)
-#' 
-#' ## Usage with runSimulationBatch
-#' ## Define two (or multiple) parameter sets
-#' par1 <- createCompletePar(x = 50, y = 50, dispersal = 0 , runs = c(500,1000),
-#'         density = 1, environment = 0.5, specRate = 1) 
-#' par2 <- createCompletePar(x = 50, y = 50, dispersal = 0 , runs = c(500,1000),
-#'         density = 2, environment = 0.5, specRate = 1)
-#' 
-#' ## Merge the parameter sets. It is important to note, that the funktion
-#' ## needs a list of parameter sets.
-#' par <- list(par1,par2)
-#' 
-#' ## Run the model
-#' simubatch <- runSimulationBatch(par, parallel=2) 
-#' 
-#' ## Compare results to null model
-#' nullModel(simubatch[[1]],localPlotSize = 100, numberOfPlots = 10, repetitions = 10)
-#' nullModel(simubatch[[2]],localPlotSize = 100, numberOfPlots = 10, repetitions = 10)
-#' 
+#' @example /inst/examples/nullModel-help.R
+
 #' @export
 nullModel <- function(simu, which.result=NULL, abundance = FALSE, localPlotSize, numberOfPlots, repetitions, fun="mpd"){
 

PhyloSim/R/parCreator.R

@@ -23,14 +23,7 @@
 #' @param prunePhylogeny Logical, determining whether the phylogeny should be prune by the internal pruning function
 #' @details If runs is a sequence of generations the intermediate and end results are saved in the output of \code{runSimulation}. \cr\cr If type = "Rneutral" the model will run entirely in R. This model is to be seen only for test and teaching purpose. To be used in practice it is far too slow. Also the output is reduced. Only the species landscape and the parameter settings will be displayed in the output.
 #' @return A List with parameters
-#' @examples 
-#' ## Define a parameter set
-#' par <- createCompletePar(x = 50, y = 50, dispersal = FALSE , runs = c(500,1000),
-#'         density = 1, environment = 0.5, specRate = 1)
-#'
-#' ## Run the model
-#' simu <- runSimulation(par)
-#' 
+#' @example /inst/examples/parCreator-help.R
 #' @export
 
 createCompletePar <- function(x = 50, y = 50, dispersal = "global", runs = 100, specRate = 1.0, density = 0, environment = 0, fitnessActsOn = "mortality" , fitnessBaseMortalityRatio = 10, densityCut = 1, seed=NULL,  type = "base", fission = 0, redQueen = 0, redQueenStrength = 0, protracted = 0, airmat = 1, scenario = NULL, calculateSummaries = FALSE, convertToBinaryTree = TRUE, prunePhylogeny = TRUE){

PhyloSim/R/phylogeneticDispersion.R

@@ -7,24 +7,9 @@
 #' @param types String, determines which null model should be created. Possible inputs are "PhylMeta" (default), "PhylSample", "PhylPool", "SamplePool" (see details). 
 #' @param which.result Integer, determines which result should be used. This argument is only usefull if your 'runs' argument in \code{\link{createCompletePar}} contains more than one element. By default (NULL), the last result is used. You can choose a particular result, a vector of results, or use all result with which.result = "all".
 #' @param fun String, determines which function should be used to calculate the phylogenetic diversity in the sample plot. Possible inputs are "mpd" or "pd" (see details).
-#' @details In the types argument "PhylMeta" is equivalent to \code{\link{nullModel}} with abundance = FALSE, "PhylSample" is equivalent to the same function with abundance = TRUE, wheras the two other option use \code{\link[picante]{ses.mpd}}. "PhylPool" uses the argument null.model = "phylogeny.pool", "SamplePool" is setting null.model to "sample.pool". \cr\cr The fun argument is only used if types="PhylSample". For more information see \code{\link{nullModel}}. \cr \cr If yu choose which.result = NULL (default), the length of the output corresponds to the length of the 'runs' argument in your parameter definition. Otherwise the length of the list corresponds to the length of your which.result argument. \cr\cr The structure of the output is organitzed as follows with output[[n]] you will get the results for the scenario 'n'. With output[[n]][[t]] you will get the results for 'n' at timestep 't'. output[[n]][[t]] is a list that contains one vector with p values for each element in the plotlengths argument.
+#' @details In the types argument "PhylMeta" is equivalent to \code{\link{nullModel}} with abundance = FALSE, "PhylSample" is equivalent to the same function with abundance = TRUE, wheras the two other option use \code{\link[picante]{ses.mpd}}. "PhylPool" uses the argument null.model = "phylogeny.pool", "SamplePool" is setting null.model to "sample.pool". \cr\cr The fun argument is only used if types="PhylSample". For more information see \code{\link{nullModel}}. \cr \cr If yu choose which.result = NULL (default), the length of the output corresponds to the length of the 'runs' argument in your parameter definition. Otherwise the length of the list corresponds to the length of your which.result argument. \cr\cr The structure of the output is organitzed as follows with `output[[n]]` you will get the results for the scenario 'n'. With `output[[n]][[t]]` you will get the results for `n` at timestep `t`. `output[[n]][[t]]` is a list that contains one vector with p values for each element in the plotlengths argument.
 #' @return A list with pValues for each plot in the observed metacommunity. If you have calculated multiple scenarios, the results can be visualized by \code{\link{plotPhylogeneticDisperion}}.
-#' @examples 
-#' ## Create a set of parameters
-#' par1 <- createCompletePar(x = 50, y = 50, dispersal = 0 , runs = c(500,1000),
-#'         density = 0, environment = 0.5, specRate = 1) 
-#' par2 <- createCompletePar(x = 50, y = 50, dispersal = 0 , runs = c(500,1000),
-#'         density = 1, environment = 0.5, specRate = 1)
-#' 
-#' ## Merge the parameter sets. 
-#' par <- list(par1,par2)
-#' 
-#' ## Run the model
-#' simu <- runSimulationBatch(par, parallel = 2) 
-#' 
-#' ## Calculate null model and compare the observed results against
-#' pValues <- calculatePhylogeneticDispersion(simu, plotlength=20, plots=20, replicates=20, type="PhylMeta")
-#' 
+#' @example /inst/examples/phylogeneticDispersion-help.R
 #' 
 #' @export
 

PhyloSim/R/plotHighlightLocalPhylo.R

@@ -7,37 +7,7 @@
 #' @param subplot if no simu object is given, a communitytable of a local community can be given here
 #' @param phylogeny if no simu object is ginve, an object of the class 'phylo' can be given here to describe the communites phylogeny
 #' @details This function works with a single simu object (class "phylosim"). If no simu object is given, it is also possible to calculate the clades from a given phylogeny and localc plots. Here the phylogeny represents the metacommunity wihtin which the local plots create the clades
-#' @examples  
-#' 
-#' #Load data
-#' data(simu.neutral.global)
-#' data(simu.neutral.local)
-#' data(simu.envcom.local)
-#' 
-#'  
-#' 
-#' #Plot clades for neutral model with global dispersal with three subplots
-#' par(mfrow=c(1,3))
-#' highlightLocalPhylo(simu.neutral.global, size = 50, n = 3) 
-#' 
-#'  
-#'
-#' #Plot clades for neutral model with local dispersal with three subplots
-#' par(mfrow=c(1,3))
-#' highlightLocalPhylo(simu.neutral.local, size = 50, n = 3) 
-#' 
-#'  
-#'
-#'#Plot clades for environment and competition model with global dispersal with three subplots
-#' par(mfrow=c(1,3))
-#' highlightLocalPhylo(simu.envcom.local, size = 50, n = 3) 
-#' 
-#'  
-#'
-#'#increasing plot size
-#'par(mfrow=c(2,2))
-#'highlightLocalPhylo(simu.envcom.local, size = 50, n =2)
-#'highlightLocalPhylo(simu.envcom.local, size = 1000, n =2)
+#' @example /inst/examples/plotHighlightLocalPhylo-help.R
 #' @export
 highlightLocalPhylo <- function(simu,which.result=NULL, size, n, subplot = NULL, phylogeny=NULL){
 

PhyloSim/R/plotPhylogeneticDispersion.R

@@ -10,51 +10,7 @@
 #' @param ymin Float, determines the plot limit (min) of the y axis.
 #' @param means Integer, determines the number of results which are used to average the results.
 #' @details In every subplot the x-axis represents the size of the subplots used in the null models. Hence, it is recommended to use a vector of plot sizes in your \code{\link{calculatePhylogeneticDispersion}} setup. \cr\cr The which.result argument here is used on the input list of p-values. Hence, which.result = 1 plots the first list slice of the input here. This is not necessarily the first time step of of your parameter settings in \code{\link{runSimulationBatch}}. \cr\cr For an further explanation please see the Examples section. 
-#' @examples 
-#' ## First the experimental design has to be defined.
-#' ## In this example we will test seven different combinations of the parameters
-#' ## 'density and 'environment' under four different dispersal distances.
-#' ## This design leads to 28 experiments.
-#'   
-#' dispOptions <- 4
-#' fitOptions <- 7
-#'
-#' # These are the parameters that are tested.  
-#' # We are testing seven combinations of the parameters 'density' and 'environment'...
-#' density <- rep(c(0,seq(0,1,len = fitOptions-2),1),dispOptions)
-#' environment <- rep(c(0,seq(1,0,len = fitOptions-2),1),dispOptions)
-#' 
-#' # ... for four different dispersal ranges.
-#' dispersal <-  rep(c(0,0.5, 2,4), each = fitOptions)
-#' 
-#' ## The modes and scenarios are only defined to label the plots. They have no influence on the 
-#' ## calculations.
-#' modes <- ifelse(dispersal == 0, "global", "local")
-#' scenarios <- paste(modes, " dens=", density, " env=", environment, sep = "")
-#' 
-#' ## Now we can define a list of parameter sets.
-#' pars <- list()
-#' for (i in 1:length(scenarios)){pars[[i]] = createCompletePar(x = 20,y = 20, runs = 1000,scenario = scenarios[i], dispersal = dispersal[i],specRate = 2,density = density[i],environment = environment[i], fitnessBaseMortalityRatio = 5, densityCut = 1,seed = 1000)}
-#' 
-#' ## Run the simulations
-#' simulationOut <- runSimulationBatch(pars, parallel = 2)
-#' 
-#' ## Calculate null models. For each model run 9 plot sizes are tested. In the plot they are 
-#' ## used to calculate the confidence interval for the results.
-#' nullMeta <- calculatePhylogeneticDispersion(simulationOut, plotlengths = c(2,3,4,5,6,7,8,9,10), reduce = TRUE)
-#' 
-#' ## Now we can define the positions and labels of the plots.
-#' ## Note that here the 28 simulations need to be covered in the right order. 
-#' ## In this example there will be 7 rows and 4 collumns to represent the 28 cases.
-#' positions <- list(x= c(1:7),
-#'    y = c(4, 1:3), # this is beacause dispersal = "global" is equal to dispersal = "0"
-#'    zname = c("neutral", "1", "0.75", "0.5", "0.25", "0", "both"), # = environment
-#'    yname = c("global", "0.5", "2", "4"),  # = dispersal
-#'    xname=c("neutral", "0", "0.25", "0.5","0.75","1","both")) # = density
-#' 
-#' ## Now you can plot the results.
-#' plotPhylogeneticDispersion(pvalues = nullMeta, positions = positions, title = "Null Meta")
-#' 
+#' @example /inst/examples/plotPhylogeneticDispersion-help.R
 #' @export
 #' 
 plotPhylogeneticDispersion <- function(pvalues, positions=NULL, title = "P-values", which.result = NULL, xmax = 5.5, ymax = 2.5, xmin = -0.2, ymin = 0.5, means=1){

PhyloSim/R/plotRAC.R

@@ -6,36 +6,7 @@
 #' @param title String, determining the title of the plot.
 #' @details Each species is given a rank according to their abundance (highest = rank 1). Then the the species' abundance is plotted in dependency of their rank. It can be used as an indicator for the ammount of equally abundant species a community can support. \cr\cr If which.result = "all" all intermediate results are shown in one plot. The colors of the lines are plotted as a gradient from blue (first results) to red (end result).
 #' @return A dataframe containing the ranked abundances, sorted by ascending rank. If which.result = "all" only the plot will be returned.
-#' @examples 
-#' 
-#' #Load data
-#' data(simu.neutral.global)
-#' data(simu.neutral.local)
-#' data(simu.envcom.local)
-#' 
-#'  
-#' 
-#' #Plot RAC curve for neutral model and global dispersion
-#' 
-#' rac(simu = simu.neutral.global)
-#' rac(simu = simu.neutral.global, plot ="bar")
-#' 
-#'  
-#' 
-#' #Plot RAC curve for neutral model and local dispersion
-#' 
-#' rac(simu = simu.neutral.local)
-#' rac(simu = simu.neutral.local, plot ="bar")
-#' 
-#'  
-#' 
-#' #Plot RAC curve for environment and competition model and local dispersion
-#' 
-#' rac(simu = simu.envcom.local)
-#' rac(simu = simu.envcom.local, plot ="bar")
-#' 
-#'  
-#' 
+#' @example inst/examples/plotRAC-help.R
 #' @export
 
 rac <- function(simu,which.result=NULL, plot="line", title="RAC"){