
Plot parameter-recovery simulation results
Source:R/api-simulation.R
plot.mfrm_recovery_simulation.RdPlot parameter-recovery simulation results
Usage
# S3 method for class 'mfrm_recovery_simulation'
plot(
x,
y = NULL,
type = c("summary", "coverage", "errors", "scatter", "replications"),
metric = c("rmse", "bias", "mae", "correlation", "coverage", "mcse_bias", "mcse_rmse",
"raw_rmse", "raw_bias", "mean_se", "se_available"),
parameter_type = NULL,
facet = NULL,
comparison = c("aligned", "unaligned"),
draw = TRUE,
...
)Arguments
- x
Output from
simulate_mfrm_recovery().- y
Reserved for S3 generic compatibility.
- type
Plot route:
"summary"draws a metric fromsummary(x)$recovery_summary,"coverage"draws 95% coverage by parameter group,"errors"draws row-level recovery-error distributions,"scatter"draws truth against estimated values, and"replications"summarizes run status.- metric
Summary metric used when
type = "summary". Supported values are"rmse","bias","mae","correlation","coverage","mcse_bias","mcse_rmse","raw_rmse","raw_bias","mean_se", and"se_available".- parameter_type
Optional parameter type filter, such as
"person","facet","step","slope", or"population".- facet
Optional facet filter.
- comparison
Error/estimate scale for row-level routes.
"aligned"usesEstimateAligned/ErrorAligned;"unaligned"usesEstimate/ErrorRawon the same comparison scale.- draw
If
TRUE, draw with base graphics. IfFALSE, return anmfrm_plot_dataobject with reusable plot tables and metadata.- ...
Reserved for generic compatibility.
Details
These plots are intended as simulation-review graphics. They do not replace
the row-level x$recovery table or the ADEMP metadata; they make the main
recovery estimands easier to inspect during model-development and design
checks. Coverage is displayed only for groups with valid centered structural
intervals, conditional on availability. Summary/coverage routes refresh
aggregates from saved rows; their data$availability_table preserves all
selected groups, including those omitted from drawing. Inspect counts,
availability rates, MCSEs and CIReasons there and in summary(x).
A wholly unavailable coverage plot gives an informative error; it does not
draw missing coverage as zero. See simulate_mfrm_recovery() for the target
and the treatment of legacy saved intervals. A zero mean-aligned bias is an
identification identity, not evidence of unbiased estimation.
Examples
# One saved replication illustrates output structure, not precise rates.
# Regeneration recipe: examples/simulation-results.R in the package.
saved <- readRDS(system.file("examples", "simulation-recovery.rds",
package = "mfrmr", mustWork = TRUE))
# Inspect saved$generation_warnings and the result's run/status tables.
rec <- saved$result
plot(rec, type = "summary", metric = "rmse", draw = FALSE)
#> <mfrm_plot_data>
#> name : recovery_simulation
#> title : Parameter recovery: RMSE
#> subtitle : Summary by parameter type, facet, and comparison scale
#> notes :
#> [note] MCSE uses independent simulation trials, with a ratio
#> linearization for unequal numbers of available parameter rows; fewer
#> than two contributing trials gives NA.
#> [note] Coverage95 is conditional on available centered facet intervals.
#> Report ExpectedRows, CoverageRows, CoverageAvailabilityRate and
#> FailedReps alongside it; unavailable intervals are not counted as
#> noncoverage.
#> [note] Mean-aligned location Bias and complete identified log-slope
#> group Bias are zero by construction; they are not evidence of truth
#> centering and receive BiasStatus = not_assessed. RMSE describes
#> within-group relative recovery.
#> [note] Some fitted models did not report convergence; inspect
#> `rep_overview` before interpreting recovery summaries.
#> [note] Some planned targets have no supported centered structural
#> interval. RawSE preserves source uncertainty, including Person-score
#> uncertainty, without treating it as an interval for this target.
#> data :
#> $type : character [1]
#> $metric : character [1]
#> $metric_label : character [1]
#> $comparison : character [1]
#> $parameter_type : NULL
#> $facet : NULL
#> $plot_table : data.frame [4 x 41]
#> $availability_table : data.frame [4 x 39]
#> $plot_name : character [1]
#> legend : 0 entries
#> ref lines: 0
#> Use `plot_data()` to extract the saved values and notes.
#> For supported views, `as_ggplot()` redraws this saved result.