diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json
new file mode 100644
index 0000000000..fe623e6316
--- /dev/null
+++ b/dev/.documenter-siteinfo.json
@@ -0,0 +1 @@
+{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2025-01-17T14:35:30","documenter_version":"1.8.0"}}
\ No newline at end of file
diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js
index 6adfbbbf4b..7d68cd808b 100644
--- a/dev/assets/documenter.js
+++ b/dev/assets/documenter.js
@@ -1,15 +1,15 @@
// Generated by Documenter.jl
requirejs.config({
paths: {
- 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/languages/julia.min',
+ 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min',
'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min',
- 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min',
- 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/contrib/auto-render.min',
- 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min',
+ 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min',
+ 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min',
+ 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min',
'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min',
- 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min',
- 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min',
- 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/languages/julia-repl.min',
+ 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min',
+ 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min',
+ 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min',
},
shim: {
"highlight-julia": {
@@ -70,13 +70,96 @@ $(document).ready(function() {
hljs.highlightAll();
})
+})
+////////////////////////////////////////////////////////////////////////////////
+require(['jquery'], function($) {
+
+let timer = 0;
+var isExpanded = true;
+
+$(document).on(
+ "click",
+ ".docstring .docstring-article-toggle-button",
+ function () {
+ let articleToggleTitle = "Expand docstring";
+ const parent = $(this).parent();
+
+ debounce(() => {
+ if (parent.siblings("section").is(":visible")) {
+ parent
+ .find("a.docstring-article-toggle-button")
+ .removeClass("fa-chevron-down")
+ .addClass("fa-chevron-right");
+ } else {
+ parent
+ .find("a.docstring-article-toggle-button")
+ .removeClass("fa-chevron-right")
+ .addClass("fa-chevron-down");
+
+ articleToggleTitle = "Collapse docstring";
+ }
+
+ parent
+ .children(".docstring-article-toggle-button")
+ .prop("title", articleToggleTitle);
+ parent.siblings("section").slideToggle();
+ });
+ }
+);
+
+$(document).on("click", ".docs-article-toggle-button", function (event) {
+ let articleToggleTitle = "Expand docstring";
+ let navArticleToggleTitle = "Expand all docstrings";
+ let animationSpeed = event.noToggleAnimation ? 0 : 400;
+
+ debounce(() => {
+ if (isExpanded) {
+ $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down");
+ $("a.docstring-article-toggle-button")
+ .removeClass("fa-chevron-down")
+ .addClass("fa-chevron-right");
+
+ isExpanded = false;
+
+ $(".docstring section").slideUp(animationSpeed);
+ } else {
+ $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up");
+ $("a.docstring-article-toggle-button")
+ .removeClass("fa-chevron-right")
+ .addClass("fa-chevron-down");
+
+ isExpanded = true;
+ articleToggleTitle = "Collapse docstring";
+ navArticleToggleTitle = "Collapse all docstrings";
+
+ $(".docstring section").slideDown(animationSpeed);
+ }
+
+ $(this).prop("title", navArticleToggleTitle);
+ $(".docstring-article-toggle-button").prop("title", articleToggleTitle);
+ });
+});
+
+function debounce(callback, timeout = 300) {
+ if (Date.now() - timer > timeout) {
+ callback();
+ }
+
+ clearTimeout(timer);
+
+ timer = Date.now();
+}
+
})
////////////////////////////////////////////////////////////////////////////////
require([], function() {
function addCopyButtonCallbacks() {
for (const el of document.getElementsByTagName("pre")) {
const button = document.createElement("button");
- button.classList.add("copy-button", "fas", "fa-copy");
+ button.classList.add("copy-button", "fa-solid", "fa-copy");
+ button.setAttribute("aria-label", "Copy this code block");
+ button.setAttribute("title", "Copy");
+
el.appendChild(button);
const success = function () {
@@ -85,7 +168,7 @@ function addCopyButtonCallbacks() {
};
const failure = function () {
- button.classList.add("error", "fa-times");
+ button.classList.add("error", "fa-xmark");
button.classList.remove("fa-copy");
};
@@ -94,7 +177,7 @@ function addCopyButtonCallbacks() {
setTimeout(function () {
button.classList.add("fa-copy");
- button.classList.remove("success", "fa-check", "fa-times");
+ button.classList.remove("success", "fa-check", "fa-xmark");
}, 5000);
});
}
@@ -138,29 +221,602 @@ require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) {
// Manages the top navigation bar (hides it when the user starts scrolling down on the
// mobile).
window.Headroom = Headroom; // work around buggy module loading?
-$(document).ready(function() {
- $('#documenter .docs-navbar').headroom({
- "tolerance": {"up": 10, "down": 10},
+$(document).ready(function () {
+ $("#documenter .docs-navbar").headroom({
+ tolerance: { up: 10, down: 10 },
});
+});
+
+})
+////////////////////////////////////////////////////////////////////////////////
+require(['jquery'], function($) {
+
+$(document).ready(function () {
+ let meta = $("div[data-docstringscollapsed]").data();
+
+ if (meta?.docstringscollapsed) {
+ $("#documenter-article-toggle-button").trigger({
+ type: "click",
+ noToggleAnimation: true,
+ });
+ }
+});
+
})
+////////////////////////////////////////////////////////////////////////////////
+require(['jquery'], function($) {
+
+/*
+To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc
+
+PSEUDOCODE:
+
+Searching happens automatically as the user types or adjusts the selected filters.
+To preserve responsiveness, as much as possible of the slow parts of the search are done
+in a web worker. Searching and result generation are done in the worker, and filtering and
+DOM updates are done in the main thread. The filters are in the main thread as they should
+be very quick to apply. This lets filters be changed without re-searching with minisearch
+(which is possible even if filtering is on the worker thread) and also lets filters be
+changed _while_ the worker is searching and without message passing (neither of which are
+possible if filtering is on the worker thread)
+
+SEARCH WORKER:
+
+Import minisearch
+
+Build index
+
+On message from main thread
+ run search
+ find the first 200 unique results from each category, and compute their divs for display
+ note that this is necessary and sufficient information for the main thread to find the
+ first 200 unique results from any given filter set
+ post results to main thread
+
+MAIN:
+
+Launch worker
+
+Declare nonconstant globals (worker_is_running, last_search_text, unfiltered_results)
+
+On text update
+ if worker is not running, launch_search()
+
+launch_search
+ set worker_is_running to true, set last_search_text to the search text
+ post the search query to worker
+
+on message from worker
+ if last_search_text is not the same as the text in the search field,
+ the latest search result is not reflective of the latest search query, so update again
+ launch_search()
+ otherwise
+ set worker_is_running to false
+
+ regardless, display the new search results to the user
+ save the unfiltered_results as a global
+ update_search()
+
+on filter click
+ adjust the filter selection
+ update_search()
+
+update_search
+ apply search filters by looping through the unfiltered_results and finding the first 200
+ unique results that match the filters
+
+ Update the DOM
+*/
+
+/////// SEARCH WORKER ///////
+
+function worker_function(documenterSearchIndex, documenterBaseURL, filters) {
+ importScripts(
+ "https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min.js"
+ );
+
+ let data = documenterSearchIndex.map((x, key) => {
+ x["id"] = key; // minisearch requires a unique for each object
+ return x;
+ });
+
+ // list below is the lunr 2.1.3 list minus the intersect with names(Base)
+ // (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with)
+ // ideally we'd just filter the original list but it's not available as a variable
+ const stopWords = new Set([
+ "a",
+ "able",
+ "about",
+ "across",
+ "after",
+ "almost",
+ "also",
+ "am",
+ "among",
+ "an",
+ "and",
+ "are",
+ "as",
+ "at",
+ "be",
+ "because",
+ "been",
+ "but",
+ "by",
+ "can",
+ "cannot",
+ "could",
+ "dear",
+ "did",
+ "does",
+ "either",
+ "ever",
+ "every",
+ "from",
+ "got",
+ "had",
+ "has",
+ "have",
+ "he",
+ "her",
+ "hers",
+ "him",
+ "his",
+ "how",
+ "however",
+ "i",
+ "if",
+ "into",
+ "it",
+ "its",
+ "just",
+ "least",
+ "like",
+ "likely",
+ "may",
+ "me",
+ "might",
+ "most",
+ "must",
+ "my",
+ "neither",
+ "no",
+ "nor",
+ "not",
+ "of",
+ "off",
+ "often",
+ "on",
+ "or",
+ "other",
+ "our",
+ "own",
+ "rather",
+ "said",
+ "say",
+ "says",
+ "she",
+ "should",
+ "since",
+ "so",
+ "some",
+ "than",
+ "that",
+ "the",
+ "their",
+ "them",
+ "then",
+ "there",
+ "these",
+ "they",
+ "this",
+ "tis",
+ "to",
+ "too",
+ "twas",
+ "us",
+ "wants",
+ "was",
+ "we",
+ "were",
+ "what",
+ "when",
+ "who",
+ "whom",
+ "why",
+ "will",
+ "would",
+ "yet",
+ "you",
+ "your",
+ ]);
+
+ let index = new MiniSearch({
+ fields: ["title", "text"], // fields to index for full-text search
+ storeFields: ["location", "title", "text", "category", "page"], // fields to return with results
+ processTerm: (term) => {
+ let word = stopWords.has(term) ? null : term;
+ if (word) {
+ // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names
+ word = word
+ .replace(/^[^a-zA-Z0-9@!]+/, "")
+ .replace(/[^a-zA-Z0-9@!]+$/, "");
+
+ word = word.toLowerCase();
+ }
+
+ return word ?? null;
+ },
+ // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not
+ // find anything if searching for "add!", only for the entire qualification
+ tokenize: (string) => string.split(/[\s\-\.]+/),
+ // options which will be applied during the search
+ searchOptions: {
+ prefix: true,
+ boost: { title: 100 },
+ fuzzy: 2,
+ },
+ });
+
+ index.addAll(data);
+
+ /**
+ * Used to map characters to HTML entities.
+ * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts
+ */
+ const htmlEscapes = {
+ "&": "&",
+ "<": "<",
+ ">": ">",
+ '"': """,
+ "'": "'",
+ };
+
+ /**
+ * Used to match HTML entities and HTML characters.
+ * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts
+ */
+ const reUnescapedHtml = /[&<>"']/g;
+ const reHasUnescapedHtml = RegExp(reUnescapedHtml.source);
+
+ /**
+ * Escape function from lodash
+ * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts
+ */
+ function escape(string) {
+ return string && reHasUnescapedHtml.test(string)
+ ? string.replace(reUnescapedHtml, (chr) => htmlEscapes[chr])
+ : string || "";
+ }
+
+ /**
+ * RegX escape function from MDN
+ * Refer: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
+ */
+ function escapeRegExp(string) {
+ return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+ }
+
+ /**
+ * Make the result component given a minisearch result data object and the value
+ * of the search input as queryString. To view the result object structure, refer:
+ * https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult
+ *
+ * @param {object} result
+ * @param {string} querystring
+ * @returns string
+ */
+ function make_search_result(result, querystring) {
+ let search_divider = `
`;
+ let display_link =
+ result.location.slice(Math.max(0), Math.min(50, result.location.length)) +
+ (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div
+
+ if (result.page !== "") {
+ display_link += ` (${result.page})`;
+ }
+ searchstring = escapeRegExp(querystring);
+ let textindex = new RegExp(`${searchstring}`, "i").exec(result.text);
+ let text =
+ textindex !== null
+ ? result.text.slice(
+ Math.max(textindex.index - 100, 0),
+ Math.min(
+ textindex.index + querystring.length + 100,
+ result.text.length
+ )
+ )
+ : ""; // cut-off text before and after from the match
+
+ text = text.length ? escape(text) : "";
+
+ let display_result = text.length
+ ? "..." +
+ text.replace(
+ new RegExp(`${escape(searchstring)}`, "i"), // For first occurrence
+ '$&'
+ ) +
+ "..."
+ : ""; // highlights the match
+
+ let in_code = false;
+ if (!["page", "section"].includes(result.category.toLowerCase())) {
+ in_code = true;
+ }
+
+ // We encode the full url to escape some special characters which can lead to broken links
+ let result_div = `
+
+
`;
+ }
+}
+
+function waitUntilSearchIndexAvailable() {
+ // It is possible that the documenter.js script runs before the page
+ // has finished loading and documenterSearchIndex gets defined.
+ // So we need to wait until the search index actually loads before setting
+ // up all the search-related stuff.
+ if (typeof documenterSearchIndex !== "undefined") {
+ runSearchMainCode();
+ } else {
+ console.warn("Search Index not available, waiting");
+ setTimeout(waitUntilSearchIndexAvailable, 1000);
+ }
+}
+
+// The actual entry point to the search code
+waitUntilSearchIndexAvailable();
})
////////////////////////////////////////////////////////////////////////////////
require(['jquery'], function($) {
// Modal settings dialog
-$(document).ready(function() {
- var settings = $('#documenter-settings');
- $('#documenter-settings-button').click(function(){
- settings.toggleClass('is-active');
+$(document).ready(function () {
+ var settings = $("#documenter-settings");
+ $("#documenter-settings-button").click(function () {
+ settings.toggleClass("is-active");
});
// Close the dialog if X is clicked
- $('#documenter-settings button.delete').click(function(){
- settings.removeClass('is-active');
+ $("#documenter-settings button.delete").click(function () {
+ settings.removeClass("is-active");
});
// Close dialog if ESC is pressed
- $(document).keyup(function(e) {
- if (e.keyCode == 27) settings.removeClass('is-active');
+ $(document).keyup(function (e) {
+ if (e.keyCode == 27) settings.removeClass("is-active");
});
});
@@ -168,151 +824,246 @@ $(document).ready(function() {
////////////////////////////////////////////////////////////////////////////////
require(['jquery'], function($) {
+$(document).ready(function () {
+ let search_modal_header = `
+
+
In censoring of data, values exceeding an upper limit (right censoring) or falling below a lower limit (left censoring), or both (interval censoring) are replaced by the corresponding limit itself. The package provides the censored function, which creates the most appropriate distribution to represent a censored version of a given distribution.
A censored distribution can be constructed using the following signature:
In censoring of data, values exceeding an upper limit (right censoring) or falling below a lower limit (left censoring), or both (interval censoring) are replaced by the corresponding limit itself. The package provides the censored function, which creates the most appropriate distribution to represent a censored version of a given distribution.
A censored distribution can be constructed using the following signature:
A censored distributiond of a distribution d0 to the interval $[l, u]=$[lower, upper] has the probability density (mass) function:
\[f(x; d_0, l, u) = \begin{cases}
P_{Z \sim d_0}(Z \le l), & x = l \\
f_{d_0}(x), & l < x < u \\
@@ -7,4 +7,4 @@
\end{cases}, \quad x \in [l, u]\]
where $f_{d_0}(x)$ is the probability density (mass) function of $d_0$.
If $Z \sim d_0$, and X = clamp(Z, l, u), then $X \sim d$. Note that this implies that even if $d_0$ is continuous, its censored form assigns positive probability to the bounds $l$ and $u$. Therefore, a censored continuous distribution has atoms and is a mixture of discrete and continuous components.
censored(d0; lower=l) # d0 left-censored to the interval [l, Inf)
censored(d0; upper=u) # d0 right-censored to the interval (-Inf, u]
censored(d0; lower=l, upper=u) # d0 interval-censored to the interval [l, u]
-censored(d0, l, u) # d0 interval-censored to the interval [l, u]
Implementation
To implement a specialized censored form for distributions of type D, instead of overloading a method with one of the above signatures, one or more of the following methods should be implemented:
For example, these functions are available for the following uncensored distributions:
DiscreteUniform
Exponential
LogUniform
Normal
Uniform
mode is not implemented for censored distributions.
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
+censored(d0, l, u) # d0 interval-censored to the interval [l, u]
Implementation
To implement a specialized censored form for distributions of type D, instead of overloading a method with one of the above signatures, one or more of the following methods should be implemented:
Cholesky-variate distributions are distributions whose variate forms are CholeskyVariate. This means each draw is a factorization of a positive-definite matrix of type LinearAlgebra.Cholesky (the object produced by the function LinearAlgebra.cholesky applied to a dense positive-definite matrix.)
The LKJCholesky distribution of size $d$ with shape parameter $\eta$ is a distribution over LinearAlgebra.Cholesky factorisations of $d\times d$ real correlation matrices (positive-definite matrices with ones on the diagonal).
Variates or samples of the distribution are LinearAlgebra.Cholesky objects, as might be returned by F = LinearAlgebra.cholesky(R), so that Matrix(F) ≈ R is a variate or sample of LKJ.
Sampling LKJCholesky is faster than sampling LKJ, and often having the correlation matrix in factorized form makes subsequent computations cheaper as well.
Note
LinearAlgebra.Cholesky stores either the upper or lower Cholesky factor, related by F.U == F.L'. Both can be accessed with F.U and F.L, but if the factor not stored is requested, then a copy is made. The uplo parameter specifies whether the upper ('U') or lower ('L') Cholesky factor is stored when randomly generating samples. Set uplo to 'U' if the upper factor is desired to avoid allocating a copy when calling F.U.
Lewandowski D, Kurowicka D, Joe H. Generating random correlation matrices based on vines and extended onion method, Journal of Multivariate Analysis (2009), 100(9): 1989-2001 doi: 10.1016/j.jmva.2009.04.008
Cholesky-variate distributions are distributions whose variate forms are CholeskyVariate. This means each draw is a factorization of a positive-definite matrix of type LinearAlgebra.Cholesky (the object produced by the function LinearAlgebra.cholesky applied to a dense positive-definite matrix.)
The LKJCholesky distribution of size $d$ with shape parameter $\eta$ is a distribution over LinearAlgebra.Cholesky factorisations of $d\times d$ real correlation matrices (positive-definite matrices with ones on the diagonal).
Variates or samples of the distribution are LinearAlgebra.Cholesky objects, as might be returned by F = LinearAlgebra.cholesky(R), so that Matrix(F) ≈ R is a variate or sample of LKJ.
Sampling LKJCholesky is faster than sampling LKJ, and often having the correlation matrix in factorized form makes subsequent computations cheaper as well.
Note
LinearAlgebra.Cholesky stores either the upper or lower Cholesky factor, related by F.U == F.L'. Both can be accessed with F.U and F.L, but if the factor not stored is requested, then a copy is made. The uplo parameter specifies whether the upper ('U') or lower ('L') Cholesky factor is stored when randomly generating samples. Set uplo to 'U' if the upper factor is desired to avoid allocating a copy when calling F.U.
Lewandowski D, Kurowicka D, Joe H. Generating random correlation matrices based on vines and extended onion method, Journal of Multivariate Analysis (2009), 100(9): 1989-2001 doi: 10.1016/j.jmva.2009.04.008
A convolution of two probability distributions is the probability distribution of the sum of two independent random variables that are distributed according to these distributions.
The convolution of two distributions can be constructed with convolve.
Convolve two distributions and return the distribution corresponding to the sum of independent random variables drawn from the underlying distributions.
Currently, the function is only defined in cases where the convolution has a closed form. More precisely, the function is defined if the distributions of d1 and d2 are the same and one of
A convolution of two probability distributions is the probability distribution of the sum of two independent random variables that are distributed according to these distributions.
The convolution of two distributions can be constructed with convolve.
Convolve two distributions and return the distribution corresponding to the sum of independent random variables drawn from the underlying distributions.
Currently, the function is only defined in cases where the convolution has a closed form. More precisely, the function is defined if the distributions of d1 and d2 are the same and one of
A probability distribution has a probability density, so DensityInterface.DensityKind(::Distribution) === HasDensity().
For single variate values x, DensityInterface.logdensityof(d::Distribution, x) is equivalent to logpdf(d, x) and DensityInterface.densityof(d::Distribution, x) is equivalent to pdf(d, x).
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
A probability distribution has a probability density, so DensityInterface.DensityKind(::Distribution) === HasDensity().
For single variate values x, DensityInterface.logdensityof(d::Distribution, x) is equivalent to logpdf(d, x) and DensityInterface.densityof(d::Distribution, x) is equivalent to pdf(d, x).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
diff --git a/dev/extends/index.html b/dev/extends/index.html
index fbcfa66cd3..b1e8926edf 100644
--- a/dev/extends/index.html
+++ b/dev/extends/index.html
@@ -1,5 +1,5 @@
-Create New Samplers and Distributions · Distributions.jl
Whereas this package already provides a large collection of common distributions out of the box, there are still occasions where you want to create new distributions (e.g. your application requires a special kind of distribution, or you want to contribute to this package).
Generally, you don't have to implement every API method listed in the documentation. This package provides a series of generic functions that turn a small number of internal methods into user-end API methods. What you need to do is to implement this small set of internal methods for your distributions.
By default, Discrete sampleables have the support of type Int while Continuous sampleables have the support of type Float64. If this assumption does not hold for your new distribution or sampler, or its ValueSupport is neither Discrete nor Continuous, you should implement the eltype method in addition to the other methods listed below.
Note: The methods that need to be implemented are different for distributions of different variate forms.
To implement a univariate sampler, one can define a subtype (say Spl) of Sampleable{Univariate,S} (where S can be Discrete or Continuous), and provide a rand method, as
function rand(rng::AbstractRNG, s::Spl)
+Create New Samplers and Distributions · Distributions.jl
Whereas this package already provides a large collection of common distributions out of the box, there are still occasions where you want to create new distributions (e.g. your application requires a special kind of distribution, or you want to contribute to this package).
Generally, you don't have to implement every API method listed in the documentation. This package provides a series of generic functions that turn a small number of internal methods into user-end API methods. What you need to do is to implement this small set of internal methods for your distributions.
By default, Discrete sampleables have the support of type Int while Continuous sampleables have the support of type Float64. If this assumption does not hold for your new distribution or sampler, or its ValueSupport is neither Discrete nor Continuous, you should implement the eltype method in addition to the other methods listed below.
Note: The methods that need to be implemented are different for distributions of different variate forms.
To implement a univariate sampler, one can define a subtype (say Spl) of Sampleable{Univariate,S} (where S can be Discrete or Continuous), and provide a rand method, as
function rand(rng::AbstractRNG, s::Spl)
# ... generate a single sample from s
end
The package already implements a vectorized version of rand! and rand that repeatedly calls the scalar version to generate multiple samples; as wells as a one arg version that uses the default random number generator.
To implement a multivariate sampler, one can define a subtype of Sampleable{Multivariate,S}, and provide both length and _rand! methods, as
Base.length(s::Spl) = ... # return the length of each sample
@@ -34,5 +34,5 @@
function _rand!(rng::AbstractRNG, s::Spl, x::DenseMatrix{T}) where T<:Real
# ... generate a single matrix sample to x
-end
Note that you can assume x has correct dimensions in _rand! and don't have to perform dimension checking, the generic rand and rand! will do dimension checking and array allocation for you.
sampler(d::Distribution) -> Sampleable
-sampler(s::Sampleable) -> s
Samplers can often rely on pre-computed quantities (that are not parameters themselves) to improve efficiency. If such a sampler exists, it can be provided with this sampler method, which would be used for batch sampling. The general fallback is sampler(d::Distribution) = d.
Note that if there exist faster methods for batch evaluation, one should override _logpdf! and _pdf!.
Furthermore, the generic loglikelihood function repeatedly calls _logpdf. If there is a better way to compute the log-likelihood, one should override loglikelihood.
It is also recommended that one also implements the following statistics functions:
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
+end
Note that you can assume x has correct dimensions in _rand! and don't have to perform dimension checking, the generic rand and rand! will do dimension checking and array allocation for you.
sampler(d::Distribution) -> Sampleable
+sampler(s::Sampleable) -> s
Samplers can often rely on pre-computed quantities (that are not parameters themselves) to improve efficiency. If such a sampler exists, it can be provided with this sampler method, which would be used for batch sampling. The general fallback is sampler(d::Distribution) = d.
Note that if there exist faster methods for batch evaluation, one should override _logpdf! and _pdf!.
Furthermore, the generic loglikelihood function repeatedly calls _logpdf. If there is a better way to compute the log-likelihood, one should override loglikelihood.
It is also recommended that one also implements the following statistics functions:
This package provides methods to fit a distribution to a given set of samples. Generally, one may write
d = fit(D, x)
This statement fits a distribution of type D to a given dataset x, where x should be an array comprised of all samples. The fit function will choose a reasonable way to fit the distribution, which, in most cases, is maximum likelihood estimation.
Note
One can use as the first argument simply the distribution name, like Binomial, or a concrete distribution with a type parameter, like Normal{Float64} or Exponential{Float32}. However, in the latter case the type parameter of the distribution will be ignored:
For most of these distributions, the usage is as described above. For a few special distributions that require additional information for estimation, we have to use a modified interface:
fit_mle(Binomial, n, x) # n is the number of trials in each experiment
+Distribution Fitting · Distributions.jl
This package provides methods to fit a distribution to a given set of samples. Generally, one may write
d = fit(D, x)
This statement fits a distribution of type D to a given dataset x, where x should be an array comprised of all samples. The fit function will choose a reasonable way to fit the distribution, which, in most cases, is maximum likelihood estimation.
Note
One can use as the first argument simply the distribution name, like Binomial, or a concrete distribution with a type parameter, like Normal{Float64} or Exponential{Float32}. However, in the latter case the type parameter of the distribution will be ignored:
For most of these distributions, the usage is as described above. For a few special distributions that require additional information for estimation, we have to use a modified interface:
fit_mle(Binomial, n, x) # n is the number of trials in each experiment
fit_mle(Binomial, n, x, w)
fit_mle(Categorical, k, x) # k is the space size (i.e. the number of distinct values)
@@ -10,4 +10,4 @@
fit_mle(Categorical, x, w)
For many distributions, the estimation can be based on (sum of) sufficient statistics computed from a dataset. To simplify implementation, for such distributions, we implement suffstats method instead of fit_mle directly:
ss = suffstats(D, x) # ss captures the sufficient statistics of x
ss = suffstats(D, x, w) # ss captures the sufficient statistics of a weighted dataset
-d = fit_mle(D, ss) # maximum likelihood estimation based on sufficient stats
When fit_mle on D is invoked, a fallback fit_mle method will first call suffstats to compute the sufficient statistics, and then a fit_mle method on sufficient statistics to get the result. For some distributions, this way is not the most efficient, and we specialize the fit_mle method to implement more efficient estimation algorithms.
Maximum-a-Posteriori (MAP) estimation is also supported by this package, which is implemented as part of the conjugate exponential family framework (see :ref:Conjugate Prior and Posterior <ref-conj>).
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
+d = fit_mle(D, ss) # maximum likelihood estimation based on sufficient stats
When fit_mle on D is invoked, a fallback fit_mle method will first call suffstats to compute the sufficient statistics, and then a fit_mle method on sufficient statistics to get the result. For some distributions, this way is not the most efficient, and we specialize the fit_mle method to implement more efficient estimation algorithms.
Maximum-a-Posteriori (MAP) estimation is also supported by this package, which is implemented as part of the conjugate exponential family framework (see :ref:Conjugate Prior and Posterior <ref-conj>).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
Matrix-variate distributions are the distributions whose variate forms are Matrixvariate (i.e each sample is a matrix). Abstract types for matrix-variate distributions:
Matrix-variate distributions are the distributions whose variate forms are Matrixvariate (i.e each sample is a matrix). Abstract types for matrix-variate distributions:
pdf(d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) where {N}
Evaluate the probability density function of d at x.
This function checks if the size of x is compatible with distribution d. This check can be disabled by using @inbounds.
Implementation
Instead of pdf one should implement _pdf(d, x) which does not have to check the size of x. However, since the default definition of pdf(d, x) falls back to logpdf(d, x) usually it is sufficient to implement logpdf.
pdf(d::Distribution{ArrayLikeVariate{N}}, x::AbstractArray{<:Real,N}) where {N}
Evaluate the probability density function of d at x.
This function checks if the size of x is compatible with distribution d. This check can be disabled by using @inbounds.
Implementation
Instead of pdf one should implement _pdf(d, x) which does not have to check the size of x. However, since the default definition of pdf(d, x) falls back to logpdf(d, x) usually it is sufficient to implement logpdf.
M::AbstractMatrix n x p mean
U::AbstractPDMat n x n row covariance
-V::AbstractPDMat p x p column covariance
The matrix normal distribution generalizes the multivariate normal distribution to $n\times p$ real matrices $\mathbf{X}$. If $\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M}, \mathbf{U}, \mathbf{V})$, then its probability density function is
$\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M},\mathbf{U},\mathbf{V})$ if and only if $\text{vec}(\mathbf{X})\sim \textrm{N}(\text{vec}(\mathbf{M}),\mathbf{V}\otimes\mathbf{U})$.
ν::Real degrees of freedom (whole number or a real number greater than p - 1)
+V::AbstractPDMat p x p column covariance
The matrix normal distribution generalizes the multivariate normal distribution to $n\times p$ real matrices $\mathbf{X}$. If $\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M}, \mathbf{U}, \mathbf{V})$, then its probability density function is
$\mathbf{X}\sim \textrm{MN}_{n,p}(\mathbf{M},\mathbf{U},\mathbf{V})$ if and only if $\text{vec}(\mathbf{X})\sim \textrm{N}(\text{vec}(\mathbf{M}),\mathbf{V}\otimes\mathbf{U})$.
If $\nu\leq p-1$, then $\mathbf{H}$ is rank $\nu$ and it has a density with respect to a suitably chosen volume element on the space of positive semidefinite matrices. See here.
ν::Real degrees of freedom (greater than p - 1)
Ψ::AbstractPDMat p x p scale matrix
The inverse Wishart distribution generalizes the inverse gamma distribution to $p\times p$ real, positive definite matrices $\boldsymbol{\Sigma}$. If $\boldsymbol{\Sigma}\sim \textrm{IW}_p(\nu,\boldsymbol{\Psi})$, then its probability density function is
ν::Real positive degrees of freedom
M::AbstractMatrix n x p location
Σ::AbstractPDMat n x n scale
Ω::AbstractPDMat p x p scale
The matrix t-distribution generalizes the multivariate t-distribution to $n\times p$ real matrices $\mathbf{X}$. If $\mathbf{X}\sim \textrm{MT}_{n,p}(\nu,\mathbf{M},\boldsymbol{\Sigma}, \boldsymbol{\Omega})$, then its probability density function is
p::Int dimension
n1::Real degrees of freedom (greater than p - 1)
n2::Real degrees of freedom (greater than p - 1)
The matrix beta distribution generalizes the beta distribution to $p\times p$ real matrices $\mathbf{U}$ for which $\mathbf{U}$ and $\mathbf{I}_p-\mathbf{U}$ are both positive definite. If $\mathbf{U}\sim \textrm{MB}_p(n_1/2, n_2/2)$, then its probability density function is
If $\mathbf{S}_1\sim \textrm{W}_p(n_1,\mathbf{I}_p)$ and $\mathbf{S}_2\sim \textrm{W}_p(n_2,\mathbf{I}_p)$ are independent, and we use $\mathcal{L}(\cdot)$ to denote the lower Cholesky factor, then
n1::Real degrees of freedom (greater than p - 1)
+|\mathbf{U}|^{(n_1-p-1)/2}\left|\mathbf{I}_p-\mathbf{U}\right|^{(n_2-p-1)/2}.\]
If $\mathbf{S}_1\sim \textrm{W}_p(n_1,\mathbf{I}_p)$ and $\mathbf{S}_2\sim \textrm{W}_p(n_2,\mathbf{I}_p)$ are independent, and we use $\mathcal{L}(\cdot)$ to denote the lower Cholesky factor, then
n1::Real degrees of freedom (greater than p - 1)
n2::Real degrees of freedom (greater than p - 1)
B::AbstractPDMat p x p scale
The matrix F-distribution (sometimes called the matrix beta type II distribution) generalizes the F-Distribution to $p\times p$ real, positive definite matrices $\boldsymbol{\Sigma}$. If $\boldsymbol{\Sigma}\sim \textrm{MF}_{p}(n_1/2,n_2/2,\mathbf{B})$, then its probability density function is
The LKJ distribution is a distribution over $d\times d$ real correlation matrices (positive-definite matrices with ones on the diagonal). If $\mathbf{R}\sim \textrm{LKJ}_{d}(\eta)$, then its probability density function is
A mixture model is a probabilistic distribution that combines a set of components to represent the overall distribution. Generally, the probability density/mass function is given by a convex combination of the pdf/pmf of individual components, as
A mixture model is characterized by a set of component parameters $\Theta=\{\theta_1, \ldots, \theta_K\}$ and a prior distribution $\pi$ over these components.
A mixture model is a probabilistic distribution that combines a set of components to represent the overall distribution. Generally, the probability density/mass function is given by a convex combination of the pdf/pmf of individual components, as
A mixture model is characterized by a set of component parameters $\Theta=\{\theta_1, \ldots, \theta_K\}$ and a prior distribution $\pi$ over these components.
This package introduces a type MixtureModel, defined as follows, to represent a mixture model:
abstract type AbstractMixtureModel{VF<:VariateForm,VS<:ValueSupport} <: Distribution{VF, VS} end
struct MixtureModel{VF<:VariateForm,VS<:ValueSupport,Component<:Distribution} <: AbstractMixtureModel{VF,VS}
components::Vector{Component}
@@ -7,7 +7,7 @@
end
const UnivariateMixture = AbstractMixtureModel{Univariate}
-const MultivariateMixture = AbstractMixtureModel{Multivariate}
Remarks:
We introduce AbstractMixtureModel as a base type, which allows one to define a mixture model with different internal implementations, while still being able to leverage the common methods defined for AbstractMixtureModel.
# constructs a mixture of three normal distributions,
+const MultivariateMixture = AbstractMixtureModel{Multivariate}
Remarks:
We introduce AbstractMixtureModel as a base type, which allows one to define a mixture model with different internal implementations, while still being able to leverage the common methods defined for AbstractMixtureModel.
# constructs a mixture of three normal distributions,
# with prior probabilities [0.2, 0.5, 0.3]
MixtureModel(Normal[
Normal(-2.0, 1.2),
@@ -28,4 +28,4 @@
# The following example shows how one can make a Gaussian mixture
# where all components share the same unit variance
-MixtureModel(map(u -> Normal(u, 1.0), [-2.0, 0.0, 3.0]))
There are several methods for the estimation of mixture models from data, and this problem remains an open research topic. This package does not provide facilities for estimating mixture models. One can resort to other packages, e.g.GaussianMixtures.jl, for this purpose.
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
There are several methods for the estimation of mixture models from data, and this problem remains an open research topic. This package does not provide facilities for estimating mixture models. One can resort to other packages, e.g.GaussianMixtures.jl, for this purpose.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
Multivariate distributions are the distributions whose variate forms are Multivariate (i.e each sample is a vector). Abstract types for multivariate distributions:
Multivariate distributions are the distributions whose variate forms are Multivariate (i.e each sample is a vector). Abstract types for multivariate distributions:
The methods listed below are implemented for each multivariate distribution, which provides a consistent interface to work with multivariate distributions.
The default element type of a sample. This is the type of elements of the samples generated by the rand method. However, one can provide an array of different element types to store the samples using rand!.
If $x$ is a vector, it returns whether x is within the support of $d$. If $x$ is a matrix, it returns whether every column in $x$ is within the support of $d$.
Note: For multivariate distributions, the pdf value is usually very small or large, and therefore direct evaluation of the pdf may cause numerical problems. It is generally advisable to perform probability computation in log scale.
The Multinomial distribution generalizes the binomial distribution. Consider n independent draws from a Categorical distribution over a finite set of size k, and let $X = (X_1, ..., X_k)$ where $X_i$ represents the number of times the element $i$ occurs, then the distribution of $X$ is a multinomial distribution. Each sample of a multinomial distribution is a k-dimensional integer vector that sums to n.
The methods listed below are implemented for each multivariate distribution, which provides a consistent interface to work with multivariate distributions.
The default element type of a sample. This is the type of elements of the samples generated by the rand method. However, one can provide an array of different element types to store the samples using rand!.
If $x$ is a vector, it returns whether x is within the support of $d$. If $x$ is a matrix, it returns whether every column in $x$ is within the support of $d$.
Note: For multivariate distributions, the pdf value is usually very small or large, and therefore direct evaluation of the pdf may cause numerical problems. It is generally advisable to perform probability computation in log scale.
The Multinomial distribution generalizes the binomial distribution. Consider n independent draws from a Categorical distribution over a finite set of size k, and let $X = (X_1, ..., X_k)$ where $X_i$ represents the number of times the element $i$ occurs, then the distribution of $X$ is a multinomial distribution. Each sample of a multinomial distribution is a k-dimensional integer vector that sums to n.
Multinomial(n, p) # Multinomial distribution for n trials with probability vector p
Multinomial(n, k) # Multinomial distribution for n trials with equal probabilities
- # over 1:k
The Multivariate normal distribution is a multidimensional generalization of the normal distribution. The probability density function of a d-dimensional multivariate normal distribution with mean vector $\boldsymbol{\mu}$ and covariance matrix $\boldsymbol{\Sigma}$ is:
The Multivariate normal distribution is a multidimensional generalization of the normal distribution. The probability density function of a d-dimensional multivariate normal distribution with mean vector $\boldsymbol{\mu}$ and covariance matrix $\boldsymbol{\Sigma}$ is:
We realize that the mean vector and the covariance often have special forms in practice, which can be exploited to simplify the computation. For example, the mean vector is sometimes just a zero vector, while the covariance matrix can be a diagonal matrix or even in the form of $\sigma^2 \mathbf{I}$. To take advantage of such special cases, we introduce a parametric type MvNormal, defined as below, which allows users to specify the special structure of the mean and covariance.
The multivariate normal distribution is an exponential family distribution, with two canonical parameters: the potential vector$\mathbf{h}$ and the precision matrix$\mathbf{J}$. The relation between these parameters and the conventional representation (i.e. the one using mean $\boldsymbol{\mu}$ and covariance $\boldsymbol{\Sigma}$) is:
The canonical parameterization is widely used in Bayesian analysis. We provide a type MvNormalCanon, which is also a subtype of AbstractMvNormal to represent a multivariate normal distribution using canonical parameters. Particularly, MvNormalCanon is defined as:
struct MvNormalCanon{T<:Real,P<:AbstractPDMat,V<:AbstractVector} <: AbstractMvNormal
+dot(b, d) # == Normal(dot(b, μ), b' * Σ * b)
The multivariate normal distribution is an exponential family distribution, with two canonical parameters: the potential vector$\mathbf{h}$ and the precision matrix$\mathbf{J}$. The relation between these parameters and the conventional representation (i.e. the one using mean $\boldsymbol{\mu}$ and covariance $\boldsymbol{\Sigma}$) is:
The canonical parameterization is widely used in Bayesian analysis. We provide a type MvNormalCanon, which is also a subtype of AbstractMvNormal to represent a multivariate normal distribution using canonical parameters. Particularly, MvNormalCanon is defined as:
MvLogitNormal(μ, Σ) # MvLogitNormal with y ~ MvNormal(μ, Σ)
MvLogitNormal(MvNormal(μ, Σ)) # same as above
-MvLogitNormal(MvNormalCanon(μ, J)) # MvLogitNormal with y ~ MvNormalCanon(μ, J)
Fields
normal::AbstractMvNormal: contains the $d-1$-dimensional distribution of $y$
If $\boldsymbol X \sim \mathcal{N}(\boldsymbol\mu,\,\boldsymbol\Sigma)$ has a multivariate normal distribution then $\boldsymbol Y=\exp(\boldsymbol X)$ has a multivariate lognormal distribution.
Mean vector $\boldsymbol{\mu}$ and covariance matrix $\boldsymbol{\Sigma}$ of the underlying normal distribution are known as the location and scale parameters of the corresponding lognormal distribution.
The Dirichlet distribution is often used as the conjugate prior for Categorical or Multinomial distributions. The probability density function of a Dirichlet distribution with parameter $\alpha = (\alpha_1, \ldots, \alpha_k)$ is:
\[f(x; \alpha) = \frac{1}{B(\alpha)} \prod_{i=1}^k x_i^{\alpha_i - 1}, \quad \text{ with }
+MvLogitNormal(MvNormalCanon(μ, J)) # MvLogitNormal with y ~ MvNormalCanon(μ, J)
Fields
normal::AbstractMvNormal: contains the $d-1$-dimensional distribution of $y$
If $\boldsymbol X \sim \mathcal{N}(\boldsymbol\mu,\,\boldsymbol\Sigma)$ has a multivariate normal distribution then $\boldsymbol Y=\exp(\boldsymbol X)$ has a multivariate lognormal distribution.
Mean vector $\boldsymbol{\mu}$ and covariance matrix $\boldsymbol{\Sigma}$ of the underlying normal distribution are known as the location and scale parameters of the corresponding lognormal distribution.
The Dirichlet distribution is often used as the conjugate prior for Categorical or Multinomial distributions. The probability density function of a Dirichlet distribution with parameter $\alpha = (\alpha_1, \ldots, \alpha_k)$ is:
# Let alpha be a vector
Dirichlet(alpha) # Dirichlet distribution with parameter vector alpha
# Let a be a positive scalar
-Dirichlet(k, a) # Dirichlet distribution with parameter a * ones(k)
In addition to the methods listed in the common interface above, we also provide the following methods for all multivariate distributions under the base type AbstractMvNormal:
Return the squared Mahalanobis distance from x to the center of d, w.r.t. the covariance. When x is a vector, it returns a scalar value. When x is a matrix, it returns a vector of length size(x,2).
sqmahal!(r, d, x) with write the results to a pre-allocated array r.
It can be necessary to calculate the parameters of the lognormal (location vector and scale matrix) from a given covariance and mean, median or mode. To that end, the following functions are provided.
Calculate the location vector (the mean of the underlying normal distribution).
If s == :meancov, then m is taken as the mean, and S the covariance matrix of a lognormal distribution.
If s == :mean | :median | :mode, then m is taken as the mean, median or mode of the lognormal respectively, and S is interpreted as the scale matrix (the covariance of the underlying normal distribution).
It is not possible to analytically calculate the location vector from e.g., median + covariance, or from mode + covariance.
In addition to the methods listed in the common interface above, we also provide the following methods for all multivariate distributions under the base type AbstractMvNormal:
Return the squared Mahalanobis distance from x to the center of d, w.r.t. the covariance. When x is a vector, it returns a scalar value. When x is a matrix, it returns a vector of length size(x,2).
sqmahal!(r, d, x) with write the results to a pre-allocated array r.
It can be necessary to calculate the parameters of the lognormal (location vector and scale matrix) from a given covariance and mean, median or mode. To that end, the following functions are provided.
Calculate the location vector (the mean of the underlying normal distribution).
If s == :meancov, then m is taken as the mean, and S the covariance matrix of a lognormal distribution.
If s == :mean | :median | :mode, then m is taken as the mean, median or mode of the lognormal respectively, and S is interpreted as the scale matrix (the covariance of the underlying normal distribution).
It is not possible to analytically calculate the location vector from e.g., median + covariance, or from mode + covariance.
The $i$th Order Statistic of a random sample of size $n$ from a univariate distribution is the $i$th element after sorting in increasing order. As a special case, the first and $n$th order statistics are the minimum and maximum of the sample, while for odd $n$, the $\lceil \frac{n}{2} \rceil$th entry is the sample median.
Given any univariate distribution and the sample size $n$, we can construct the distribution of its $i$th order statistic:
Construct the distribution of the rank$=i$th order statistic from n independent samples from dist.
The $i$th order statistic of a sample is the $i$th element of the sorted sample. For example, the 1st order statistic is the sample minimum, while the $n$th order statistic is the sample maximum.
If $f$ is the probability density (mass) function of dist with distribution function $F$, then the probability density function $g$ of the order statistic for continuous dist is
The $i$th Order Statistic of a random sample of size $n$ from a univariate distribution is the $i$th element after sorting in increasing order. As a special case, the first and $n$th order statistics are the minimum and maximum of the sample, while for odd $n$, the $\lceil \frac{n}{2} \rceil$th entry is the sample median.
Given any univariate distribution and the sample size $n$, we can construct the distribution of its $i$th order statistic:
Construct the distribution of the rank$=i$th order statistic from n independent samples from dist.
The $i$th order statistic of a sample is the $i$th element of the sorted sample. For example, the 1st order statistic is the sample minimum, while the $n$th order statistic is the sample maximum.
If $f$ is the probability density (mass) function of dist with distribution function $F$, then the probability density function $g$ of the order statistic for continuous dist is
where $x_-$ is the largest element in the support of dist less than $x$.
For the joint distribution of a subset of order statistics, use JointOrderStatistics instead.
Examples
OrderStatistic(Cauchy(), 10, 1) # distribution of the sample minimum
OrderStatistic(DiscreteUniform(10), 10, 10) # distribution of the sample maximum
-OrderStatistic(Gamma(1, 1), 11, 5) # distribution of the sample median
If we are interested in more than one order statistic, for continuous univariate distributions we can also construct the joint distribution of order statistics:
If we are interested in more than one order statistic, for continuous univariate distributions we can also construct the joint distribution of order statistics:
Construct the joint distribution of order statistics for the specified ranks from an IID sample of size n from dist.
The $i$th order statistic of a sample is the $i$th element of the sorted sample. For example, the 1st order statistic is the sample minimum, while the $n$th order statistic is the sample maximum.
ranks must be a sorted vector or tuple of unique Ints between 1 and n.
For a single order statistic, use OrderStatistic instead.
Examples
JointOrderStatistics(Normal(), 10) # Product(fill(Normal(), 10)) restricted to ordered vectors
JointOrderStatistics(Cauchy(), 10, 2:9) # joint distribution of all but the extrema
-JointOrderStatistics(Cauchy(), 10, (1, 10)) # joint distribution of only the extrema
Product distributions are joint distributions of multiple independent distributions. It is recommended to use product_distribution to construct product distributions. Depending on the type of the argument, it may construct a different distribution type.
A distribution of M + N-dimensional arrays, constructed from an N-dimensional array of independent M-dimensional distributions by stacking them.
Users should use product_distribution to construct a product distribution of independent distributions instead of constructing a ProductDistribution directly.
Product distributions are joint distributions of multiple independent distributions. It is recommended to use product_distribution to construct product distributions. Depending on the type of the argument, it may construct a different distribution type.
A distribution of M + N-dimensional arrays, constructed from an N-dimensional array of independent M-dimensional distributions by stacking them.
Users should use product_distribution to construct a product distribution of independent distributions instead of constructing a ProductDistribution directly.
A distribution of NamedTuples, constructed from a NamedTuple of independent named distributions.
Users should use product_distribution to construct a product distribution of independent distributions instead of constructing a ProductNamedTupleDistribution directly.
Examples
julia> d = product_distribution((x=Normal(), y=Dirichlet([2, 4])))
ProductNamedTupleDistribution{(:x, :y)}(
x: Normal{Float64}(μ=0.0, σ=1.0)
@@ -23,4 +23,4 @@
(x = 0.0, y = [0.3333333333333333, 0.6666666666666666])
julia> var(d) # var of marginals
-(x = 1.0, y = [0.031746031746031744, 0.031746031746031744])
Return a Distribution of reshape(X, dims) where X is a random variable with distribution d.
The default implementation returns a ReshapedDistribution. However, it can return more optimized distributions for specific types of distributions and numbers of dimensions. Therefore it is recommended to use reshape instead of the constructor of ReshapedDistribution.
Implementation
Since reshape(d, dims::Int...) calls reshape(d, dims::Dims), one should implement reshape(d, ::Dims) for desired distributions d.
The default implementation returns a ReshapedDistribution. However, it can return more optimized distributions for specific types of distributions and numbers of dimensions. Therefore it is recommended to use vec instead of the constructor of ReshapedDistribution.
Implementation
Since vec(d) is defined as reshape(d, length(d)) one should implement reshape(d, ::Tuple{Int}) rather than vec.
Return a Distribution of reshape(X, dims) where X is a random variable with distribution d.
The default implementation returns a ReshapedDistribution. However, it can return more optimized distributions for specific types of distributions and numbers of dimensions. Therefore it is recommended to use reshape instead of the constructor of ReshapedDistribution.
Implementation
Since reshape(d, dims::Int...) calls reshape(d, dims::Dims), one should implement reshape(d, ::Dims) for desired distributions d.
The default implementation returns a ReshapedDistribution. However, it can return more optimized distributions for specific types of distributions and numbers of dimensions. Therefore it is recommended to use vec instead of the constructor of ReshapedDistribution.
Implementation
Since vec(d) is defined as reshape(d, length(d)) one should implement reshape(d, ::Tuple{Int}) rather than vec.
The Distributions package is available through the Julia package system by running Pkg.add("Distributions"). Throughout, we assume that you have installed the package.
The Distributions package is available through the Julia package system by running Pkg.add("Distributions"). Throughout, we assume that you have installed the package.
It is often useful to approximate an empirical distribution with a theoretical distribution. As an example, we can use the array x we created above and ask which normal distribution best describes it:
Since x is a random draw from Normal, it's easy to check that the fitted values are sensible. Indeed, the estimates [0.04, 1.12] are close to the true values of [0.0, 1.0] that we used to generate x.
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
Since x is a random draw from Normal, it's easy to check that the fitted values are sensible. Indeed, the estimates [0.04, 1.12] are close to the true values of [0.0, 1.0] that we used to generate x.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
The truncated normal distribution is a particularly important one in the family of truncated distributions. Unlike the general case, truncated normal distributions support mean, mode, modes, var, std, and entropy.
Functions to compute statistics, such as mean, mode, var, std, and entropy, are not available for generic truncated distributions. Generally, there are no easy ways to compute such quantities due to the complications incurred by truncation. However, these methods are supported for truncated normal distributions Truncated{<:Normal} which can be constructed with truncated(::Normal, ...).
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
+truncated(d0, l, u) # d0 truncated to the interval [l, u]
The function falls back to constructing a Truncated wrapper.
Implementation
To implement a specialized truncated form for distributions of type D, one or more of the following methods should be implemented:
truncated(d0::D, l::T, u::T) where {T <: Real}: interval-truncated
The truncated normal distribution is a particularly important one in the family of truncated distributions. Unlike the general case, truncated normal distributions support mean, mode, modes, var, std, and entropy.
Functions to compute statistics, such as mean, mode, var, std, and entropy, are not available for generic truncated distributions. Generally, there are no easy ways to compute such quantities due to the complications incurred by truncation. However, these methods are supported for truncated normal distributions Truncated{<:Normal} which can be constructed with truncated(::Normal, ...).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
The root of this type hierarchy is Sampleable. The abstract type Sampleable subsumes any types of objects from which one can draw samples, which particularly includes samplers and distributions. Formally, Sampleable is defined as
abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end
It has two type parameters that define the kind of samples that can be drawn therefrom.
Multiple samples are often organized into an array, depending on the variate form.
The basic functionalities that a sampleable object provides are to retrieve information about the samples it generates and to draw samples. Particularly, the following functions are provided for sampleable objects:
The default element type of a sample. This is the type of elements of the samples generated by the rand method. However, one can provide an array of different element types to store the samples using rand!.
We use Distribution, a subtype of Sampleable as defined below, to capture probabilistic distributions. In addition to being sampleable, a distribution typically comes with an explicit way to combine its domain, probability density function, and many other quantities.
abstract type Distribution{F<:VariateForm,S<:ValueSupport} <: Sampleable{F,S} end
Distributions.Distribution
To simplify the use in practice, we introduce a series of type alias as follows:
The root of this type hierarchy is Sampleable. The abstract type Sampleable subsumes any types of objects from which one can draw samples, which particularly includes samplers and distributions. Formally, Sampleable is defined as
abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end
It has two type parameters that define the kind of samples that can be drawn therefrom.
Multiple samples are often organized into an array, depending on the variate form.
The basic functionalities that a sampleable object provides are to retrieve information about the samples it generates and to draw samples. Particularly, the following functions are provided for sampleable objects:
The default element type of a sample. This is the type of elements of the samples generated by the rand method. However, one can provide an array of different element types to store the samples using rand!.
We use Distribution, a subtype of Sampleable as defined below, to capture probabilistic distributions. In addition to being sampleable, a distribution typically comes with an explicit way to combine its domain, probability density function, and many other quantities.
abstract type Distribution{F<:VariateForm,S<:ValueSupport} <: Sampleable{F,S} end
Distributions.Distribution
To simplify the use in practice, we introduce a series of type alias as follows:
All methods applicable to Sampleable also apply to Distribution. The API for distributions of different variate forms are different (refer to univariates, multivariates, and matrix for details).
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
All methods applicable to Sampleable also apply to Distribution. The API for distributions of different variate forms are different (refer to univariates, multivariates, and matrix for details).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.
Univariate distributions are the distributions whose variate forms are Univariate (i.e each sample is a scalar). Abstract types for univariate distributions:
Univariate distributions are the distributions whose variate forms are Univariate (i.e each sample is a scalar). Abstract types for univariate distributions:
A series of methods is implemented for each univariate distribution, which provides useful functionalities such as moment computation, pdf evaluation, and sampling (i.e. random number generation).
Note:params are defined for all univariate distributions, while other parameter retrieval methods are only defined for those distributions for which these parameters make sense. See below for details.
Return the median value of distribution d. The median is the smallest x in the support of d for which cdf(d, x) ≥ 1/2. Corresponding to this definition as 1/2-quantile, a fallback is provided calling the quantile function.
The cumulant-generating-function is the logarithm of the moment-generating function: cgf = log ∘ mgf. In practice, however, the right hand side may have overflow issues.
When x is a scalar, it returns whether x is within the support of d (e.g., insupport(d, x) = minimum(d) <= x <= maximum(d)). When x is an array, it returns whether every element in x is within the support of d.
Generic fallback methods are provided, but it is often the case that insupport can be done more efficiently, and a specialized insupport is thus desirable. You should also override this function if the support is composed of multiple disjoint intervals.
A series of methods is implemented for each univariate distribution, which provides useful functionalities such as moment computation, pdf evaluation, and sampling (i.e. random number generation).
Note:params are defined for all univariate distributions, while other parameter retrieval methods are only defined for those distributions for which these parameters make sense. See below for details.
Return the median value of distribution d. The median is the smallest x in the support of d for which cdf(d, x) ≥ 1/2. Corresponding to this definition as 1/2-quantile, a fallback is provided calling the quantile function.
The cumulant-generating-function is the logarithm of the moment-generating function: cgf = log ∘ mgf. In practice, however, the right hand side may have overflow issues.
When x is a scalar, it returns whether x is within the support of d (e.g., insupport(d, x) = minimum(d) <= x <= maximum(d)). When x is an array, it returns whether every element in x is within the support of d.
Generic fallback methods are provided, but it is often the case that insupport can be done more efficiently, and a specialized insupport is thus desirable. You should also override this function if the support is composed of multiple disjoint intervals.
The Arcsine distribution has probability density function
\[f(x) = \frac{1}{\pi \sqrt{(x - a) (b - x)}}, \quad x \in [a, b]\]
Arcsine() # Arcsine distribution with support [0, 1]
Arcsine(b) # Arcsine distribution with support [0, b]
Arcsine(a, b) # Arcsine distribution with support [a, b]
@@ -10,2455 +10,53 @@
minimum(d) # Get the lower bound, i.e. a
maximum(d) # Get the upper bound, i.e. b
location(d) # Get the left bound, i.e. a
-scale(d) # Get the span of the support, i.e. b - a
The Beta distribution is related to the Gamma distribution via the property that if $X \sim \operatorname{Gamma}(\alpha)$ and $Y \sim \operatorname{Gamma}(\beta)$ independently, then $X / (X + Y) \sim \operatorname{Beta}(\alpha, \beta)$.
Beta() # equivalent to Beta(1, 1)
Beta(α) # equivalent to Beta(α, α)
Beta(α, β) # Beta distribution with shape parameters α and β
-params(d) # Get the parameters, i.e. (α, β)
The Beta prime distribution is related to the Beta distribution via the relationship that if $X \sim \operatorname{Beta}(\alpha, \beta)$ then $\frac{X}{1 - X} \sim \operatorname{BetaPrime}(\alpha, \beta)$
BetaPrime() # equivalent to BetaPrime(1, 1)
BetaPrime(α) # equivalent to BetaPrime(α, α)
BetaPrime(α, β) # Beta prime distribution with shape parameters α and β
-params(d) # Get the parameters, i.e. (α, β)
Cauchy() # Standard Cauchy distribution, i.e. Cauchy(0, 1)
Cauchy(μ) # Cauchy distribution with location μ and unit scale, i.e. Cauchy(μ, 1)
Cauchy(μ, σ) # Cauchy distribution with location μ and scale σ
params(d) # Get the parameters, i.e. (μ, σ)
location(d) # Get the location parameter, i.e. μ
-scale(d) # Get the scale parameter, i.e. σ
The distribution arises as the limit distribution of various cube-root-n consistent estimators, including the isotonic regression estimator of Brunk, the isotonic density estimator of Grenander, the least median of squares estimator of Rousseeuw, and the maximum score estimator of Manski.
For theoretical results, see e.g. Kim and Pollard, Annals of Statistics, 1990. The code for the computation of pdf and cdf is based on the algorithm described in Groeneboom and Wellner, Journal of Computational and Graphical Statistics, 2001.
cdf(Chernoff(),-x) # For tail probabilities, use this instead of 1-cdf(Chernoff(),x)
The distribution arises as the limit distribution of various cube-root-n consistent estimators, including the isotonic regression estimator of Brunk, the isotonic density estimator of Grenander, the least median of squares estimator of Rousseeuw, and the maximum score estimator of Manski.
For theoretical results, see e.g. Kim and Pollard, Annals of Statistics, 1990. The code for the computation of pdf and cdf is based on the algorithm described in Groeneboom and Wellner, Journal of Computational and Graphical Statistics, 2001.
cdf(Chernoff(),-x) # For tail probabilities, use this instead of 1-cdf(Chernoff(),x)
The Erlang distribution is a special case of a Gamma distribution with integer shape parameter.
Erlang() # Erlang distribution with unit shape and unit scale, i.e. Erlang(1, 1)
Erlang(a) # Erlang distribution with shape parameter a and unit scale, i.e. Erlang(a, 1)
-Erlang(a, s) # Erlang distribution with shape parameter a and scale s
The Exponential distribution with scale parameter θ has probability density function
\[f(x; \theta) = \frac{1}{\theta} e^{-\frac{x}{\theta}}, \quad x > 0\]
Exponential() # Exponential distribution with unit scale, i.e. Exponential(1)
Exponential(θ) # Exponential distribution with scale θ
params(d) # Get the parameters, i.e. (θ,)
scale(d) # Get the scale parameter, i.e. θ
-rate(d) # Get the rate parameter, i.e. 1 / θ
It is related to the Chisq distribution via the property that if $X_1 \sim \operatorname{Chisq}(\nu_1)$ and $X_2 \sim \operatorname{Chisq}(\nu_2)$, then $(X_1/\nu_1) / (X_2 / \nu_2) \sim \operatorname{FDist}(\nu_1, \nu_2)$.
FDist(ν1, ν2) # F-Distribution with parameters ν1 and ν2
-params(d) # Get the parameters, i.e. (ν1, ν2)
Frechet() # Fréchet distribution with unit shape and unit scale, i.e. Frechet(1, 1)
Frechet(α) # Fréchet distribution with shape α and unit scale, i.e. Frechet(α, 1)
Frechet(α, θ) # Fréchet distribution with shape α and scale θ
params(d) # Get the parameters, i.e. (α, θ)
shape(d) # Get the shape parameter, i.e. α
-scale(d) # Get the scale parameter, i.e. θ
Gamma() # Gamma distribution with unit shape and unit scale, i.e. Gamma(1, 1)
Gamma(α) # Gamma distribution with shape α and unit scale, i.e. Gamma(α, 1)
Gamma(α, θ) # Gamma distribution with shape α and scale θ
params(d) # Get the parameters, i.e. (α, θ)
shape(d) # Get the shape parameter, i.e. α
-scale(d) # Get the scale parameter, i.e. θ
\[x \in \begin{cases}
@@ -2470,175 +68,7 @@
params(d) # Get the parameters, i.e. (μ, σ, ξ)
location(d) # Get the location parameter, i.e. μ
scale(d) # Get the scale parameter, i.e. σ
-shape(d) # Get the shape parameter, i.e. ξ (sometimes called c)
The Gumbel (maxima) distribution with location μ and scale θ has probability density function
\[f(x; \mu, \theta) = \frac{1}{\theta} e^{-(z + e^{-z})},
\quad \text{ with } z = \frac{x - \mu}{\theta}\]
Gumbel() # Gumbel distribution with zero location and unit scale, i.e. Gumbel(0, 1)
Gumbel(μ) # Gumbel distribution with location μ and unit scale, i.e. Gumbel(μ, 1)
Gumbel(μ, θ) # Gumbel distribution with location μ and scale θ
params(d) # Get the parameters, i.e. (μ, θ)
location(d) # Get the location parameter, i.e. μ
-scale(d) # Get the scale parameter, i.e. θ
It is related to the Gamma distribution: if $X \sim \operatorname{Gamma}(\alpha, \beta)$, then $1 / X \sim \operatorname{InverseGamma}(\alpha, \beta^{-1})$.
InverseGamma() # Inverse Gamma distribution with unit shape and unit scale, i.e. InverseGamma(1, 1)
InverseGamma(α) # Inverse Gamma distribution with shape α and unit scale, i.e. InverseGamma(α, 1)
InverseGamma(α, θ) # Inverse Gamma distribution with shape α and scale θ
params(d) # Get the parameters, i.e. (α, θ)
shape(d) # Get the shape parameter, i.e. α
-scale(d) # Get the scale parameter, i.e. θ
InverseGaussian() # Inverse Gaussian distribution with unit mean and unit shape, i.e. InverseGaussian(1, 1)
InverseGaussian(μ), # Inverse Gaussian distribution with mean μ and unit shape, i.e. InverseGaussian(μ, 1)
InverseGaussian(μ, λ) # Inverse Gaussian distribution with mean μ and shape λ
params(d) # Get the parameters, i.e. (μ, λ)
mean(d) # Get the mean parameter, i.e. μ
-shape(d) # Get the shape parameter, i.e. λ
where $Z \sim \mathcal{N}(0,1)$, then $X \sim \operatorname{Johnson}(\xi, \lambda, \gamma, \delta)$.
JohnsonSU() # Equivalent to JohnsonSU(0, 1, 0, 1)
JohnsonSU(ξ, λ, γ, δ) # JohnsonSU's S_U-distribution with parameters ξ, λ, γ and δ
params(d) # Get the parameters, i.e. (ξ, λ, γ, δ)
shape(d) # Get the shape parameter, i.e. ξ
-scale(d) # Get the scale parameter, i.e. λ
The Kumaraswamy distribution with shape parameters a > 0 and b > 0 has probability density function
\[f(x; a, b) = a b x^{a - 1} (1 - x^a)^{b - 1}, \quad 0 < x < 1\]
It is related to the Beta distribution by the following identity: if $X \sim \operatorname{Kumaraswamy}(a, b)$ then $X^a \sim \operatorname{Beta}(1, b)$. In particular, if $X \sim \operatorname{Kumaraswamy}(1, 1)$ then $X \sim \operatorname{Uniform}(0, 1)$.
The Kumaraswamy distribution with shape parameters a > 0 and b > 0 has probability density function
\[f(x; a, b) = a b x^{a - 1} (1 - x^a)^{b - 1}, \quad 0 < x < 1\]
It is related to the Beta distribution by the following identity: if $X \sim \operatorname{Kumaraswamy}(a, b)$ then $X^a \sim \operatorname{Beta}(1, b)$. In particular, if $X \sim \operatorname{Kumaraswamy}(1, 1)$ then $X \sim \operatorname{Uniform}(0, 1)$.
Laplace() # Laplace distribution with zero location and unit scale, i.e. Laplace(0, 1)
Laplace(μ) # Laplace distribution with location μ and unit scale, i.e. Laplace(μ, 1)
Laplace(μ, θ) # Laplace distribution with location μ and scale θ
params(d) # Get the parameters, i.e., (μ, θ)
location(d) # Get the location parameter, i.e. μ
-scale(d) # Get the scale parameter, i.e. θ
Levy() # Levy distribution with zero location and unit scale, i.e. Levy(0, 1)
Levy(μ) # Levy distribution with location μ and unit scale, i.e. Levy(μ, 1)
Levy(μ, σ) # Levy distribution with location μ and scale σ
params(d) # Get the parameters, i.e. (μ, σ)
-location(d) # Get the location parameter, i.e. μ
It was first described by Lindley[1] and was studied in greater detail by Ghitany et al.[2] Note that Lindley(θ) is a mixture of an Exponential(θ) and a Gamma(2, θ) with respective mixing weights p = θ/(1 + θ) and 1 - p.
It was first described by Lindley[1] and was studied in greater detail by Ghitany et al.[2] Note that Lindley(θ) is a mixture of an Exponential(θ) and a Gamma(2, θ) with respective mixing weights p = θ/(1 + θ) and 1 - p.
Logistic() # Logistic distribution with zero location and unit scale, i.e. Logistic(0, 1)
Logistic(μ) # Logistic distribution with location μ and unit scale, i.e. Logistic(μ, 1)
Logistic(μ, θ) # Logistic distribution with location μ and scale θ
params(d) # Get the parameters, i.e. (μ, θ)
location(d) # Get the location parameter, i.e. μ
-scale(d) # Get the scale parameter, i.e. θ
The logit normal distribution is the distribution of of a random variable whose logit has a Normal distribution. Or inversely, when applying the logistic function to a Normal random variable then the resulting random variable follows a logit normal distribution.
If $X \sim \operatorname{Normal}(\mu, \sigma)$ then $\operatorname{logistic}(X) \sim \operatorname{LogitNormal}(\mu,\sigma)$.
The probability density function is
\[f(x; \mu, \sigma) = \frac{1}{x \sqrt{2 \pi \sigma^2}}
+scale(d) # Get the scale parameter, i.e. θ
The logit normal distribution is the distribution of of a random variable whose logit has a Normal distribution. Or inversely, when applying the logistic function to a Normal random variable then the resulting random variable follows a logit normal distribution.
If $X \sim \operatorname{Normal}(\mu, \sigma)$ then $\operatorname{logistic}(X) \sim \operatorname{LogitNormal}(\mu,\sigma)$.
\[\text{logit}(x) = \ln\left(\frac{x}{1-x}\right)
\quad 0 < x < 1\]
LogitNormal() # Logit-normal distribution with zero logit-mean and unit scale
@@ -4495,151 +139,7 @@
median(d) # Get the median, i.e. logistic(μ)
The following properties have no analytical solution but numerical approximations. In order to avoid package dependencies for numerical optimization, they are currently not implemented.
mean(d)
var(d)
std(d)
-mode(d)
Similarly, skewness, kurtosis, and entropy are not implemented.
The log normal distribution is the distribution of the exponential of a Normal variate: if $X \sim \operatorname{Normal}(\mu, \sigma)$ then $\exp(X) \sim \operatorname{LogNormal}(\mu,\sigma)$. The probability density function is
The log normal distribution is the distribution of the exponential of a Normal variate: if $X \sim \operatorname{Normal}(\mu, \sigma)$ then $\exp(X) \sim \operatorname{LogNormal}(\mu,\sigma)$. The probability density function is
LogNormal() # Log-normal distribution with zero log-mean and unit scale
LogNormal(μ) # Log-normal distribution with log-mean mu and unit scale
@@ -4648,2409 +148,39 @@
params(d) # Get the parameters, i.e. (μ, σ)
meanlogx(d) # Get the mean of log(X), i.e. μ
varlogx(d) # Get the variance of log(X), i.e. σ^2
-stdlogx(d) # Get the standard deviation of log(X), i.e. σ
A positive random variable X is log-uniformly with parameters a and b if the logarithm of X is Uniform(log(a), log(b)). The log uniform distribution is also known as reciprocal distribution.
It is the distribution of the sum of squares of ν independent Normal variates with individual means $\mu_i$ and
\[\lambda = \sum_{i=1}^\nu \mu_i^2\]
NoncentralChisq(ν, λ) # Noncentral chi-squared distribution with ν degrees of freedom and noncentrality parameter λ
+stdlogx(d) # Get the standard deviation of log(X), i.e. σ
A positive random variable X is log-uniformly with parameters a and b if the logarithm of X is Uniform(log(a), log(b)). The log uniform distribution is also known as reciprocal distribution.
It is the distribution of the sum of squares of ν independent Normal variates with individual means $\mu_i$ and
\[\lambda = \sum_{i=1}^\nu \mu_i^2\]
NoncentralChisq(ν, λ) # Noncentral chi-squared distribution with ν degrees of freedom and noncentrality parameter λ
-params(d) # Get the parameters, i.e. (ν, λ)
Note that if σ == 0, then the distribution is a point mass concentrated at μ. Though not technically a continuous distribution, it is allowed so as to account for cases where σ may have underflowed, and the functions are defined by taking the pointwise limit as $σ → 0$.
Normal() # standard Normal distribution with zero mean and unit variance
Normal(μ) # Normal distribution with mean μ and unit variance
Normal(μ, σ) # Normal distribution with mean μ and variance σ^2
params(d) # Get the parameters, i.e. (μ, σ)
mean(d) # Get the mean, i.e. μ
-std(d) # Get the standard deviation, i.e. σ
Canonical parametrisation of the Normal distribution with canonical parameters η and λ.
The two canonical parameters of a normal distribution $\mathcal{N}(\mu, \sigma^2)$ with mean $\mu$ and standard deviation $\sigma$ are $\eta = \sigma^{-2} \mu$ and $\lambda = \sigma^{-2}$.
Canonical parametrisation of the Normal distribution with canonical parameters η and λ.
The two canonical parameters of a normal distribution $\mathcal{N}(\mu, \sigma^2)$ with mean $\mu$ and standard deviation $\sigma$ are $\eta = \sigma^{-2} \mu$ and $\lambda = \sigma^{-2}$.
Pareto() # Pareto distribution with unit shape and unit scale, i.e. Pareto(1, 1)
Pareto(α) # Pareto distribution with shape α and unit scale, i.e. Pareto(α, 1)
Pareto(α, θ) # Pareto distribution with shape α and scale θ
params(d) # Get the parameters, i.e. (α, θ)
shape(d) # Get the shape parameter, i.e. α
-scale(d) # Get the scale parameter, i.e. θ
The p-Generalized Gaussian distribution, more commonly known as the exponential power or the generalized normal distribution, with scale α, location μ, and shape p has the probability density function
\[f(x, \mu, \alpha, p) = \frac{p}{2\alpha\Gamma(1/p)} e^{-(\frac{|x-\mu|}{\alpha})^p} \quad x \in (-\infty, +\infty) , \alpha > 0, p > 0\]
The p-Generalized Gaussian (GGD) is a parametric distribution that incorporates the normal (p = 2) and Laplacian (p = 1) distributions as special cases. As p → ∞, the distribution approaches the Uniform distribution on [μ - α, μ + α].
PGeneralizedGaussian() # GGD with location 0, scale √2, and shape 2 (the normal distribution)
+scale(d) # Get the scale parameter, i.e. θ
The p-Generalized Gaussian distribution, more commonly known as the exponential power or the generalized normal distribution, with scale α, location μ, and shape p has the probability density function
\[f(x, \mu, \alpha, p) = \frac{p}{2\alpha\Gamma(1/p)} e^{-(\frac{|x-\mu|}{\alpha})^p} \quad x \in (-\infty, +\infty) , \alpha > 0, p > 0\]
The p-Generalized Gaussian (GGD) is a parametric distribution that incorporates the normal (p = 2) and Laplacian (p = 1) distributions as special cases. As p → ∞, the distribution approaches the Uniform distribution on [μ - α, μ + α].
PGeneralizedGaussian() # GGD with location 0, scale √2, and shape 2 (the normal distribution)
PGeneralizedGaussian(μ, α, p) # GGD with location μ, scale α, and shape p
params(d) # Get the parameters, i.e. (μ, α, p)
location(d) # Get the location parameter, μ
scale(d) # Get the scale parameter, α
-shape(d) # Get the shape parameter, p
The Rayleigh distribution with scale σ has probability density function
\[f(x; \sigma) = \frac{x}{\sigma^2} e^{-\frac{x^2}{2 \sigma^2}}, \quad x > 0\]
It is related to the Normal distribution via the property that if $X, Y \sim \operatorname{Normal}(0,\sigma)$, independently, then $\sqrt{X^2 + Y^2} \sim \operatorname{Rayleigh}(\sigma)$.
Rayleigh() # Rayleigh distribution with unit scale, i.e. Rayleigh(1)
+shape(d) # Get the shape parameter, p
The Rayleigh distribution with scale σ has probability density function
\[f(x; \sigma) = \frac{x}{\sigma^2} e^{-\frac{x^2}{2 \sigma^2}}, \quad x > 0\]
It is related to the Normal distribution via the property that if $X, Y \sim \operatorname{Normal}(0,\sigma)$, independently, then $\sqrt{X^2 + Y^2} \sim \operatorname{Rayleigh}(\sigma)$.
Rayleigh() # Rayleigh distribution with unit scale, i.e. Rayleigh(1)
Rayleigh(σ) # Rayleigh distribution with scale σ
params(d) # Get the parameters, i.e. (σ,)
-scale(d) # Get the scale parameter, i.e. σ
Rician() # Rician distribution with parameters ν=0 and σ=1
Rician(ν, σ) # Rician distribution with parameters ν and σ
params(d) # Get the parameters, i.e. (ν, σ)
shape(d) # Get the shape parameter K = ν²/2σ²
-scale(d) # Get the scale parameter Ω = ν² + 2σ²
The skew normal distribution is a continuous probability distribution that generalises the normal distribution to allow for non-zero skewness. Given a location ξ, scale ω, and shape α, it has the probability density function
\[f(x; \xi, \omega, \alpha) =
+scale(d) # Get the scale parameter, i.e. σ
The skew normal distribution is a continuous probability distribution that generalises the normal distribution to allow for non-zero skewness. Given a location ξ, scale ω, and shape α, it has the probability density function
SymTriangularDist() # Symmetric triangular distribution with zero location and unit scale
SymTriangularDist(μ) # Symmetric triangular distribution with location μ and unit scale
SymTriangularDist(μ, s) # Symmetric triangular distribution with location μ and scale σ
params(d) # Get the parameters, i.e. (μ, σ)
location(d) # Get the location parameter, i.e. μ
-scale(d) # Get the scale parameter, i.e. σ
The triangular distribution with lower limit a, upper limit b and mode c has probability density function
\[f(x; a, b, c)= \begin{cases}
0 & \mathrm{for\ } x < a, \\
\frac{2(x-a)}{(b-a)(c-a)} & \mathrm{for\ } a \le x \leq c, \\[4pt]
\frac{2(b-x)}{(b-a)(b-c)} & \mathrm{for\ } c < x \le b, \\[4pt]
@@ -7793,802 +222,23 @@
params(d) # Get the parameters, i.e. (a, b, c)
minimum(d) # Get the lower bound, i.e. a
maximum(d) # Get the upper bound, i.e. b
-mode(d) # Get the mode, i.e. c
The continuous uniform distribution over an interval $[a, b]$ has probability density function
\[f(x; a, b) = \frac{1}{b - a}, \quad a \le x \le b\]
Uniform() # Uniform distribution over [0, 1]
Uniform(a, b) # Uniform distribution over [a, b]
params(d) # Get the parameters, i.e. (a, b)
minimum(d) # Get the lower bound, i.e. a
maximum(d) # Get the upper bound, i.e. b
location(d) # Get the location parameter, i.e. a
-scale(d) # Get the scale parameter, i.e. b - a
VonMises() # von Mises distribution with zero mean and unit concentration
VonMises(κ) # von Mises distribution with zero mean and concentration κ
-VonMises(μ, κ) # von Mises distribution with mean μ and concentration κ
The Weibull distribution with shape α and scale θ has probability density function
\[f(x; \alpha, \theta) = \frac{\alpha}{\theta} \left( \frac{x}{\theta} \right)^{\alpha-1} e^{-(x/\theta)^\alpha},
+VonMises(μ, κ) # von Mises distribution with mean μ and concentration κ
Weibull() # Weibull distribution with unit shape and unit scale, i.e. Weibull(1, 1)
Weibull(α) # Weibull distribution with shape α and unit scale, i.e. Weibull(α, 1)
Weibull(α, θ) # Weibull distribution with shape α and scale θ
params(d) # Get the parameters, i.e. (α, θ)
shape(d) # Get the shape parameter, i.e. α
-scale(d) # Get the scale parameter, i.e. θ
A Bernoulli distribution is parameterized by a success rate p, which takes value 1 with probability p and 0 with probability 1-p.
\[P(X = k) = \begin{cases}
1 - p & \quad \text{for } k = 0, \\
p & \quad \text{for } k = 1.
\end{cases}\]
Bernoulli() # Bernoulli distribution with p = 0.5
@@ -8596,60 +246,60 @@
params(d) # Get the parameters, i.e. (p,)
succprob(d) # Get the success rate, i.e. p
-failprob(d) # Get the failure rate, i.e. 1 - p
A Beta-binomial distribution is the compound distribution of the Binomial distribution where the probability of success p is distributed according to the Beta. It has three parameters: n, the number of trials and two shape parameters α, β
\[P(X = k) = {n \choose k} B(k + \alpha, n - k + \beta) / B(\alpha, \beta), \quad \text{ for } k = 0,1,2, \ldots, n.\]
BetaBinomial(n, α, β) # BetaBinomial distribution with n trials and shape parameters α, β
+\end{cases}\]
A Beta-binomial distribution is the compound distribution of the Binomial distribution where the probability of success p is distributed according to the Beta. It has three parameters: n, the number of trials and two shape parameters α, β
\[P(X = k) = {n \choose k} B(k + \alpha, n - k + \beta) / B(\alpha, \beta), \quad \text{ for } k = 0,1,2, \ldots, n.\]
BetaBinomial(n, α, β) # BetaBinomial distribution with n trials and shape parameters α, β
params(d) # Get the parameters, i.e. (n, α, β)
-ntrials(d) # Get the number of trials, i.e. n
A Binomial distribution characterizes the number of successes in a sequence of independent trials. It has two parameters: n, the number of trials, and p, the probability of success in an individual trial, with the distribution:
\[P(X = k) = {n \choose k}p^k(1-p)^{n-k}, \quad \text{ for } k = 0,1,2, \ldots, n.\]
Binomial() # Binomial distribution with n = 1 and p = 0.5
+ntrials(d) # Get the number of trials, i.e. n
A Binomial distribution characterizes the number of successes in a sequence of independent trials. It has two parameters: n, the number of trials, and p, the probability of success in an individual trial, with the distribution:
\[P(X = k) = {n \choose k}p^k(1-p)^{n-k}, \quad \text{ for } k = 0,1,2, \ldots, n.\]
Binomial() # Binomial distribution with n = 1 and p = 0.5
Binomial(n) # Binomial distribution for n trials with success rate p = 0.5
Binomial(n, p) # Binomial distribution for n trials with success rate p
params(d) # Get the parameters, i.e. (n, p)
ntrials(d) # Get the number of trials, i.e. n
succprob(d) # Get the success rate, i.e. p
-failprob(d) # Get the failure rate, i.e. 1 - p
Categorical(p) # Categorical distribution with probability vector p
params(d) # Get the parameters, i.e. (p,)
probs(d) # Get the probability vector, i.e. p
-ncategories(d) # Get the number of categories, i.e. K
Here, p must be a real vector, of which all components are nonnegative and sum to one.
Note: The input vector p is directly used as a field of the constructed distribution, without being copied.
Categorical is simply a type alias describing a special case of a DiscreteNonParametric distribution, so non-specialized methods defined for DiscreteNonParametric apply to Categorical as well.
A Dirac distribution is parameterized by its only value x, and takes its value with probability 1.
\[P(X = \hat{x}) = \begin{cases}
+ncategories(d) # Get the number of categories, i.e. K
Here, p must be a real vector, of which all components are nonnegative and sum to one.
Note: The input vector p is directly used as a field of the constructed distribution, without being copied.
Categorical is simply a type alias describing a special case of a DiscreteNonParametric distribution, so non-specialized methods defined for DiscreteNonParametric apply to Categorical as well.
A Discrete uniform distribution is a uniform distribution over a consecutive sequence of integers between a and b, inclusive.
\[P(X = k) = 1 / (b - a + 1) \quad \text{for } k = a, a+1, \ldots, b.\]
DiscreteUniform(a, b) # a uniform distribution over {a, a+1, ..., b}
params(d) # Get the parameters, i.e. (a, b)
span(d) # Get the span of the support, i.e. (b - a + 1)
probval(d) # Get the probability value, i.e. 1 / (b - a + 1)
minimum(d) # Return a
-maximum(d) # Return b
A Discrete nonparametric distribution explicitly defines an arbitrary probability mass function in terms of a list of real support values and their corresponding probabilities
d = DiscreteNonParametric(xs, ps)
+maximum(d) # Return b
A Discrete nonparametric distribution explicitly defines an arbitrary probability mass function in terms of a list of real support values and their corresponding probabilities
d = DiscreteNonParametric(xs, ps)
params(d) # Get the parameters, i.e. (xs, ps)
support(d) # Get a sorted AbstractVector describing the support (xs) of the distribution
-probs(d) # Get a Vector of the probabilities (ps) associated with the support
A Geometric distribution characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate p.
\[P(X = k) = p (1 - p)^k, \quad \text{for } k = 0, 1, 2, \ldots.\]
Geometric() # Geometric distribution with success rate 0.5
+probs(d) # Get a Vector of the probabilities (ps) associated with the support
A Geometric distribution characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate p.
\[P(X = k) = p (1 - p)^k, \quad \text{for } k = 0, 1, 2, \ldots.\]
Geometric() # Geometric distribution with success rate 0.5
Geometric(p) # Geometric distribution with success rate p
params(d) # Get the parameters, i.e. (p,)
succprob(d) # Get the success rate, i.e. p
-failprob(d) # Get the failure rate, i.e. 1 - p
A Hypergeometric distribution describes the number of successes in n draws without replacement from a finite population containing s successes and f failures.
A Hypergeometric distribution describes the number of successes in n draws without replacement from a finite population containing s successes and f failures.
Hypergeometric(s, f, n) # Hypergeometric distribution for a population with
# s successes and f failures, and a sequence of n trials.
-params(d) # Get the parameters, i.e. (s, f, n)
A Negative binomial distribution describes the number of failures before the rth success in a sequence of independent Bernoulli trials. It is parameterized by r, the number of successes, and p, the probability of success in an individual trial.
A Negative binomial distribution describes the number of failures before the rth success in a sequence of independent Bernoulli trials. It is parameterized by r, the number of successes, and p, the probability of success in an individual trial.
NegativeBinomial() # Negative binomial distribution with r = 1 and p = 0.5
NegativeBinomial(r, p) # Negative binomial distribution with r successes and success rate p
params(d) # Get the parameters, i.e. (r, p)
succprob(d) # Get the success rate, i.e. p
-failprob(d) # Get the failure rate, i.e. 1 - p
A Poisson distribution describes the number of independent events occurring within a unit time interval, given the average rate of occurrence λ.
\[P(X = k) = \frac{\lambda^k}{k!} e^{-\lambda}, \quad \text{ for } k = 0,1,2,\ldots.\]
Poisson() # Poisson distribution with rate parameter 1
Poisson(lambda) # Poisson distribution with rate parameter lambda
params(d) # Get the parameters, i.e. (λ,)
-mean(d) # Get the mean arrival rate, i.e. λ
A Poisson-binomial distribution describes the number of successes in a sequence of independent trials, wherein each trial has a different success rate. It is parameterized by a vector p (of length $K$), where $K$ is the total number of trials and p[i] corresponds to the probability of success of the ith trial.
\[P(X = k) = \sum\limits_{A\in F_k} \prod\limits_{i\in A} p[i] \prod\limits_{j\in A^c} (1-p[j]), \quad \text{ for } k = 0,1,2,\ldots,K,\]
where $F_k$ is the set of all subsets of $k$ integers that can be selected from $\{1,2,3,...,K\}$.
PoissonBinomial(p) # Poisson Binomial distribution with success rate vector p
+mean(d) # Get the mean arrival rate, i.e. λ
A Poisson-binomial distribution describes the number of successes in a sequence of independent trials, wherein each trial has a different success rate. It is parameterized by a vector p (of length $K$), where $K$ is the total number of trials and p[i] corresponds to the probability of success of the ith trial.
\[P(X = k) = \sum\limits_{A\in F_k} \prod\limits_{i\in A} p[i] \prod\limits_{j\in A^c} (1-p[j]), \quad \text{ for } k = 0,1,2,\ldots,K,\]
where $F_k$ is the set of all subsets of $k$ integers that can be selected from $\{1,2,3,...,K\}$.
PoissonBinomial(p) # Poisson Binomial distribution with success rate vector p
params(d) # Get the parameters, i.e. (p,)
succprob(d) # Get the vector of success rates, i.e. p
-failprob(d) # Get the vector of failure rates, i.e. 1-p
where $I_k$ is the modified Bessel function of the first kind.
Skellam(μ1, μ2) # Skellam distribution for the difference between two Poisson variables,
# respectively with expected values μ1 and μ2.
-params(d) # Get the parameters, i.e. (μ1, μ2)
The Robust Soliton distribution of length K, mode M (i.e., the location of the robust component spike), peeling process failure probability δ, and minimum non-zero probability mass atol. More specifically, degrees i for which pdf(Ω, i)<atol are set to 0. Letting atol=0 yields the regular robust Soliton distribution.
Soliton(K, M, δ) # Robust Soliton distribution (with atol=0)
+params(d) # Get the parameters, i.e. (μ1, μ2)
The Robust Soliton distribution of length K, mode M (i.e., the location of the robust component spike), peeling process failure probability δ, and minimum non-zero probability mass atol. More specifically, degrees i for which pdf(Ω, i)<atol are set to 0. Letting atol=0 yields the regular robust Soliton distribution.
Soliton(K, M, δ) # Robust Soliton distribution (with atol=0)
Soliton(K, M, δ, atol) # Robust Soliton distribution with minimum non-zero probability mass atol
params(Ω) # Get the parameters ,i.e., (K, M, δ, atol)
@@ -8657,4 +307,4 @@
pdf(Ω, i) # Evaluate the pdf at i
cdf(Ω, i) # Evaluate the pdf at i
rand(Ω) # Sample from Ω
-rand(Ω, n) # Draw n samples from Ω
1Lindley, D. V. (1958). Fiducial Distributions and Bayes' Theorem. Journal of the Royal Statistical Society: Series B (Methodological), 20(1), 102–107.
2Ghitany, M. E., Atieh, B., & Nadarajah, S. (2008). Lindley distribution and its application. Mathematics and Computers in Simulation, 78(4), 493–506.
Settings
This document was generated with Documenter.jl version 0.27.25 on Friday 17 January 2025. Using Julia version 1.11.2.
1Lindley, D. V. (1958). Fiducial Distributions and Bayes' Theorem. Journal of the Royal Statistical Society: Series B (Methodological), 20(1), 102–107.
2Ghitany, M. E., Atieh, B., & Nadarajah, S. (2008). Lindley distribution and its application. Mathematics and Computers in Simulation, 78(4), 493–506.
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 17 January 2025. Using Julia version 1.11.2.