work on documentation

ChangeLog

@@ -1,3 +1,7 @@
+0.4-4 (09/28/2023)
+-----
+Improved documentation.
+
 0.4-3 (07/21/2023)
 -----
 Argument ignore.last.observed in mig.predict swapped for post.last.observed.

DESCRIPTION

@@ -1,13 +1,13 @@
 Package: bayesMig
-Version: 0.4-3
-Date: 2023-07-21
+Version: 0.4-4
+Date: 2023-09-28
 Title: Bayesian Projection of Migration
 Author: Jon Azose, Hana Sevcikova and Adrian Raftery
 Maintainer: Hana Sevcikova <[email protected]>
 Depends: R (>= 3.5.0), bayesTFR
 Imports: coda, truncnorm, wpp2019
 Suggests: 
-Description: Producing probabilistic projections of net migration rate for all countries of the world using a Bayesian hierarchical model <doi:10.1007/s13524-015-0415-0>.
+Description: Producing probabilistic projections of net migration rate for all countries of the world or for subnational units using a Bayesian hierarchical model <doi:10.1007/s13524-015-0415-0>.
 License: GPL (>= 2)
 URL: http://bayespop.csss.washington.edu
 RoxygenNote: 7.2.1

R/bayesMig.R

@@ -4,7 +4,8 @@
 #' @description Collection of functions for making probabilistic projections of net migration rate for all countries of the world,
 #' using a Bayesian hierarchical model (BHM) and the United Nations demographic time series. The model can be also applied
 #' to user-defined data for other locations, such as subnational units.
-#' Methodological details are provided in Azose & Raftery (2015).
+#' Methodological details are provided in Azose & Raftery (2015). The projected rates can be used 
+#' as input to population projections generated via the \pkg{bayesPop} package.
 #'
 #' @author Jon Azose, Hana Sevcikova and Adrian Raftery
 #'
@@ -47,16 +48,22 @@
 #' \code{\link{get.mig.convergence.all}} functions.
 #' 
 #' Historical data on migration rates are taken from the \pkg{wpp2019} (default), \pkg{wpp2022} or \pkg{wpp2017} package, 
-#' depending on users settings. Alternatively, users can input their own data.
+#' depending on users settings. Alternatively, users can input their own data. These can be either 
+#' 5-year or annual time series. An example file with historical annual US migration rates is included
+#' in the package. Its usage is shown in the Example of \code{\link{mig.predict}}.
 #' 
+#' @note As this package has been designed for simulating migration on a national level, many 
+#'      functions use arguments and terminology related to countries. However, a \dQuote{country}
+#'      is to be interpreted as any location included in the simulation. 
 #' @examples
 #' \dontrun{
 #' # Run a real simulation (can take long time)
 #' sim.dir <- tempfile()
 #' m <- run.mig.mcmc(nr.chains = 4, iter = 10000, thin = 10, output.dir = sim.dir,
 #'         verbose.iter = 1000)
 #' 
-#' # Prediction for all countries
+#' # Prediction for all countries 
+#' # (use argument save.as.ascii for passing predictions into bayesPop)
 #' pred <- mig.predict(sim.dir = sim.dir, nr.traj = 1000, burnin = 1000)
 #' 
 #' # Explore results
@@ -67,11 +74,15 @@
 #' mig.diagnose(sim.dir, burnin = 4000, thin = 1)
 #' 
 #' unlink(sim.dir, recursive = TRUE)
+#' # For annual projections on sub-national level, see ?mig.predict.
 #' }
 #' 
 #' @references Azose, J. J., & Raftery, A. E. (2015). 
 #' Bayesian probabilistic projection of international migration. Demography, 52(5), 1627-1650.
 #' \doi{10.1007/s13524-015-0415-0}.
+#' 
+#' Azose, J.J., Ševčíková, H., Raftery, A.E. (2016): Probabilistic population projections with migration uncertainty. 
+#' Proceedings of the National Academy of Sciences 113:6460–6465. \doi{10.1073/pnas.1606119113}.
 #' @name bayesMig-package
 #' @aliases bayesMig
 NULL

R/get_outputs.R

@@ -256,7 +256,7 @@ mig.parameter.names <- function() {
   return(c("a","b","mu_global","sigma2_mu"))
 }
 
-#' @param country.code Country code. If it is given, the country-specific parameter names contain 
+#' @param country.code Location code. If it is given, the country-specific parameter names contain 
 #'     the suffix \sQuote{_country\eqn{X}} where \eqn{X} is the \code{country.code}.
 #'     
 #' @return \code{mig.parameter.names.cs} returns names of the country-specific parameters.
