Type:	Package
Title:	Simulation-Based Landscape Construction for Dynamical Systems
Version:	0.4.0
Description:	A toolbox for constructing potential landscapes for dynamical systems using Monte Carlo simulation. The method is based on the potential landscape definition by Wang et al. (2008) <doi:10.1073/pnas.0800579105> (also see Zhou & Li, 2016 <doi:10.1063/1.4943096> for further mathematical discussions) and can be used for a large variety of models.
License:	GPL (≥ 3)
URL:	https://sciurus365.github.io/simlandr/, https://github.com/Sciurus365/simlandr
BugReports:	https://github.com/Sciurus365/simlandr/issues
Depends:	R (≥ 4.1.0)
Imports:	bigmemory, coda, digest, dplyr, forcats, furrr, gganimate, ggplot2, grDevices, htmlwidgets, ks, lifecycle, magrittr, MASS, methods, plotly, progress, purrr, rlang, Sim.DiffProc, tibble, tidyr
Suggests:	knitr, rmarkdown, webshot
Encoding:	UTF-8
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-02-12 13:52:09 UTC; jingm
Author:	Jingmeng Cui [aut, cre]
Maintainer:	Jingmeng Cui <jingmeng.cui@outlook.com>
Repository:	CRAN
Date/Publication:	2025-02-12 15:30:02 UTC

simlandr: Simulation-Based Landscape Construction for Dynamical Systems

Description

A toolbox for constructing potential landscapes for dynamical systems using Monte Carlo simulation. The method is based on the potential landscape definition by Wang et al. (2008) doi:10.1073/pnas.0800579105 (also see Zhou & Li, 2016 doi:10.1063/1.4943096 for further mathematical discussions) and can be used for a large variety of models.

Author(s)

Maintainer: Jingmeng Cui jingmeng.cui@outlook.com (ORCID)

See Also

Useful links:

• https://sciurus365.github.io/simlandr/

• https://github.com/Sciurus365/simlandr

• Report bugs at https://github.com/Sciurus365/simlandr/issues

Pipe operator

Description

See ⁠magrittr::[\%>\%][magrittr::pipe]⁠ for details.

Usage

lhs %>% rhs

Create and modify argument sets, then make an argument grid for batch simulation

Description

An argument set contains the descriptions of the relevant variables in a batch simulation. Use new_arg_set() to create an arg_set object, and use add_arg_ele() to add an element to the arg_set. After adding all elements in the argument set, use make_arg_grid() to make an argument grid that can be used directly for running batch simulation.

Usage

new_arg_set()

add_arg_ele(arg_set, arg_name, ele_name, start, end, by)

nele(arg_set)

narg(arg_set)

## S3 method for class 'arg_set'
print(x, detail = FALSE, ...)

make_arg_grid(arg_set)

## S3 method for class 'arg_grid'
print(x, detail = FALSE, ...)

Arguments

Value

new_arg_set() returns an arg_set object.

add_arg_ele() returns an arg_set object.

nele() returns an integer.

narg() returns an integer.

make_arg_gird() returns an arg_grid object.

Functions

• new_arg_set(): Create an arg_set.

• add_arg_ele(): Add an element to an arg_set.

• nele(): The number of elements in an arg_set.

• narg(): The number of arguments in an arg_set.

• print(arg_set): Print an arg_set object.

• make_arg_grid(): Make an argument grid from an argument set.

• print(arg_grid): Print an arg_grid object

See Also

batch_simulation() for running batch simulation and a concrete example.

as.mcmc.list generic function

Description

See coda::as.mcmc.list(), as.mcmc.list.list() for details.

Convert a list of simulation output to a mcmc.list object

Description

This function can be used to convert a list of simulation output to a mcmc.list object. This may be useful when the output of the simulation is a list of matrices, and you want to perform convergence checks using the functions in the coda package. See coda::mcmc.list() for more information, and also see the examples in the documentation of sim_SDE().

Usage

## S3 method for class 'list'
as.mcmc.list(x, ...)

Arguments

Value

A mcmc.list object

Attach all matrices in a batch simulation

Description

Attach all matrices in a batch simulation

