Documentation update

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: MoNAn
 Type: Package
 Title: Mobility Network Analysis
-Version: 0.1.0
-Date: 2023-08-02
+Version: 0.1.1
+Date: 2023-08-15
 Authors@R: c(person("Per", "Block", role = c("cre", "aut", "cph"), email = "block@soziologie.uzh.ch"), 
     person("Christoph", "Stadtfeld", role = "aut"),
     person("Nico", "Keiser", role = "aut"))

MoNAnExampleScript.R

@@ -40,13 +40,13 @@ myState <- createProcessState(
 
 ##### create cache #####
 
-# define dependent variable and create cache object
+# cache object
 myCache <- createWeightedCache(myState, resourceCovariates = c("sex"))
 
 
 ##### create effects object #####
 
-# create an effects object
+# effects object
 myEffects <- createEffectsObject(
   list(
     list("loops"),
@@ -96,7 +96,7 @@ myAlg <- createAlgorithm(myState, myEffects, multinomialProposal = FALSE)
 
 ##### estimate mobility network model #####
 
-# estimate mobility network model
+# mobility network model
 myResDN <- estimateMobilityNetwork(
   myState, myCache, myEffects, myAlg,
   initialParameters = NULL,
@@ -170,7 +170,7 @@ myGofTieWeight <- gofDistributionNetwork(ans = myResDN, simulations = myResDN$de
 plot(myGofTieWeight, lvls = 1:15)
 
 
-##### estimate mobility network model #####
+##### simulate mobility network #####
 
 mySimDN <- simulateMobilityNetworks(myState,
                                     myCache,

R/3_coreFunctions.R

@@ -4,11 +4,11 @@
 #' createAlgorithm
 #'
 #' Specifies the algorithm used in the estimation based on characteristics
-#' of the state, the effects and the dependent variable.
+#' of the state and the effects.
 #'
-#' @param state A monan state object that contains all relevant information about
+#' @param state An object of class "processState.monan" that contains all relevant information about
 #' the outcome in the form of an edgelist, the nodesets, and covariates.
-#' @param effects An effect object that specifies the model.
+#' @param effects An object of class "effectsList.monan" that specifies the model.
 #' @param multinomialProposal How should the next possible outcome in the simulation chains
 #' be sampled? If TRUE, fewer simulation steps are needed, but each simulation
 #' step takes considerably longer. Defaults to FALSE.
@@ -33,13 +33,13 @@
 #' A recommended value is at least 0.5 * n_Individuals * n_locations if
 #' multinomialProposal = F, and at least n_Individuals if multinomialProposal = T
 #' which is set as default.
-#' @param initialIterationsN2 The number of draws taken in subpphase 1 of Phase 2.
+#' @param initialIterationsN2 The number of draws taken in subphase 1 of Phase 2.
 #' For first estimations, a recommended value is around 50 (default to 50).
 #' Note that in later subphases, the number of iterations increases.
 #' If this is a further estimation to improve convergence, higher values (100+)
 #' are recommended.
 #' @param nsubN2 Number of subphases in Phase 2. In case this is the first
-#' estimation, 4 subphases are recommended and is set as default. If convergence
+#' estimation, 4 subphases are recommended and set as default. If convergence
 #' in a previous estimation was close, then 1-2 subphases should be enough.
 #' @param initGain The magnitude of parameter updates in the first subphase of
 #' Phase 2. Values of around 0.2 (default) are recommended.
@@ -192,15 +192,16 @@ createAlgorithm <-
 #' createEdgelist
 #'
 #' Creates an edgelist object, which is the standard format of the outcome to be modelled
-#' by monan.
+#' by MoNAn.
 #'
 #' @param el An edgelist in the form of a matrix with two columns and N rows.
 #' The first column indicates the origin of a person/resource, the second row the destination.
-#' Each row is one observation.
-#' @param nodeSet The nodesets of the edgelists. For edgelists, this is a vector with three
-#' entries describing between what locations who is mobile, i.e., c(location, location, individuals/resources).
+#' Each row represents one observation.
+#' @param nodeSet The nodesets of the edgelists. This is a vector with three 
+#' entries referencing the names of the nodesets of locations and individuals 
+#' of the form c(location, location, individuals).
 #'
-#' @return an object of type edgelist.monan
+#' @return An object of class "edgelist.monan".
 #' @export
 #'
 #' @seealso [createProcessState()]
@@ -236,7 +237,7 @@ createEdgelist <-
 #' Effects without further parameters only contain the effect name (e.g., loops).
 #' @param checkProcessState For internal use only.
 #'
-#' @return A monan effects object.
+#' @return An object of class "effectsList.monan".
 #' @export
 #'
 #' @examples
@@ -317,12 +318,12 @@ createEffectsObject <-
 #' NOTE: The outcome variable of the model is not defined as a network, but as an edgelist!
 #'
 #' @param m A square matrix containing the network data.
-#' @param isSymmetric Currently not in use, defaults to FALSE.
-#' @param isBipartite Currently not in use, defaults to FALSE.
+#' @param isSymmetric Currently not in use.
+#' @param isBipartite Currently not in use.
 #' @param nodeSet Which nodeset are the nodes of the network. Usually this will
 #' be the locations in the data.
 #'
-#' @return a monan network object.
+#' @return An object of class "network.monan".
 #' @export
 #'
 #' @seealso [createProcessState()], [createEdgelist()]
@@ -358,7 +359,7 @@ createNetwork <-
 #'
 #' Determines and names the nodesets of individuals and locations that make up the mobility network.
 #'
-#' @param x Either a single number indicating how many items are in this node-set
+#' @param x Either a single number indicating how many items are in this nodeset
 #' or a vector from 1:n_items.
 #' @param isPresent Currently not in use.
 #' @param considerWhenSampling A boolean/logical vector of the length of the nodeset.
@@ -371,7 +372,7 @@ createNetwork <-
 #' is, their mobility is exogenously defined and does not follow the same logic as
 #' the mobility of everybody else.
 #'
-#' @return A monan nodeset object.
+#' @return An object of class "nodeSet.monan".
 #' @export
 #'
 #' @seealso [createProcessState()]
@@ -420,7 +421,7 @@ createNodeSet <-
 
 #' createNodeVariable
 #'
-#' Assigns an covariate to one nodeset, i.e., an exogenous characteristic of mobile
+#' Assigns a covariate to one nodeset, i.e., an exogenous characteristic of mobile
 #' individuals/resources or locations.
 #'
 #' @param values A vector assigning the covariate value to each element of the nodeset.
@@ -429,9 +430,9 @@ createNodeSet <-
 #' @param addSame Will the variable be used to model categorical homophily (e.g.,
 #' with the same_covariate effect)? In this case, addSame needs to be set to TRUE.
 #' @param addSim Will the variable be used to model continuous homophily (e.g.,
-#' with the sim_covariate effect)? In this case, addSame needs to be set to TRUE.
+#' with the sim_covariate effect)? In this case, addSim needs to be set to TRUE.
 #'
-#' @return A monan node variable object
+#' @return An object of class "nodeVar.monan".
 #' @export
 #'
 #' @seealso [createProcessState()]
@@ -478,13 +479,13 @@ createNodeVariable <-
 #' outcome variable (edgelist), the nodesets, and all covariates.
 #'
 #' @param elements A named list of the outcome variable (edgelist), the nodesets,
-#' and all covariates that contain the information
-#' about the data that will be used in the estimation.
+#' and all covariates that contain the information about the data that will be 
+#' used in the estimation.
 #' @param dependentVariable The name of the outcome variable (edgelist) as
 #' specified under "elements". This indicates what outcome
 #' the researcher is interested in.
 #'
-#' @return A monan process state object.
+#' @return An object of class "processState.monan".
 #' @export
 #'
 #' @seealso [createEdgelist()], [createNodeSet()],
@@ -585,9 +586,9 @@ createProcessState <- function(elements, dependentVariable) {
 #' @param processState The processs state that provides the data basis for
 #' creating the cache.
 #' @param resourceCovariates A vector of resource covariates that will be
-#' used in the model specification?
+#' used in the model specification.
 #'
-#' @return A monan cache object.
+#' @return A cache object provided as a list.
 #' @export
 #'
 #' @seealso [createProcessState()]
@@ -669,32 +670,31 @@ createWeightedCache <-
 #' The core function of the package in which the model for the analysis of
 #' mobility tables is estimated.
 #'
-#' @param state A monan state object that contains all relevant information about
+#' @aliases estimateDistributionNetwork
+#' @param state An object of class "processState.monan" which contains all relevant information about
 #' the outcome in the form of an edgelist, the nodesets, and covariates.
-#' @param cache A monan cache object created from the same state object that is
-#' used in the estimation
-#' @param effects An effect object that specifies the model.
-#' @param algorithm An object that specifies the algorithm used in the estimation.
+#' @param cache A cache object created from the same state object that is
+#' used in the estimation.
+#' @param effects An object of class "effectsList.monan" that specifies the model.
+#' @param algorithm An object of class "algorithm.monan" which specifies the algorithm used in the estimation.
 #' @param initialParameters Starting values for the parameters. Using starting
-#' values e.g. from a multinomial logit model (see getMultinomialStatistics())
+#' values, e.g., from a multinomial logit model (see [getMultinomialStatistics()])
 #' increases the chances of model convergence in the first run of the estimation
 #' considerably.
 #' @param prevAns If a previous estimation did not yield satisfactory convergence,
 #' the outcome object of that estimation should be specified here to provide new
 #' starting values for the estimation.
-#' @param parallel Computation on multiple cores?
-#' @param cpus Number of cores for computation in case parallel = T.
+#' @param parallel Logical: computation on multiple cores?
+#' @param cpus Number of cores for computation in case parallel = TRUE.
 #' @param verbose Logical: display information about estimation progress in the console?
 #' @param returnDeps Logical: should the simulated values of Phase 3 be stored and returned?
 #' This is necessary to run GoF tests.
 #' Note that this might result in very large objects.
 #' @param fish Logical: display a fish?
 #'
-#' @aliases estimateDistributionNetwork
-#'
-#' @return A monan results object that contains the estimates, standard errors,
+#' @return An object of class "result.monan" that contains the estimates, standard errors,
 #' and convergence statistics. Furthermore, the covariance matrix used to calculate
-#' the standard errors is included, which also shows colinearity between effects.
+#' the standard errors is included, which also shows collinearity between effects.
 #' In case returnDeps = TRUE, the simulations of Phase 3 are included, too.
 #' @export
 #'
@@ -901,18 +901,18 @@ estimateDistributionNetwork <- estimateMobilityNetwork
 
 #' simulateMobilityNetworks
 #'
-#' Simulates mobility networks for a given data, effects, and parameters. This
-#' function is mainly interesting to explore the behaviour of the model or to
+#' Simulates mobility networks for given data, effects, and parameters. This
+#' function is mainly interesting to explore the behavior of the model or to
 #' do counter-factual simulations.
 #'
 #' @aliases simulateDistributionNetworks
-#' @param state A monan state object that contains all relevant information about
+#' @param state An object of class "processState.monan" that contains all relevant information about
 #' nodesets, and covariates. Further, an edgelist of the dependent variable needs
 #' to be specified with the initial mobility network as starting value for the
-#' simulation. For a large enough burnin, any initial mobility network is allowed.
-#' @param cache A monan cache object created from the same state object that is
+#' simulation. For a large enough burn-in, any initial mobility network is allowed.
+#' @param cache A cache object created from the same state object that is
 #' used in the simulation.
-#' @param effects An effect object that specifies the model.
+#' @param effects An object of class "effectsList.monan" that specifies the model.
 #' @param parameters The parameters associated with the effects that shall be used
 #' in the simulations.
 #' @param allowLoops Logical: can individuals/resources stay in their origin?
@@ -924,7 +924,7 @@ estimateDistributionNetwork <- estimateMobilityNetwork
 #' network. A recommended value for the lower bound is n_Individuals * n_locations.
 #' @param nSimulations The number of mobility networks to be simulated.
 #'
-#' @return A list with nSimulations entries, where each entry contains a further list with the
+#' @return An object of class "sims.monan" with nSimulations entries, where each entry contains a further list with the
 #' state and the cache of the current simulation stored.
 #' @export
 #'