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.
sobol_indices()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.
sobol_matrices()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.
Need a high-speed mirror for your open-source project?
Contact our mirror admin team at info@clientvps.com.
This archive is provided as a free public service to the community.
Proudly supported by infrastructure from VPSPulse , RxServers , BuyNumber , UnitVPS , OffshoreName and secure payment technology by ArionPay.