Construct prewhitening options — prewhiten

Convenience constructor for the prewhiten= list accepted by lss().

Usage

prewhiten_options(
  method = c("none", "ar", "arma"),
  p = "auto",
  q = 0L,
  p_max = 6L,
  pooling = c("global", "voxel", "run", "parcel"),
  runs = NULL,
  parcels = NULL,
  exact_first = c("ar1", "none"),
  compute_residuals = TRUE,
  design = NULL,
  acvf_correction = NULL,
  correction_max_lag = 25L,
  voxel_bins = 50L,
  residual_model = NULL
)

Arguments

method: "none", "ar", or "arma".
p: AR order or "auto".
q: MA order for ARMA.
p_max: Maximum AR order when p="auto".
pooling: "global", "voxel", "run", or "parcel".
runs: Optional complete exact-integer run identifiers. Required for pooling = "run"; execution requires one value per timepoint.
parcels: Optional complete exact-integer parcel identifiers. Required for pooling = "parcel"; execution requires one value per voxel.
exact_first: "ar1" or "none".
compute_residuals: Logical.
design: Optional numeric design matrix whose projection produced the residuals used to estimate the noise model. Supplying it opts in to fmriAR's residual-autocovariance bias correction. It must represent the same column space as the design used for residualization.
acvf_correction: Optional bias-correction matrix, or list of matrices, produced by fmriAR::acvf_bias_matrix(). This is a cached alternative to design; the two options are mutually exclusive.
correction_max_lag: Positive integer lag budget used when design is supplied. See fmriAR::fit_noise() for the computational and filtering requirements of the correction.
voxel_bins: Positive integer number of autocorrelation bins used by pooling = "voxel" in the weight-matrix LSS methods. Voxels with similar residual autocorrelation share one AR model refitted from their pooled residuals (default 50).
residual_model: Which model's OLS residuals the noise model is estimated from. "aggregate" (the default unless design or acvf_correction is supplied) keeps the confounds plus one summed regressor per trial group or basis function: fast and available for every pooling mode, but trial-to-trial response variability stays in the residuals and inflates the autocorrelation estimate when it is large relative to the noise. "full" uses every trial regressor (the LSA model); with many trials this removes so many degrees of freedom that the autocorrelation is biased strongly downward. "corrected" uses the full model and fmriAR's residual-autocovariance bias correction, built automatically; it is the least biased choice but costs roughly O(n^2 x trials) and requires method = "ar" with global or run pooling. Supplying design or acvf_correction yourself implies "full". See vignette("prewhitening").

Value

A list with class "fmrilss_prewhiten_options".

Examples

prewhiten_options(method = "ar", p = 1, pooling = "run",
                  runs = rep(1:2, each = 50))
#> $method
#> [1] "ar"
#> 
#> $p
#> [1] 1
#> 
#> $q
#> [1] 0
#> 
#> $p_max
#> [1] 6
#> 
#> $pooling
#> [1] "run"
#> 
#> $runs
#>   [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#>  [38] 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
#>  [75] 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
#> 
#> $parcels
#> NULL
#> 
#> $exact_first
#> [1] "ar1"
#> 
#> $compute_residuals
#> [1] TRUE
#> 
#> $design
#> NULL
#> 
#> $acvf_correction
#> NULL
#> 
#> $correction_max_lag
#> [1] 25
#> 
#> $voxel_bins
#> [1] 50
#> 
#> $residual_model
#> [1] "aggregate"
#> 
#> attr(,"class")
#> [1] "fmrilss_prewhiten_options" "list"