tfr.predict {bayesTFR} | R Documentation |

## Generating Posterior Trajectories of the Total Fertility Rate

### Description

Using the posterior parameter samples simulated by `run.tfr.mcmc`

(and possibly `run.tfr3.mcmc`

) the function generates posterior trajectories for the total fertility rate for all countries of the world.

### Usage

```
tfr.predict(mcmc.set = NULL, end.year = 2100,
sim.dir = file.path(getwd(), "bayesTFR.output"),
replace.output = FALSE, start.year = NULL,
nr.traj = NULL, thin = NULL, burnin = 2000,
use.diagnostics = FALSE, use.tfr3 = TRUE, burnin3 = 2000,
mu = 2.1, rho = 0.8859, sigmaAR1 = 0.1016, min.tfr = 0.5,
use.correlation = FALSE, save.as.ascii = 0, output.dir = NULL,
low.memory = TRUE, seed = NULL, verbose = TRUE, uncertainty = FALSE, ...)
```

### Arguments

`mcmc.set` |
Object of class |

`end.year` |
End year of the prediction. |

`sim.dir` |
Directory with the MCMC simulation results. It should equal to the |

`replace.output` |
Logical. If |

`start.year` |
Start year of the prediction. By default the prediction is started at the next time period after |

`nr.traj` |
Number of trajectories to be generated. If |

`thin` |
Thinning interval used for determining the number of trajectories. Only relevant, if |

`burnin` |
Number of iterations to be discarded from the beginning of the parameter traces. |

`use.diagnostics` |
Logical determining if an existing convergence diagnostics for phase II MCMCs should be used for choosing the values of |

`use.tfr3` |
Logical determining if phase III should be predicted via MCMCs (simulated via |

`burnin3` |
Burnin used for phase III MCMCs. Only relevant if |

`save.as.ascii` |
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. |

`output.dir` |
Directory into which the resulting prediction object and the trajectories are stored. If it is |

`low.memory` |
Logical indicating if the prediction should run in a low-memory mode. If it is |

`mu` |
Long-term mean |

`rho` |
Autoregressive parameter |

`sigmaAR1` |
Standard deviation |

`min.tfr` |
Smallest TFR value allowed. |

`use.correlation` |
Logical. If |

`seed` |
Seed of the random number generator. If |

`verbose` |
Logical switching log messages on and off. |

`uncertainty` |
Logical. If the MCMC steps has considered uncertainty of past TFR and |

`...` |
Further arguments passed to the underlying functions. |

### Details

The trajectories are generated using a distribution of country-specific decline curves (Alkema et al 2011) and either a classic AR(1) process or a country-specific AR(1) process (Raftery et al 2013). Phase II parameter samples simulated using `run.tfr.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`

(see `create.thinned.tfr.mcmc`

).

If Phase III is projected using a BHM (i.e. if `use.tfr3`

is `TRUE`

), parameter samples simulated via `run.tfr3.mcmc`

are used from which burnin (given by `burnin3`

) is discarded and the chains are evenly thinned in a way that the total size corresponds to the final size of the Phase II parameter samples. Countries for which there are no simulated country-specific Phase III parameters (e.g. because their TFR is still in Phase II or it is an aggregated region) use samples of the “world” AR(1) parameters.

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.

The resulting prediction object is saved into ‘{output.dir}/predictions’. Trajectories for all countries are saved into the same directory in a binary format, one file per country. 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 of a UN-specific format. They are selected by equal spacing (see function `convert.tfr.trajectories`

for more details on the conversion). In addition, two summary files are created: one in a user-friendly format, the other using a UN-specific coding of the variants and time (see `write.projection.summary`

for more details).

### Value

Object of class `bayesTFR.prediction`

which is a list containing components:

`quantiles` |
A |

`traj.mean.sd` |
A |

`nr.traj` |
Number of trajectories. |

`trf_matrix_reconstructed` |
Matrix containing imputed TFR values on spots where the original TFR matrix has missing values, i.e. between the last observed data point and the present year. |

`output.directory` |
Directory where trajectories corresponding to this prediction are stored. |

`nr.projections` |
Number of projections. |

`burnin` , `thin` , `burnin3` , `thin3` |
Burnin and thin used for this prediction for Phase II and Phase III, respectively. |

`end.year` |
The end year of this prediction. |

`mu` , `rho` , `sigma_t` , `sigmaAR1` |
Parameters of the AR(1) process. |

`min.tfr` |
Input value of minimum threshold for TFR. |

`na.index` |
Index of trajectories for which at least one country got |

`mcmc.set` |
Object of class |

### Author(s)

Hana Sevcikova, Leontine Alkema, Peiran Liu, Bailey Fosdick

### References

Peiran Liu, Hana Sevcikova, Adrian E. Raftery (2023): Probabilistic Estimation and Projection of the Annual Total Fertility Rate Accounting for Past Uncertainty: A Major Update of the bayesTFR R Package. Journal of Statistical Software, 106(8), 1-36. doi:10.18637/jss.v106.i08.

L. Alkema, A. E. Raftery, P. Gerland, S. J. Clark, F. Pelletier, Buettner, T., Heilig, G.K. (2011). Probabilistic Projections of the Total Fertility Rate for All Countries. Demography, Vol. 48, 815-839. doi:10.1007/s13524-011-0040-5.

Raftery, A.E., Alkema, L. and Gerland, P. (2014). Bayesian Population Projections for the United Nations. Statistical Science, Vol. 29, 58-68. doi:10.1214/13-STS419.

Fosdick, B., Raftery, A.E. (2014). Regional Probabilistic Fertility Forecasting by Modeling Between-Country Correlations. Demographic Research, Vol. 30, 1011-1034. doi:10.4054/demres.2014.30.35

### See Also

`run.tfr.mcmc`

, `run.tfr3.mcmc`

, `create.thinned.tfr.mcmc`

, `convert.tfr.trajectories`

, `write.projection.summary`

,
`get.tfr.prediction`

, `summary.bayesTFR.prediction`

### Examples

```
## Not run:
sim.dir <- tempfile()
m <- run.tfr.mcmc(nr.chains=1, iter=10, output.dir=sim.dir, verbose=TRUE)
m3 <- run.tfr3.mcmc(sim.dir=sim.dir, nr.chains=2, iter=40, thin=1, verbose=TRUE)
pred <- tfr.predict(m, burnin=0, burnin3=10, verbose=TRUE)
summary(pred, country="Iceland")
unlink(sim.dir, recursive=TRUE)
## End(Not run)
```

*bayesTFR*version 7.4-2 Index]