vinecopulib::tools_stats namespace

Utilities for statistical analysis.

Classes

class BoxCovering
Covers the unit hypercube with boxes and assigns each sample to a box.
struct SmoothingWorkspace

Functions

auto simulate_uniform(const size_t& n, const size_t& d, bool qrng, std::vector<int> seeds) -> Eigen::MatrixXd
Simulates from the multivariate uniform distribution.
auto simulate_normal(const size_t& n, const size_t& d, bool qrng, std::vector<int> seeds) -> Eigen::MatrixXd
Simulates from independendent normals.
auto pseudo_obs_1d_impl(std::vector<double>&& xvec, const std::string& ties_method, const std::vector<double>& weights, const std::vector<int>& seeds, double scale) -> Eigen::VectorXd
auto to_pseudo_obs(Eigen::MatrixXd x, const std::string& ties_method, const Eigen::VectorXd& weights, std::vector<int> seeds, double scale) -> Eigen::MatrixXd
Applies the empirical probability integral transform to a data matrix.
auto to_pseudo_obs_1d(Eigen::VectorXd x, const std::string& ties_method, const Eigen::VectorXd& weights, std::vector<int> seeds, double scale) -> Eigen::VectorXd
Applies the empirical probability integral transform to a data vector.
auto default_soft_scale() -> double
The scale of to_pseudo_obs() for copula data: the square root of the machine epsilon.
auto swaps_pair(const Eigen::MatrixXd& u) -> bool
Whether a pair is in the order of its own values.
auto pair_soft_pseudo_obs(const Eigen::MatrixXd& data, const Eigen::VectorXd& weights, double scale, const std::vector<int>& seeds) -> Eigen::MatrixXd
Pseudo-observations of a pair, as a kernel pair copula ranks it.
auto mix64(uint64_t z) -> uint64_t
auto find_latent_sample(const Eigen::MatrixXd& u, double b, size_t niter) -> Eigen::MatrixXd
Recovers a continuous latent sample from a sample of a discrete copula.
auto next_power_of_two(size_t n) -> size_t
auto win(const Eigen::VectorXd& x, size_t wl, SmoothingWorkspace& ws) -> Eigen::VectorXd
window smoother
auto cef(const Eigen::VectorXd& x, const Eigen::Matrix<size_t, Eigen::Dynamic, 1>& ind, const Eigen::Matrix<size_t, Eigen::Dynamic, 1>& ranks, size_t wl, SmoothingWorkspace& ws) -> Eigen::VectorXd
helper routine for ace (In R, this would be win(x[ind], wl)[ranks])
auto ace(const Eigen::MatrixXd& data, const Eigen::VectorXd& weights = Eigen::VectorXd(), size_t wl = 0, size_t outer_iter_max = 100, size_t inner_iter_max = 10, double outer_abs_tol = 2e-15, double inner_abs_tol = 1e-4) -> Eigen::MatrixXd
alternating conditional expectation algorithm
auto ghalton(const size_t& n, const size_t& d, const std::vector<int>& seeds) -> Eigen::MatrixXd
Simulates from the multivariate Generalized Halton Sequence.
auto sobol(const size_t& n, const size_t& d, const std::vector<int>& seeds) -> Eigen::MatrixXd
Simulates from the multivariate Sobol sequence.
auto pbvt(const Eigen::MatrixXd& z, int nu, double rho) -> Eigen::VectorXd
Computes bivariate t probabilities.
auto pbvnorm(const Eigen::MatrixXd& z, double rho) -> Eigen::VectorXd
Compute bivariate normal probabilities.
auto dnorm(const Eigen::MatrixXd& x) -> Eigen::MatrixXd
Density function of the Standard normal distribution.
auto pnorm(const Eigen::MatrixXd& x) -> Eigen::MatrixXd
Distribution function of the Standard normal distribution.
auto qnorm(const Eigen::MatrixXd& x) -> Eigen::MatrixXd
Quantile function of the Standard normal distribution.
auto dt(const Eigen::MatrixXd& x, double nu) -> Eigen::MatrixXd
Density function of the Student t distribution.
auto pt(const Eigen::MatrixXd& x, double nu) -> Eigen::MatrixXd
Distribution function of the Student t distribution.
auto qt(const Eigen::MatrixXd& x, double nu) -> Eigen::MatrixXd
Quantile function of the Student t distribution.

