{"id":20669470,"url":"https://github.com/iitis/datagencopulabased.jl","last_synced_at":"2025-03-10T16:35:26.977Z","repository":{"id":44635870,"uuid":"104478558","full_name":"iitis/DatagenCopulaBased.jl","owner":"iitis","description":"Data generator based on copulas","archived":false,"fork":false,"pushed_at":"2023-05-17T08:30:00.000Z","size":667,"stargazers_count":23,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-17T13:32:20.504Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iitis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-22T13:37:47.000Z","updated_at":"2024-11-15T12:02:18.000Z","dependencies_parsed_at":"2025-01-17T13:30:17.220Z","dependency_job_id":"d9de36ac-cb39-4efc-8eac-a6a22405898f","html_url":"https://github.com/iitis/DatagenCopulaBased.jl","commit_stats":{"total_commits":458,"total_committers":5,"mean_commits":91.6,"dds":0.05458515283842791,"last_synced_commit":"7071dfab5d12d9cf01073399c05884d31e52bfcb"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FDatagenCopulaBased.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FDatagenCopulaBased.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FDatagenCopulaBased.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FDatagenCopulaBased.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iitis","download_url":"https://codeload.github.com/iitis/DatagenCopulaBased.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242884474,"owners_count":20201124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T20:14:28.945Z","updated_at":"2025-03-10T16:35:26.944Z","avatar_url":"https://github.com/iitis.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DatagenCopulaBased.jl\n\n[![Coverage Status](https://coveralls.io/repos/github/iitis/DatagenCopulaBased.jl/badge.svg?branch=master)](https://coveralls.io/github/iitis/DatagenCopulaBased.jl?branch=master)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7944064.svg)](https://doi.org/10.5281/zenodo.7944064)\n\nCopula based data generator. Returns data in the form of the `t x n` matrix `U` where`t` numerates the number of realizations, and `n` numerates the number of marginals. By the copula definition each marginal `uᵢ` is uniformly distributed on the segment `[0,1]`. Realizations of such marginal would be `U[:,i]`.\n\nInterdependence between marginals is modeled by the `n`-variate copula, see e.g.: R. B. Nelsen, 'An introduction to copulas', Springer Science \\\u0026 Business Media (2007). See also K. Domino: 'Selected Methods for non-Gaussian Data Analysis', Gliwice, IITiS PAN, 2019, [arXiv:1811.10486] (https://arxiv.org/abs/1811.10486).\n\nThis module support the following copula families:\n* Elliptical copulas (Gaussian, t-Student),\n* Frechet copulas (maximal, minimal, independent),\n* Marshall-Olkin copulas,\n* Archimedean copulas (Clayton, Frank, Gumbel, Ali-Mikhail-Haq),\n* Archimedean nested copulas.\n\n## Installation\n\nWithin Julia, run\n\n```julia\npkg\u003e add DatagenCopulaBased\n```\nTo install the files Julia 1.0 or higher is required.\n\n# Sampling data\n\nTo sample `t` realisations of data from `copula::TypeOfCopula` use\n```julia\njulia\u003e simulate_copula(t::Int, copula::TypeOfCopula; rng::AbstractRNG = Random.GLOBAL_RNG)\n```\nwhere `rng` is the random number genrator that can be selected.\n\n```julia\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(3, GaussianCopula([1. 0.5; 0.5 1.]))\n3×2 Array{Float64,2}:\n 0.589188  0.815308\n 0.708285  0.924962\n 0.747341  0.156994\n```\nFor `simulate_copula` all mentioned below copulas are supported.\n\nGiven `U` the preallocated matrix of `Float64` it can be filled by\n`size(U,1)` sample of the copula by running:\n\n```julia\njulia\u003e simulate_copula!(U::Matrix{Float64}, copula::TypeOfCopula; rng::AbstractRNG = Random.GLOBAL_RNG)\n```\nFor `simulate_copula!` all mentioned Archimedean copulas (including nested and the chain) as well as the Frechet and the Marshal-Olkin copulas are supported. Number of marginals `size(U,2)` in the preallocated matrix must equal to these in the copula model, else the `Assertionerror` will be raised.\n\n```julia\njulia\u003e u = zeros(6,3)\n6×3 Array{Float64,2}:\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n\njulia\u003e Random.seed!(43);\n\njulia\u003e c = ClaytonCopula(3, 3.)\nClaytonCopula{Float64}(3, 3.0)\n\njulia\u003e simulate_copula!(u, c)\n\njulia\u003e u\n6×3 Array{Float64,2}:\n 0.740919   0.936613   0.968594\n 0.369025   0.698884   0.586236\n 0.0701388  0.185901   0.0890538\n 0.535579   0.516761   0.538476\n 0.487668   0.549494   0.804122\n 0.653199   0.0923366  0.387304\n```\n\n## Elliptical copulas\n\nElliptical copula is derived form the multivariate elliptical distribution (such as the Gaussian or the t-Student). Suppose `F(x₁, ..., xₙ)` is the Cumulative Density Function (CDF)\nof such multivariate distribution, and `Fᵢ(xᵢ)` is the univariate CDF of its `i`th marginal (we assume it is continuous). Hence `uᵢ = Fᵢ(xᵢ)` is modeled by the uniform distribution on `[0,1]`. Given the elliptical multivariate distribution, the elliptical\ncopula is: `C(u₁, ..., uₙ) = F(F₁⁻¹(u₁), ..., Fₙ⁻¹(uₙ))`.\n\n### The Gaussian copula\n\n```julia\njulia\u003e GaussianCopula(Σ::Matrix{Float64})\n```\nThe Gaussian copula is parameterized by the correlation matrix `Σ` that needs to be symmetric, positively defined and with ones on the diagonal. The number of marginals is given by the size of `Σ`.\n\n```julia\njulia\u003e GaussianCopula([1. 0.5; 0.5 1.])\nGaussianCopula{Float64}([1.0 0.5; 0.5 1.0], 2)\n```\n\n### The t-Student copula\n\n```julia\njulia\u003e StudentCopula(Σ::Matrix{Float64}, ν::Int)\n```\n\nThe t-Student copula is parameterized by the `Σ` matrix a in the Gaussian copula case, and by the integer parameter `ν \u003e 0 ` interpreted as the number of degrees of freedom. The number of marginals is given by the size of `Σ`.\n\n```julia\njulia\u003e StudentCopula([1. 0.5; 0.5 1.], 1)\nStudentCopula{Float64}([1.0 0.5; 0.5 1.0], 1, 2)\n```\n\n## The Marshall-Olkin copula\n\nThe Marshall-Olkin copula is derived form the Marshall-Olkin exponential distribution with positively valued parameters. The Marshall-Olkin copula models the dependency between the random variables subjected to external shocks. The shock connected with the single variable is modeled there by `λₖ`, while the shock connected with two variables by `λₖₗ`, etc...\n\n```julia\njulia\u003e MarshallOlkinCopula(λ::Vector{Float64})\n```\n\nParameters are ordered as follow in the argument vector `λ = [λ₁, λ₂, ..., λₙ, λ₁₂, λ₁₃, ..., λ₁ₙ, λ₂₃, ..., λₙ₋₁ₙ, λ₁₂₃, ..., λ₁₂...ₙ]`, all must be non-negative. The number of marginals of such implemented Marshal-Olkin copula is `n = ceil(Int, log(2, length(λ)-1))`.\n\nTo generate data from the Marshall-Olkin copula we use algorithm presented in P. Embrechts, F. Lindskog, A McNeil 'modeling Dependence with Copulas and Applications to Risk Management', 2001.\n\n```julia\njulia\u003e c = MarshallOlkinCopula([1., 2., 3.])\nMarshallOlkinCopula{Float64}(2, [1.0, 2.0, 3.0])\n\njulia\u003e Random.seed!(43);\n\njulia\u003e 5×2 Matrix{Float64}:\n 0.854724   0.821831\n 0.885202   0.858624\n 0.471677   0.244436\n 0.834864   0.356275\n 0.0661758  0.033564\n```\n\n## The Frechet copula\n\nThe two parameters Frechet copula is `C(u₁, u₂) = α C_{max}(u₁, u₂) + β C_{min}(u₁, u₂) + (1- α - β) C_{⟂}(u₁, u₂)`. Here `C_{max}(u₁, u₂)` yields maximal `1` cross-correlation, while `C_{min}(u₁, u₂)` minimal `-1` cross correlation. The `C_{min}(u₁, u₂)` is the copula only in the bivariate case.\nObviously we require `0 ≤ α ≤ 1` , where `0 ≤ β ≤ 1` and `0 ≤ 1-α - β ≤ 1`.\n\n```julia\njulia\u003e FrechetCopula(n::Int, α::Float64, β::Float64)\n```\nis supported only for `n = 2`.\n\n```julia\njulia\u003e c = FrechetCopula(2, 0.4, 0.4)\nFrechetCopula{Float64}(2, 0.4, 0.4)\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(5, c)\n5×2 Matrix{Float64}:\n 0.180975   0.775377\n 0.924876   0.408278\n 0.599463   0.400537\n 0.661781   0.661781\n 0.0950087  0.0950087\n\n```\n\nThe one parameter Frechet copula `C(u₁, ..., uₙ) = α C_{max}(u₁, ..., uₙ) + (1-α) C_{⟂}(u₁, ..., uₙ)`, where `0 ≤ α ≤ 1` is supported for any `n ≥ 2`.\n\n```julia\njulia\u003e FrechetCopula(n::Int, α::Float64)\n```\n```julia\njulia\u003e c = FrechetCopula(3, 0.4)\nFrechetCopula{Float64}(3, 0.4, 0.0)\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(5, c)\n5×3 Matrix{Float64}:\n 0.180975    0.775377   0.888934\n 0.408278    0.912603   0.828727\n 0.661781    0.661781   0.661781\n 0.125437    0.0950087  0.130474\n 0.00463791  0.0288987  0.521601\n ```\n\n## The Archimedean copulas\n\nThe bivariate Archimedean copula `C(u₁,u₂) = φ⁻¹(φ(u₁)+φ(u₂))` is defined by the continuous strictly decreasing generator function `φ(t)` parameterized by `θ`. Such generator must fulfill `φ(t): [0,1] →[0, ∞)`.\nThe `n`-variate Archimedean copula can be defined analogically: `C(u₁,..., uₙ) = φ⁻¹(φ(u₁)+...+φ(uₙ))`. Here the constrains for the `θ` parameter are more strict, see: M. Hofert, 'Sampling Archimedean copulas', Computational Statistics \u0026 Data Analysis, 52 (2008), 5163-5174.\n\nFollowing Archimedean copulas are supported in the module:\n\n * Clayton copula - parameter domain: `θ ∈ (0, ∞)` for `n \u003e 2` and `θ ∈ [-1, 0) ∪ (0, ∞)` for `n = 2`,\n ```julia\n julia\u003e ClaytonCopula(n::Int, θ::Float64)\n ```\n * Frank copula - parameter domain: `θ ∈ (0, ∞)` for `n \u003e 2` and `θ ∈ (-∞, 0) ∪ (0, ∞)` for `n = 2`,\n ```julia\n julia\u003e FrankCopula(n::Int, θ::Float64)\n ```\n * Gumbel copula - parameter domain: `θ ∈ [1, ∞)`,\n ```julia\n julia\u003e GumbelCopula(n::Int, θ::Float64)\n ```\n * Ali-Mikhail-Haq copula - parameter domain: `θ ∈ (0, 1)` for `n \u003e 2` and  `θ ∈ [-1, 1]` for `n = 2`\n ```julia\n julia\u003e AmhCopula(n::Int, θ::Float64)\n ```\n\nFor implemented sampling algorithms see as well P. Kumar, 'Probability Distributions and Estimation\nof Ali-Mikhail-Haq Copula', Applied Mathematical Sciences, Vol. 4, 2010, no. 14, 657 - 666; and R. B. Nelsen, 'An introduction to copulas', Springer Science \\\u0026 Business Media (2007).\n\n\n```julia\njulia\u003e c = ClaytonCopula(3, 3.)\nClaytonCopula{Float64}(3, 3.0)\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(5, c)\n5×3 Array{Float64,2}:\n 0.740919   0.936613  0.968594\n 0.369025   0.698884  0.586236\n 0.0701388  0.185901  0.0890538\n 0.535579   0.516761  0.538476\n 0.487668   0.549494  0.804122  \n```\n\nThe optional third empty type `\u003c: CorrelationType` parameter is used to compute `θ` from the expected Kendall - `KendallCorrelation` or Speraman\n`SpearmanCorrelation` cross-correlation.\nHere only positive correlations are supported, and there are some limitations are for the Ali-Mikhail-Haq copula due to limitations on `θ` there.\n\n\n```julia\njulia\u003e c = ClaytonCopula(3, 0.5, KendallCorrelation)\nClaytonCopula{Float64}(3, 2.0)\n\njulia\u003e x = simulate_copula(500_000, c);\n\njulia\u003e corkendall(x)\n3×3 Array{Float64,2}:\n 1.0       0.500576  0.499986\n 0.500576  1.0       0.501574\n 0.499986  0.501574  1.0      \n```\n\n```julia\njulia\u003e c = ClaytonCopula(3, 0.5, SpearmanCorrelation)\nClaytonCopula{Float64}(3, 1.0760904048732394)\n\njulia\u003e x = simulate_copula(500_000, c);\n\njulia\u003e corspearman(x)\n3×3 Array{Float64,2}:\n 1.0       0.499662  0.499637\n 0.499662  1.0       0.500228\n 0.499637  0.500228  1.0   \n```\nThe reversed Gumbel, Clayton and Ali-Mikhail-Haq copulas are supported as well:\n\n```julia\njulia\u003e GumbelCopulaRev(n::Int, θ::Float64)\n```\n```julia\njulia\u003e ClaytonCopulaRev(n::Int, θ::Float64)\n```\n```julia\njulia\u003e AmhCopulaRev(n::Int, θ::Float64)\n```\n\nThe reversed copula is introduced by the following transformation  `∀ᵢ uᵢ → 1-uᵢ`. For modeling justification see: K. Domino, T. Błachowicz, M. Ciupak, 'The use of copula functions for predictive analysis of correlations between extreme storm tides',\nPhysica A: Statistical Mechanics and its Applications 413, 489-497, (2014); and K. Domino, T. Błachowicz, 'The use of copula functions for modeling the risk of\ninvestment in shares traded on the Warsaw Stock Exchange', Physica A: Statistical Mechanics and its Applications 413, 77-85, (2014).\n\n```julia\njulia\u003e c = ClaytonCopulaRev(2, 5.)\nClaytonCopulaRev{Float64}(2, 5.0)\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(10, c)\n10×2 Array{Float64,2}:\n 0.246822   0.0735546\n 0.0214448  0.154414\n 0.453721   0.598829\n 0.87328    0.91861  \n 0.896485   0.899053\n 0.966261   0.981044\n 0.0372783  0.0100412\n 0.899013   0.758491\n 0.473352   0.334147\n 0.0438898  0.256301\n```\n\n### The nested Archimedean copulas\n\nThe Nested Archimedean copula is\n`C_θ(C_ϕ₁(u₁₁, ..., u₁,ₙ₁), ..., C_ϕₖ(uₖ₁, ..., uₖ,ₙₖ), u₁ , ... uₘ)`.\nHere `θ` is the parameter of the parent copula while `ϕᵢ` is the parameter of the child copula. If `m \u003e 0`, some random variables will be modeled by the parent copula only. The example is:\n\n```julia\njulia\u003e NestedClaytonCopula(childred::Vector{ClaytonCopula}, m::Int, θ::Float64)\n```\n\n```julia\njulia\u003e a = ClaytonCopula(2, 3.)\nClaytonCopula{Float64}(2, 3.0)\n\njulia\u003e b = ClaytonCopula(2, 4.)\nClaytonCopula{Float64}(2, 4.0)\n\njulia\u003e NestedClaytonCopula([a,b], 0, 1.)\nNestedClaytonCopula{Float64}(ClaytonCopula{Float64}[ClaytonCopula{Float64}(2, 3.0), ClaytonCopula{Float64}(2, 4.0)], 0, 1.0, 4)\n```\nOnly the nesting within the same family is supported. The sufficient nesting condition requires parameters of the children copulas to be larger than the parameter of the parent copula. For sampling one uses the algorithm form  McNeil, A.J., 'Sampling nested Archimedean copulas', Journal of Statistical Computation and Simulation 78, 567–581 (2008).\n\n```julia\njulia\u003e a = ClaytonCopula(2, 0.9, KendallCorrelation)\nClaytonCopula{Float64}(2, 18.000000000000004)\n\njulia\u003e b = NestedClaytonCopula([a], 1, .2, KendallCorrelation)\nNestedClaytonCopula{Float64}(ClaytonCopula{Float64}[ClaytonCopula{Float64}(2, 18.000000000000004)], 1, 0.5, 3)\n\njulia\u003e x = simulate_copula(500000, b);\n\njulia\u003e corkendall(x)\n3×3 Array{Float64,2}:\n 1.0       0.899927  0.201108\n 0.899927  1.0       0.201252\n 0.201108  0.201252  1.0    \n\n```\n\nFor the Gumbel copula the double nesting is supported. Double Nested copula is: `C_θ(C_ϕ₁(C_Ψ₁₁(u,...), ..., C_C_Ψ₁,ₗ₁(u...)), ..., C_ϕₖ(C_Ψₖ₁(u,...), ..., C_Ψₖ,ₗₖ(u,...)))`. These are in the following form.\n\n```julia\njulia\u003e DoubleNestedGumbelCopula(children::Vector{NestedGumbelCopula}, θ)\n```\n\n```julia\njulia\u003e a = GumbelCopula(2, 2.)\nGumbelCopula{Float64}(2, 2.0)\n\njulia\u003e b = GumbelCopula(2, 3.)\nGumbelCopula{Float64}(2, 3.0)\n\njulia\u003e c = GumbelCopula(2, 4.)\nGumbelCopula{Float64}(2, 4.0)\n\njulia\u003e p = NestedGumbelCopula([a,b], 0, 1.75)\nNestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 2.0), GumbelCopula{Float64}(2, 3.0)], 0, 1.75, 4)\n\njulia\u003e p1 = NestedGumbelCopula([c], 1, 1.5)\nNestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 4.0)], 1, 1.5, 3)\n\njulia\u003e gp = DoubleNestedGumbelCopula([p, p1], 1.2)\nDoubleNestedGumbelCopula{Float64}(NestedGumbelCopula{Float64}[NestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 2.0), GumbelCopula{Float64}(2, 3.0)], 0, 1.75, 4), NestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 4.0)], 1, 1.5, 3)], 1.2, 7)\n\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(2, gp)\n2×7 Array{Float64,2}:\n 0.103462  0.358534  0.068492  0.0914353  0.90365   0.861869  0.0716466\n 0.755824  0.946489  0.745881  0.916382   0.448706  0.354352  0.676657\n```\n\nAnother example\n\n```julia\njulia\u003e a = GumbelCopula(2, .9, KendallCorrelation)\nGumbelCopula{Float64}(2, 10.000000000000002)\n\njulia\u003e b = GumbelCopula(2, 0.8, KendallCorrelation)\nGumbelCopula{Float64}(2, 5.000000000000001)\n\njulia\u003e p = NestedGumbelCopula([a], 1, 0.6, KendallCorrelation)\nNestedGumbelCopula(GumbelCopula[GumbelCopula(2, 10.000000000000002)], 1, 2.5)\n\njulia\u003e p1 = NestedGumbelCopula([b], 1, 0.5, KendallCorrelation)\nNestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 10.000000000000002)], 1, 2.5, 3)\n\njulia\u003e pp = DoubleNestedGumbelCopula([p,p1], 0.1, KendallCorrelation)\nDoubleNestedGumbelCopula{Float64}(NestedGumbelCopula{Float64}[NestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 10.000000000000002)], 1, 2.5, 3), NestedGumbelCopula{Float64}(GumbelCopula{Float64}[GumbelCopula{Float64}(2, 4.0)], 1, 1.5, 3)], 1.1111111111111112, 6)\n\n\njulia\u003e x = simulate_copula(750_000, pp);\n\njulia\u003e corkendall(x)\n6×6 Array{Float64,2}:\n 1.0        0.90994    0.599545   0.0981701  0.0982193  0.099066\n 0.90994    1.0        0.599713   0.0981766  0.0982359  0.0990366\n 0.599545   0.599713   1.0        0.099002   0.0989463  0.0991464\n 0.0981701  0.0981766  0.099002   1.0        0.819611   0.499707\n 0.0982193  0.0982359  0.0989463  0.819611   1.0        0.499743\n 0.099066   0.0990366  0.0991464  0.499707   0.499743   1.0    \n```\n\nHierarchical nested Gumbel copula is supported as well `C_θₙ₋₁(C_θₙ₋₂( ... C_θ₂(C_θ₁(u₁, u₂), u₃) ,..., uₙ₋₁)uₙ)`. Here bivariate Gumbel copulas are nested one in the another. The most inner is the ground ... ground child one and the most outer is the ground ... ground parent one. Numbel of marginals is `n = length(θ)+1`.\n\n```julia\njulia\u003e HierarchicalGumbelCopula(θ::Vector{Float64})\n```\nHere `θ` is the parameter vector, starting form the ground ... ground child one and ending on the ground ... ground parent one. Hence elements of `θ`\nmust be sorted in the descending order.\n\n```julia\njulia\u003e c = HierarchicalGumbelCopula([5., 4., 3.])\nHierarchicalGumbelCopula{Float64}(4, [5.0, 4.0, 3.0])\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(3, c)\n3×4 Array{Float64,2}:\n 0.100353  0.207903  0.0988337  0.0431565\n 0.347417  0.217052  0.223734   0.042903\n 0.73617   0.347349  0.168348   0.410963\n```\n\n```julia\njulia\u003e c = HierarchicalGumbelCopula([.9, 0.7, 0.5, 0.1], KendallCorrelation)\nHierarchicalGumbelCopula{Float64}(5, [10.000000000000002, 3.333333333333333, 2.0, 1.1111111111111112])\n\njulia\u003e x = simulate_copula(750_000, c);\n\njulia\u003e corkendall(x)\n5×5 Array{Float64,2}:\n 1.0       0.900078  0.700316   0.499483   0.100431\n 0.900078  1.0       0.700184   0.499376   0.100567\n 0.700316  0.700184  1.0        0.499635   0.0999502\n 0.499483  0.499376  0.499635   1.0        0.0999432\n 0.100431  0.100567  0.0999502  0.0999432  1.0  \n```\n\n## The chain of bivariate copulas\n\nThe chain of the bivariate copulas is determined by the sequence of bivariate copulas `C₁, C₂, ..., Cₙ₋₁` where each model the subsequent pair of marginals `Cₖ(uₖ, uₖ₊₁)`.  Hence the cross-correlation is introduced locally and decreases as the distance between marginals grows.\n\n### The chain of bivariate Archimedean copulas\n\nIn this case, each element of the copula chain is the Archimedean copula (Clayton, Frank and Ali-Mikhail-Haq families are supported). Hence the chain is parameterized by the parameters vector `θ` (with parameters domains as in the case of bivariate copulas) and the vector of string determining the copula family. Following families are supported: Clayton - key: \"clayton\", Frank - key: \"frank\" and Ali-Mikhail-Haq - key: \"amh\".\nThe `i`th element of the vector `θ` (and the `i`th element of the string with copulas names) determine the cross-correlation between the `i`th and the `i+1`th marginal. Number of marginals is `n = length(θ)+1`\n\n```julia\njulia\u003e ChainArchimedeanCopulas(θ::Vector{Float64}, copulas::Vector{String})\n```\n\nif one want to use one copula type, use\n\n```julia\njulia\u003e ChainArchimedeanCopulas(θ::Vector{Float64}, copulas::String)\n```\n\n```julia\njulia\u003e ChainArchimedeanCopulas([2., 3.], [\"clayton\", \"frank\"])\nChainArchimedeanCopulas(3, [2.0, 3.0], [\"clayton\", \"frank\"])\n```\n\n```julia\njulia\u003e ChainArchimedeanCopulas([2., 3.], \"frank\")\nChainArchimedeanCopulas(3, [2.0, 3.0], [\"frank\", \"frank\"])\n\n```\n\n```julia\njulia\u003e c = ChainArchimedeanCopulas([0.7, 0.5, 0.7], \"clayton\", KendallCorrelation)\nChainArchimedeanCopulas{Float64}(4, [4.666666666666666, 2.0, 4.666666666666666], [\"clayton\", \"clayton\", \"clayton\"])\n\njulia\u003e x = simulate_copula(750_000, c);\n\njulia\u003e corkendall(x)\n4×4 Array{Float64,2}:\n 1.0       0.699611  0.443936  0.399355\n 0.699611  1.0       0.499728  0.443053\n 0.443936  0.499728  1.0       0.699855\n 0.399355  0.443053  0.699855  1.0       \n```\n\nNegative correlations are supported here as well:\n\n```julia\njulia\u003e c = ChainArchimedeanCopulas([0.7, 0.5, -0.7], \"clayton\", KendallCorrelation)\nChainArchimedeanCopulas{Float64}(4, [4.666666666666666, 2.0, -0.8235294117647058], [\"clayton\", \"clayton\", \"clayton\"])\n\njulia\u003e x = simulate_copula(750_000, c);\n\njulia\u003e corkendall(x)\n4×4 Array{Float64,2}:\n  1.0        0.69992    0.445151  -0.372628\n  0.69992    1.0        0.500511  -0.413707\n  0.445151   0.500511   1.0       -0.699821\n -0.372628  -0.413707  -0.699821   1.0    \n```\n\n### The chain of bivariate Frechet copulas\n\n\nHere, each bivariate copula is the two parameters Frechet one `Cₖ = C_{αₖ,βₖ}(uₖ, uₖ₊₁)`, where `αₖ` and `βₖ` are elements of parameter vectors `α` and `β` that must be of the equal size. Number of marginals in `n = length(α) = length(β)`.\n\n```julia\njulia\u003e c = ChainFrechetCopulas(α, β)\n```\n\n```julia\njulia\u003e c = ChainFrechetCopulas([0.2, 0.3], [0.5, 0.1])\nChainFrechetCopulas{Float64}(3, [0.2, 0.3], [0.5, 0.1])\n\njulia\u003e Random.seed!(43);\n\njulia\u003e simulate_copula(3, c)\n3×3 Array{Float64,2}:\n 0.828727  0.171273  0.180975\n 0.400537  0.408278  0.775377\n 0.429437  0.912603  0.888934\n```\n\n\n## Correlation matrix generation\n\nWe supply a few methods to generate a `n x n` correlation matrix `Σ`.\n\n### Fully random cases\n\nto generate randomly a correlation matrix run\n\n```julia\njulia\u003e cormatgen(n::Int)\n```\n\nor\n\n```julia\njulia\u003e cormatgen_rand(n::Int)\n```\n\nFor different methods we have different outputs\n\n```julia\njulia\u003e Random.seed!(43);\n\njulia\u003e cormatgen(4)\n4×4 Array{Float64,2}:\n 1.0       0.396865  0.339354  0.193335\n 0.396865  1.0       0.887028  0.51934\n 0.339354  0.887028  1.0       0.551519\n 0.193335  0.51934   0.551519  1.0     \n\njulia\u003e cormatgen_rand(4)\n4×4 Array{Float64,2}:\n 1.0       0.659183  0.916879  0.486979\n 0.659183  1.0       0.676167  0.808264\n 0.916879  0.676167  1.0       0.731206\n 0.486979  0.808264  0.731206  1.0  \n```\n\nIn general the second case gives higher values of correlations.\n\n### Deterministic cases\n\nTo generate a correlation matrix with constant elements run\n\n```julia\njulia\u003e cormatgen_constant(n::Int, α::Float64)\n```\n\nparameter `α` should satisfy `0 \u003c= α \u003c= 1`\n\n```julia\njulia\u003e cormatgen_constant(4, 0.4)\n4×4 Array{Float64,2}:\n 1.0  0.4  0.4  0.4\n 0.4  1.0  0.4  0.4\n 0.4  0.4  1.0  0.4\n 0.4  0.4  0.4  1.0\n```\nthe generalisation is with two parameters `0 \u003c= α \u003c= 1` and `α \u003e β`\n\n```julia\njulia\u003e cormatgen_two_constant(n::Int, α::Float64, β::Float64)\n```\n\n```julia\njulia\u003e cormatgen_two_constant(4, 0.5, 0.2)\n4×4 Array{Float64,2}:\n 1.0  0.5  0.2  0.2\n 0.5  1.0  0.2  0.2\n 0.2  0.2  1.0  0.2\n 0.2  0.2  0.2  1.0\n```\nHere the first constant refer to the \"nesting\" of the higher\ncorrelation for the first half of marginals.\nTo generate the Toeplitz matrix with parameter `0 \u003c= ρ \u003c= 1` run:\n\n```julia\njulia\u003e cormatgen_toeplitz(n::Int, ρ::Float64)\n\njulia\u003e cormatgen_toeplitz(4, 0.5)\n4×4 Array{Float64,2}:\n 1.0    0.5   0.25  0.125\n 0.5    1.0   0.5   0.25\n 0.25   0.5   1.0   0.5  \n 0.125  0.25  0.5   1.0  \n```\n\n### Partially random and partially deterministic cases\n\nTo generate constant matrix with the noise run\n\n```julia\njulia\u003e cormatgen_constant_noised(n::Int, α::Float64; ϵ::Float64 = (1.-α)/2.)\n```\nwhere the parameter `ϵ` must satisfy `0 \u003c= ϵ \u003c= 1-α`\n\n```julia\njulia\u003e Random.seed!(43);\n\njulia\u003e cormatgen_constant_noised(4, 0.5)\n4×4 Array{Float64,2}:\n 1.0       0.314724  0.590368  0.346992\n 0.314724  1.0       0.314256  0.512183\n 0.590368  0.314256  1.0       0.538089\n 0.346992  0.512183  0.538089  1.0   \n```\n\nAnalogically to generate noised two constants matrix run\n\n```julia\njulia\u003e Random.seed!(43);\n\njulia\u003e cormatgen_two_constant_noised(4, 0.8, 0.2)\n4×4 Array{Float64,2}:\n 1.0       0.754384  0.194805  0.171162\n 0.754384  1.0       0.117009  0.27321\n 0.194805  0.117009  1.0       0.139476\n 0.171162  0.27321   0.139476  1.0    \n```\n\nHere the first constant refer to the \"nesting\" of the higher\ncorrelation for the first half of marginals.\nFinally to generate noised Toeplitz matrix run:\n\n```julia\njulia\u003e cormatgen_toeplitz_noised(n::Int, ρ::Float64; ϵ=(1-ρ)/(1+ρ)/2)\n```\nwhere the parameter `ϵ must satisfy 0 \u003c= ϵ \u003c= (1-ρ)/(1+ρ)`\n\n```julia\njulia\u003e Random.seed!(43);\n\njulia\u003e cormatgen_toeplitz_noised(4, 0.5)\n4×4 Array{Float64,2}:\n 1.0        0.376483  0.310246  0.0229948\n 0.376483   1.0       0.376171  0.258122\n 0.310246   0.376171  1.0       0.525393\n 0.0229948  0.258122  0.525393  1.0  \n```\n\n## Changes the subset of marginals of multivariate Gaussian distributed data\n\nTo change the chosen marginals subset, determined by the vector of indices`ind`, of the multivariate Gaussian distributed data `x` by means of t-Student sub-copula with\na parameter `ν` run:\n\n```julia\njulia\u003e gcop2tstudent(x::Matrix{Float64}, ind::Vector{Int}, ν::Int; naive::Bool = false, rng = Random.GLOBAL_RNG)\n```\nall univariate marginal distributions will be Gaussian, hence unaffected by the transformation. The keyword `naive` means the naive resampling if true.\nCustom random number generator is supported.\n\n```julia\n\njulia\u003e Σ = [1. 0.5 0.5; 0.5 1. 0.5; 0.5 0.5 1];\n\njulia\u003e Random.seed!(42);\n\njulia\u003e x = Array(rand(MvNormal(Σ), 6)')\n6×3 Array{Float64,2}:\n -0.556027  -0.662861   -0.384124\n -0.299484   1.38993    -0.571326\n -0.468606  -0.0990787  -2.3464  \n  1.00331    1.43902     0.966819\n  0.518149   1.55065     0.989712\n -0.886205   0.149748   -1.54419\n\njulia\u003e gcop2tstudent(x, [1,2], 6)\n6×3 Array{Float64,2}:\n -0.519458  -0.498377   -0.384124\n -0.37937    1.66806    -0.571326\n -0.432902  -0.0178933  -2.3464  \n  1.01216    1.50814     0.966819\n  0.226484   1.12436     0.989712\n -0.727203   0.238701   -1.54419\n```\nTo change the chosen marginals subset  of the multivariate Gaussian distributed data `x` by means of the Archimedean copula run:\n\n```julia\njulia\u003e gcop2arch(x::Matrix{Float64}, inds::Vector{Pair{String,Vector{Int64}}}; naive::Bool = false, notnested::Bool = false, rng = Random.GLOBAL_RNG)\n```\n\nMarginals to be changed are list in `inds[i][2]`, while the corresponding Archimedean copula is determined in `inds[i][1]`.\nMany disjoint subsets of marginals with different Archimedean copulas can be transformed. All univariate marginal distributions are Gaussian hence unaffected by the transformation. The keyword `naive` indicates the use of the naive data resampling if `true`. The keyword `notnested` if `true` indicates the use of one parameter Archimedean copula instead of a nested one. Custom random number generator is supported.\n\n```julia\n\njulia\u003e Σ = [1. 0.5 0.5; 0.5 1. 0.5; 0.5 0.5 1];\n\njulia\u003e Random.seed!(42)\n\njulia\u003e x = Array(rand(MvNormal(Σ), 6)')\n6×3 Array{Float64,2}:\n -0.556027  -0.662861   -0.384124\n -0.299484   1.38993    -0.571326\n -0.468606  -0.0990787  -2.3464\n  1.00331    1.43902     0.966819\n  0.518149   1.55065     0.989712\n -0.886205   0.149748   -1.54419\n\njulia\u003e gcop2arch(x, [\"clayton\" =\u003e [1,2]])\n6×3 Array{Float64,2}:\n -0.742443   0.424851  -0.384124\n  0.211894   0.195774  -0.571326\n -0.989417  -0.299369  -2.3464\n  0.157683   1.47768    0.966819\n  0.154893   0.893253   0.989712\n -0.657297  -0.339814  -1.54419\n\n\njulia\u003e Random.seed!(42);\n\njulia\u003e x = Array(rand(MvNormal(Σ), 6)');\n\njulia\u003e gcop2arch(x, [\"gumbel\" =\u003e [1,2]])\n6×3 Array{Float64,2}:\n0.178913   1.60797    -0.384124\n0.579476   0.880272   -0.571326\n-0.986662  -0.0180474  -2.3464  \n1.20299    2.55397     0.966819\n0.857086   1.86212     0.989712\n-0.548206  -0.439289   -1.54419\n\n```\n\nTo change the chosen marginals subset list in `ind` of the multivariate Gaussian distributed data `x` by means of the Frechet maximal copula run:\n\n```julia\njulia\u003e gcop2frechet(x::Matrix{Float64}, ind::Vector{Int}; naive::Bool = false)\n```\nall univariate marginal distributions are Gaussian as they are unaffected by the transformation. The keyword `naive` means naive resampling if true.\n\n```julia\n\njulia\u003e Σ = [1. 0.5 0.5; 0.5 1. 0.5; 0.5 0.5 1];\n\njulia\u003e Random.seed!(42)\n\njulia\u003e x = Array(rand(MvNormal(Σ), 6)');\n\njulia\u003e gcop2frechet(x, [1,2])\n6×3 Array{Float64,2}:\n -0.875777   -0.374723   -0.384124\n  0.0960334   0.905703   -0.571326\n -0.599792   -0.0110945  -2.3464\n  0.813717    1.8513      0.966819\n  0.599255    1.56873     0.989712\n -0.7223     -0.172507   -1.54419\n```\n\nTo change the chosen marginals subset list in `ind` of themultivariate Gaussian distributed data `x` by means of the bivariate Marshall-Olkin copula run:\n\n```julia\njulia\u003e gcop2marshallolkin(x::Matrix{Float64}, ind::Vector{Int}, λ1::Float64 = 1., λ2::Float64 = 1.5; naive::Bool = false, rng = Random.GLOBAL_RNG)\n```\nall univariate marginal distributions are Gaussian and unaffected by the transformation. In the keyword `naive` is `true` uses the naive resampling.\nThe algorithm requires `length(ind) = 2` `λ₁ ≥ 0` and `λ₂ ≥ 0`. The parameter `λ₁₂` is computed from expected correlation between both changed marginals. Custom random number generator is supported.\n\n```julia\n\njulia\u003e Σ = [1. 0.5 0.5; 0.5 1. 0.5; 0.5 0.5 1];\n\njulia\u003e Random.seed!(42);\n\njulia\u003e x = Array(rand(MvNormal(Σ), 6)');\n\njulia\u003e gcop2marshallolkin(x, [1,2])\n6×3 Array{Float64,2}:\n -0.790756   0.784371  -0.384124\n -0.28088    0.338086  -0.571326\n -0.90688   -0.509684  -2.3464  \n  0.738628   1.71026    0.966819\n  0.353654   1.19357    0.989712\n -0.867606  -0.589929  -1.54419\n```\n## Helpers\n\n### Converting marginals\n\nTakes matrix `X`: `size(X) = (t, n)` ie `t` realisations of `n`-dimensional random variable, with all uniform marginal univariate distributions `∀ᵢ X[:,i] ∼ Uniform(0,1)`, and convert those marginals to the common distribution `d` with parameters `p[i]`\n\n```julia\njulia\u003e convertmarg!(x::Matrix{T}, d::UnionAll, p::Union{Vector{Vector{Int64}}, Vector{Vector{Float64}}}; testunif::Bool = true)\n```\n\nIf `testunif = true` each marginal is tested for uniformity.\n\n```julia\njulia\u003e c = GaussianCopula([1. 0.5; 0.5 1.])\n\njulia\u003e Random.seed!(43);\n\njulia\u003e x = simulate_copula(10, c);\n\n\njulia\u003e convertmarg!(x, Normal, [[0, 1],[0, 10]])\n\njulia\u003e x\n10×2 Array{Float64,2}:\n10×2 Matrix{Float64}:\n  0.225457      8.97627\n  0.548381     14.3926\n  0.666147    -10.0689\n -0.746662     -9.03553\n -0.746857     17.2101\n -0.608109     -3.45649\n -0.136555      0.700419\n  0.215631     -7.34409\n -0.00352701   -0.434793\n -0.876853      2.39009\n\n```\n\nTo convert `i` th marginal to univariate distribution `d` with parameters array\n`p` run\n```julia\n\njulia\u003e using Distributions\n\njulia\u003e quantile.(d(p...), x[:,i])\n```\n\n```julia\njulia\u003e c = GaussianCopula([1. 0.5; 0.5 1.])\n\njulia\u003e Random.seed!(43);\n\njulia\u003e x = simulate_copula(10, c);\n\njulia\u003e quantile.(Levy(0, 1), x[:,2])\n10-element Array{Float64,1}:\n  18.327904335047272\n 112.72788160148863  \n   0.4992650891811052\n   0.5642861403809334\n 350.0676959136128   \n   1.2175971128674394\n   2.510078079677982\n   0.6980591543550244\n   2.0290242635860944\n   3.527994542141473\n```\nTo convert all marginals to the same `d` with the same parameters `p` run\n\n```\njulia\u003e using Distributions\n\njulia\u003e quantile.(d(p...), x)\n```\n\n```julia\njulia\u003e quantile.(Levy(0, 1), x)\n10×2 Array{Float64,2}:\n 3.42919    18.3279  \n 7.14305   112.728   \n 9.6359      0.499265\n 0.687009    0.564286\n 0.686835  350.068   \n 0.827224    1.2176  \n 1.71944     2.51008\n 3.3597      0.698059\n 2.18374     2.02902\n 0.582946    3.52799\n```\n## BigFloat implementation, developement version.\n\nFor some copulas: Marshall-Olkin, Frechet, Gumbel, Frank, Ali-Mikhail-Haq,and Nested Gumbel the BigFloat implementation is supported. However it is a development version that requires enhancement of other Julia packages.\n\n```julia\n\njulia\u003e θ = BigFloat(2.);\n\njulia\u003e Random.seed!(43)\nMersenneTwister(43)\n\njulia\u003e simulate_copula(3, c)\n3×3 Matrix{BigFloat}:\n 0.201305  0.277557  0.387158\n 0.395095  0.536081  0.152753\n 0.612178  0.39509   0.426144\n\n```\n\n# Citing this work\n\nThis project was partially financed by the National Science Centre, Poland – project number 2014/15/B/ST6/05204;\n\n* while reffering to `gcop2arch()`, `gcop2frechet()`, and `gcop2marshallolkin()` - please cite K. Domino, A. Glos: 'Introducing higher order correlations to marginals' subset of multivariate data by means of Archimedean copulas', [arXiv:1803.07813] (https://arxiv.org/abs/1803.07813);\n\n* while reffering to `gcop2tstudent()` - please cite K. Domino: 'Multivariate cumulants in outlier detection for financial data analysis', Physica A: Statistical Mechanics and its Applications Volume 558, 15 November 2020, 124995 (https://doi.org/10.1016/j.physa.2020.124995);\n\n* you may also cite K. Domino: 'Selected Methods for non-Gaussian Data Analysis', Gliwice, IITiS PAN, 2019, ISBN: 978-83-926054-3-0, [arXiv:1811.10486] (https://arxiv.org/abs/1811.10486)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitis%2Fdatagencopulabased.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiitis%2Fdatagencopulabased.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitis%2Fdatagencopulabased.jl/lists"}