exposureBirths {dembase} | R Documentation

## Calculate exposure to use for modelling births.

### Description

In models of births, the relevant exposure term is usually the person-years lived by women of reproductive age. `exposureBirths` makes it easy to calculate this term in typical cases.

### Usage

    exposureBirths(
      object,
      triangles = FALSE,
      births = NULL,
      dominant = c("Female", "Male")
    )

    ## S4 method for signature 'Counts'
    exposureBirths(
      object,
      triangles = FALSE,
      births = NULL,
      dominant = c("Female", "Male")
    )

### Arguments

`object` | An object of class `Counts`.
`triangles` | Logical. If `TRUE`, the return value includes a dimension with `dimtype` code"triangle". Defaults to `FALSE`.
`births` | A `DemographicArray` object giving birth counts or rates.
`dominant` | `"Female"` (the default) or `"Male"`. Whether to use the number of potential mothers or potential fathers when calculating exposures.

### Details

The `births` argument is a tabulation of births or birth rates, typically including the age of mothers. Minimum and maxium ages for exposure are taken from this tabulation.

Fertility models are almost always "female dominant", that is, they only take account of the number of reproductive-age females, and ignore the number of reproductive age-males. By default, if `object` has two sexes, then `exposureBirths` only includes females. However, if `dominant` is set to "Male", it will only include males.

`births` can contain a sex dimension. However, this dimension describes the sex of the child, not the parent. The sex of the parent is still determined by `dominant` argument, and the same exposure is used for female and male births.

If `births` contains origin-destination or parent-child dimensions exposures are repeated once for each value of the destination or child dimension(s).

### Value

A `Counts` object, with the same dimensions as `births`.

### See Also

To calculate exposure for quantities other than births, see `exposure` (and, for origin-destination or parent-child arrays, possibly also `addPair`). To tidy fertility data, see `reallocateToEndAges`.

### Examples

    ## prepare data
    library(demdata)
    popn <- demdata::nz.popn.reg
    births <- demdata::nz.births.reg
    popn <- Counts(popn, dimscales = c(year = "Points"))
    births <- Counts(births, dimscales = c(year = "Intervals"))
    popn <- subarray(popn, year %in% c(1996, 2001, 2006, 2011, 2016))
    births <- collapseDimension(births, dimension = "region")
    births <- collapseIntervals(births, dimension = "year", width = 5)
    births.nosex <- collapseDimension(births, dimension = "sex")

    ## no triangles
    exposureBirths(popn, births = births.nosex)

    ## with triangles
    exposureBirths(popn, triangles = TRUE, births = births.nosex)

    ## dominant
    exposureBirths(popn, births = births.nosex, dominant = "Male")

    ## distinguish sex of births
    exposureBirths(popn, births = births)

    ## origin-destination - same exposure for each destination
    popn <- Counts(array(11:14,
                         dim = c(2, 2),
                         dimnames = list(time = c(2010, 2020),
                                         region = c("A", "B"))))
    births <- Values(array(c(0.3, 0.2, 0.5, 0.4),
                           dim = c(2, 2, 1),
                           dimnames = list(region_orig = c("A", "B"),
                                           region_dest = c("A", "B"),
                                           time = "2011-2020")))
    exposureBirths(popn, births = births)

[Package dembase version 0.0.0.119 Index]