Add vignette for custom knockoff statistic

[svoss09]

Scope

The {knockofftools} infrastructure allows the user to provide a custom
knockoff statistic. However, the current documentation doesn't
contain any information on the required structure of the function(s).

The new vignette should cover the separate functions and their
structural details that are required for seamless integration.

Worked example will be:

• {ranger} engine - more commonly used than {randomForestSRC} in general
  ({randomForestSRC} has default anti-split for importance-measure)

• importance measure. The vignette will use

  • the (built-in) permutation importance provided by {ranger}
    (allow focusing on the design of the custom functions as no additional
    step is required for importance computation)
  • example of Shapley values using {treeshap}

Details

Writing the functions

The following description of individual components follows the current
structure in the package.

• stat_* <- function(X, X_k, y, type = "regression", ...) { ... }

  • input as for existing stat_* functions, with
    ... to pass further arguments for importance score calculation
    (can apply to modelling or importance, resp.)
  • output: data frame/tibble, exactly one column named W,
    one row per predictor, rownames equal to colnames(X)
  • skeleton, including checks and comparison of
    original and corresponding knockoff variable importance
  • call helper for modeling and importance computation

• helper functions called within stat_*:

  • model_*() <- function(X, y, type = "regression", ...) { ... }
    to fit the custom model on combined feature matrix after swapping
  • importance_*() to compute individual importances for knockoff and
    original variables
  • both wrapped in scores_*() to match scores_random_forest()

Using the functions

Custom statistic needs to be available in current environment, i.e.
before calling knockoff.statistics() with custom statistic,
the user can either

• attach custom extension package, that exports the required functions
  (recommended)
• source function definitions from a script
• define the functions in the current script / on the fly

Advanced usage

With the custom functions in place, user can also implement the
"manual" workflow for knockoff.statistics(), i.e.

• create knockoffs
• swap
• model
• compute importance scores
• aggregate and correct for swapping

Using the example custom functions, show how this allows to extract additional
information, that would not be accessible using the knockoff.statistics()
wrapper.
For instance, compute both multiple importance metrics on the same model, keep
importances for original and knockoff variables separately, or
extract model performance measure.

Related Tasks

• update knockoff.statistics() documentation

[kormama1]

@svoss09 and @ahrensmaike, this looks really good and well thought out. I particularly, like the additional "manual workflow" feature of the vignette. No critiques really. Thank you!