
# sensobol 1.2.0

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.

## New sensitivity estimators in `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' sequence scrambling in `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.

## Bug fixes

* `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.

## Robustness / hardening

* 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`.

## Tests

* 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.

# sensobol 1.1.9

* 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.

# sensobol 1.1.8

* 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()`.

# sensobol 1.1.7

* 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()`.

# sensobol 1.1.6

* Added missing package anchors.

# sensobol 1.1.5

* Added the journal citation for the "discrepancy_ersatz" function. It is published
in A. Puy, P. T. Roy and A. Saltelli. 2024. "Discrepancy measures for global sensitivity
analysis". Technometrics. DOI: 10.1080/00401706.2024.2304341.

# sensobol 1.1.4

* Added the function "discrepancy_ersatz" to use the S-ersatz discrepancy as a 
sensitivity measure. The S-ersatz is published in A. Puy, P. Roy and A. Saltelli. 2023.
Discrepancy measures for sensitivity analysis. arXiv: 2206.13470).

# sensobol 1.1.3

* Added the function "load_packages" to load (and install in case they are not already in the local R setup) all required libraries in just one call.

# sensobol 1.1.2

* 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.

# sensobol 1.1.1

* The CITATION file has changed. Citations to sensobol should now refer to the paper published in the Journal of Statistical Software: 

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

* The metafunction has been extended with a piecewise large, piecewise small and an oscillation function.

# sensobol 1.1.0

* The package now includes support to calculate and plot up to fourth-order effects.

# sensobol 1.0.4

* Fixed redundant links in the bibliography in .Rd files.

# sensobol 1.0.3

* Added a help page for the package.

* Corrected a bug in sobol_ode.

# sensobol 1.0.2

* The function `plot_sensobol`has 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_convergence`has been added to check the convergence of
Sobol' indices across sub-samples of the model output.

# sensobol 1.0.1

* 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_indices`can be printed with a call to `plot`.

# sensobol 1.0.0

* 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.

# sensobol 0.2.2

* 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.

# sensobol 0.2.1

* 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.

# sensobol 0.2.0

* New option in the `sobol_matrices` function: the option `cluster` allows to create Sobol' matrices for clusters of parameters.

* New test functions added: 
  - Bratley & Fox 1988.
  - Bratley et al. 1992
  - Oakley & O'Hagan 2004
  
* Added references to all test functions.

# sensobol 0.1.1

* The vignette rendered wrongly in the previous version;
now the issue is corrected.

* Corrected the following note, found in the CRAN check: 
  - Namespace in Imports field not imported from: ‘parallel’.
 
* Some functions that were exported to the R package manual 
are now internal.

# sensobol 0.1.0

* Added a NEWS.md file to track changes to the package.

