fit_general_average_model: Fit general model to averages and apply trend to original...

In caldwellst/augury: Provides Streamlined Methods for Data Imputation and Forecasting for WHO DDI Statistics

Fit general model to averages and apply trend to original data

Description

Used within predict_general_mdl_avg_trend(), this function fits the model to the data frame, working whether the model is being fit across the entire data frame or being fit to each group individually. Data is filtered prior to fitting, model(s) are fit, and then fitted values are generated on the original.

Usage

fit_general_average_model(
  df,
  model,
  formula,
  average_cols,
  weight_col,
  ...,
  formula_vars,
  test_col,
  group_col,
  group_models,
  sort_col,
  sort_descending,
  pred_col,
  pred_upper_col,
  pred_lower_col,
  filter_na,
  ret,
  error_correct,
  error_correct_cols,
  shift_trend
)

Arguments

df	Data frame of model data.
model	An R function that outputs a model object with a predict.model generic, where stats::family() contains an inverse link function linkinv and predict.model() accepts the se.fit = TRUE argument and returns confidence intervals. This includes stats::lm, stats::glm, and lme4::lmer.
formula	A formula that will be supplied to the model, such as y~x. Variables defined in the formula will be used in the averaging. If the variable is defined as part of average_cols, then it will be used within dplyr::group_by() prior to averaging. If it is not a part of average_cols, then it must be a numeric column whose average will be taken.
average_cols	Column name(s) of column(s) for use in grouping data for averaging, such as regions. If missing, uses global average of the data for infilling.
weight_col	Column name of column of weights to be used in averaging, such as country population.
...	Other arguments passed to the model function.
formula_vars	Variables included in the model formula, generated by all.vars(formula).
test_col	Name of logical column specifying which response values to remove for testing the model's predictive accuracy. If NULL, ignored. See model_error() for details on the methods and metrics returned.
group_col	Column name(s) of group(s) to use in dplyr::group_by() when supplying type, calculating mean absolute scaled error on data involving time series, and if group_models, then fitting and predicting models too. If NULL, not used. Defaults to "iso3".
group_models	Logical, whether or not to run separate models for each group defined by average_cols. If the sort_col is part of average_cols, then it is not used to group models.
sort_col	Column name(s) to use to dplyr::arrange() the data prior to supplying type and calculating mean absolute scaled error on data involving time series. If NULL, not used. Defaults to "year".
sort_descending	Logical value on whether the sorted values from sort_col should be sorted in descending order. Defaults to FALSE.
pred_col	Column name to store predicted value.
pred_upper_col	Column name to store upper bound of confidence interval generated by the predict_... function. This stores the full set of generated values for the upper bound.
pred_lower_col	Column name to store lower bound of confidence interval generated by the predict_... function. This stores the full set of generated values for the lower bound.
filter_na	Character value specifying how, if at all, to filter NA values from the dataset prior to applying the model. By default, all observations with missing values are removed, although it can also remove rows only if they have missing dependent or independent variables, or no filtering at all.
ret	Character vector specifying what values the function returns. Defaults to returning a data frame, but can return a vector of model error, the model itself or a list with all 3 as components.
error_correct	Logical value indicating whether or not whether mean error should be used to adjust predicted values. If TRUE, the mean error between observed and predicted data points will be used to adjust predictions. If error_correct_cols is not NULL, mean error will be used within those groups instead of overall mean error.
error_correct_cols	Column names of data frame to group by when applying error correction to the predicted values.
shift_trend	Logical value specifying whether or not to shift predictions so that the trend matches up to the last observation. If error_correct and shift_trend are both TRUE, shift_trend takes precedence.

Details

If fitting models individually to each group, mdl will never be returned, as as these are instead a large group of models. Otherwise, a list of mdl and df is returned and used within predict_general_mdl().

Value

List of mdl (fitted model) and df (data frame with fitted values and confidence bounds generated from the model).

caldwellst/augury documentation built on Oct. 10, 2024, 8:20 a.m.