fic.flexsurvreg: Focused information criteria for flexible parametric survival...
In fic: Focused Information Criteria for Model Comparison

Description Usage Arguments Details Examples

Focused information criteria for parametric survival models fitted with the flexsurv package.

## S3 method for class 'flexsurvreg'
fic(wide, inds, inds0 = NULL, gamma0 = 0,
  focus = NULL, focus_deriv = NULL, wt = NULL, sub = NULL, B = 0,
  loss = loss_mse, ...)

`wide`	Object of class `"flexsurvreg"` containing the wide model. These are returned, for example, by the `flexsurvreg` and the `flexsurvspline` functions.
`inds`	Matrix or vector of indicators for which parameters are included in the submodel or submodels to be assessed. A matrix should be supplied if there are multiple submodels. This should have number of rows equal to the number of submodels, and number of columns equal to the total number of parameters in the wide model. It contains 1s in the positions where the parameter is included in the submodel, and 0s in positions where the parameter is excluded. This should always be 1 in the positions defining the narrow model, as specified in `inds0`.
`inds0`	Vector of indicators specifying the narrow model, in the same format as `inds`. If this is omitted, the narrow model is assumed to be defined by the first row of `inds` (if `inds` is a matrix), or `inds` itself if this is a vector.
`gamma0`	Vector of special values taken by the parameters gamma which define the narrow model. This defaults to 0, as in covariate selection, where "excluded" coefficients are fixed to 0. This should either be a scalar, assumed to be the same for all parameters fixed in the narrow model, or a vector of length equal to the number of parameters from the wide model which are fixed in the narrow model, that is, the number of entries of `inds0` which are zero.
`focus`	An R function with: first argument named `par`, denoting a vector of parameters, of the same length as in wide model other arguments defining alternative focuses. These are supplied through the `...` argument to `fic`. In the built-in examples, there is an argument named `X`, denoting alternative covariate values. The required format is documented below. The function should return the focus quantity of interest. If additional arguments are supplied which are vectors or matrices, e.g. `X`, then these are assumed to represent multiple focuses, and `focus` should return a vector giving the focus for `par` and each row of `X`. Otherwise `focus` should return a scalar giving the focus value at `par`. Not required if `focus_deriv` is specified. Alternatively, `focus` can be a character string naming a built-in focus function supplied by the fic package. Currently these include: `"prob_logistic"`, the probability of the outcome in a logistic regression model `"mean_normal"` the mean outcome in a normal linear regression model See `focus_fns` for the functions underlying these built-in focuses.
`focus_deriv`	Vector of partial derivatives of the focus function with respect to the parameters in the wide model. This is not usually needed, as it can generally be computed automatically and accurately from the function supplied in `focus`, using numerical differentiation.
`wt`	Vector of weights to apply to different covariate values in `X`. This should have length equal to the number of alternative values for the covariates, that is, the number of alternative focuses of interest. The covariate-specific focused model comparison statistics are then supplemented by averaged statistics for a population defined by this distribution of covariate values. If this argument is omitted, the values are assumed to have equal weight when computing the average. The weights are not normalised, though the interpretation is unclear if the weights don't sum to one.
`sub`	List of objects of class `flexsurvreg` containing the submodels to be assessed. Optional. Only required if you want the estimate of the focus function under the submodels to be included in the results.
`B`	If `B` is 0 (the default) the standard analytic formulae for the focused model comparison statistics are used with mean square error loss. If `B`>0, then a parametric bootstrap method is used with `B` bootstrap samples, and the loss specified in the `loss` argument. More details of this approach are given in the package vignette "Focused model comparison with bootstrapping and alternative loss functions".
`loss`	A function returning an estimated loss for a submodel estimate under the sampling distribution of the wide model. Only applicable when using bootstrapping. This should have two arguments `sub` and `wide`. `sub` should be a scalar giving the focus estimate from a submodel. `wide` should be a vector with a sample of focus estimates from the wide model, e.g. generated by a bootstrap method. By default this is a function calculating the root mean square error of the submodel estimate. An example is given in the vignette "Focused model comparison with bootstrapping and alternative loss functions".
`...`	Other arguments to the focus function can be supplied here. The built-in focus functions `prob_logistic` and `mean_normal` take an argument `X` giving covariate values defining the focus. This can either be a matrix or a vector, or a list or data frame that can be coerced into a matrix. If just one focus is needed, then `X` can be a vector of length equal to the number of parameters in the wide model. To compute focused model comparison statistics for multiple focuses defined by the same focus function evaluated at multiple covariate values, `X` should be a matrix, with number of columns equal to the number of parameters in the wide model, and number of rows equal to the number of alternative focuses. For a typical regression model, the first parameter will denote an intercept, so the first value of `X` should be 1, and the remaining values should correspond to covariates whose coefficients form parameters of the wide model. See the examples in the vignette. Arguments to the focus function other than `X` can also be supplied as a matrix, vector, list or data frame in the same way. An exception is when the argument is supplied as a vector, this is assumed to refer to multiple focuses. For example, suppose the focus function defines the quantile of a distribution, and takes an argument `focus_p`, then calling `fic(...,focus_p=c(0.1, 0.9))` indicates two alternative focuses defined by the 0.1 and 0.9 quantiles.

Any situation where all models being compared are special cases of a single "wide" model are supported. Examples include covariate selection, selection between models for the baseline hazard/survival with different levels of flexibility (e.g. comparing exponential, Weibull and generalized gamma). Some of these are illustrated in the fic package vignette "Examples of focused model comparison: parametric survival models".

The choice between flexsurvspline models with different numbers of knots is not supported, unless perhaps if the knot locations are defined manually so that models are nested within each other, but this has not been investigated.

## Simulated example from the "fic" package vignette on
## parametric survival modelling.
## See this vignette for more details and more examples.

set.seed(1)

if (requireNamespace("flexsurv", quietly=TRUE)){

## Simulate from an exponential 
y <- rexp(50); cen <- rep(1,50)

## Fit wide generalized gamma, and compare
## exponential, weibull and generalized gamma models
indmat <- rbind(exp    = c(1,0,0),
                weib   = c(1,1,0),
                ggamma = c(1,1,1))
gge <- flexsurv::flexsurvreg(survival::Surv(y, cen) ~ 1, dist="gengamma")

## Focus is restricted mean survival over 8 time units 
focus <- function(par){
   flexsurv::rmst_gengamma(8, par[1], exp(par[2]), par[3])
}

## Weibull model actually has lowest FIC and RMSE even though it's
## not true: extra variability is deemed worth alleviating the
## risk of bias.

fic(gge, inds=indmat, gamma0=c(0,1), focus=focus)

}