Fit a Generalised SiGN Model and Evaluate Fit Quality

This function fits a generalised version of the SiGN model to observed choice proportions using non-linear least squares via nlsLM(), and evaluates model fit using both descriptive and likelihood-based metrics. A beta-distributed error model is used to estimate the log-likelihood and compute AIC and BIC values. The model includes three free parameters: bias (b), sensitivity to reinforcement rate (k_r), and sensitivity to delay reduction (k_d).

Usage

SiGN_gen_eval(params, observed, b = 1, k_r = 1, k_d = 1, epsilon = 0.001, ...)

Arguments

params: A list of parameter inputs compatible with the SiGN() function, such as the output from choice_params(). Must be of the same length as observed.
observed: A numeric vector of observed choice proportions, one per condition. Values must lie strictly between 0 and 1.
b: Starting value for the bias parameter (default is 1).
k_r: Starting value for the reinforcement rate sensitivity parameter (default is 1).
k_d: Starting value for the delay reduction sensitivity parameter (default is 1).
epsilon: A small positive value used to prevent undefined operations (e.g., division by zero). Used when computing delay reductions or for numerical stability in likelihood calculations.
...: Additional arguments passed to internal functions.

Value

A list of class "SiGN_gen_eval" with the following components:

param_est: A data frame of estimated model parameters (b, k_r, k_d).
desc_stats: Descriptive statistics summarizing model fit (e.g., RMSE, R-squared, MAE, CCC).
info_criteria: A data frame with the estimated phi, total log-likelihood, AIC, and BIC.
mod_info: The full model object returned by nlsLM().
phi_optim_result: The result from optimize() used to estimate the beta model precision parameter.
residuals: Vector of residuals (observed minus predicted choice proportions).
details: A data frame of all intermediate values, including predictions and components of the SiGN model.

Details

The function assumes that each observed choice proportion is independent and follows a beta distribution centred around the predicted value from the generalised SiGN model. A single precision parameter (phi) is estimated per model fit. AIC and BIC are based on four free parameters (three from the model, one from the error distribution). Residual checks are recommended. For additional details regarding the Beta error model, see choice_mod_eval.

Examples

params <- do.call(choice_params, as.list(subopt_avian[9:24]))
result <- SiGN_gen_eval(params, subopt_avian$cp, b = 1, k_r = 1, k_d = 1)
#> ℹ Default starting values (1, 1, 1) are being used. For better results, consider setting values that match the patterns in your data - poor starting points can trip up the fitting algorithm.
print(result)
#> $param_est
#>          b       k_r       k_d
#> b 1.030268 0.8627061 0.6784299
#> 
#> $desc_stats
#>     n r_squared    mean_bias      rmse        mae  median_ae       ccc
#> 1 128 0.7968094 -0.007361284 0.1299345 0.09918741 0.07952289 0.9033226
#> 
#> $info_criteria
#>   n_parameters      phi   logLik       AIC       BIC
#> 1            4 8.165909 10.48557 -12.97115 -1.563027