@@ -314,7 +314,7 @@ coda.mcmc.bayesMig.mcmc <- function(mcmc, country=NULL, par.names=NULL,
 #' @param mcmc.list A list of objects of class \code{bayesMig.mcmc}, or an object of class \code{\link{bayesMig.mcmc.set}} or \code{\link{bayesMig.prediction}}.
 #' If \code{NULL}, the MCMCs are
 #' loaded from \code{sim.dir}. Either \code{mcmc} or \code{sim.dir} must be given.
-#' @param country Country name or code. Used in connection with the \code{par.names.cs} argument
+#' @param country Location name or code. Used in connection with the \code{par.names.cs} argument
 #' (see below).
 #' @param chain.ids Vector of chain identifiers. By default, all chains available in the \code{mcmc.list}
 #' object are included.
@@ -323,7 +323,7 @@ coda.mcmc.bayesMig.mcmc <- function(mcmc, country=NULL, par.names=NULL,
 #' those returned by the \code{mig.parameter.names} function, which includes all country-independent
 #' parameters in the BHM.
 #' @param par.names.cs Names of country-specific parameters to be included. The argument \code{country}
-#' is used to filter out traces that correspond to a specific country. If \code{country} is not given, 
+#' is used to filter out traces that correspond to a specific location. If \code{country} is not given, 
 #' traces of each parameter are given for all countries. Default names are those returned by 
 #' \code{mig.parameter.names.cs()}, which includes all country-specific parameters in the BHM.
 #' @param low.memory Logical indicating if the function should run in a memory-efficient mode.
@@ -575,7 +575,7 @@ summary.bayesMig.mcmc <- function(object, country = NULL,
   if(missing(par.names.cs)) par.names.cs <- mig.parameter.names.cs()
   if (!is.null(country)) {
     country.obj <- get.country.object(country, object$meta)
-    if(is.null(country.obj$name)) stop("Country ", country, " not found.")
+    if(is.null(country.obj$name)) stop("Location ", country, " not found.")
     res$country.name <- country.obj$name
     country <- country.obj$code
   } 
@@ -587,23 +587,25 @@ summary.bayesMig.mcmc <- function(object, country = NULL,
 #' @title Summary Statistics for Migration Markov Chain Monte Carlo 
 #'
 #' @description Summary of an object \code{\link{bayesMig.mcmc.set}} or \code{\link{bayesMig.mcmc}},
-#'     computed via \code{\link{run.mig.mcmc}}.  It can be obtained either for all countries or 
-#'     for a specific country, and either for all parameters or for specific parameters.
+#'     computed via \code{\link{run.mig.mcmc}}.  It can be obtained either for all locations or 
+#'     for a specific location, and either for all parameters or for specific parameters.
 #'     The function uses the \code{\link[coda]{summary.mcmc}} function of the \pkg{coda} package.
 #' 
 #' @param object Object of class \code{\link{bayesMig.mcmc.set}} or \code{\link{bayesMig.mcmc}}.
-#' @param country Country name or code if a country-specific summary is desired. 
-#'     The code can be either numeric or ISO-2 or ISO-3 characters. By default, summary 
-#'     for all countries is generated.
+#' @param country Location name or code if a location-specific summary is desired. The code can be either numeric 
+#'     or (if locations are countries) ISO-2 or ISO-3 characters. By default, summary 
+#'     for all locations is generated.
 #' @param chain.id Identifiers of MCMC chains. By default, all chains are considered.
-#' @param par.names Country independent parameters to be included in the summary. 
+#' @param par.names Country independent parameters (hyperparameters) to be included in the summary. 
 #'     The default names are given by \code{\link{mig.parameter.names}()}.
-#' @param par.names.cs Country-specific parameters to be included in the summary.
+#' @param par.names.cs Location-specific parameters to be included in the summary.
 #'     The default names are given by \code{\link{mig.parameter.names.cs}()}.
 #' @param meta.only Logical. If it is \code{TRUE}, only meta information of the simulation is included.
 #' @param thin Thinning interval. Only used if larger than the \code{thin} argument used in \code{\link{run.mig.mcmc}}.
 #' @param burnin Number of iterations to be discarded from the beginning of each chain before computing the summary.
 #' @param \dots Additional arguments passed to the \code{\link[coda]{summary.mcmc}} function of the \pkg{coda} package.
+#' @examples
+#' # See example in ?run.mig.mcmc
 #' @export
 #' @rdname summary-mcmc
 #' 
@@ -628,7 +630,7 @@ summary.bayesMig.mcmc.set <- function(object, country=NULL, chain.id=NULL,
   }
   if (!is.null(country)) {
     country.obj <- get.country.object(country, object$meta)
-    if(is.null(country.obj$name)) stop("Country ", country, " not found.")
+    if(is.null(country.obj$name)) stop("Location ", country, " not found.")
     res$country.name <- country.obj$name
     country <- country.obj$code
   }
@@ -685,7 +687,7 @@ print.bayesMig.mcmc <- function(x, ...) {
 #' @export
 print.summary.bayesMig.mcmc <- function(x, ...) {
   if(!is.null(x$country.name)){
-    cat('\nCountry:', x$country.name, '\n')
+    cat('\nLocation:', x$country.name, '\n')
     if (is.null(x$results))
       cat('\tnot used for estimation.\n')
   }
@@ -711,15 +713,18 @@ print.bayesMig.prediction <- function(x, ...) {
 
 #' @title Summary of Prediction of Net Migration Rate
 #'
-#' @description Country-specific summary of an object of class \code{\link{bayesMig.prediction}}, 
+#' @description Summary of an object of class \code{\link{bayesMig.prediction}}, 
 #'     created using the function \code{\link{mig.predict}}. The summary contains the mean, 
 #'     standard deviation and several commonly used quantiles of the simulated trajectories.
 #' 
 #' @param object Object of class \code{\link{bayesMig.prediction}}.
-#' @param country Country name or code if a country-specific summary is desired. 
-#'     The code can be either numeric or ISO-2 or ISO-3 characters. If it is \code{NULL}, only prediction parameters are included.
+#' @param country Location name or code if a location-specific summary is desired. 
+#'     The code can be either numeric or (if locations are countries) ISO-2 or ISO-3 characters. 
+#'     If it is \code{NULL}, only prediction meta info is included.
 #' @param compact Logical switching between a smaller and larger number of displayed quantiles.
 #' @param \dots A list of further arguments.
+#' @examples
+#' # See example in ?mig.predict
 #' @export
 #' @rdname summary-prediction
 #' 
@@ -741,13 +746,13 @@ print.summary.bayesMig.prediction <- function(x, digits = 3, ...) {
       x$projection.years[length(x$projection.years)], ')')
   cat('\nTrajectories:', x$nr.traj)
   cat('\nBurnin:', x$burnin)
-
+  cat('\n')
   if(!is.null(x$country.name)) {
-    cat('\nCountry:', x$country.name, '\n')
+    cat('\nLocation:', x$country.name, '\n')
     cat('\nProjected Migration Rate:')
     cat('\n')
     print(x$projections, digits=digits, ...)
-  }
+  } 
 }
 
 #' @title Summary of Convergence Diagnostics

R/plot_functions.R

@@ -24,7 +24,7 @@
 #'     device (\code{FALSE}) or into an existing device (\code{TRUE}). One can use this argument to plot
 #'     trajectories from multiple countries into one graphics.
 #' @param scale Logical. If \code{TRUE}, values are scaled to be \dQuote{per population}, i.e. 
-#'     they are divided by \code{pop.denom} passed to \code{\link{mig.predict}}.
+#'     they are divided by \code{pop.denom} passed to \code{\link{run.mig.mcmc}}.
 #' @param \dots Additional graphical parameters. In addition, for \code{mig.trajectories.plot.all} 
 #'     any of the arguments of \code{tfr.trajectories.plot} can be passed here.
 #'     
@@ -328,7 +328,10 @@ mig.pardensity.cs.plot <- function(country, mcmc.list = NULL, sim.dir = file.pat
 #'     to \code{\link[bayesTFR]{tfr.map.gvis}}. In \code{e0.ggmap}, \dots are arguments that can be passed 
 #'     to \code{\link[bayesTFR]{tfr.ggmap}}. In addition, functions that use the \pkg{rworldmap} package accept 
 #'     arguments passed to the \code{\link[rworldmap]{mapCountryData}} function of the \pkg{rworldmap} package.
-#' @details \code{mig.map} creates a single map for the given time period and quantile. 
+#' @details The functions only work for national simulations where location codes 
+#'     correspond to the countries' UN codes.  
+#'     
+#'     \code{mig.map} creates a single map for the given time period and quantile. 
 #'     \code{mig.map.all} generates a sequence of maps, namely one for each projection period. 
 #'     If the package \pkg{fields} is installed, a color bar legend at the botom of the map is created.
 #'