Usage

attach_all_matrices(bs, backingpath = "bp")

Arguments

Value

A batch_simulation object with all hash_big_matrixes attached.

Autolayer generic function

Description

See ggplot2::autolayer(), autolayer.barrier() for details.

Get a ggplot2 layer from a barrier object

Description

This layer can show the saddle point (2d) and the minimal energy path (3d) on the landscape.

Usage

## S3 method for class 'barrier'
autolayer(object, path = TRUE, ...)

Arguments

Value

A ggplot2 layer that can be added to an existing landscape plot.

Perform a batch simulation.

Description

Perform a batch simulation.

Usage

batch_simulation(
  arg_grid,
  sim_fun,
  default_list = list(),
  bigmemory = TRUE,
  ...
)

## S3 method for class 'batch_simulation'
print(x, detail = FALSE, ...)

Arguments

Value

A batch_simulation object, also a data frame. The first column, var, is a list of ele_list that contains all the variables; the second to the second last columns are the values of the variables; the last column is the output of the simulation function.

Functions

• batch_simulation(): Perform a batch simulation.

Examples

batch_arg_set_grad <- new_arg_set()
batch_arg_set_grad <- batch_arg_set_grad %>%
  add_arg_ele(
    arg_name = "parameter", ele_name = "a",
    start = -6, end = -1, by = 1
  )
batch_grid_grad <- make_arg_grid(batch_arg_set_grad)
batch_output_grad <- batch_simulation(batch_grid_grad, sim_fun_grad,
  default_list = list(
    initial = list(x = 0, y = 0),
    parameter = list(a = -4, b = 0, c = 0, sigmasq = 1)
  ),
  length = 1e2,
  seed = 1614,
  bigmemory = FALSE
)
print(batch_output_grad)

Functions for calculating energy barrier from landscapes

Description

Functions for calculating energy barrier from landscapes

Usage

calculate_barrier(l, ...)

## S3 method for class ''2d_landscape''
calculate_barrier(
  l,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  base = exp(1),
  ...
)

## S3 method for class ''3d_landscape''
calculate_barrier(
  l,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  Umax,
  expand = TRUE,
  omit_unstable = FALSE,
  base = exp(1),
  ...
)

## S3 method for class ''2d_landscape_batch''
calculate_barrier(
  l,
  bg = NULL,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  base = exp(1),
  ...
)

## S3 method for class ''3d_landscape_batch''
calculate_barrier(
  l,
  bg = NULL,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  Umax,
  expand = TRUE,
  omit_unstable = FALSE,
  base = exp(1),
  ...
)

Arguments

Value

A barrier object that contains the (batch) barrier calculation result(s).

Graphical diagnoses to check if the simulation converges

Description

Compare the distribution of different stages of simulation (for plot_type == "bin" or plot_type = "density"), or show how the percentiles of the distribution evolve over time (for plot_type == cumuplot, see coda::cumuplot() for details). More convergence checking methods for MCMC data are available at the coda package. Be cautious: each convergence checking method has its shortcomings, so do not blindly use any results as the definitive conclusion that a simulation converges or not.

Usage

check_conv(output, vars, sample_perc = 0.2, plot_type = "bin")

## S3 method for class 'check_conv'
print(x, ask = TRUE, ...)

Arguments

Value

A check_conv object that contains the convergence checking result(for plot_type == "bin" or plot_type = "density"), or draw the cumuplot without a return value (for plot_type == cumuplot).

Methods (by generic)

• print(check_conv): Print a check_conv object.

Fill a vector of values into a structure list.

Description

Fill a vector of values into a structure list.

Usage

fill_in_struct(vec, struct)

Arguments

Value

A ele_list object.

See Also

modified_simulation()

Summarize the barrier height from a barrier object

Description

This function was deprecated. Use summary() instead. (See summary.barrier().)

Usage

get_barrier_height(object, ...)

Arguments

Value

A vector (for a single barrier calculation result) or a data.frame (for batch barrier calculation results) that contains the barrier heights on the landscape.

Get the probability distribution from a landscape object

Description

Get the probability distribution from a landscape object

Usage

