Multivariate dist (#8)

* up codecov

* modified:   src/continuous/Burr.jl

* Rename Package

* modified:   src/ProbabilityDistributions.jl

* modified:   Project.toml

* modified:   Project.toml

* rename again

* add multivariate t, normal distributions and CDF

* add tests

* modified:   Project.toml

* modified:   docs/src/bestiary/multivariate.md

* modified:   docs/src/bestiary/multivariate.md
	modified:   test/continuous_test.jl

Author: Santymax98

Project.toml

@@ -1,14 +1,16 @@
 name = "AdditionalDistributions"
 uuid = "6655a985-646a-4595-ab89-59c8a6085518"
+version = "0.1.1"
 authors = ["Santiago Jimenez Ramos <[email protected]>"]
 description = "A collection of additional probability distributions not included in Distributions.jl, fully compatible with its API."
-version = "0.1.1"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 HypergeometricFunctions = "34004b35-14d8-5ef3-9330-4cdb6864b03a"
 LambertW = "984bce1d-4616-540c-a9ee-88d1112d94c9"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LogExpFunctions = "2ab3a3ac-af41-5b50-aa03-7779005ae688"
+Primes = "27ebfcd6-29c5-5fa9-bf4b-fb8fc14df3ae"
 QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
@@ -19,9 +21,12 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 [compat]
 Aqua = "0.8"
 Distributions = "0.25"
+ForwardDiff = "0.10, 1"
 HypergeometricFunctions = "0.3"
 LambertW = "0.4"
+LinearAlgebra = "1"
 LogExpFunctions = "0.3"
+Primes = "0.5.7"
 QuadGK = "2"
 Random = "1"
 Roots = "1"
@@ -32,14 +37,15 @@ StatsBase = "0.33"
 Test = "1"
 TestItemRunner = "1.1.0"
 TestItems = "1.0.0"
-julia = "1.9"
+julia = "1.6, 1.9"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestItemRunner = "f8b46487-2199-4994-9208-9a1283c18c0a"
 TestItems = "1c621080-faea-4a02-84b6-bbd5e436b8fe"
 
 [targets]
-test = ["Test", "StableRNGs", "Aqua", "TestItemRunner", "TestItems"]
+test = ["Test", "StableRNGs", "Aqua", "TestItemRunner", "TestItems", "ForwardDiff"]

README.md

@@ -5,66 +5,93 @@
 [![Build Status](https://github.com/Santymax98/AdditionalDistributions.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/Santymax98/AdditionalDistributions.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/Santymax98/AdditionalDistributions.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/Santymax98/AdditionalDistributions.jl)
 
-The [*AdditionalDistributions*](https://github.com/Santymax98/AdditionalDistributions.jl) package is a comprehensive extension of [*Distributions.jl*](https://github.com/JuliaStats/Distributions.jl).
-It is designed to expand the functionality of the base package by incorporating both discrete and continuous probability distributions that are not included in `Distributions`, either due to their specialized nature or because they are less commonly used.
-*AdditionalDistributions* aims to provide a broader range of statistical tools for data analysis, simulation, and probabilistic modeling, catering to both academic and scientific needs where these additional distributions are essential.
-
 ---
 
-## Motivation and Relationship with Distributions.jl
-
-Although several additional distributions have been proposed for inclusion in `Distributions.jl` as early as [JuliaStats/Distributions.jl#124](https://github.com/JuliaStats/Distributions.jl/issues/124) (2013), many of them have not yet been integrated into the main package.
-The motivation behind *AdditionalDistributions.jl* is therefore to provide a **flexible yet rigorous, API-compatible environment** for developing and testing both classical and new distribution families — **without compromising statistical quality, numerical stability, or consistency** with the `Distributions.jl` interface.
+**AdditionalDistributions.jl** extends the [Distributions.jl](https://github.com/JuliaStats/Distributions.jl)
+ecosystem by providing additional discrete, continuous, and multivariate probability
+distributions that are not yet available in the base package.
 
-This package also serves as a foundation for future **multivariate** and **computationally optimized distributions**, designed for efficient integration with [`Copulas.jl`](https://github.com/lrnv/Copulas.jl), where the author is an active co-developer.
-These implementations aim to offer faster, more stable probability evaluations for dependence modeling and simulation, while remaining interoperable with the broader JuliaStats ecosystem.
+It maintains full API compatibility (`pdf`, `cdf`, `rand`, etc.) and emphasizes
+**accuracy, efficiency, and completeness** — integrating advanced cumulative
+probability algorithms for multivariate Gaussian and Student’s *t* models.
 
 ---
 
-## Purpose and Scope
+## 🔹 Key Features
 
-The purpose of `AdditionalDistributions.jl` is to serve as a well-maintained repository for distributions that are too exotic or specialized to be included in the main `Distributions.jl` package.
-This includes distributions that are frequently required in specific fields of research but are not yet available in Julia, as well as new or experimental distributions that may not be widely used but have significant potential applications.
+- 📈 **Extensive library of distributions** — zero-inflated, generalized, and heavy-tailed families.
+- ⚡ **High-performance QMC algorithms** for multivariate CDFs (`MvGaussian`, `MvTStudent`),  
+  significantly faster than [MvNormalCDF.jl](https://github.com/JuliaStats/MvNormalCDF.jl)
+  with minimal loss in absolute precision (typically within `1e-5`–`1e-6`).
+- 🧮 **Full API compatibility** with `Distributions.jl`.
+- 🧩 **Research-oriented architecture**, extensible to new distributional forms.
+- 🧠 **Reproducibility-focused testing**, with benchmarks aligned with *mvtnorm* (R, Genz & Bretz 2002).
+
+---
 
-For instance, you can define the following distributions (among many others):
+## 🚀 Example
 
 ```julia
-julia> using Distributions, AdditionalDistributions
-julia> BetaNegBinomial(r, α, β) # Discrete univariate
-julia> Lomax(α, λ)              # Continuous univariate
-julia> ZINB(r, θ, p)            # Discrete univariate
-julia> Gompertz(η, b)           # Continuous univariate
+using AdditionalDistributions
+
+# Univariate and multivariate distributions
+d1 = Lomax(α=2.0, λ=3.0)
+d2 = ZINB(r=4, θ=0.7, p=0.2)
+
+pdf(d1, 1.5), cdf(d2, 3)
+
+# Accurate CDF for a multivariate t distribution
+Σ = [1.0 0.5; 0.5 1.0]
+d3 = MvTStudent(ν=5, Σ)
+cdf(d3, [-1.0, -1.0], [1.0, 1.0])
 ```
 
-These distributions, along with others like the ARGUS or Zero-Inflated Poisson (ZIP), are essential in various fields of research but are not included in the base `Distributions.jl` package.
-`AdditionalDistributions.jl` provides these and more, ensuring that users have access to a broad spectrum of statistical tools.
+---
+
+## 🧩 Performance Highlights
+
+| Algorithm                | Library                      | Mean Error | Relative Speed     |
+| ------------------------ | ---------------------------- | ---------- | ------------------ |
+| QMC–Sobol (this package) | `AdditionalDistributions.jl` | `≈ 1e-5`   | **1.5×–3× faster** |
+| Adaptive Genz–Bretz      | `MvNormalCDF.jl`             | `≈ 1e-6`   | slower             |
+| QRSVN (R `mvtnorm`)      | Reference                    | `≈ 1e-6`   | —                  |
+
+Our implementation sacrifices a marginal amount of absolute precision
+for a substantial speedup in moderate to high dimensions (3–25).
 
 ---
 
-## Key Features
+## 🧭 Roadmap
 
-* **Extensive Range of Distributions:** Includes a wide variety of distributions, some of which are not commonly found in standard statistical libraries.
-* **Seamless Integration:** Fully compatible with `Distributions.jl`, allowing joint use with other packages in the Julia ecosystem.
-* **Detailed Documentation:** Comprehensive references and examples for each implemented distribution.
-* **Community-Driven Development:** Contributions are welcome — from new distributions to documentation improvements.
+* [ ] Add `Generalized Hyperbolic` and `Skew-t` families.
+* [ ] Implement flexible parameter fitting (`fit_mle`, `fit_map`).
+* [ ] Integrate symbolic representations for documentation.
+* [ ] Parallelize with threads
+* [ ] Maybe GPU-parallelized QMC backend (planned).
 
 ---
 
-## Maintaining Relevance and Utility
+## 🤝 Contributing
 
-Given the importance of these additional distributions in various academic and scientific applications, we are committed to the ongoing maintenance and development of `AdditionalDistributions.jl`.
-Our goal is to ensure that the package remains a valuable resource for the Julia community.
-To support this, we are considering moving the package under the `JuliaStats` organization, which would provide additional support and visibility, ensuring its long-term sustainability.
+We welcome contributions!
+All code follows the design and testing conventions of
+[`Distributions.jl`](https://github.com/JuliaStats/Distributions.jl),
+ensuring consistency and interoperability.
 
-With *AdditionalDistributions*, you can:
+### Guidelines
 
-* **Sample from distributions:** Draw random samples from a variety of distributions.
-* **Calculate moments and other properties:** Obtain moments (mean, variance, skewness, kurtosis), entropy, and other statistical metrics.
-* **Evaluate probability density/mass functions:** Compute `pdf`, `logpdf`, and related functions.
-* **Utilize moment-generating, quantile, and characteristic functions:** Access `mgf`, `quantile`, and `cf` for in-depth statistical analysis.
+* Open an issue to discuss bugs or ideas.
+* Use `@testitem`-based testsets (same as `Distributions.jl`).
+* Follow `Documenter.jl` docstring style and type annotations.
 
----
+Pull requests improving:
+
+* distribution coverage,
+* algorithmic efficiency,
+* or documentation clarity are particularly encouraged.
 
-## Future Directions
+---
 
-In future releases, we plan to implement **maximum-likelihood estimators**, expand **multivariate coverage**, and introduce **optimized numerical backends** to support efficient use within `Copulas.jl` and other packages in the JuliaStats and SciML ecosystems.
+**Author:** Santiago Jiménez
+**License:** MIT
+**Repository:** [Santymax98/AdditionalDistributions.jl](https://github.com/Santymax98/AdditionalDistributions.jl)

docs/make.jl

@@ -25,6 +25,7 @@ makedocs(;
         "Bestiary" => [
             "Discrete Distributions"=>"bestiary/discrete.md",
             "Continuous Distribution"=>"bestiary/continuous.md",
+            "Multivariate Distributions"=>"bestiary/multivariate.md",
         ],
     ],
 )

docs/src/bestiary/multivariate.md

@@ -0,0 +1,67 @@
+## Extra Multivariate Distributions
+
+The following multivariate distributions extend the behavior of `Distributions.jl` to include **numerically stable cumulative
+probability computations** using custom Quasi–Monte Carlo (QMC) integration routines.
+
+---
+
+```@docs
+MvGaussian
+```
+
+**Notes**
+
+* Equivalent to `Distributions.MvNormal`, but implements its own `cdf(a, b)` method based on a high–precision QMC integrator.
+* Compatible with reference datasets from [MvNormalCDF.jl](https://github.com/JuliaStats/MvNormalCDF.jl), adjusted for local reproducibility.
+* Fully compatible with `mean`, `cov`, `pdf`, `logpdf`, and `rand`.
+
+**Example**
+
+```julia
+μ = [0.0, 0.0]
+Σ = [1.0 0.5; 0.5 1.0]
+d = MvGaussian(μ, Σ)
+cdf(d, [-1.0, -1.0], [1.0, 1.0])
+```
+
+```@docs
+MvTStudent
+```
+
+**Notes**
+
+* Equivalent to `Distributions.MvTDist`, but with a custom `cdf(a, b)` based on the same QMC integrator.
+* For ν → ∞, numerical results converge to those of `MvGaussian`.
+* Benchmarked against `pmvt` from *mvtnorm* (R, Genz & Bretz, 2002).
+
+**Example**
+
+```julia
+ν = 10
+Σ = [1.0 0.4; 0.4 1.0]
+d = MvTStudent(ν, Σ)
+cdf(d, [-1.0, -1.0], [1.0, 1.0])
+```
+
+---
+
+### Implementation Notes
+
+Both types serve as lightweight wrappers around their `Distributions.jl` counterparts:
+
+```julia
+struct MvGaussian{D<:Distributions.MvNormal}
+    dist::D
+end
+
+struct MvTStudent{D<:Distributions.MvTDist}
+    dist::D
+end
+```
+
+All statistical methods (`mean`, `cov`, `pdf`, etc.) are delegated to their internal distribution objects, ensuring full compatibility while
+adding numerical integration support for the cumulative distribution function.
+
+```@docs
+AdditionalDistributions.mvtcdf
+```