feat: Inital setup of MACB function

This defines the API and core calculation for calculating MACB
from an input `data.table`.

References #60, #19

NAMESPACE

@@ -17,6 +17,7 @@ export(gen_u5_ax)
 export(iterate_ax)
 export(leslie_matrix)
 export(lifetable)
+export(macb_from_nfx)
 export(mx_ax_to_qx)
 export(mx_qx_to_ax)
 export(mx_to_ax)

R/mcab.R

@@ -0,0 +1,52 @@
+#' @title Calculate Mean Age of Childbearing from Fertility Rate (MACB)
+#'
+#' @description
+#' The mean age at childbearing is the mean age of mothers at the birth of their
+#' children if women were subject throughout their lives to the age-specific
+#' fertility rates observed in a given year.
+#'
+#' See [UNPOP page][1] for more deatils.
+#'
+#' [1]: https://www.un.org/en/development/desa/population/publications/dataset/fertility/age-childbearing.asp
+#'
+#' @param dt \[`data.table()`\]\cr A data.table with columns 'age_start',
+#'   'age_end', and a column of fertility rates named after `nfx_col`.
+#' @param nfx_col \[`character(1)`\]\cr Name of fertility rate column in `dt`.
+#'   Defualts to "nfx".
+#' @inheritParams gen_lifetable_parameters
+#' @param value_col \[`character(1)`\]\cr Name of output 'MACB' column. Defaults
+#'   to "mcab"
+#'
+#' @return \[`data.table()`\] A data.table with calculated 'MACB' for each
+#'   unique grouping in `id_cols`, stored in `value_col`.
+#'
+#' @export
+#'
+#' @examples
+macb_from_nfx <- function(dt, id_cols, nfx_col = "nfx", value_col = "macb") {
+
+
+  # Validate parameters -----------------------------------------------------
+
+  assertthat::assert_that(
+    assertthat::is.string(nfx_col),
+    assertthat::is.string(value_col)
+  )
+
+
+  # Prep id columns ---------------------------------------------------------
+
+  id_cols_no_age <- id_cols[!id_cols %in% c("age_start", "age_end")]
+
+
+  # Calculate MACB ----------------------------------------------------------
+
+  macb_dt <- dt[
+    ,
+    get(value_col) = weighted.mean((age_end - age_start) / 2, get(nfx_col)),
+    by = id_cols_no_age
+  ]
+
+  return(macb_dt)
+
+}