Calculate total fertility aggregates

Source: R/agg_tf.R

Calculate total fertility for a specified age range using age-specific fertility rates.

agg_tf(
  dt,
  id_cols,
  age_mapping,
  missing_dt_severity = "stop",
  overlapping_dt_severity = "stop",
  present_agg_severity = "stop",
  na_value_severity = "stop",
  quiet = FALSE
)

Arguments

dt

[data.table()]
ASFR input data. Must include all columns in id_cols, and a column for 'asfr'.

id_cols

[character()]
ID columns that uniquely identify each row of dt.

age_mapping

[data.table()]
Specification of age interval to aggregate to. Required columns are 'age_start' and 'age_end'.

missing_dt_severity

[character(1)]
What should happen when dt is missing levels of col_stem that prevent aggregation or scaling from occurring? Can be either 'skip', 'stop', 'warning', 'message', or 'none'. Default is 'stop'. See section on 'Severity Arguments' for more information.

overlapping_dt_severity

[character(1)]
When aggregating/scaling an interval variable or collapse_interval_cols=TRUE what should happen when overlapping intervals are identified? Can be either 'skip', 'stop', 'warning', 'message', or 'none'. Default is 'stop'. See section on 'Severity Arguments' for more information.

present_agg_severity

[logical(1)]
What should happen when dt already has requested aggregates (from mapping)? Can be either 'skip', 'stop', 'warning', 'message', or 'none'. Default is 'stop'. See section on 'Severity Arguments' for more information.

na_value_severity

[character(1)]
What should happen when 'NA' values are present in value_cols? Can be either 'skip', 'stop', 'warning', 'message', or 'none'. Default is 'stop'. See section on 'Severity Arguments' for more information.

quiet

[logical(1)]
Should progress messages be suppressed as the function is run? Default is False.

Value

[data.table()]
Aggregated total fertility with columns for all id_cols and a 'tf' column. Will only return the age groups specified in age_mapping.

Details

Calculate total fertility aggregate for ages within a specific age range. TFR (total fertility rate) is measured over the entire reproductive age span, typically defined as between age 15 and 49 (or 10 and 54). agg_tf also allows calculation of total fertility for other age spans like total fertility under 25 and total fertility over 30.

Total fertility is calculated as the sum of ASFR multiplied by the number of years in an age group. This number represents the average number of children born to a woman if (1) she experiences a specific set of age specific fertility rates and (2) she survives through the end of the age span. Preston pg 95.

This is different from an age-specific fertility rate (ASFR) or a crude birth rate (CBR), both of which are calculated as births/population for a particular age group or all reproductive ages, respectively.

Severity Arguments

missing_dt_severity:

Check for missing levels of col_stem, the variable being aggregated or scaled over.

  1. stop: throw error (this is the default).

  2. warning or message: throw warning/message and continue with aggregation/scaling for requested aggregations/scalings where expected input data in dt is available.

  3. none: don't throw error or warning, continue with aggregation/scaling for requested aggregations/scalings where expected input data in dt is available.

  4. skip: skip this check and continue with aggregation/scaling.

present_agg_severity (agg only):

Check for requested aggregates in mapping that are already present

  1. stop: throw error (this is the default).

  2. warning or message: throw warning/message, drop aggregates and continue with aggregation.

  3. none: don't throw error or warning, drop aggregates and continue with aggregation.

  4. skip: skip this check and add to the values already present for the aggregates.

na_value_severity:

Check for 'NA' values in the value_cols.

  1. stop: throw error (this is the default).

  2. warning or message: throw warning/message, drop missing values and continue with aggregation/scaling where possible (this likely will cause another error because of missing_dt_severity, consider setting missing_dt_severity = "skip" for functionality similiar to na.rm = TRUE).

  3. none: don't throw error or warning, drop missing values and continue with aggregation/scaling where possible (this likely will cause another error because of missing_dt_severity, consider setting missing_dt_severity = "skip" for functionality similiar to na.rm = TRUE).

  4. skip: skip this check and propagate NA values through aggregation/scaling.

overlapping_dt_severity: Check for overlapping intervals that prevent collapsing to the most detailed common set of intervals. Or check for overlapping intervals in col_stem when aggregating/scaling.

  1. stop: throw error (this is the default).

  2. warning or message: throw warning/message, drop overlapping intervals and continue with aggregation/scaling where possible (this may cause another error because of missing_dt_severity).

  3. none: don't throw error or warning, drop overlapping intervals and continue with aggregation/scaling where possible (this may cause another error because of missing_dt_severity).

  4. skip: skip this check and continue with aggregation/scaling.

References

Preston, Samuel, Patrick Heuveline, and Michel Guillot. 2001. Demography: Measuring and Modeling Population. Wiley.

Examples

# calculate total fertility under 25 (ages 10 to 24)
dt <- data.table::data.table(
  age_start = c(10, 15, 20, 25, 30, 35, 40, 45),
  age_end = c(15, 20, 25, 30, 35, 40, 45, 50),
  asfr = c(0.00005, 0.02, 0.07, 0.08, 0.05, 0.02, 0.004, 0.0002)
)

dt <- agg_tf(
  dt = dt,
  id_cols = c("age_start", "age_end"),
  age_mapping = data.table::data.table(age_start = 10, age_end = 25)
)
#> Aggregating age
#> Interval group 1 of 1: [10, 15),[15, 20),[20, 25),[25, 30),[30, 35),[35, 40),[40, 45),[45, 50)
#> Aggregate 1 of 1: [10, 25)