Dependence measures

auto pairwise_mcor(const Eigen::MatrixXd& x, const Eigen::VectorXd& weights) -> double
auto pairwise_cxi(const Eigen::MatrixXd& x, const Eigen::VectorXd& weights) -> double
calculates the pairwise symmetrized Chatterjee's xi.

Function documentation

Eigen::MatrixXd vinecopulib::tools_stats::simulate_uniform(const size_t& n, const size_t& d, bool qrng, std::vector<int> seeds)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Simulates from the multivariate uniform distribution.

Parameters
n Number of observations.
d Dimension.
qrng If true, quasi-numbers are generated.
seeds Seeds of the random number generator; if empty (default), the random number generator is seeded randomly. Given seeds draw the same numbers on every platform.
Returns An $ n \times d $ matrix of independent $ \mathrm{U}[0, 1] $ random variables, on a grid of $ 2^{-53} $ .

If qrng = TRUE, generalized Halton sequences (see ghalton()) are used for $ d \leq 300 $ and Sobol sequences otherwise (see sobol()).

Eigen::MatrixXd vinecopulib::tools_stats::simulate_normal(const size_t& n, const size_t& d, bool qrng, std::vector<int> seeds)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Simulates from independendent normals.

Parameters
n Number of observations.
d Dimension.
qrng If true, quasi-numbers are generated.
seeds Seeds of the random number generator; if empty (default), the random number generator is seeded randomly. //!
Returns An $ n \times d $ matrix of independent $ \mathrm{N}(0, 1) $ random variables.

Eigen::VectorXd vinecopulib::tools_stats::pseudo_obs_1d_impl(std::vector<double>&& xvec, const std::string& ties_method, const std::vector<double>& weights, const std::vector<int>& seeds, double scale)
#include <vinecopulib/include/vinecopulib/misc/implementation/tools_stats.ipp>

Eigen::MatrixXd vinecopulib::tools_stats::to_pseudo_obs(Eigen::MatrixXd x, const std::string& ties_method, const Eigen::VectorXd& weights, std::vector<int> seeds, double scale)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Applies the empirical probability integral transform to a data matrix.

Parameters
x A matrix of real numbers.
ties_method Indicates how to treat ties; same as in R, see https://stat.ethz.ch/R-manual/R-devel/library/base/html/rank.html.
weights Vector of weights for the observations.
seeds Seeds for the random number generator, used only when ties_method = "random"; each column appends its index to them.
scale Distance below which distinct values rank partly as tied, in the units of x; zero (default) ranks by value.
Returns Pseudo-observations of the copula, i.e. $ F_X(x) $ (column-wise).

Gives pseudo-observations from the copula by applying the empirical distribution function (scaled by $ n + 1 $ ) to each margin/column.

Eigen::VectorXd vinecopulib::tools_stats::to_pseudo_obs_1d(Eigen::VectorXd x, const std::string& ties_method, const Eigen::VectorXd& weights, std::vector<int> seeds, double scale)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Applies the empirical probability integral transform to a data vector.

Parameters
x A vector of real numbers.
ties_method Indicates how to treat ties; same as in R, see https://stat.ethz.ch/R-manual/R-devel/library/base/html/rank.html.
weights Vector of weights for the observations.
seeds Seeds for the random number generator, used only when ties_method = "random".
scale As for to_pseudo_obs().
Returns Pseudo-observations of the copula, i.e. $ F_X(x) $ .

Gives pseudo-observations from the copula by applying the empirical distribution function (scaled by $ n + 1 $ ) to each margin/column.

double vinecopulib::tools_stats::default_soft_scale()
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

The scale of to_pseudo_obs() for copula data: the square root of the machine epsilon.

bool vinecopulib::tools_stats::swaps_pair(const Eigen::MatrixXd& u)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Whether a pair is in the order of its own values.

Parameters
u A pair, [u1, u2] or [u1, u2, u1^-, u2^-].
Returns Whether the columns have to be swapped.

At the first row whose two values (or, with four columns, left limits) differ, the smaller comes first.

