This release adds four new variance-based estimators and randomised
quasi-Monte Carlo (RQMC) support to sobol_matrices(). All additions are
backward compatible: existing code keeps its previous behaviour through the
default argument values.
Three new first-order estimators:
first = "owen" (Owen 2013): an antithetic-pair estimator,
V_i = (1/2N) * sum((Y_AB^(i) - Y_A) * (Y_B - Y_BA^(i))), in which both
factors are exactly zero when input X_i has no effect on the output. This
gives a zero-bias estimate at S_i = 0 and is useful for discriminating
"essentially zero" from "small but real" inputs. Requires the sampling
design c("A","B","AB","BA").first = "martinez" (Martinez 2011): the covariance form of the
Pearson-correlation estimator, i.e. the first-order counterpart of the
existing total = "glen" total-order estimator.first = "mauntz" (Mauntz-centered Saltelli; Saltelli et al. 2010): a
centered version of the Saltelli estimator that is asymptotically
equivalent to first = "saltelli" but more stable in finite samples
because the f_0^2 cross-term is cancelled exactly through centering.One new total-order estimator, total = "owen" (Owen 2013): a replicated
total-order estimator that averages the two equivalent Jansen estimates
obtained from the (A, A_B^(i)) and (B, B_A^(i)) pairs, halving the
variance of plain Jansen at the same total cost when both A_B and B_A
matrices are already available. Requires the sampling design
c("A","B","AB","BA").
The matrix/estimator concordance check in sobol_boot() now admits the new
estimators only on their valid sampling designs and errors informatively
otherwise. All four estimators integrate with the existing higher-order
(second, third, fourth), grouped and bootstrap workflows.
Two new arguments:
scrambling = c("none", "shift", "owen"). The default "none"
reproduces the deterministic Sobol' sequence from randtoolbox as in
earlier releases. "shift" applies a Cranley-Patterson digital shift
(Cranley & Patterson 1976) on top of the randtoolbox output -- no new
dependency. "owen" switches to an in-house Sobol' generator
(Joe-Kuo direction numbers, Joe & Kuo 2008) with hash-based Owen
scrambling (Owen 1995; Burley 2020). The Owen path is independent of
randtoolbox, so the package keeps working if the upstream sampler
changes its API (as happened when randtoolbox disabled its own
scrambling argument). Supports up to 250 dimensions.seed = NULL. When supplied, the scrambling is fully reproducible across
runs; the user's global RNG state is preserved (set and restored
internally). When NULL, a fresh random scrambling is drawn from R's RNG
on each call.Added src/sobol_owen.cpp and src/sobol_direction_numbers.h implementing
the in-house Sobol' generator (Antonov-Saleev recurrence on Joe-Kuo
direction numbers) and the Burley hash-based Owen scrambler (Laine-Karras
hash sandwiched between bit reversals). No new R dependencies introduced.
The Joe-Kuo direction-number table is public domain, sourced from
https://web.maths.unsw.edu.au/~fkuo/sobol/new-joe-kuo-6.21201 and subsetted
to the first 250 dimensions.
sobol_convergence() now correctly produces the third-order convergence
plot. The internal filter referred to the obsolete "Sijk" label instead
of "Sijl", so plot.order = "third" previously returned an empty plot.
sobol_indices() no longer errors for a single parameter
(params of length one) or for a groups specification that resolves to a
single group. The conditional output matrices were being dropped to vectors,
which broke the downstream Rfast column operations.
plot() of higher-order indices (second, third, fourth) now works when the
sensobol object was produced without bootstrapping. Previously the plot
filtered on a confidence-interval column that only exists when
boot = TRUE, silently yielding an empty plot; point estimates are now
shown, with error bars added only when confidence intervals are available.
discrepancy_ersatz() no longer silently drops a sample point whose first
coordinate is exactly 0 (e.g. under Owen scrambling or user-transformed
inputs). The x-index now receives the same zero-guard already applied to the
y-index.
Higher-order (sobol_indices()) interaction indices are now keyed with a
"_" separator (e.g. "1_12") instead of bare digit concatenation. The old
scheme could confuse, for example, the pairs (1, 12) and (11, 2) once the
number of inputs reached 112, silently mis-assigning second-, third- and
fourth-order indices. The math is unchanged for typical input counts.
vars_matrices() now drops the star-centre point from each cross section
with a tolerance test (spacing h/2) instead of exact floating-point
equality, making the STAR-VARS construction robust for arbitrary centre
coordinates (e.g. type = "R"). Output is byte-identical to previous
versions for the default quasi-random centres.
vars_to() rounds the derived number of cross-section points, guarding the
internal slicing against floating-point drift in 1/h.
Added test coverage for the four new estimators (expectation agreement with
established estimators, higher-order designs, grouped designs, bootstrap,
error paths) and for the new scrambling modes (regression for
scrambling = "none", reproducibility, range/mean/variance convergence,
QMC integration error smaller than plain MC, integration with groups and
higher-order designs, RNG-state preservation, validation/error paths).
Added regression tests for all four bug fixes above.
Added a new groups argument to sobol_matrices() and sobol_indices() that
allows the user to compute Sobol' first-, total- and higher-order indices for
groups of parameters rather than for individual parameters. This is the
standard device used in Sobol'-based sensitivity analysis to handle correlated
inputs by moving them together. groups accepts either a named list of
character vectors of parameter names (e.g.
groups = list(g1 = "X1", g2 = c("X2", "X3"))) or a character vector of
length length(params) aligned with params. The grouping must be a strict
partition of params (each parameter appears in exactly one group). When
groups = NULL (the default), behaviour is unchanged. The order argument is
reinterpreted as interactions between groups when groups is supplied.
Added test coverage for the new grouped design in both sobol_matrices() and
sobol_indices(), including row-count, column-swap, list/vector equivalence,
trivial-partition regression, and validation error paths.
Fixed repeated set.seed() calls in metafunction(): the seed is now set once
at the beginning of the function, allowing the RNG to advance naturally across
all subsequent sample() and rnorm() calls.
Added #' @keywords internal / #' @noRd roxygen2 blocks to all undocumented
internal helpers: sobol_dummy_boot(), sobol_boot(), bootstats(),
sobol_sample(), plot_sobol_convergence(), add_ribbon(), theme_AP(),
CutBySize(), s_ersatz(), and ishigami().
Updated the package-level documentation in sensobol-package.R to correctly
state support for up to fourth-order (not third-order) Sobol' indices.
Expanded the @return documentation of sobol_convergence() to enumerate all
list elements returned, including their types and column names.
Fixed multi-line string in stop() call in sobol_convergence() by replacing
the embedded newline with paste().
Extended test coverage to include: second and third-order indices, sobol_convergence()
workflow and error paths, vars_matrices() / vars_to(), discrepancy_ersatz(),
metafunction() reproducibility, and plot.sensobol().
Fixed boolean logic errors in sobol_boot(): replaced !x == "value" chains
with %in% to correctly validate estimator names for all matrix configurations.
Added early anyNA() guard in sobol_indices() and sobol_dummy() to stop
with an informative error when Y contains NA or NaN values.
Added input validation in sobol_matrices() (N must be a positive integer),
sobol_convergence() (sub.sample must be non-empty, positive, and sorted),
and vars_matrices() (star.centers must be a positive integer).
Replaced auto-installing behaviour in load_packages(): the function no longer
calls install.packages() silently; it now stops with an informative message
directing the user to install the missing package themselves.
Replaced deprecated expect_is() with expect_true(is.matrix()) in the test
suite.
Expanded test coverage to include the core sobol_indices() workflow,
bootstrap output, all new validation error paths, sobol_dummy(), and the
benchmark test functions ishigami_Fun() and sobol_Fun().
Fixed a bug on sobol_matrices that caused the function to fail when a single parameter was passed into the "params" argument.
Added a line in the help page of the sobol_indices and sobol_dummy functions informing that the Y argument does not accept NA or NaN values in the model output.
Arnald Puy, Samuele Lo Piano, Andrea Saltelli, and Simon A. Levin. sensobol: an R package to compute variance-based sensitivity indices. Journal of Statistical Software 102.5 (2022), pp. 1-37. doi: 10.18637/jss.v102.i05
Added a help page for the package.
Corrected a bug in sobol_ode.
The function plot_sensobolhas been eliminated. Now the Sobol' indices can be plot by a single call to plot.
Third-order indices are now referred to as Sijl rather than Sijk.
The function sobol_convergencehas been added to check the convergence of
Sobol' indices across sub-samples of the model output.
The output of sobol_indices is now an object of class sensobol. Besides including the indices, it also informs on the sum of first-order effects, the estimators used in the computation and the total number of model runs.
The output of vars_to is now an object of class vars. Besides including the indices, it also informs on the number of stars and the h value used.
The function plot_sobol is deprecated and will be removed from future versions. Now the output of sobol_indicescan be printed with a call to plot.
This is a major package upgrade.
The package now includes four first-order (Sobol', Salteli, Jansen and Azzini) and eight total-order (Jansen, Sobol', Homma, Saltelli, Janon, Glen, Azzini and VARS-TO) sensitivity estimators.
The sample matrix can be constructed either with Sobol' quasi-random numbers, a latin hypercube design or random numbers.
Several functions to plot the results of the uncertainty and sensitivity analysis have been incorporated: the function plot_scatter plots the model inputs against the output, whereas the function plot_multiscatter plots x_i against x_j and maps the resulting coordinate to its respective model output value.
The package can now be used in models with either a scalar or a multivariate output.
This release prepares the users for a major upcoming improvement of the package.
Added warnings to the function sobol_matrices. The arguments n and k will
be substituted by N and params in the next release of the package. The
arguments second and third will be substituted by the argument order in the next
release of the package.
Added warnings to the functions plot_uncertainty, plot_scatter, sobol_dummy and sobol_indices. The argument n will be substituted by N in the next release of the package.
The function sobol_ci is deprecated. The computation of confidence intervals
will be done directly by sobol_indices in the next version of the package.
The function sobol_ci_dummy is deprecated. The computation of confidence intervals
for dummy parameters will be done directly by sobol_dummy in the next version of the package.
The function sobol_replicas is deprecated and will be removed in the next version
of the package.
The test function ishigami_Mapply would be renamed as ishigami_Fun in the next
release of the package.
Corrected a bug in the plot_uncertainty function. Now the function
demands to add the initial sample size n to visualize the model output uncertainty.
Corrected some functions to adapt them to data.table 1.12.4.
Added a new function (sobol_replicas) to easily extract the bootstrapped Sobol' indices.
New option in the sobol_matrices function: the option cluster allows to create Sobol' matrices for clusters of parameters.
New test functions added:
Added references to all test functions.
The vignette rendered wrongly in the previous version; now the issue is corrected.
Corrected the following note, found in the CRAN check:
Some functions that were exported to the R package manual are now internal.