Skip to contents

Add common metrics to an experience study

Source: R/mutate_metrics.R
mutate_metrics.Rd

mutate_metrics() calculates metrics for an experience study using common measures associated with the data. These measures are identified via the measure_sets argument which can be provided directly or be guessed using regular expressions (regexs). See guess_measure_sets() for additional detail on how this guessing is implemented.

Usage

mutate_metrics(
  .data,
  measure_sets = guess_measure_sets(.data),
  metrics = list(AVG_OBSRV = avg_observed, AVG_EXPEC = avg_expected, CI_FCTR = ci_fctr,
    AE_RATIO = ae_ratio, CREDIBILITY = credibility),
  ...,
  .by = NULL,
  .keep = c("all", "used", "unused", "none"),
  .before = NULL,
  .after = NULL
)

Arguments

.data

A base::data.frame() that houses an experience study.

measure_sets

A (potentially named) list of measure sets. Only need to specify once if chaining multiple expstudy functions as the measure_sets will be passed as an attribute in results.

metrics

A named list of functions to calculate metrics. Each function will be applied to each set identified in measure_sets.

...

Additional (optional) arguments passed along to each (metric function)metrics.

.by

[Experimental]

<tidy-select> Optionally, a selection of columns to group by for just this operation, functioning as an alternative to group_by(). For details and examples, see ?dplyr_by.

.keep

Control which columns from .data are retained in the output. Grouping columns and columns created by ... are always kept.

  • "all" retains all columns from .data. This is the default.

  • "used" retains only the columns used in ... to create new columns. This is useful for checking your work, as it displays inputs and outputs side-by-side.

  • "unused" retains only the columns not used in ... to create new columns. This is useful if you generate new columns, but no longer need the columns used to generate them.

  • "none" doesn't retain any extra columns from .data. Only the grouping variables and columns created by ... are kept.

.before, .after

<tidy-select> Optionally, control where new columns should appear (the default is to add to the right hand side). See relocate() for more details.

Value

An object of the same type as .data. The output has the following properties:

  • Columns from .data will be preserved according to the .keep argument.

  • Existing columns that are modified by ... will always be returned in their original location.

  • New columns created through ... will be placed according to the .before and .after arguments.

  • The number of rows is not affected.

  • Columns given the value NULL will be removed.

  • Groups will be recomputed if a grouping variable is mutated.

  • Data frame attributes are preserved.

Details

This function is structured in a way that uses sets of measures within the study as the first function argument of each metric function. The default argument uses a set of metric functions, provided by expstudy, which are commonly requested metrics used in actuarial analyses. For convenience, a vectorized version of these default metric functions have also been provided; see metrics for more information.

Naming convention

expstudy uses a naming convention where some functions are prefixed by the underling dplyr verb. The purpose of this is to associate the resulting structure of the expstudy function with a very similar output as what the dplyr function would produce. Note that the intention here is not replace all dplyr use cases but instead add specific functionality to streamline routine experience study analyses.

Examples

# Metrics can be added at a seriatim level, but often are
# calculated after some aggregation is applied to a cohort:
mortexp |>
  dplyr::group_by(
    GENDER
  ) |>
  summarise_measures() |>
  mutate_metrics()
#> # A tibble: 2 × 19
#>   GENDER MORT_ACTUAL_CNT MORT_EXPOSURE_CNT MORT_EXPECTED_CNT MORT_VARIANCE_CNT
#> * <fct>            <dbl>             <dbl>             <dbl>             <dbl>
#> 1 FEMALE             146             6313.              115.              115.
#> 2 MALE               169             7983.              142.              141.
#> # ℹ 14 more variables: MORT_ACTUAL_AMT <dbl>, MORT_EXPOSURE_AMT <dbl>,
#> #   MORT_EXPECTED_AMT <dbl>, MORT_VARIANCE_AMT <dbl>, AVG_OBSRV_CNT <dbl>,
#> #   AVG_EXPEC_CNT <dbl>, CI_FCTR_CNT <dbl>, AE_RATIO_CNT <dbl>,
#> #   CREDIBILITY_CNT <dbl>, AVG_OBSRV_AMT <dbl>, AVG_EXPEC_AMT <dbl>,
#> #   CI_FCTR_AMT <dbl>, AE_RATIO_AMT <dbl>, CREDIBILITY_AMT <dbl>