Options

Logging and Verbosity

By default, macpan2 writes logs to the following path, which will be different on each machine.

library(macpan2)
file.path(
    getOption("macpan2_log_dir")
  , ".macpan2"
  , getOption("macpan2_session_name")
  , "log.txt"
)
#> [1] "/github/home/.local/share/R/macpan2/.macpan2/default/log.txt"

To log to the working directory, use options(macpan2_log_dir = ""). You can also get console output from the TMB engine using options(macpan2_verbose = TRUE).

• macpan2_session_name
  Default: "default"
• macpan2_log_dir
  Default: tools::R_user_dir("macpan2")
• macpan2_verbose
  Default: FALSE
  Controls whether the TMB engine is verbose.
  Passed as !getOption("macpan2_verbose") to TMB::MakeADFun().

Here are some examples of controlling logging and verbosity.

options(macpan2_session_name = "demo")
options(macpan2_log_dir = "")  # logs go under the working directory
options(macpan2_verbose = TRUE)

Output Data Formatting (for Scalar-Only Models)

When a model contains only scalar variables, the default output structure—which includes row, col, and a generic matrix column—can be unnecessarily complex. The following options simplify the output in these cases by:

1. Dropping the row and col columns when they provide no information.
2. Renaming the matrix column to something more meaningful.

Note that macpan2_collapse_traj also applies to all mp_trajectory_*() functions that return a data frame, such as mp_trajectory_sd() and mp_trajectory_par().

These options are often worth enabling in scalar-only models to simplify results. The only reason they are not defaults is to preserve backward compatibility with earlier versions of macpan2.

options(
    macpan2_collapse_traj = TRUE
  , macpan2_collapse_coef = TRUE
  , macpan2_collapse_default = TRUE
)

Thanks to Jonathan Dushoff for the ideas here.

Numerical Tolerances

• macpan2_tol_hazard_div
  Default: 1e-8
  Tolerance passed to proportions() via mp_hazard() to avoid division by zero.
• macpan2_tol_singular_cov
  Default: 1e-6
  Used to check whether a covariance matrix is suitable for simulating multivariate normal parameter samples.

Here is an example.

options(macpan2_tol_singular_cov = 1e-4)

Simulation and Reproducibility

• macpan2_traj_tmb_macro
  Default: "simulate"
  Allowed: "simulate", "report"
"simulate" respects set.seed(); "report" (pre-2.4.0 behavior) does not.

Time-Restricted Functions

Some engine functions have constraints based on their use in time steps or access to history.

• macpan2_time_dep_funcs
  Default: c("convolution", "rbind_lag", "rbind_time", "cbind_lag", "cbind_time")
  These functions require their first argument to have saved simulation history.
• macpan2_non_iterable_funcs
  Default: c("time_var", "rbinom", "rpois", "rnorm", "rnbinom", "reulermultinom")
  These functions cannot be called multiple times within a single time step (e.g., RK4). Includes all stochastic and time-varying calls.

Engine Control

• macpan2_dll
  Default: "macpan2"
  Name of the C++ shared object to use.

You can use a custom engine that is an alternative version of src/macpan2.cpp, called project-directory/alt.cpp for example, by running the following code:

TMB::compile("project-directory/alt.cpp")
dyn.load(TMB::dynlib("alt"))
options(macpan2_dll = "alt")

• macpan2_saving_conflict_msg_fn
  Default: base::message()
  Function to use when both must_save and must_not_save are specified. Applies to mp_tmb_model_spec() and related functions with those arguments.