get_dist(l, index = 1)

Arguments

Value

A data.frame that contains the distribution in the tidy format or the raw simulation result.

Get a ggplot2 layer from a barrier object

Description

This function was deprecated. Use autolayer() instead. (See autolayer.barrier().)

Usage

get_geom(object, ...)

Arguments

Value

A ggplot2 layer that can be added to an existing landscape plot.

Class "hash_big_matrix": big matrix with a md5 hash reference

Description

hash_big_matrix class is a modified class from bigmemory::big.matrix-class(). Its purpose is to help users operate big matrices within hard disk in a reusable way, so that the large matrices do not consume too much memory, and the matrices can be reused for the next time. Comparing with bigmemory::big.matrix-class(), the major enhancement of hash_big_matrix class is that the backing files are, by default, stored in a permanent place, with the md5 of the object as the file name. With this explicit name, hash_big_matrix objects can be easily reloaded into workspace every time.

Usage

as_hash_big_matrix(x, backingpath = "bp", silence = TRUE, ...)

attach_hash_big_matrix(x, backingpath = "bp")

Arguments

Functions

• as_hash_big_matrix(): Create a hash_big_matrix object from a matrix.

• attach_hash_big_matrix(): Attach a hash_big_matrix object from the backing file to the workspace.

Slots

md5

The md5 value of the matrix.

address

Inherited from big.matrix.

Make a matrix of 2D static landscape plots for one or two parameters

Description

Make a matrix of 2D static landscape plots for one or two parameters

Usage

