FitControlsVinecop class
A class for controlling fits of vine copula models.
Base classes
- class FitControlsBicop
- A class for controlling fits of bivariate copula models.
Constructors, destructors, conversion operators
- FitControlsVinecop()
- Instantiates default controls for fitting vine copula models.
-
FitControlsVinecop(std::vector<BicopFamily> family_set,
std::string parametric_method = "mle",
std::string nonparametric_method = "constant",
double nonparametric_mult = 1.0,
size_
t nonparametric_grid_size = 30, size_ t trunc_lvl = std::numeric_limits<size_ t>::max(), std::string tree_criterion = "tau", double threshold = 0.0, std::string selection_criterion = "aic", const Eigen::VectorXd& weights = Eigen::VectorXd(), double psi0 = 0.9, bool preselect_families = true, bool select_trunc_lvl = false, bool select_threshold = false, bool select_families = true, bool show_trace = false, size_ t num_threads = 1, std::string tree_algorithm = "mst_prim", bool allow_rotations = true, std::vector<int> seeds = std::vector<int>()) explicit - Instantiates custom controls for fitting vine copula models.
-
FitControlsVinecop(const FitControlsBicop& controls,
size_
t trunc_lvl = std::numeric_limits<size_ t>::max(), std::string tree_criterion = "tau", double threshold = 0.0, bool select_trunc_lvl = false, bool select_threshold = false, bool select_families = true, bool show_trace = false, std::string tree_algorithm = "mst_prim", std::vector<int> seeds = std::vector<int>()) explicit - Instantiates custom controls for fitting vine copula models.
- FitControlsVinecop(const FitControlsConfig& config) explicit
- Instantiates the controls from a configuration object.
Public functions
- auto str() const -> std::string
- Summarizes the controls into a string (can be used for printing).
Getters and setters.
-
auto get_trunc_lvl() const -> size_
t - Gets the truncation level.
- auto get_tree_criterion() const -> std::string
- Gets the criterion for tree selection.
- auto get_tree_criterion_function() const -> TreeCriterionFunction
- Gets the custom criterion function for tree selection.
- auto get_threshold() const -> double
- Gets the threshold parameter.
- auto get_show_trace() const -> bool
- Gets whether a trace is shown during fitting.
- auto get_select_trunc_lvl() const -> bool
- Gets whether to select the truncation level automatically.
- auto get_select_threshold() const -> bool
- Gets whether to select the threshold automatically.
- auto get_select_families() const -> bool
- Gets whether to select the families automatically.
- auto needs_sparse_select() const -> bool
- auto get_fit_controls_bicop() const -> FitControlsBicop
- Gets the fit controls for bivariate fitting.
- auto get_tree_algorithm() const -> std::string
- Gets the maximum spanning tree algorithm.
- auto get_seeds() const -> std::vector<int>
- Gets the random seeds for the random number generator.
-
auto get_conditioning_set() const -> std::vector<size_
t> - Gets the conditioning set for conditioning-aware selection.
- auto get_rng() const -> boost::random::mt19937
- Gets the random number generator.
-
auto set_trunc_lvl(size_
t trunc_lvl) -> void - Sets the truncation level.
- auto set_tree_criterion(std::string tree_criterion) -> void
- Sets the criterion for tree selection.
- auto set_tree_criterion_function(TreeCriterionFunction tree_criterion_function) -> void
- Sets the custom criterion function for tree selection.
- auto set_threshold(double threshold) -> void
- Sets the threshold parameter.
- auto set_show_trace(bool show_trace) -> void
- Sets whether a trace is shown during fitting.
- auto set_select_trunc_lvl(bool select_trunc_lvl) -> void
- Sets whether to select the truncation level automatically.
- auto set_select_threshold(bool select_threshold) -> void
- Sets whether to select the threshold automatically.
- auto set_select_families(bool select_families) -> void
- Sets whether to select the families automatically.
- auto set_fit_controls_bicop(const FitControlsBicop& controls) -> void
- Sets the fit controls for bivariate fitting.
- auto set_tree_algorithm(std::string tree_algorithm) -> void
- Sets the maximum spanning tree algorithm.
- auto set_seeds(std::vector<int> seeds) -> void
- Sets the random seeds for the random number generator.
-
auto set_conditioning_set(std::vector<size_
t> conditioning_set) -> void - Sets the conditioning set for conditioning-aware selection.
Function documentation
vinecopulib::
Instantiates custom controls for fitting vine copula models.
| Parameters | |
|---|---|
| family_set | The set of copula families to consider (if empty, then all families are included). |
| parametric_method | The fit method for parametric families; possible choices: "mle", "itau". |
| nonparametric_method | The fit method for the local-likelihood nonparametric family (TLLs); possible choices: "constant", "linear", "quadratic". |
| nonparametric_mult | A factor with which the smoothing parameters are multiplied. |
| nonparametric_grid_size | The size of the interpolation grid backing the local-likelihood nonparametric family (TLLs). |
| trunc_lvl | Truncation level for truncated vines. |
| tree_criterion | The criterion for selecting the spanning tree ("tau", "rho", "hoeffd", "mcor", "cxi", "joe", or "custom") during the tree-wise structure selection. "custom" uses the callable set through set_. |
| threshold | For thresholded vines (0 = no threshold). |
| selection_criterion | The selection criterion ("loglik", "aic", "bic", "mbic", or "mbicv") for the pair copula families. |
| weights | A vector of weights for the observations. |
| psi0 | Only for selection_criterion = "mbic", prior probability of non-independence. |
| preselect_families | Whether to exclude families before fitting based on symmetry properties of the data. |
| select_trunc_lvl | Whether the truncation shall be selected automatically. |
| select_threshold | Whether the threshold parameter shall be selected automatically. |
| select_families | Whether the families shall be selected automatically, or should the method simply update the parameters for the pair copulas already present in the model. |
| show_trace | Whether to show a trace of the building progress. |
| num_threads | Number of concurrent threads to use while fitting pair copulas within a tree; never uses more than the number of concurrent threads supported by the implementation. A custom tree criterion is exempt and always runs on the calling thread. |
| tree_algorithm | The algorithm for building the spanning tree ("mst_prim", "mst_kruskal", "random_weighted", or "random_unweighted") during the tree-wise structure selection. "mst_prim" and "mst_kruskal" use Prim's and Kruskal's algorithms respectively to select the maximum spanning tree, maximizing the sum of the edge weights (i.e., tree_criterion). "random_weighted" and "random_unweighted" use Wilson's algorithm to generate a random spanning tree, either with probability proportional to the product of the edge weights (weighted) or uniformly (unweighted). |
| allow_rotations | Allow rotations for the families when doing model selection (default: true). |
| seeds | A vector of random seeds for the random number generator for parts of the algorithm that are randomized (e.g., random tree selection). |
vinecopulib::
Instantiates custom controls for fitting vine copula models.
| Parameters | |
|---|---|
| controls | See FitControlsBicop(). |
| trunc_lvl | Truncation level for truncated vines. |
| tree_criterion | The criterion for selecting the spanning tree ("tau", "rho", "hoeffd", "mcor", "cxi", "joe", or "custom") during the tree-wise structure selection. "custom" uses the callable set through set_. |
| threshold | For thresholded vines (0 = no threshold). |
| select_trunc_lvl | Whether the truncation shall be selected automatically. |
| select_threshold | Whether the threshold parameter shall be selected automatically. |
| select_families | Whether the families shall be selected automatically, or should the method simply update the parameters for the pair copulas already present in the model. |
| show_trace | Whether to show a trace of the building progress. |
| tree_algorithm | The algorithm for building the spanning tree ("mst_prim", "mst_kruskal", "random_weighted", or "random_unweighted") during the tree-wise structure selection. "mst_prim" and "mst_kruskal" use Prim's and Kruskal's algorithms respectively to select the maximum spanning tree, maximizing the sum of the edge weights (i.e., tree_criterion). "random_weighted" and "random_unweighted" use Wilson's algorithm to generate a random spanning tree, either with probability proportional to the product of the edge weights (weighted) or uniformly (unweighted). |
| seeds | A vector of random seeds for the random number generator for parts of the algorithm that are randomized (e.g., random tree selection). |
vinecopulib::
Instantiates the controls from a configuration object.
| Parameters | |
|---|---|
| config | The configuration object. |
size_
Gets the truncation level.
| Returns | the truncation level (the number of trees that will be fit; pair copulas above this level are forced to independence). |
|---|
std::string vinecopulib::
Gets the criterion for tree selection.
| Returns | the edge-weighting criterion used to grow the structure (one of "tau", "rho", "hoeffd", "mcor", "cxi", "joe", "custom"). |
|---|
TreeCriterionFunction vinecopulib::
Gets the custom criterion function for tree selection.
| Returns | the custom edge-weight function used when tree_criterion is "custom" (empty otherwise). It is always called on the thread that starts the fit, so it need not be thread safe. |
|---|
double vinecopulib::
Gets the threshold parameter.
| Returns | the absolute-dependence threshold below which pair copulas are set to independence during structure selection (0 disables). |
|---|
bool vinecopulib::
Gets whether a trace is shown during fitting.
| Returns | whether progress information is printed during fitting. |
|---|
bool vinecopulib::
Gets whether to select the truncation level automatically.
| Returns | whether the truncation level is selected automatically via the mBICv criterion during fitting. |
|---|
bool vinecopulib::
Gets whether to select the threshold automatically.
| Returns | whether the threshold is selected automatically during fitting. |
|---|
bool vinecopulib::
Gets whether to select the families automatically.
| Returns | whether pair-copula families are selected during fitting (when false, pre-specified families are used). |
|---|
bool vinecopulib::
| Returns | whether sparse selection (truncation or thresholding) is enabled in the current configuration. |
|---|
FitControlsBicop vinecopulib::
Gets the fit controls for bivariate fitting.
| Returns | the bicop fit controls used for each pair-copula fit. |
|---|
std::string vinecopulib::
Gets the maximum spanning tree algorithm.
| Returns | the structure-selection algorithm (one of "mst_prim" for Dissmann's greedy heuristic or "random_weighted" for Wilson-weighted random spanning trees). |
|---|
std::vector<size_
Gets the conditioning set for conditioning-aware selection.
| Returns | the conditioning set (1-based variable indices) placed at the tail of the vine order during structure selection; empty for unconditional selection. |
|---|
void vinecopulib::
Sets the custom criterion function for tree selection.
| Parameters | |
|---|---|
| tree_criterion_function | a callable mapping a two-column matrix of pair-copula data and a vector of weights to a scalar dependence value. |
Sets the custom edge-weight function used when tree_criterion is "custom". The two may be set in either order, but a fit is rejected unless both are set. The function is always called on the thread that starts the fit, so it need not be thread safe; the pair-copula fits still use num_threads threads.
void vinecopulib::
Sets the conditioning set for conditioning-aware selection.
| Parameters | |
|---|---|
| conditioning_set | 1-based variable indices to place at the tail of the vine order (so they can be conditioned on with Vinecop::); empty for unconditional selection. |
Sets the conditioning set for conditioning-aware structure selection.