derivePopulation: Derive population counts from initial population and...
In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description Usage Arguments Details Value See Also Examples

Given initial population counts, and counts for components such as births, deaths, and migration, derive population counts for subsequent years.

derivePopulation(
  initial,
  births = NULL,
  internal = NULL,
  entries = list(),
  exits = list(),
  net = list(),
  movements = TRUE,
  adjust = FALSE,
  scale = 0.1,
  fixed = character()
)

`initial`	The starting or jump-off population. An object of class `Counts`.
`births`	A `Counts` object.
`internal`	If `internal` uses an origin-destination format, an ordinary `Counts` object; if it uses a pool or net format, an object created by functions `collapseOrigDest`, `Pool`, or `Net`.
`entries`	A named list of `Counts` objects.
`exits`	A named list of `Counts` objects.
`net`	A named list of `Counts` objects.
`movements`	Logical. If `TRUE` (the default) and `Movements` account is returned. If `FALSE`, a `Transitions` account is returned.
`adjust`	Logical. If `FALSE` (the default) an error is raised of the initial population and components imply negative population counts. If `TRUE`, the components are adjusted until negative population counts are eliminated.
`scale`	A non-negative number governing the size of the steps made when adjusting.
`fixed`	Names of components that should not be adjusted.

Sometimes values for the initial population and components imply negative population counts. In such cases, an error will be raised if the adjust is FALSE (the default). Otherwise, derivePopulation will randomly revise entries (eg births) upwards and exits (eg deaths) downwards until the population counts become non-negative, via function makeConsistent.

The initial argument does not need to have a time dimension, but it does, the dimension must be of length 1, and must have dimscale "Points". The components must have identical time dimensions to one another, and these dimensions must have dimscale "Intervals".

If initial has an age dimension, then all components must have an age dimension, except for births. (births will be given age and triangle dimensions, and entries will be randomly distributed across these.)

A DemographicAccount.

Most of the work for derivePopulation is done by function makeConsistent.

initial <- Counts(array(c(10, 15),
                        dim = 2,
                        dimnames = list(age = c("0-29", "30+"))))
births <- Counts(array(13,
                       dim = c(1, 1),
                       dimnames = list(age = "30+",
                                       time = "1971-2000")))
deaths <- Counts(array(c(0, 9),
                       dim = c(2, 1),
                       dimnames = list(age = c("0-29", "30+"),
                                       time = c("1971-2000"))))
derivePopulation(initial = initial,
                  births = births,
                  exits = list(deaths = deaths))

## 'births' has no age dimension, so it is given one
births.no.age <- Counts(array(13,
                              dim = 1,
                              dimnames = list(time = "1971-2000")))
derivePopulation(initial = initial,
                  births = births.no.age,
                  exits = list(deaths = deaths))

## Calculations using age-time steps of one quarter.  (Note, incidentally,
## that an account does not have to start from age 0 if it does not
## include births.)
initial <- Counts(array(11:15,
                        dim = c(5, 1),
                        dimnames = list(age = c("20-20.25", "20.25-20.5",
                                           "20.5-20.75", "20.75-21", "21+"),
                                        time = 2000)),
                  dimscales = c(time = "Points"))
deaths <- Counts(array(c(0, 2, 1, 3, 4, 1, 2, 3, 1, 5),
                       dim = c(5, 2, 1),
                       dimnames = list(age = c("20-20.25", "20.25-20.5",
                                           "20.5-20.75", "20.75-21", "21+"),
                                       triangle = c("Lower", "Upper"),
                                       time = "2000-2000.25")))
account <- derivePopulation(initial = initial,
                            exits = list(deaths = deaths))
account
summary(account)