Using the posterior parameter samples simulated by run.mig.mcmc,
generate posterior trajectories for the net migration rates for all countries of
the world, or all locations included in the estimation. This code does not adjust trajectories to ensure that net
migration counts over all countries sum to zero.
mig.predict(
mcmc.set = NULL,
end.year = 2100,
sim.dir = NULL,
replace.output = FALSE,
start.year = NULL,
nr.traj = NULL,
thin = NULL,
burnin = 20000,
use.cummulative.threshold = FALSE,
ignore.gcc.in.threshold = FALSE,
post.last.observed = c("obsdata", "alldata", "impute"),
save.as.ascii = 0,
output.dir = NULL,
seed = NULL,
verbose = TRUE,
...
)Object of class bayesMig.prediction which is a list with components
containing details of the prediction. Key result component is an array of quantiles with dimensions
(number of locations) x (number of computed quantiles) x (number of projected time points).
First time point in the sequence is not a projection, but the last observed time period.
Other key result components include traj.mean.sd, a summary of means and standard deviations for each country
at each time point. See bayesTFR.prediction for more detail.
Object of class bayesMig.mcmc.set corresponding to sampled
parameter values for net migration model. If it is NULL, the object
is loaded from the directory specified in sim.dir
End year of the prediction
Directory with MCMC simulation results. It should be the same as
the output.dir argument in run.mig.mcmc
Logical value. If TRUE, existing predictions in
output.dir will be replaced by results of this run.
Start year of the prediction, i.e. the first predicted year. By default the prediction is
started at the next time period after present.year set in the estimation
step. If start.year is smaller than the default, the behavior is controlled by
the post.last.observed argument: Either data post start.year is ignored (default)
or the projection is set to the available data (post.last.observed = "a").
Number of trajectories to be generated.
If NULL, the argument thin is taken to determine the number of
trajectories. If both are NULL, the number of trajectories
corresponds to the size of the parameter sample.
Thinning interval used for determining the number of trajectories.
Only relevant if nr.traj is NULL.
Number of iterations to be discarded from the beginning of the parameter traces.
If TRUE historical cummulative thresholds are applied
to avoid sampling rates that are too extreme. The thresholds are
derived over prior rates of all locations. As a time span for deriving the limits on projected rates,
at each projected time point, six prior time periods are used in a 5-year simulation,
corresponding to 30 years in an annual simulation.
In a national simulation, prior rates of GCC countries (plus Western Sahara and Djibouti) are excluded
when deriving thresholds for non-GCC countries. If this option is used in a non-country simulation,
e.g. in a sub-national settings, set the ignore.gcc.in.threshold argument to TRUE.
If use.cummulative.threshold is TRUE, by default the GCC countries
(plus Western Sahara and Djibouti) identified by numerical codes of the countries are excluded from computing
the historical cummulative thresholds for non-GCC countries. If this argument is TRUE, this distinction is not made.
It is important to set it to TRUE in a sub-national simulation to avoid any random overlaps
of UN codes and user-defined codes.
If a user-specific data file was used during estimation and the data
contained the “last.observed” column, this argument determines how to treat the time periods
between the last observed point and the start year of the prediction, for locations where there is
a gap between them, or if short-term predictions were included in the file. It is also relevant
if start.year is set to a smaller value than present.year in the estimation.
Possible values are:
“obsdata” or “o” (default) uses any non-missing observed data
provided in the data file during estimation, up to the time point defined by the argument start.year
(excluding the start year itself).
“alldata” or “a” would similarly use the provided data but would use all data, even if it goes beyond the start year. This allows to use short-term deterministic projections for locations where it is available.
“impute” or “i” would ignore all data beyond the last observed data point and impute the missing time periods.
Either a number determining how many trajectories should be converted into an ASCII file, or 'all' in which case all trajectories are converted. It should be set to 0 if no conversion is desired. If this argument is larger than zero, the resulting file can be used as input into population projection via bayesPop, see Details.
Directory into which the resulting prediction object and the
trajectories are stored. If it is NULL, it is set to either sim.dir,
or to output.dir of mcmc.set$meta if mcmc.set is given.
Seed of the random number generator. If NULL no seed is set.
Can be used to generate reproducible projections.
Logical value. Switches log messages on and off.
Further arguments passed to the underlying functions.
The trajectories of net migration rates for each location are generated using the model of Azose & Raftery (2015).
Parameter samples simulated via run.mig.mcmc are used from all chains, from which the given burnin
was discarded. They are evenly thinned to match nr.traj or using the thin argument.
Such thinned parameter traces, collapsed into one chain, if they do not already exist, are stored on disk
into the sub-directory thinned_mcmc_t_b where t is the value of thin and
b the value of burnin.
The projection is run for all missing values before the present year, if any. Medians over the trajectories are used as imputed values and the trajectories are discarded. The process then continues by projecting the future values where all generated trajectories are kept.
A special case is when the argument start.year is given that is smaller than or equal to
the present year. In such a case, imputed missing values before present year are treated
as ordinary predictions (trajectories are kept). If post.last.observed is “a”,
all historical data between start year and present year are used as projections.
The resulting prediction object is saved into {output.dir}/predictions. Trajectories
for all locations are saved into the same directory in a binary format, one file per location.
At the end of the projection, if save.as.ascii is larger than 0, the function converts
the given number of trajectories into a CSV file, called ascii_trajectories.csv also located
in the predictions directory. The converted trajectories are selected by equal spacing.
In addition to the converted trajectories, two summary files are created: one in a user-friendly format, the other using
a UN-specific coding, as described in mig.write.projection.summary.
If it is desired to use these predictions as input to population projections in bayesPop,
enter the full file path of the ascii_trajectories.csv file into the inputs argument
of bayesPop::pop.predict as item migtraj and set the argument mig.is.rate appropriately.
Azose, J. J., & Raftery, A. E. (2015). Bayesian probabilistic projection of international migration. Demography, 52(5), 1627-1650. tools:::Rd_expr_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. tools:::Rd_expr_doi("10.1073/pnas.1606119113").
# Toy simulation for US states
us.mig.file <- file.path(find.package("bayesMig"), "extdata", "USmigrates.txt")
sim.dir <- tempfile()
m <- run.mig.mcmc(nr.chains = 2, iter = 30, thin = 1, my.mig.file = us.mig.file,
output.dir = sim.dir, present.year = 2017, annual = TRUE)
# Prediction
pred <- mig.predict(sim.dir = sim.dir, burnin = 5, end.year = 2050)
# here unrealistic results since this is a toy simulation
mig.trajectories.plot(pred, "Hawaii", pi = 80, ylim = c(-0.02, 0.02))
mig.trajectories.table(pred, "Hawaii")
summary(pred, "California")
# view locations included in the simulation
get.countries.table(pred)
unlink(sim.dir, recursive = TRUE)
# For projections on national level, see ?bayesMig.
Run the code above in your browser using DataLab