tfr.median.set {bayesTFR}

Editing Medians of the Projection

Description

These functions are to be used by expert analysts. They allow to change the projection medians either to specific values, including the WPP values, or shift the medians by a given constant, or by a specific adjusting procedure.

Usage

tfr.median.set(sim.dir, country, values, years = NULL)

tfr.median.shift(sim.dir, country, reset = FALSE, shift = 0, 
    from = NULL, to = NULL)
    
tfr.median.adjust(sim.dir, countries, factor1 = 2/3, factor2 = 1/3, forceAR1 = FALSE)

tfr.median.reset(sim.dir, countries = NULL)

tfr.shift.prediction.to.wpp(sim.dir, ...)

Arguments

sim.dir

Directory containing the prediction object.

country

Name or numerical code of a country.

countries

Vector of country names or codes. If NULL in the tfr.median.reset function, the reset is done for all countries.

values

Array of the new median values.

years

Numeric vector giving years which values correspond to. Ideally it should be of the same length as values. If it is NULL, values are set starting from the first prediction period. If values correspond to consecutive years, only the first year might be given here. A year t represents a prediction period [t_i, t_{i+1}] if t_i < t \leq t_{i+1}.

reset

Logical. If TRUE medians in a range of from and to are reset to their original values.

shift

Constant by which the medians should be offset. It is not used if reset is TRUE.

from

Year from which the offset/reset should start. By default, it starts at the first prediction period.

to

Year until which the offset/reset should be done. By default, it is set to the last prediction period.

factor1, factor2

Adjusting factors for the first and second projection period, respectively (see below).

forceAR1

Logical. If TRUE, the given countries are forced to enter Phase III (i.e. the AR(1) process) in the first projection period.

...

Additional arguments passed to the underlying adjustment function. It can be verbose to show/hide the progress of the adjustment and wpp.year to adjust it to if it differs from the wpp year of the simulation.

Details

The function tfr.median.set can be used to set the medians of the given country to specific values. Function tfr.median.shift can be used to offset the medians by a specific constant, or to reset the medians to their original BHM values. Function tfr.median.adjust runs the prediction procedure for the given countries with an additional decrement in the model in the first two projection periods. In the first projection period it is computed as factor1*S where S is a difference between observed decrement and the expected decrement (by the double logistic function) in the last observed period. In the second projection period, in the formula factor1 is replaced by factor2. If forceAR1 is set to TRUE, we recommend to set factor1 and factor2 to 0. The function then calls tfr.median.set in order to store the new median for each country.

Functiontfr.shift.prediction.to.wpp shifts the projected medians so that they correspond to the values found in the tfrprojMed datasets of the wpp package that either corresponds to the package used for the simulation itself or is given by the wpp.year argument. If using wpp2022, the dataset name is automatically adjusted depending if it is an annual or a 5-year simulation.

Function tfr.median.reset resets medians of the given countries to the original values. By default it deletes adjustments for all countries.

In all five functions, if a median is modified, the corresponding offset is stored in the prediction object (element median.shift) and the updated prediction object is written back to disk. All functions in the package that use trajectories and trajectory statistics use the median.shift values to offset the results correspondingly, i.e. trajectories are shifted the same way as the medians.

Value

All functions return an updated object of class bayesTFR.prediction.

Author(s)

Hana Sevcikova, Leontine Alkema

See Also

tfr.median.set.all for shifting estimation medians.