make_2d_matrix(
  bs,
  x,
  rows = NULL,
  cols,
  lims,
  kde_fun = c("ks", "base"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  individual_landscape = TRUE
)

Arguments

Value

A ⁠2d_matrix_landscape⁠ object that describes the landscape of the system, including the smoothed distribution and the landscape plot.

Make 2D static landscape plot for a single simulation output

Description

Make 2D static landscape plot for a single simulation output

Usage

make_2d_static(
  output,
  x,
  lims,
  kde_fun = c("ks", "base"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

make_2d_single(
  output,
  x,
  lims,
  kde_fun = c("ks", "base"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

Arguments

Value

A ⁠2d_static_landscape⁠ object that describes the landscape of the system, including the smooth distribution and the landscape plot.

Make a tidy data.frame from smooth 2d distribution matrix

Description

Make a tidy data.frame from smooth 2d distribution matrix

Usage

make_2d_tidy_dist(dist_2d, value = NULL, var_name = NULL)

Arguments

Value

A tidy data.frame.

Make 3d animations from multiple simulations

Description

Make 3d animations from multiple simulations

Usage

make_3d_animation(
  bs,
  x,
  y,
  fr,
  lims,
  kde_fun = c("ks", "MASS"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  individual_landscape = TRUE,
  mat_3d = FALSE
)

Arguments

Value

A ⁠3d_animation_landscape⁠ object that describes the landscape of the system, including the smoothed distribution and the landscape plot.

Make a matrix of 3D static landscape plots for one or two parameters

Description

Currently only 3D (x, y, color) is supported. Matrices with 3D (x, y, z) plots are not supported.

Usage

make_3d_matrix(
  bs,
  x,
  y,
  rows = NULL,
  cols,
  lims,
  kde_fun = c("ks", "MASS"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  individual_landscape = TRUE
)

Arguments

Value

A ⁠3d_matrix_landscape⁠ object that describes the landscape of the system, including the smoothed distribution and the landscape plot.

Make 3D static landscape plots from simulation output

Description

Make 3D static landscape plots from simulation output

Usage

make_3d_static(
  output,
  x,
  y,
  lims,
  kde_fun = c("ks", "MASS"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

make_3d_single(
  output,
  x,
  y,
  lims,
  kde_fun = c("ks", "MASS"),
  n = 200,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

Arguments

Value

A ⁠3d_static_landscape⁠ object that describes the landscape of the system, including the smooth distribution and the landscape plot.

Make 4D static space-color plots from simulation output

Description

Make 4D static space-color plots from simulation output

Usage

make_4d_static(
  output,
  x,
  y,
  z,
  lims,
  kde_fun = "ks",
  n = 50,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

make_4d_single(
  output,
  x,
  y,
  z,
  lims,
  kde_fun = "ks",
  n = 50,
  h,
  adjust = 1,
  Umax = 5,
  weight_var = NULL
)

Arguments

Value

A ⁠4d_static_landscape⁠ object that describes the landscape of the system, including the smoothed distribution and the landscape plot.

Make a grid for calculating barriers for 2d landscapes

Description

Make a grid for calculating barriers for 2d landscapes

Usage

make_barrier_grid_2d(
  ag,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  df = NULL,
  print_template = FALSE
)

Arguments

Value

A barrier_grid_2d object that specifies the condition for each barrier calculation.

Make a grid for calculating barriers for 3d landscapes

Description

Make a grid for calculating barriers for 3d landscapes

Usage

make_barrier_grid_3d(
  ag,
  start_location_value,
  start_r,
  end_location_value,
  end_r,
  df = NULL,
  print_template = FALSE
)

Arguments

Value

A barrier_grid_3d object that specifies the condition for each barrier calculation.

Calculate 1D, 2D, or 3D kernel smooth distribution

Description

Calculate 1D, 2D, or 3D kernel smooth distribution

Usage

make_kernel_dist(
  output,
  var_names,
  lims,
  kde_fun,
  n,
  h,
  adjust,
  weight_var = NULL
)

Arguments

Value

A list of the smooth distribution.

Modify a single simulation

Description

Modify a single simulation

Usage

modified_simulation(sim_fun, ele_list, default_list, bigmemory = TRUE, ...)

Arguments

Simulate multiple 1-3D Markovian Stochastic Differential Equations

Description

Simulate multiple Monte Carlo simulations of 1-3D Markovian Stochastic Differential Equations from a grid or random sample of initial values. Parallel processing is supported. To register a parallel backend, use future::plan(). For example, future::plan(future::multisession). For more information, see future::plan(). Functions imported from other programming languages, such as C++ or Python functions, may not work in parallel processing. If you are uncertain whether there are unknown stable states of the system that are difficult to reach, it is recommended to start with running a large number (i.e., increasing R) of short simulations to see if the system reaches to the known stable states.

Usage

multi_init_simulation(
  sim_fun,
  R = 10,
  range_x0,
  sample_mode = c("grid", "random"),
  ...,
  .furrr_options = list(.options = furrr::furrr_options(seed = TRUE)),
  return_object = c("mcmc.list", "raw")
)

Arguments

Value

A list of mcmc objects or a tibble of initial values and raw simulation results, depending on the value of return_object.

Examples

# Adapted from the example in the Sim.DiffProc package

set.seed(1234, kind = "L'Ecuyer-CMRG")
mu <- 4
sigma <- 0.1
fx <- expression(y, (mu * (1 - x^2) * y - x))
gx <- expression(0, 2 * sigma)

multiple_mod2d <- multi_init_simulation(sim_SDE, range_x0 = c(-3, 3, -10, 10),
R = 3, sample_mode = "grid", drift = fx, diffusion = gx,
N = 1000, Dt = 0.01, type = "str", method = "rk1",
keep_full = FALSE, M = 2)

# The output is a mcmc.list object. You can use the functions
# in the coda package to modify it and perform convergence check,
# for example,

library(coda)
plot(multiple_mod2d)
window(multiple_mod2d, start = 500)
effectiveSize(multiple_mod2d)

Make plots from landscape objects

Description

Make plots from landscape objects

Usage

## S3 method for class 'landscape'
plot(x, index = 1, ...)

Arguments

Value

The plot.

Save landscape plots

Description

Save landscape plots

Usage

save_landscape(l, path = NULL, selfcontained = FALSE, ...)

Arguments

Value

The function saves the plot to a specific path. It does not have a return value.

Simulate 1-3D Markovian Stochastic Differential Equations

Description

A wrapper to the simulation utilities provided by the Sim.DiffProc package. You may skip this step and write your own simulation function for more customized simulation.

Usage

sim_SDE(
  N = 1000,
  M = 1,
  x0,
  t0 = 0,
  T = 1,
  Dt = rlang::missing_arg(),
  drift,
  diffusion,
  corr = NULL,
  alpha = 0.5,
  mu = 0.5,
  type = "ito",
  method = "euler",
  keep_full = TRUE
)

Arguments

Value

Depending on the value of keep_full, the output will be a list of snssde1d, snssde2d or snssde3d objects, or a matrix or a list of matrices of the simulated values.

Examples

# From the Sim.DiffProc package

set.seed(1234, kind = "L'Ecuyer-CMRG")
mu <- 4
sigma <- 0.1
fx <- expression(y, (mu * (1 - x^2) * y - x))
gx <- expression(0, 2 * sigma)
mod2d <- sim_SDE(drift = fx, diffusion = gx, N = 1000,
Dt = 0.01, x0 = c(0, 0), type = "str", method = "rk1",
M = 2, keep_full = FALSE)

print(as.mcmc.list(mod2d))

A simple gradient simulation function for testing

Description

This is a toy stochastic gradient system which can have bistability in some conditions. Model specification:

U = x^4 + y^4 + axy + bx + cy

dx/dt = - \partial U/ \partial x + \sigma dW/dt = - 4x^3 - ay - b + \sigma dW/dt

dy/dt = - \partial U/ \partial y + \sigma dW/dt = - 4y^3 - ax - c + \sigma dW/dt

Usage

sim_fun_grad(
  initial = list(x = 0, y = 0),
  parameter = list(a = -4, b = 0, c = 0, sigmasq = 1),
  length = 1e+05,
  stepsize = 0.01,
  seed = NULL
)

Arguments

Value

A matrix of simulation results.

See Also

sim_fun_nongrad() and batch_simulation().

A simple non-gradient simulation function for testing

Description

This is a toy stochastic non-gradient system which can have multistability in some conditions. Model specification:

Usage

sim_fun_nongrad(
  initial = list(x1 = 0, x2 = 0, a = 1),
  parameter = list(b = 1, k = 1, S = 0.5, n = 4, lambda = 0.01, sigmasq1 = 8, sigmasq2 =
    8, sigmasq3 = 2),
  constrain_a = TRUE,
  amin = -0.3,
  amax = 1.8,
  length = 1e+05,
  stepsize = 0.01,
  seed = NULL,
  progress = TRUE
)

Arguments

Details

\frac {dx_ {1}}{dt} = \frac {ax_ {1}^ {n}}{S^ {n}+x_ {1}^ {n}} + \frac {bS^ {n}}{S^ {n}+x_ {2}^ {n}} - kx_ {1}+ \sigma_1 dW_1/dt

\frac {dx_ {2}}{dt} = \frac {ax_ {2}^ {n}}{S^ {n}+x_ {2}^ {n}} + \frac {bS^ {n}}{S^ {n}+x_ {1}^ {n}} - kx_ {2}+ \sigma_2 dW_2/dt

\frac {da}{dt} = -\lambda a+ \sigma_3 dW_3/dt

Value

A matrix of simulation results.

References

Wang, J., Zhang, K., Xu, L., & Wang, E. (2011). Quantifying the Waddington landscape and biological paths for development and differentiation. Proceedings of the National Academy of Sciences, 108(20), 8257-8262. doi:10.1073/pnas.1017017108

See Also

sim_fun_grad() and batch_simulation().

A simple simulation function for testing

Description

A simple simulation function for testing

Usage

sim_fun_test(arg1, arg2, length = 1000)

Arguments

Value

A matrix of simulation results.

See Also

sim_fun_grad() and sim_fun_nongrad() for more realistic examples.

A simple yet meaningful simulation function for testing

Description

sim_fun_test2() was renamed to sim_fun_grad() to create a more consistent API.

Usage

sim_fun_test2(...)

Arguments

Summarize the barrier height from a barrier object

Description

Summarize the barrier height from a barrier object

Usage

## S3 method for class 'barrier'
summary(object, ...)

Arguments

Value

A vector (for a single barrier calculation result) or a data.frame (for batch barrier calculation results) that contains the barrier heights on the landscape.