news and misc vignette update

NEWS.md

@@ -18,6 +18,13 @@ when `exp_stats()` is passed a weighting variable.
 - Added a `summary()` method for `exposed_df` objects that calls `exp_stats()`.
 - The assumed default status in `expose()` functions was changed from the first
 observed status to the most common status.
+- The functions `as_exp_df()` and `as_trx_df()` were added to convert 
+pre-aggregated experience studies to the `exp_df` and `trx_df` formats, 
+respectively.
+- `agg_sim_dat` - a new simulated data set of pre-aggregated experience was 
+added for testing `as_exp_df()` and `as_trx_df()`.
+- `is_exp_df()` and `as_trx_df()` were added to test for the `exp_df` and 
+`trx_df` classes.
 
 # actxps 1.3.0
 

vignettes/misc.Rmd

@@ -24,6 +24,42 @@ library(actxps)
 library(lubridate)
 ```
 
+## Working with aggregate experience data
+
+Seriatim-level policy experience data is often not available for analysis. This is almost always the case with industry studies that contain experience data submitted by multiple parties. In these cases, experience is grouped by a several common policy attributes and aggregated accordingly.
+
+The typical workflow in actxps of `expose() |> exp_stats()` for termination studies or `expose() |> add_transactions() |> trx_stats()` for transaction studies doesn't apply if the starting data is aggregated. That is because another party has already gone through the steps of creating exposure records and performing an initial level of aggregation.
+
+Actxps provides two functions designed to work with aggregate experience data.
+
+- For termination studies, `as_exp_df()` converts a data frame of aggregate experience into an `exp_df` object, which is the class returned by `exp_stats()`
+= For transaction studies, `as_trx_df()` converts a data frame of aggregate experience into a `trx_df` object, which is the class returned by `trx_stats()`
+
+Both object classes have a `summary()` method which summarizes experience across any grouping variables passed to the function. The output of `summary()` will always be another `exp_df` (or `trx_df`) object, and will look just like the results of `exp_stats()` (or `trx_stats()`). For downstream reporting, summary results can be passed to the visualization functions `autoplot()` and `autotable()`.
+
+The `agg_sim_dat` data set contains aggregate experience on a theoretical block of deferred annuity contracts. Below, `as_exp_df()` is used to convert the data to an `exp_df`, and `summary()` is called using multiple grouping variables.
+
+```{r agg-exp-1}
+agg_sim_exp_df <- agg_sim_dat |> 
+  as_exp_df(col_exposure = "exposure_n", col_claims = "claims_n",
+            conf_int = TRUE,
+            start_date = 2005, end_date = 2019, target_status = "Surrender")
+```
+
+Results summarized by policy year
+
+```{r agg-exp-2}
+summary(agg_sim_exp_df, pol_yr)
+```
+
+Results summarized by income guarantee presence and product
+
+```{r agg-exp-3}
+summary(agg_sim_exp_df, inc_guar, product)
+```
+
+`as_exp_df()` and `as_trx_df()` contain several arguments for optional calculations like confidence intervals, expected values, weighting variables, and more. These arguments mirror the functionality in `exp_stats()` and `trx_stats()`. Both functions also contain multiple arguments for specifying column names associated with required values like exposures and claims.
+
 ## Policy duration functions
 
 The `pol_()` family of functions calculates policy years, months, quarters, weeks, or any other arbitrary duration. Each function accepts a vector of dates and a vector of issue dates.