Eigen::MatrixXd vinecopulib::tools_stats::pair_soft_pseudo_obs(const Eigen::MatrixXd& data, const Eigen::VectorXd& weights, double scale, const std::vector<int>& seeds)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Pseudo-observations of a pair, as a kernel pair copula ranks it.

Parameters
data The pair, [u1, u2] or [u1, u2, u1^-, u2^-].
weights Optional weights, one per observation.
scale As for to_pseudo_obs().
seeds Seeds of the tie order.
Returns An $ n \times 2 $ matrix of pseudo-observations.

to_pseudo_obs(pair, "random", weights, seeds, scale) of the first two columns, ranked in the pair's own order (swaps_pair()).

Eigen::MatrixXd vinecopulib::tools_stats::find_latent_sample(const Eigen::MatrixXd& u, double b, size_t niter)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Recovers a continuous latent sample from a sample of a discrete copula.

Parameters
u An $ n \times 4 $ matrix $ (u_1, u_2, u_1^-, u_2^-) $ holding each observation's distribution function values and their left limits; any other number of columns throws.
b The bandwidth of the kernel density estimator.
niter The number of sweeps.
Returns An $ n \times 2 $ matrix of pseudo-observations of the latent sample, i.e. on the copula scale rather than the normal scale the sweeps run on.

Treats the discrete sample as an interval-censored density estimation problem: observation $ i $ is only known to lie in the rectangle $ (u_{i1}^-, u_{i1}] \times (u_{i2}^-, u_{i2}] $ . A latent point is initialized inside that rectangle and then refined by niter sweeps: for each observation, one of the observations whose current latent point falls in its own rectangle (widened by $ b $ on the normal scale) is picked uniformly at random, and the latent point is set to that neighbor's value plus Gaussian noise of scale $ b $ — a draw from a Gaussian kernel density estimate restricted to the compatible observations. The refined points are not confined to the original rectangles.

The draw is deterministic: every random component is drawn from a fixed-seed generator, so repeated calls on the same input agree bit for bit. It is also independent of argument order: recovering the latent sample of $ (u_1, u_2) $ and of $ (u_2, u_1) $ gives the same pair of columns, swapped.

Eigen::VectorXd vinecopulib::tools_stats::win(const Eigen::VectorXd& x, size_t wl, SmoothingWorkspace& ws)
#include <vinecopulib/include/vinecopulib/misc/implementation/tools_stats.ipp>

window smoother

Eigen::VectorXd vinecopulib::tools_stats::cef(const Eigen::VectorXd& x, const Eigen::Matrix<size_t, Eigen::Dynamic, 1>& ind, const Eigen::Matrix<size_t, Eigen::Dynamic, 1>& ranks, size_t wl, SmoothingWorkspace& ws)
#include <vinecopulib/include/vinecopulib/misc/implementation/tools_stats.ipp>

helper routine for ace (In R, this would be win(x[ind], wl)[ranks])

Eigen::MatrixXd vinecopulib::tools_stats::ace(const Eigen::MatrixXd& data, const Eigen::VectorXd& weights = Eigen::VectorXd(), size_t wl = 0, size_t outer_iter_max = 100, size_t inner_iter_max = 10, double outer_abs_tol = 2e-15, double inner_abs_tol = 1e-4)
#include <vinecopulib/include/vinecopulib/misc/implementation/tools_stats.ipp>

alternating conditional expectation algorithm

Eigen::MatrixXd vinecopulib::tools_stats::ghalton(const size_t& n, const size_t& d, const std::vector<int>& seeds)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Simulates from the multivariate Generalized Halton Sequence.

Parameters
n Number of observations.
d Dimension.
seeds Seeds to scramble the quasi-random numbers; if empty (default), the quasi-random number generator is seeded randomly.
Returns An $ n \times d $ matrix of quasi-random $ \mathrm{U}[0, 1] $ variables.

For more information on Generalized Halton Sequence, see Faure, H., Lemieux, C. (2009). Generalized Halton Sequences in 2008: A Comparative Study. ACM-TOMACS 19(4), Article 15.

Eigen::MatrixXd vinecopulib::tools_stats::sobol(const size_t& n, const size_t& d, const std::vector<int>& seeds)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Simulates from the multivariate Sobol sequence.

