| Type: | Package |
| Title: | Visualising Output from Sequential Monte Carlo and Ensemble-Based Methods |
| Version: | 0.2.0 |
| Maintainer: | Richard G Everitt <richard.g.everitt@gmail.com> |
| Description: | Functions for plotting, and animating, the output of importance samplers, sequential Monte Carlo samplers (SMC) and ensemble-based methods. The package can be used to plot and animate histograms, densities, scatter plots and time series, and to plot the genealogy of an SMC or ensemble-based algorithm. These functions all rely on algorithm output to be supplied in tidy format. A function is provided to transform algorithm output from matrix format (one Monte Carlo point per row) to the tidy format required by the plotting and animating functions. |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.2 |
| URL: | https://github.com/richardgeveritt/ggsmc, https://richardgeveritt.github.io/ggsmc/ |
| BugReports: | https://github.com/richardgeveritt/ggsmc/issues |
| Imports: | poorman, ggplot2, gganimate |
| Suggests: | knitr, rmarkdown, testthat |
| VignetteBuilder: | knitr |
| Depends: | R (≥ 3.50) |
| License: | MIT + file LICENSE |
| NeedsCompilation: | no |
| Packaged: | 2025-11-11 12:42:56 UTC; richard |
| Author: | Richard G Everitt 
[aut, cre] |
| Repository: | CRAN |
| Date/Publication: | 2025-11-13 17:40:14 UTC |
An animated density of a single variable across targets.
Description
An animated density of a single variable across targets.
Usage
animate_density(
output,
parameter,
dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE,
duration = NULL,
animate_plot = TRUE,
save_filename = NULL,
save_path = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameter |
The parameter for which we wish to view the density. |
dimension |
(optional) The dimension of the parameter for which we wish to view the density. (default is 1) |
target |
(optiona) If specified, will fix to this target, and animate over ExternalTarget (if present in output). |
external_target |
(optional) If specified, will fix to this external_target, and animate over Target. |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the density. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
duration |
(optional) The duration of the animation. (defaults to producing an animation that uses 10 frames per second) |
animate_plot |
(optional) If TRUE, will return an animation. If FALSE, returns a gganim object that can be further modified before animating. (defaults to FALSE) |
save_filename |
(optional) If specified, the animation will be saved to a gif with this filename. (default is not to save) |
save_path |
(optional) If specified along with save_filename, will save the gif to save_path/save_filename. (defaults to working directory) |
Value
An animated density
An animated histogram of a single variable across targets.
Description
An animated histogram of a single variable across targets.
Usage
animate_histogram(
output,
parameter,
dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
bins = 30,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE,
duration = NULL,
animate_plot = TRUE,
save_filename = NULL,
save_path = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameter |
The parameter we wish to histogram. |
dimension |
(optional) The dimension of the parameter we wish to histogram. (default is 1) |
target |
(optionaL) If specified, will fix to this target, and animate over ExternalTarget (if present in output). |
external_target |
(optionaL) If specified, will fix to this external_target, and animate over Target. |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the histogram. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
bins |
(optional) Number of bins for the histogram. (default 30) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
duration |
(optional) The duration of the animation. (defaults to producing an animation that uses 10 frames per second) |
animate_plot |
(optiional) If TRUE, will return an animation. If FALSE, returns a gganim object that can be further modified before animating. (defaults to FALSE) |
save_filename |
(optional) If specified, the animation will be saved to a gif with this filename. (default is not to save) |
save_path |
(optional) If specified along with save_filename, will save the gif to save_path/save_filename. (defaults to working directory) |
Value
An animated histogram
Plot animated line graph showing parameter value vs dimension (revealed in the animation) from algorithm output.
Description
Plot animated line graph showing parameter value vs dimension (revealed in the animation) from algorithm output.
Usage
animate_reveal_time_series(
output,
parameters,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
max_line_width = 1,
alpha = 0.1,
xlimits = NULL,
ylimits = NULL,
duration = NULL,
animate_plot = TRUE,
save_filename = NULL,
save_path = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameters |
The parameters we wish to be on the y-axis of the line graph. |
target |
(optional) The target to plot. (default is to use all targets) |
external_target |
(optional) The external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the line graph. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
max_line_width |
(optional) The maximum size of the points in the plot. (default=1) |
alpha |
(optional) The transparency of the lines in the plot. (default=0.1) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
duration |
(optional) The duration of the animation. (defaults to producing an animation that uses 10 frames per second) |
animate_plot |
(optiional) If TRUE, will return an animation. If FALSE, returns a gganim object that can be further modified before animating. (defaults to FALSE) |
save_filename |
(optional) If specified, the animation will be saved to a gif with this filename. (default is not to save) |
save_path |
(optional) If specified along with save_filename, will save the gif to save_path/save_filename. (defaults to working directory) |
Value
An animated line graph, which successively adds points along the time axis.
A histogram of a single variable from a single target.
Description
A histogram of a single variable from a single target.
Usage
animate_scatter(
output,
x_parameter,
x_dimension,
y_parameter,
y_dimension,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
max_size = 1,
alpha = 0.1,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE,
view_follow = FALSE,
shadow_mark_proportion_of_max_size = NULL,
shadow_wake_length = NULL,
duration = NULL,
animate_plot = TRUE,
save_filename = NULL,
save_path = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
x_parameter |
The parameter indexed by the x-axis. |
x_dimension |
(optional) The dimension of the x-parameter we wish to histogram. (default is 1) |
y_parameter |
The parameter indexed by the y-axis. |
y_dimension |
(optional) The dimension of the y-parameter we wish to histogram. (default is 1) |
target |
(optionaL) If specified, will fix to this target, and animate over ExternalTarget (if present in output). |
external_target |
(optionaL) If specified, will fix to this external_target, and animate over Target. |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the scatter plot. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
max_size |
(optional) The maximum size of the points in the plot. (default=1) |
alpha |
(optional) The transparency of the points in the plot. (default=0.1) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
view_follow |
(optional) If TRUE, the view will follow the particles. (default FALSE) |
shadow_mark_proportion_of_max_size |
(optional) If set, the animation will leave behind shadow points, of a size (and transparency) specified by this proportion. (default to not set) |
shadow_wake_length |
(optional) If set, the animation will leave a shadow wake behind each point, of a duration given by this parameter (proportion of the entire animation length). (default to not set) |
duration |
(optional) The duration of the animation. (defaults to producing an animation that uses 10 frames per second) |
animate_plot |
(optiional) If TRUE, will return an animation. If FALSE, returns a gganim object that can be further modified before animating. (defaults to FALSE) |
save_filename |
(optional) If specified, the animation will be saved to a gif with this filename. (default is not to save) |
save_path |
(optional) If specified along with save_filename, will save the gif to save_path/save_filename. (defaults to working directory) |
Value
A scatter plot in a ggplot figure.
Plot animated line graph showing parameter value vs dimension across targets from algorithm output.
Description
Plot animated line graph showing parameter value vs dimension across targets from algorithm output.
Usage
animate_time_series(
output,
parameters,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
max_line_width = 1,
alpha = 0.1,
xlimits = NULL,
ylimits = NULL,
duration = NULL,
animate_plot = TRUE,
save_filename = NULL,
save_path = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameters |
The parameters we wish to be on the y-axis of the line graph. |
target |
(optional) The target to plot. (default is to use all targets) |
external_target |
(optional) The external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the line graph. If TRUE, will use the particle weights. (defaults to TRUE) |
max_line_width |
(optional) The maximum size of the points in the plot. (default=1) |
alpha |
(optional) The transparency of the lines in the plot. (default=0.1) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
duration |
(optional) The duration of the animation. (defaults to producing an animation that uses 10 frames per second) |
animate_plot |
(optiional) If TRUE, will return an animation. If FALSE, returns a gganim object that can be further modified before animating. (defaults to FALSE) |
save_filename |
(optional) If specified, the animation will be saved to a gif with this filename. (default is not to save) |
save_path |
(optional) If specified along with save_filename, will save the gif to save_path/save_filename. (defaults to working directory) |
Value
An animated line graph, showing how the lines evolve through the sequence of targets.
Data generated from a constant velocity (or continuous white noise acceleration, CWNA) model for 20 time steps.
Description
Data generated from a constant velocity (or continuous white noise acceleration, CWNA) model for 20 time steps.
Usage
cwna_data
Format
20 observations of 4 variables.
10000 simulations from a stochastic Lotka-Volterra model, assigned weights according to a Gaussian approximate Bayesian computation kernel with tolerance equal to 50.
Description
10000 simulations from a stochastic Lotka-Volterra model, assigned weights according to a Gaussian approximate Bayesian computation kernel with tolerance equal to 50.
Usage
lv_output
Format
320000 observations of 15 variables.
Convert IS, SMC or EnK output stored as a matrix to tidy format.
Description
Convert IS, SMC or EnK output stored as a matrix to tidy format.
Usage
matrix2tidy(output, parameter, target = 1, log_weights = NULL)
Arguments
output |
Matrix output (one point per row) from an IS algorithm, or one target from a SMC or EnK algorithm. |
parameter |
The name to assign the parameter in the tidy output. |
target |
(optional) The target index to use in the tidy output (default 1). |
log_weights |
(optional) The log_weights to use in the tidy output (default all equal). |
Value
The output in tidy format.
The output of an SMC sampler where the initial distribution is a Gaussian and the final target is a mixture of Gaussians. 25 particles were used, with an adaptive method to determine the sequence of targets, and a Metropolis-Hastings move to move the particles at each step.
Description
The output of an SMC sampler where the initial distribution is a Gaussian and the final target is a mixture of Gaussians. 25 particles were used, with an adaptive method to determine the sequence of targets, and a Metropolis-Hastings move to move the particles at each step.
Usage
mixture_25_particles
Format
175 observations of 13 variables.
A density of a single variable.
Description
A density of a single variable.
Usage
plot_density(
output,
parameter,
dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameter |
The parameter for which we wish to view the density. |
dimension |
(optional) The dimension of the parameter for which we wish to view the density. (default is 1) |
target |
(optional) The index of the target for which we wish to view the density. (default to all targets) |
external_target |
(optional) The index of the external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the density. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
Value
A density in a ggplot figure.
Plot an SMC or EnK genealogy from algorithm output.
Description
Plot an SMC or EnK genealogy from algorithm output.
Usage
plot_genealogy(
output,
parameter,
dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
alpha_points = 0.1,
alpha_lines = 0.1,
axis_limits = NULL,
vertical = TRUE,
arrows = TRUE,
default_title = FALSE
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameter |
The parameter we wish to see the evolution of. |
dimension |
(optional) The dimension of the parameter we wish to see the evolution of. (default is 1) |
target |
(optional) The target to plot. (default is to use all targets) |
external_target |
(optional) The external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the line graph. If TRUE, will use the particle weights. (defaults to TRUE) |
alpha_points |
(optional) The transparency of the points in the plot. (default=0.1) |
alpha_lines |
(optional) The transparency of the lines in the plot. (default=0.1) |
axis_limits |
(optional) Input of the form c(start,end), which specifies the ends of the parameter axis. |
vertical |
(optional) If TRUE (default), plots a genealogy vertically. If FALSE, plots horizontally. |
arrows |
(optional) If TRUE (default), includes arrowheads. If FALSE, arrowheads are omitted. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
Value
A particle genealogy in a ggplot figure.
A histogram of a single variable.
Description
A histogram of a single variable.
Usage
plot_histogram(
output,
parameter,
dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
bins = 30,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameter |
The parameter we wish to histogram. |
dimension |
(optional) The dimension of the parameter we wish to histogram. (default is 1) |
target |
(optional) The index of the target we wish to histogram. (default to all targets) |
external_target |
(optional) The index of the external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the histogram. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
bins |
(optional) Number of bins for the histogram. (default 30) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
Value
A histogram in a ggplot figure.
A histogram of a single variable from a single target
Description
A histogram of a single variable from a single target
Usage
plot_scatter(
output,
x_parameter,
x_dimension = 1,
y_parameter,
y_dimension = 1,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
max_size = 1,
alpha = 0.1,
xlimits = NULL,
ylimits = NULL,
default_title = FALSE
)
Arguments
output |
Output from the SMC or EnK algorithm. |
x_parameter |
The parameter indexed by the x-axis. |
x_dimension |
(optional) The dimension of the x-parameter we wish to histogram. (default is 1) |
y_parameter |
The parameter indexed by the y-axis. |
y_dimension |
(optional) The dimension of the y-parameter we wish to histogram. (default is 1) |
target |
(optional) The index of the target we wish to plot. (default is to use all targets) |
external_target |
(optional) The index of the external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the scatter plot. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
max_size |
(optional) The maximum size of the points in the plot. (default=1) |
alpha |
(optional) The transparency of the points in the plot. (default=0.1) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
default_title |
(optional) If TRUE, will provide a default title for the figure. If FALSE, no title is used. (defaults to FALSE) |
Value
A scatter plot in a ggplot figure.
Plot line graph showing parameter value vs dimension from algorithm output.
Description
Plot line graph showing parameter value vs dimension from algorithm output.
Usage
plot_time_series(
output,
parameters,
target = NULL,
external_target = NULL,
use_initial_points = TRUE,
use_weights = TRUE,
mcmc = FALSE,
max_line_width = 1,
alpha = 0.1,
xlimits = NULL,
ylimits = NULL
)
Arguments
output |
Output from the SMC or EnK algorithm. |
parameters |
The parameters we wish to be on the y-axis of the line graph. |
target |
(optional) The target to plot. (default is to use all targets) |
external_target |
(optional) The external target to plot. (default is to use all external targets, or to ignore if the column is not present) |
use_initial_points |
(optional) If target is not specified and this argument is TRUE, will add the initial unweighted proposed points to the output to be plotted. (default is TRUE) |
use_weights |
(optional) If FALSE, will ignore particle weights in the line graph. If TRUE, will use the particle weights. (defaults to TRUE) |
mcmc |
(optional) If TRUE, the user is indicating that the output is from an MCMC algorithm. This will set use_initial_points=FALSE and use_weights=FALSE no matter what the user sets these arguments to. (default is FALSE) |
max_line_width |
(optional) The maximum size of the points in the plot. (default=1) |
alpha |
(optional) The transparency of the lines in the plot. (default=0.1) |
xlimits |
(optional) Input of the form c(start,end), which specifies the ends of the x-axis. |
ylimits |
(optional) Input of the form c(start,end), which specifies the ends of the y-axis. |
Value
A line graph in a ggplot figure.
The output of a bootstrap particle filter on the cwna_data. The output consists of 100 particles over 20 time steps.
Description
The output of a bootstrap particle filter on the cwna_data. The output consists of 100 particles over 20 time steps.
Usage
sir_cwna_model
Format
4000 observations of 13 variables.