Save and read portable SBT fits

sbt_fit_save() writes only the lean portable core of an sbt_fit() object. RTMB objectives live in a session-only cache and are never serialized. In a project containing a .sbt-artifacts.dcf configuration, files above its size threshold are stored as content-addressed GitHub Release assets. The requested path then contains a small pointer, while sbt_fit_read() transparently downloads, caches, and checksum-verifies the complete RDS. Projects without this configuration retain the ordinary local-RDS behaviour. The DCF configuration requires Repository (owner/repository) and Release fields. Threshold-MiB defaults to 90, Release-Name defaults to "SBT fit artefacts", and Enabled: false disables external storage. Remote pointers contain no credentials. Private repositories use the GitHub token available through gh::gh_token(), and downloaded fits are cached below tools::R_user_dir("sbt", "cache") unless the sbt.artifact_cache option specifies another directory. sbt_fit_read() validates the portable state and, by default, rebuilds and caches a fresh objective from the current compatible model implementation. Compatibility is controlled by the explicit model scientific contract rather than the exact source checksum. A changed source checksum within the same contract produces a warning and the rebuilt objective must still reproduce the saved objective. Supported older schemas are upgraded in memory without optimization or sampling.

Usage

sbt_fit_save(x, file, compress = "gzip", overwrite = FALSE)

sbt_fit_read(file, strict = FALSE, rebuild = TRUE, verify_validation = TRUE)

Arguments

x

An sbt_fit object.

file

File path.

compress

Compression passed to saveRDS().

overwrite

If TRUE, replace an existing file.

strict

If TRUE, error when the saved model scientific contract is incompatible with the current package. Source-checksum differences within the same contract are warnings and are verified by objective rebuilding. If FALSE, incompatibilities are warned about and the portable results remain available for inspection.

rebuild

Rebuild and cache a fresh RTMB objective after reading when the fit has resolved configuration. Defaults to TRUE; use FALSE for lightweight inspection or intentionally incompatible historical fits.

verify_validation

Verify any embedded fit-validation record against its compact payload and diagnostic checksums. Set to FALSE only when a caller will explicitly use check_mle(..., mode = "skip") or check_mcmc(..., mode = "skip"), or will verify the record separately.

Value

sbt_fit_save() invisibly returns the normalized file path; sbt_fit_read() returns an sbt_fit object.

See also

Other fit workflow: check_mcmc(), check_mle(), sbt_add_bounds(), sbt_add_map(), sbt_add_msy(), sbt_add_parameters(), sbt_add_priors(), sbt_build_object(), sbt_example_fit(), sbt_fit(), sbt_fit_compatibility(), sbt_fit_rebuild(), sbt_fit_report(), sbt_fit_validate(), sbt_fit_validation(), sbt_mcmc(), sbt_obj(), sbt_optimise()

Examples

fit <- sbt_example_fit(rebuild = FALSE)
#> Warning: Dependency versions differ: RTMBdist, TMB
path <- tempfile(fileext = ".sbt.rds")
sbt_fit_save(fit, path)
restored <- sbt_fit_read(path, rebuild = FALSE)
#> Warning: Dependency versions differ: RTMBdist, TMB
restored
#> <sbt_fit>
#>   Model:       sbt_model (schema 2)
#>   sbt version: 3.0.0
#>   Stage:       optimised
#>   Parameters:  1559 active
#>   Objective:   7593.445
#>   Convergence: 0
#>   Estimability: All 1,559 active fixed-effect parameters are estimable.
#>   MLE check:    passed
#>   MCMC:        not stored
#>   MSY:         0 stored calculations
#>   Next:        sbt_mcmc()
#>   Created:     2026-08-21 02:09:39 UTC
unlink(path)