Parameters
n Number of observations.
d Dimension.
seeds Seeds to scramble the quasi-random numbers; if empty (default), the quasi-random number generator is seeded randomly.
Returns An $ n \times d $ matrix of quasi-random $ \mathrm{U}[0, 1] $ variables.

For more information on the Sobol sequence, see S. Joe and F. Y. Kuo (2008), constructing Sobol sequences with better two-dimensional projections, SIAM J. Sci. Comput. 30, 2635–2654.

Eigen::VectorXd vinecopulib::tools_stats::pbvt(const Eigen::MatrixXd& z, int nu, double rho)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Computes bivariate t probabilities.

Parameters
z An $ n \times 2 $ matrix of evaluation points.
nu Number of degrees of freedom.
rho Correlation.
Returns An $ n \times 1 $ vector of probabilities.

Based on the method described by Dunnett, C.W. and M. Sobel, (1954), A bivariate generalization of Student's t-distribution with tables for certain special cases, Biometrika 41, pp. 153-169. Translated from the Fortran routines of Alan Genz (www.math.wsu.edu/faculty/genz/software/fort77/mvtdstpack.f).

Eigen::VectorXd vinecopulib::tools_stats::pbvnorm(const Eigen::MatrixXd& z, double rho)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Compute bivariate normal probabilities.

Parameters
z An $ n \times 2 $ matrix of evaluation points.
rho Correlation.
Returns An $ n \times 1 $ vector of probabilities.

A function for computing bivariate normal probabilities; developed using Drezner, Z. and Wesolowsky, G. O. (1989), On the Computation of the Bivariate Normal Integral, J. Stat. Comput. Simul.. 35 pp. 101-107. with extensive modifications for double precisions by Alan Genz and Yihong Ge. Translated from the Fortran routines of Alan Genz (www.math.wsu.edu/faculty/genz/software/fort77/mvtdstpack.f).

Eigen::MatrixXd vinecopulib::tools_stats::dnorm(const Eigen::MatrixXd& x)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Density function of the Standard normal distribution.

Parameters
x Evaluation points.
Returns An $ n \times d $ matrix of evaluated densities.

Eigen::MatrixXd vinecopulib::tools_stats::pnorm(const Eigen::MatrixXd& x)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Distribution function of the Standard normal distribution.

Parameters
x Evaluation points.
Returns An $ n \times d $ matrix of evaluated probabilities.

Eigen::MatrixXd vinecopulib::tools_stats::qnorm(const Eigen::MatrixXd& x)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Quantile function of the Standard normal distribution.

Parameters
x Evaluation points.
Returns An $ n \times d $ matrix of evaluated quantiles.

Eigen::MatrixXd vinecopulib::tools_stats::dt(const Eigen::MatrixXd& x, double nu)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Density function of the Student t distribution.

Parameters
x Evaluation points.
nu Degrees of freedom parameter.
Returns An $ n \times d $ matrix of evaluated densities.

Eigen::MatrixXd vinecopulib::tools_stats::pt(const Eigen::MatrixXd& x, double nu)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Distribution function of the Student t distribution.

Parameters
x Evaluation points.
nu Degrees of freedom parameter.
Returns An $ n \times d $ matrix of evaluated probabilities.

Eigen::MatrixXd vinecopulib::tools_stats::qt(const Eigen::MatrixXd& x, double nu)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

Quantile function of the Student t distribution.

Parameters
x Evaluation points.
nu Degrees of freedom parameter.
Returns An $ n \times d $ matrix of evaluated quantiles.

double vinecopulib::tools_stats::pairwise_mcor(const Eigen::MatrixXd& x, const Eigen::VectorXd& weights)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

calculates the pairwise maximum correlation coefficient.

Symmetric in the two variables, as the measure is by definition.

double vinecopulib::tools_stats::pairwise_cxi(const Eigen::MatrixXd& x, const Eigen::VectorXd& weights)
#include <vinecopulib/include/vinecopulib/misc/tools_stats.hpp>

calculates the pairwise symmetrized Chatterjee's xi.

Chatterjee's xi measures how well one variable is a measurable function of the other and is therefore asymmetric. The symmetrized version is the larger of the two directions, so it detects a functional relationship whichever way it runs.