The `results` class stores estimation (`$estimate()`) and simulation (`$simulate()`) results.
This class is primarily intended for internal use within the `iglm` framework but provides structured access to the results via the active bindings of the main `iglm_object`.
Active bindings
coefficients_path(`matrix` or `NULL`) Read-only. The path of all estimated coefficients across iterations.
samples(`list` or `NULL`) Read-only. A list of simulated `iglm.data` objects (class `iglm.data.list`).
stats(`matrix` or `NULL`) Read-only. Matrix of summary statistics for simulated samples, which are an `mcmc` obect from `coda`.
var(`matrix` or `NULL`) Read-only. Estimated variance-covariance matrix for non-degrees coefficients.
fisher_degrees(`matrix` or `NULL`) Read-only. Fisher information matrix for degrees coefficients.
fisher_nondegrees(`matrix` or `NULL`) Read-only. Fisher information matrix for non-degrees coefficients.
score_degrees(`numeric` or `NULL`) Read-only. Score vector for degrees coefficients.
score_nondegrees(`numeric` or `NULL`) Read-only. Score vector for non-degrees coefficients.
llh(`numeric` or `NULL`) Read-only. Vector of log-likelihood values recorded during estimation.
model_assessment(`list` or `NULL`) Read-only. Results from model assessment (goodness-of-fit).
estimated(`logical`) Read-only. Flag indicating if estimation has been completed.
Methods
results$new()
Creates a new `results` object. Initializes internal fields, primarily setting up an empty matrix for the `coefficients_path` based on the expected number of coefficients.
Usage
results$new(size_coef, size_coef_degrees, file)Arguments
size_coef(integer) The number of non-degrees (structural) coefficients in the model.
size_coef_degrees(integer) The number of degrees coefficients in the model (0 if none).
file(character or `NULL`) If provided, loads the sampler state from the specified .rds file instead of initializing from parameters.
results$set_model_assessment()
Stores the results object generated by a model assessment (goodness-of-fit) procedure within this `results` container.
results$gather()
Gathers the current state of the `results` object into a list for saving or inspection. This includes all internal fields such as coefficient paths, samples, statistics, variance-covariance matrix, Fisher information, score vectors, log-likelihood values, model assessment results, and estimation status.
results$save()
Saves the current state of the `results` object to a specified file path in RDS format. This allows for persisting the results for later retrieval and analysis.
results$resize()
Resizes the internal storage for the coefficient paths to accommodate a different number of coefficients. This is useful if the model structure changes and the results object needs to be reset.
results$update()
Updates the internal fields of the `results` object with new outputs, typically after an estimation run (`$estimate()`) or simulation run (`$simulate()`). Allows selectively updating components. Appends to `coefficients_path` and `llh` if called multiple times after estimation. Replaces `samples` and `stats`.
Usage
results$update(
coefficients_path = NULL,
samples = NULL,
var = NULL,
fisher_degrees = NULL,
fisher_nondegrees = NULL,
score_degrees = NULL,
score_nondegrees = NULL,
llh = NULL,
stats = NULL,
estimated = FALSE
)Arguments
coefficients_path(matrix) A matrix where rows represent iterations and columns represent all coefficients (non-degrees then degrees), showing their values during estimation. If provided, appends to any existing path.
samples(list) A list of simulated `iglm.data` objects (class `iglm.data.list`). If provided, replaces any existing samples.
var(matrix) The estimated variance-covariance matrix for the non-degrees coefficients. Replaces existing matrix.
fisher_degrees(matrix) The Fisher information matrix for degrees coefficients. Replaces existing matrix.
fisher_nondegrees(matrix) The Fisher information matrix for non-degrees coefficients. Replaces existing matrix.
score_degrees(numeric) The score vector for degrees coefficients. Replaces existing vector.
score_nondegrees(numeric) The score vector for non-degrees coefficients. Replaces existing vector.
llh(numeric) Log-likelihood value(s). If provided, appends to the existing vector of log-likelihoods.
stats(matrix) A matrix of summary statistics from simulations, where rows correspond to simulations and columns to statistics. Replaces or extends the existing matrix and will be turned into a mcmc object from the `coda` package.
estimated(logical) A flag indicating whether these results come from a completed estimation run. Updates the internal status.
results$remove_samples()
Clears the stored simulation samples (`.samples`) and statistics (`.stats`) from the object, resetting it to an empty list. This might be used to save memory or before running new simulations.
results$plot()
Generates diagnostic plots for the estimation results. Currently plots:
The log-likelihood path across iterations.
The convergence paths for degrees coefficients (if present).
The convergence paths for non-degrees coefficients.
Optionally, can also trigger plotting of model assessment results if available.
Arguments
trace(logical) If `TRUE` (default), plot the trace plots of the estimation (log-likelihood and coefficient paths). Requires model to be estimated.
stats(logical) If `TRUE`, plots the normalized statistics from simulations. Default is `FALSE`.
model_assessment(logical) If `TRUE`, attempts to plot the results stored in the `.model_assessment` field. Requires model assessment to have been run and a suitable `plot` method for `iglm_model_assessment` objects to exist. Default is `FALSE`.
...Additional fits with identical model_assessment terms are currently identified from this argument. The names of the arguments are shown as the legend in the model assessment plots.
results$print()
Prints a concise summary of the contents of the `results` object, indicating whether various components (coefficients path, variance matrix, Fisher info, score, samples, stats, etc.) are available.