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
Method 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.generator$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.
Method set_model_assessment()
Stores the results object generated by a model assessment (goodness-of-fit) procedure within this `results` container.
Method 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.
Method 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.
Method 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.
Method 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.generator$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.
Method 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.
Method 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.
Method 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.