From 50ad279fa6ddc14c603b48773bd92566ce308ecf Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Fri, 16 Feb 2024 09:48:26 +0000 Subject: [PATCH] build based on 84440f8 --- dev/.documenter-siteinfo.json | 2 +- dev/adding/index.html | 2 +- dev/affine/index.html | 2 +- dev/api_index/index.html | 2 +- dev/api_measurebase/index.html | 28 ++++++++++++++-------------- dev/api_measuretheory/index.html | 2 +- dev/index.html | 2 +- dev/old_readme/index.html | 2 +- 8 files changed, 21 insertions(+), 21 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index adc0f86e..f27c8762 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-16T09:48:20","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-16T09:48:22","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/adding/index.html b/dev/adding/index.html index 6346acbb..e06f009b 100644 --- a/dev/adding/index.html +++ b/dev/adding/index.html @@ -21,4 +21,4 @@ gentype(::Lebesgue{ℝ₊}) = Float64 gentype(::Lebesgue{𝕀}) = Float64 -logdensity_def(::Lebesgue, x) = zero(float(x))

We haven't yet talked about gentype. When you call rand without specifying a type, there needs to be a default. That default is the gentype. This only needs to be defined for primitive measures, because others will fall back on 

gentype(μ::AbstractMeasure) = gentype(basemeasure(μ))
+logdensity_def(::Lebesgue, x) = zero(float(x))

We haven't yet talked about gentype. When you call rand without specifying a type, there needs to be a default. That default is the gentype. This only needs to be defined for primitive measures, because others will fall back on 

gentype(μ::AbstractMeasure) = gentype(basemeasure(μ))
diff --git a/dev/affine/index.html b/dev/affine/index.html index 6b5a18a0..95772210 100644 --- a/dev/affine/index.html +++ b/dev/affine/index.html @@ -13,4 +13,4 @@ 4.0

AffinePushfwd

Of particular interest (the whole point of all of this, really) is to have a natural way to work with affine transformations of measures. In accordance with the principle of "common things should have shorter names", we call this AffinePushfwd.

The structure of AffinePushfwd is relatively simple:

struct AffinePushfwd{N,M,T} <: AbstractMeasure
     f::AffineTransform{N,T}
     parent::M
-end
+end diff --git a/dev/api_index/index.html b/dev/api_index/index.html index 29dea17e..fc287208 100644 --- a/dev/api_index/index.html +++ b/dev/api_index/index.html @@ -1,2 +1,2 @@ -Index · MeasureTheory.jl

Index

+Index · MeasureTheory.jl

Index

diff --git a/dev/api_measurebase/index.html b/dev/api_measurebase/index.html index 404b17f4..9835f37f 100644 --- a/dev/api_measurebase/index.html +++ b/dev/api_measurebase/index.html @@ -1,11 +1,11 @@ -MeasureBase · MeasureTheory.jl

MeasureBase API

MeasureBase.AbstractMeasure — Method
(m::AbstractMeasure)(s)

Convenience method for massof(m, s). To make a user-defined measure callable in this way, users should add the corresponding massof method.

source
MeasureBase.Density — Type
struct Density{M,B} <: AbstractDensity
+MeasureBase · MeasureTheory.jl
MeasureBase API
MeasureBase.AbstractMeasure — Method
(m::AbstractMeasure)(s)
Convenience method for massof(m, s). To make a user-defined measure callable in this way, users should add the corresponding massof method.
source
MeasureBase.Density — Type
struct Density{M,B} <: AbstractDensity
     μ::M
     base::B
-end
For measures μ and ν, Density(μ,ν) represents the density function dμ/dν, also called the Radom-Nikodym derivative: https://en.wikipedia.org/wiki/Radon%E2%80%93Nikodymtheorem#Radon%E2%80%93Nikodymderivative
Instead of calling this directly, users should call density_rel(μ, ν) or its abbreviated form, 𝒹(μ,ν).
source
MeasureBase.DensityMeasure — Type
struct DensityMeasure{F,B} <: AbstractDensityMeasure
+end
For measures μ and ν, Density(μ,ν) represents the density function dμ/dν, also called the Radom-Nikodym derivative: https://en.wikipedia.org/wiki/Radon%E2%80%93Nikodymtheorem#Radon%E2%80%93Nikodymderivative
Instead of calling this directly, users should call density_rel(μ, ν) or its abbreviated form, 𝒹(μ,ν).
source
MeasureBase.DensityMeasure — Type
struct DensityMeasure{F,B} <: AbstractDensityMeasure
     density :: F
     base    :: B
-end
A DensityMeasure is a measure defined by a density or log-density with respect to some other "base" measure.
Users should not call DensityMeasure directly, but should instead call ∫(f, base) (if f is a density function or DensityInterface.IsDensity object) or ∫exp(f, base) (if f is a log-density function).
source
MeasureBase.Likelihood — Type
Likelihood(k::AbstractTransitionKernel, x)
"Observe" a value x, yielding a function from the parameters to ℝ.
Likelihoods are most commonly used in conjunction with an existing prior measure to yield a new measure, the posterior. In Bayes's Law, we have
$P(θ|x) ∝ P(θ) P(x|θ)$
Here $P(θ)$ is the prior. If we consider $P(x|θ)$ as a function on $θ$, then it is called a likelihood.
Since measures are most commonly manipulated using density and logdensity, it's awkward to commit a (log-)likelihood to using one or the other. To evaluate a Likelihood, we therefore use density or logdensity, depending on the circumstances. In the latter case, it is of course acting as a log-density.
For example,
julia> ℓ = Likelihood(Normal{(:μ,)}, 2.0)
+end
A DensityMeasure is a measure defined by a density or log-density with respect to some other "base" measure.
Users should not call DensityMeasure directly, but should instead call ∫(f, base) (if f is a density function or DensityInterface.IsDensity object) or ∫exp(f, base) (if f is a log-density function).
source
MeasureBase.Likelihood — Type
Likelihood(k::AbstractTransitionKernel, x)
"Observe" a value x, yielding a function from the parameters to ℝ.
Likelihoods are most commonly used in conjunction with an existing prior measure to yield a new measure, the posterior. In Bayes's Law, we have
$P(θ|x) ∝ P(θ) P(x|θ)$
Here $P(θ)$ is the prior. If we consider $P(x|θ)$ as a function on $θ$, then it is called a likelihood.
Since measures are most commonly manipulated using density and logdensity, it's awkward to commit a (log-)likelihood to using one or the other. To evaluate a Likelihood, we therefore use density or logdensity, depending on the circumstances. In the latter case, it is of course acting as a log-density.
For example,
julia> ℓ = Likelihood(Normal{(:μ,)}, 2.0)
 Likelihood(Normal{(:μ,), T} where T, 2.0)
 
 julia> density_def(ℓ, (μ=2.0,))
@@ -43,14 +43,14 @@
 Normal() ⊙ Likelihood(Normal{(:μ, :σ), T} where T, (σ = 1,), 3)
 
 julia> logdensity_def(post, 2)
--2.5
source
MeasureBase.LogDensity — Type
struct LogDensity{M,B} <: AbstractDensity
     μ::M
     base::B
-end
For measures μ and ν, LogDensity(μ,ν) represents the log-density function log(dμ/dν), also called the Radom-Nikodym derivative: https://en.wikipedia.org/wiki/Radon%E2%80%93Nikodymtheorem#Radon%E2%80%93Nikodymderivative
Instead of calling this directly, users should call logdensity_rel(μ, ν) or its abbreviated form, log𝒹(μ,ν).
source
MeasureBase.NoArgCheck — Type
MeasureBase.NoArgCheck{MU,T}
Indicates that there is no way to check of a values of type T are variate of measures of type MU.
source
MeasureBase.NoDOF — Type
MeasureBase.NoDOF{MU}
Indicates that there is no way to compute degrees of freedom of a measure of type MU with the given information, e.g. because the DOF are not a global property of the measure.
source
MeasureBase.NoTransport — Type
struct MeasureBase.NoTransport{NU,MU} end
Indicates that no transformation from a measure of type MU to a measure of type NU could be found.
source
MeasureBase.NoVolCorr — Type
NoVolCorr()
Indicate that density calculations should ignore the volume element of variate transformations. Should only be used in special cases in which the volume element has already been taken into account in a different way.
source
MeasureBase.PowerMeasure — Type
struct PowerMeasure{M,...} <: AbstractProductMeasure
A power measure is a product of a measure with itself. The number of elements in the product determines the dimensionality of the resulting support.
Note that power measures are only well-defined for integer powers.
The nth power of a measure μ can be written μ^n.
source
MeasureBase.PrimitiveMeasure — Type
abstract type PrimitiveMeasure <: AbstractMeasure end
In the MeasureTheory ecosystem, a primitive measure is a measure for which the definition and construction do not depend on any other measure. Primitive measures satisfy the following laws:
basemeasure(μ::PrimitiveMeasure) = μ
+end
For measures μ and ν, LogDensity(μ,ν) represents the log-density function log(dμ/dν), also called the Radom-Nikodym derivative: https://en.wikipedia.org/wiki/Radon%E2%80%93Nikodymtheorem#Radon%E2%80%93Nikodymderivative
Instead of calling this directly, users should call logdensity_rel(μ, ν) or its abbreviated form, log𝒹(μ,ν).
source
MeasureBase.NoArgCheck — Type
MeasureBase.NoArgCheck{MU,T}
Indicates that there is no way to check of a values of type T are variate of measures of type MU.
source
MeasureBase.NoDOF — Type
MeasureBase.NoDOF{MU}
Indicates that there is no way to compute degrees of freedom of a measure of type MU with the given information, e.g. because the DOF are not a global property of the measure.
source
MeasureBase.NoTransport — Type
struct MeasureBase.NoTransport{NU,MU} end
Indicates that no transformation from a measure of type MU to a measure of type NU could be found.
source
MeasureBase.NoVolCorr — Type
NoVolCorr()
Indicate that density calculations should ignore the volume element of variate transformations. Should only be used in special cases in which the volume element has already been taken into account in a different way.
source
MeasureBase.PowerMeasure — Type
struct PowerMeasure{M,...} <: AbstractProductMeasure
A power measure is a product of a measure with itself. The number of elements in the product determines the dimensionality of the resulting support.
Note that power measures are only well-defined for integer powers.
The nth power of a measure μ can be written μ^n.
source
MeasureBase.PrimitiveMeasure — Type
abstract type PrimitiveMeasure <: AbstractMeasure end
In the MeasureTheory ecosystem, a primitive measure is a measure for which the definition and construction do not depend on any other measure. Primitive measures satisfy the following laws:
basemeasure(μ::PrimitiveMeasure) = μ
 
 logdensity_def(μ::PrimitiveMeasure, x) = 0.0
 
-logdensity_def(μ::M, ν::M, x) where {M<:PrimitiveMeasure} = 0.0
source
MeasureBase.PushforwardMeasure — Type
struct PushforwardMeasure{F,I,M,VC<:TransformVolCorr} <: AbstractPushforward
+logdensity_def(μ::M, ν::M, x) where {M<:PrimitiveMeasure} = 0.0
source
MeasureBase.PushforwardMeasure — Type
struct PushforwardMeasure{F,I,M,VC<:TransformVolCorr} <: AbstractPushforward
     f :: F
     finv :: I
     origin :: M
@@ -58,18 +58,18 @@
 end
 
 Users should not call `PushforwardMeasure` directly. Instead call or add
-methods to `pushfwd`.
source
MeasureBase.SuperpositionMeasure — Type
struct SuperpositionMeasure{NT} <: AbstractMeasure
     components :: NT
 end
Superposition of measures is analogous to mixture distributions, but (because measures need not be normalized) requires no scaling. The superposition of two measures μ and ν can be more concisely written as μ + ν. Superposition measures satisfy
basemeasure(μ + ν) == basemeasure(μ) + basemeasure(ν)
\[    \begin{aligned}\frac{\mathrm{d}(\mu+\nu)}{\mathrm{d}(\alpha+\beta)} & =\frac{f\,\mathrm{d}\alpha+g\,\mathrm{d}\beta}{\mathrm{d}\alpha+\mathrm{d}\beta}\\
      & =\frac{f\,\mathrm{d}\alpha}{\mathrm{d}\alpha+\mathrm{d}\beta}+\frac{g\,\mathrm{d}\beta}{\mathrm{d}\alpha+\mathrm{d}\beta}\\
      & =\frac{f}{1+\frac{\mathrm{d}\beta}{\mathrm{d}\alpha}}+\frac{g}{\frac{\mathrm{d}\alpha}{\mathrm{d}\beta}+1}\\
      & =\frac{f}{1+\left(\frac{\mathrm{d}\alpha}{\mathrm{d}\beta}\right)^{-1}}+\frac{g}{\frac{\mathrm{d}\alpha}{\mathrm{d}\beta}+1}\ .
-    \end{aligned}\]
source
MeasureBase.WithVolCorr — Type
WithVolCorr()
Indicate that density calculations should take the volume element of variate transformations into account (typically via the log-abs-det-Jacobian of the transform).
source
Base.:| — Method
(m::AbstractMeasure) | constraint
Return a new measure by constraining m to satisfy constraint.
Note that the form of constraint will vary depending on the structure of a given measure. For example, a measure over NamedTuples may allow NamedTuple constraints, while another may require constraint to be a predicate or a function returning a real number (in which case the constraint could be considered as the zero-set of that function). 
At the time of this writing, invariants required of this function are not yet settled. Specifically, there's the question of normalization. It's common for conditional distributions to be normalized, but this can often not be expressed in closed form, and can be very expensive to compute. For more general measures, the notion of normalization may not even make sense.
Because of this, this interface is not yet stable, and users should expect upcoming changes.
source
DensityInterface.logdensityof — Method
logdensityof(m::AbstractMeasure, x)
Compute the log-density of the measure m at x. Density is always relative, but DensityInterface.jl does not account for this. For compatibility with this, logdensityof for a measure is always implicitly relative to rootmeasure(x). 
logdensityof works by first computing insupport(m, x). If this is true, then unsafe_logdensityof is called. If insupport(m, x) is known to be true, it can be a little faster to directly call unsafe_logdensityof(m, x). 
To compute log-density relative to basemeasure(m) or define a log-density (relative to basemeasure(m) or another measure given explicitly), see logdensity_def. 
To compute a log-density relative to a specific base-measure, see logdensity_rel. 
source
MeasureBase.:↣ — Method
If 
  • μ is an AbstractMeasure or satisfies the Measure interface, and
  • k is a function taking values from the support of μ and returning a measure
Then μ ↣ k is a measure, called a monadic bind. In a probabilistic programming language like Soss.jl, this could be expressed as
Note that bind is usually written >>=, but this symbol is unavailable in Julia.
bind = @model μ,k begin 
+    \end{aligned}\]
source
MeasureBase.WithVolCorr — Type
WithVolCorr()
Indicate that density calculations should take the volume element of variate transformations into account (typically via the log-abs-det-Jacobian of the transform).
source
Base.:| — Method
(m::AbstractMeasure) | constraint
Return a new measure by constraining m to satisfy constraint.
Note that the form of constraint will vary depending on the structure of a given measure. For example, a measure over NamedTuples may allow NamedTuple constraints, while another may require constraint to be a predicate or a function returning a real number (in which case the constraint could be considered as the zero-set of that function). 
At the time of this writing, invariants required of this function are not yet settled. Specifically, there's the question of normalization. It's common for conditional distributions to be normalized, but this can often not be expressed in closed form, and can be very expensive to compute. For more general measures, the notion of normalization may not even make sense.
Because of this, this interface is not yet stable, and users should expect upcoming changes.
source
DensityInterface.logdensityof — Method
logdensityof(m::AbstractMeasure, x)
Compute the log-density of the measure m at x. Density is always relative, but DensityInterface.jl does not account for this. For compatibility with this, logdensityof for a measure is always implicitly relative to rootmeasure(x). 
logdensityof works by first computing insupport(m, x). If this is true, then unsafe_logdensityof is called. If insupport(m, x) is known to be true, it can be a little faster to directly call unsafe_logdensityof(m, x). 
To compute log-density relative to basemeasure(m) or define a log-density (relative to basemeasure(m) or another measure given explicitly), see logdensity_def. 
To compute a log-density relative to a specific base-measure, see logdensity_rel. 
source
MeasureBase.:↣ — Method
If 
  • μ is an AbstractMeasure or satisfies the Measure interface, and
  • k is a function taking values from the support of μ and returning a measure
Then μ ↣ k is a measure, called a monadic bind. In a probabilistic programming language like Soss.jl, this could be expressed as
Note that bind is usually written >>=, but this symbol is unavailable in Julia.
bind = @model μ,k begin 
     x ~ μ
     y ~ k(x)
     return y
-end
See also bind and Bind
source
MeasureBase.:⊗ — Method
⊗(μs::AbstractMeasure...)
⊗ is a binary operator for building product measures. This satisfies the law
    basemeasure(μ ⊗ ν) == basemeasure(μ) ⊗ basemeasure(ν)
source
MeasureBase.basekernel — Function
For any k::TransitionKernel, basekernel is expected to satisfy
basekernel(k)(p) == (basemeasure ∘ k)(p)
The main purpose of basekernel is to make it efficient to compute
basemeasure(d::ProductMeasure) == productmeasure(basekernel(d.f), d.xs)
source
MeasureBase.basemeasure_sequence — Method
basemeasure_sequence(m)
Construct the longest Tuple starting with m having each term as the base measure of the previous term, and with no repeated entries.
source
MeasureBase.checked_arg — Function
MeasureBase.checked_arg(μ::MU, x::T)::T
Return x if x is a valid variate of μ, throw an ArgumentError if not, return NoArgCheck{MU,T}() if not check can be performed.
source
MeasureBase.commonbase — Method
commonbase(μ, ν, T) -> Tuple{StaticInt{i}, StaticInt{j}}
Find minimal (with respect to their sum) i and j such that there is a method
logdensity_def(basemeasure_sequence(μ)[i], basemeasure_sequence(ν)[j], ::T)
This is used in logdensity_rel to help make that function efficient.
source
MeasureBase.fill_with — Function
MeasureBase.fill_with(x, sz::NTuple{N,<:IntegerLike}) where N
Creates an array of size sz filled with x.
Returns an instance of FillArrays.Fill.
source
MeasureBase.getdof — Function
getdof(μ)
Returns the effective number of degrees of freedom of variates of measure μ.
The effective NDOF my differ from the length of the variates. For example, the effective NDOF for a Dirichlet distribution with variates of length n is n - 1.
Also see check_dof.
source
MeasureBase.insupport — Function
inssupport(m, x)
-insupport(m)
insupport(m,x) computes whether x is in the support of m.
insupport(m) returns a function, and satisfies
insupport(m)(x) == insupport(m, x)
source
MeasureBase.isnormalized — Method
isnormalized(m::AbstractMeasure)
Checks whether the measure m is normalized, that is, whether massof(m) == 1. 
For convenience, we also provide a method on non-measures that only depends on norm.
source
MeasureBase.kernel — Function
A kernel is a function that returns a measure.
k1 = kernel() do x
+end
See also bind and Bind
source
MeasureBase.:⊗ — Method
⊗(μs::AbstractMeasure...)
⊗ is a binary operator for building product measures. This satisfies the law
    basemeasure(μ ⊗ ν) == basemeasure(μ) ⊗ basemeasure(ν)
source
MeasureBase.basekernel — Function
For any k::TransitionKernel, basekernel is expected to satisfy
basekernel(k)(p) == (basemeasure ∘ k)(p)
The main purpose of basekernel is to make it efficient to compute
basemeasure(d::ProductMeasure) == productmeasure(basekernel(d.f), d.xs)
source
MeasureBase.basemeasure_sequence — Method
basemeasure_sequence(m)
Construct the longest Tuple starting with m having each term as the base measure of the previous term, and with no repeated entries.
source
MeasureBase.checked_arg — Function
MeasureBase.checked_arg(μ::MU, x::T)::T
Return x if x is a valid variate of μ, throw an ArgumentError if not, return NoArgCheck{MU,T}() if not check can be performed.
source
MeasureBase.commonbase — Method
commonbase(μ, ν, T) -> Tuple{StaticInt{i}, StaticInt{j}}
Find minimal (with respect to their sum) i and j such that there is a method
logdensity_def(basemeasure_sequence(μ)[i], basemeasure_sequence(ν)[j], ::T)
This is used in logdensity_rel to help make that function efficient.
source
MeasureBase.fill_with — Function
MeasureBase.fill_with(x, sz::NTuple{N,<:IntegerLike}) where N
Creates an array of size sz filled with x.
Returns an instance of FillArrays.Fill.
source
MeasureBase.getdof — Function
getdof(μ)
Returns the effective number of degrees of freedom of variates of measure μ.
The effective NDOF my differ from the length of the variates. For example, the effective NDOF for a Dirichlet distribution with variates of length n is n - 1.
Also see check_dof.
source
MeasureBase.insupport — Function
inssupport(m, x)
+insupport(m)
insupport(m,x) computes whether x is in the support of m.
insupport(m) returns a function, and satisfies
insupport(m)(x) == insupport(m, x)
source
MeasureBase.isnormalized — Method
isnormalized(m::AbstractMeasure)
Checks whether the measure m is normalized, that is, whether massof(m) == 1. 
For convenience, we also provide a method on non-measures that only depends on norm.
source
MeasureBase.kernel — Function
A kernel is a function that returns a measure.
k1 = kernel() do x
     Normal(x, x^2)
 end
 
@@ -83,7 +83,7 @@
     (x, x^2)
 end
 
-x = randn(); k1(x) == k2(x) == k3(x) == k4(x)
This function is not exported, because "kernel" can have so many other meanings. See for example https://github.com/JuliaGaussianProcesses/KernelFunctions.jl for another common use of this term.
Reference
  • https://en.wikipedia.org/wiki/Markov_kernel
source
MeasureBase.likelihood_ratio — Method
likelihood_ratio(ℓ::Likelihood, p, q)
Compute the log of the likelihood ratio, in order to compare two choices for parameters. This is equal to
density_rel(ℓ.k(p), ℓ.k(q), ℓ.x)
but is computed using LogarithmicNumbers.jl to avoid underflow and overflow. Since density_rel can leave common base measure unevaluated, this can be more efficient than
logdensityof(ℓ.k(p), ℓ.x) - logdensityof(ℓ.k(q), ℓ.x)
source
MeasureBase.likelihoodof — Function
likelihoodof(k::AbstractTransitionKernel, x; constraints...)
-likelihoodof(k::AbstractTransitionKernel, x, constraints::NamedTuple)
A likelihood is not a measure. Rather, a likelihood acts on a measure, through the "pointwise product" ⊙, yielding another measure.
source
MeasureBase.log_likelihood_ratio — Method
log_likelihood_ratio(ℓ::Likelihood, p, q)
Compute the log of the likelihood ratio, in order to compare two choices for parameters. This is computed as
logdensity_rel(ℓ.k(p), ℓ.k(q), ℓ.x)
Since logdensity_rel can leave common base measure unevaluated, this can be more efficient than
logdensityof(ℓ.k(p), ℓ.x) - logdensityof(ℓ.k(q), ℓ.x)
source
MeasureBase.logdensity_def — Function
logdensity_def is the standard way to define a log-density for a new measure. Note that this definition does not include checking for membership in the support; this is instead checked using insupport. logdensity_def is a low-level function, and should typically not be called directly. See logdensityof for more information and other alternatives.
logdensity_def(m, x)
Compute the log-density of the measure m at the point x, relative to basemeasure(m), and assuming insupport(m, x).
logdensity_def(m1, m2, x)
Compute the log-density of m1 relative to m2 at the point x, assuming insupport(m1, x) and insupport(m2, x).
source
MeasureBase.logdensity_rel — Method
logdensity_rel(m1, m2, x)
Compute the log-density of m1 relative to m2 at x. This function checks whether x is in the support of m1 or m2 (or both, or neither). If x is known to be in the support of both, it can be more efficient to call unsafe_logdensity_rel. 
source
MeasureBase.log𝒹 — Method
log𝒹(μ, base)
Compute the log-density (Radom-Nikodym derivative) of μ with respect to base. This is a shorthand form for logdensity_rel(μ, base)
source
MeasureBase.massof — Method
massof(m)
Get the mass of a measure - that is, integrate the measure over its support.
massof 
massof(m, dom)
Integrate the measure m over the "domain" dom. Note that domains are not defined universally, but may be specific to a given measure. If m is <:AbstractMeasure, users can also write m(dom). For new measures, users should not add new "call" methods, but instead extend MeasureBase.massof.
For example, for many univariate measures m with rootmeasure(m) == LebesgueBase(), users can call massof(m, a_b) where a_b::IntervalSets.Interval.
massof often returns a Real. But in many cases we may only know the mass is finite, or we may know nothing at all about it. For these cases, it will return UnknownFiniteMass or UnknownMass, respectively. When no massof method exists, it defaults to UnknownMass.
source
MeasureBase.one_to — Method
MeasureBase.one_to(n::IntegerLike)
Creates a range from one to n.
Returns an instance of Base.OneTo or Static.SOneTo, depending on the type of n.
source
MeasureBase.paramnames — Function
paramnames(μ) returns the names of the parameters of μ. This is equivalent to 
paramnames(μ) == (keys ∘ params)(μ)
but depends only on the type. In particular, the default implementation is
paramnames(μ::M) where {M} = paramnames(M)
New ParameterizedMeasures will automatically have a paramnames method. For other measures, this method is optional, but can be added by defining
paramnames(::Type{M}) where {M} = ...
See also params
source
MeasureBase.params — Function
params(μ) returns the parameters of a measure μ, as a NamedTuple. The default method is
params(μ) = NamedTuple()
See also paramnames
source
MeasureBase.proxy — Function
function proxy end
It's often useful to delegate methods like logdensity and basemeasure to those of a different measure. For example, a Normal{(:μ,:σ)} is equivalent to an affine transformation of a Normal{()}.
We could just have calls like Normal(μ=2,σ=4) directly construct a transformed measure, but this would make dispatch awkward.
source
MeasureBase.pullback — Function
pullback(f, μ, volcorr = WithVolCorr())
A pullback is a dual concept to a pushforward. While a pushforward needs a map from the support of a measure, a pullback requires a map into the support of a measure. The log-density is then computed through function composition, together with a volume correction as needed.
This can be useful, since the log-density of a PushforwardMeasure is computing in terms of the inverse function; the "forward" function is not used at all. In some cases, we may be focusing on log-density (and not, for example, sampling).
To manually specify an inverse, call  pullback(InverseFunctions.setinverse(f, finv), μ, volcorr).
source
MeasureBase.rebase — Method
rebase(μ, ν)
Express μ in terms of a density over ν. Satisfies
basemeasure(rebase(μ, ν)) == ν
-density(rebase(μ, ν)) == 𝒹(μ,ν)
source
MeasureBase.require_insupport — Function
MeasureBase.require_insupport(μ, x)::Nothing
Checks if x is in the support of distribution/measure μ, throws an ArgumentError if not.
source
MeasureBase.rootmeasure — Method
rootmeasure(μ::AbstractMeasure)
It's sometimes important to be able to find the fix point of a measure under basemeasure. That is, to start with some measure and apply basemeasure repeatedly until there's no change. That's what this does.
source
MeasureBase.schema — Function
schema(::Type)
schema turns a type into a value that's easier to work with. Example:     julia> nt = (a=(b=[1,2],c=(d=[3,4],e=[5,6])),f=[7,8]);     julia> NT = typeof(nt)     NamedTuple{(:a, :f),Tuple{NamedTuple{(:b, :c),Tuple{Array{Int64,1},NamedTuple{(:d, :e),Tuple{Array{Int64,1},Array{Int64,1}}}}},Array{Int64,1}}}     julia> schema(NT)     (a = (b = Array{Int64,1}, c = (d = Array{Int64,1}, e = Array{Int64,1})), f = Array{Int64,1})
source
MeasureBase.smf — Function
smf(μ, x::Real) ::Real
Compute the Stieltjes measure function (SMF) of the measure μ at the point x.
The SMF is the measure-theoretic generalization of the cumulative distribution function (CDF) from probability theory. An SMF F(x) = smf(μ, x) must have the following properties:
  1. F is nondecreasing
  2. F is right-continuous: F(x) should be the same as lim_{δ→0} F(x + |δ|).
  3. μ((a,b]) = F(b) - F(a)
Note that unlike the CDF, an SMF is only determined up to addition by a constant. For many applications, this leads to a need to evaluate an SMF at -∞. It's therefore important that smf(μ, -Inf) be fast. In practice, this will usually be called as smf(μ, static(-Inf)). It's then easy to ensure speed and avoid complex control flow by adding a method smf(μ::M, ::StaticFloat64{-Inf}).
Users who pronounce sinh as "sinch" are advised to pronounce smf as "smurf".
source
MeasureBase.transport_def — Function
transport_def(ν, μ, x)
Transforms a value x distributed according to μ to a value y distributed according to ν.
If no specialized transport_def(::MU, ::NU, ...) is available then the default implementation oftransport_def(ν, μ, x) uses the following strategy:
  • Evaluate transport_origin for μ and ν. Transform between each and it's origin, if available, and use the origin(s) as intermediate measures for another transformation.
  • If all else fails, try to transform from μ to a standard multivariate uniform measure and then to ν.
See transport_to.
source
MeasureBase.transport_origin — Function
MeasureBase.transport_origin(ν)
Default measure to pullback to resp. pushforward from when transforming between ν and another measure.
source
MeasureBase.transport_to — Function
f = transport_to(ν, μ)
Generates a measurable function f that transforms a value x distributed according to measure μ to a value y = f(x) distributed according to a measure ν.
The pushforward measure from μ under f is is equivalent to ν.
If terms of random values this implies that f(rand(μ)) is equivalent to rand(ν) (if rand(μ) and rand(ν) are supported).
The resulting function f should support ChangesOfVariables.with_logabsdet_jacobian(f, x) if mathematically well-defined, so that densities of ν can be derived from densities of μ via f (using appropriate base measures).
Returns NoTransportOrigin{typeof(ν),typeof(μ)} if no transformation from μ to ν can be found.
To add transformation rules for a measure type MyMeasure, specialize
  • MeasureBase.transport_def(ν::SomeStdMeasure, μ::CustomMeasure, x) = ...
  • MeasureBase.transport_def(ν::MyMeasure, μ::SomeStdMeasure, x) = ...
and/or
  • MeasureBase.transport_origin(ν::MyMeasure) = SomeMeasure(...)
  • MeasureBase.from_origin(μ::MyMeasure, x) = y
  • MeasureBase.to_origin(μ::MyMeasure, y) = x
and ensure MeasureBase.getdof(μ::MyMeasure) is defined correctly.
A standard measure type like StdUniform, StdExponential or StdLogistic may also be used as the source or target of the transform:
f_to_uniform(StdUniform, μ)
-f_to_uniform(ν, StdUniform)
Depending on getdof(μ) (resp. ν), an instance of the standard distribution itself or a power of it (e.g. StdUniform() or StdUniform()^dof) will be chosen as the transformation partner.
source
MeasureBase.unsafe_logdensity_rel — Method
unsafe_logdensity_rel(m1, m2, x)
Compute the log-density of m1 relative to m2 at x, assuming x is known to be in the support of both m1 and m2.
See also logdensity_rel.
source
MeasureBase.unsafe_logdensityof — Method
unsafe_logdensityof(m, x)
Compute the log-density of the measure m at x relative to rootmeasure(m). This is "unsafe" because it does not check insupport(m, x).
See also logdensityof.
source
MeasureBase.∫ — Method
∫(f, base::AbstractMeasure)
Define a new measure in terms of a density f over some measure base.
source
MeasureBase.∫exp — Method
∫exp(f, base::AbstractMeasure)
Define a new measure in terms of a log-density f over some measure base.
source
MeasureBase.𝒹 — Method
𝒹(μ, base)
Compute the density (Radom-Nikodym derivative) of μ with respect to base. This is a shorthand form for density_rel(μ, base).
source

+x = randn(); k1(x) == k2(x) == k3(x) == k4(x)

This function is not exported, because "kernel" can have so many other meanings. See for example https://github.com/JuliaGaussianProcesses/KernelFunctions.jl for another common use of this term.

Reference

  • https://en.wikipedia.org/wiki/Markov_kernel
source
MeasureBase.likelihood_ratio — Method
likelihood_ratio(ℓ::Likelihood, p, q)

Compute the log of the likelihood ratio, in order to compare two choices for parameters. This is equal to

density_rel(ℓ.k(p), ℓ.k(q), ℓ.x)

but is computed using LogarithmicNumbers.jl to avoid underflow and overflow. Since density_rel can leave common base measure unevaluated, this can be more efficient than

logdensityof(ℓ.k(p), ℓ.x) - logdensityof(ℓ.k(q), ℓ.x)
source
MeasureBase.likelihoodof — Function
likelihoodof(k::AbstractTransitionKernel, x; constraints...)
+likelihoodof(k::AbstractTransitionKernel, x, constraints::NamedTuple)

A likelihood is not a measure. Rather, a likelihood acts on a measure, through the "pointwise product" ⊙, yielding another measure.

source
MeasureBase.log_likelihood_ratio — Method
log_likelihood_ratio(ℓ::Likelihood, p, q)

Compute the log of the likelihood ratio, in order to compare two choices for parameters. This is computed as

logdensity_rel(ℓ.k(p), ℓ.k(q), ℓ.x)

Since logdensity_rel can leave common base measure unevaluated, this can be more efficient than

logdensityof(ℓ.k(p), ℓ.x) - logdensityof(ℓ.k(q), ℓ.x)
source
MeasureBase.logdensity_def — Function

logdensity_def is the standard way to define a log-density for a new measure. Note that this definition does not include checking for membership in the support; this is instead checked using insupport. logdensity_def is a low-level function, and should typically not be called directly. See logdensityof for more information and other alternatives.

logdensity_def(m, x)

Compute the log-density of the measure m at the point x, relative to basemeasure(m), and assuming insupport(m, x).

logdensity_def(m1, m2, x)

Compute the log-density of m1 relative to m2 at the point x, assuming insupport(m1, x) and insupport(m2, x).

source
MeasureBase.logdensity_rel — Method
logdensity_rel(m1, m2, x)

Compute the log-density of m1 relative to m2 at x. This function checks whether x is in the support of m1 or m2 (or both, or neither). If x is known to be in the support of both, it can be more efficient to call unsafe_logdensity_rel.

source
MeasureBase.log𝒹 — Method
log𝒹(μ, base)

Compute the log-density (Radom-Nikodym derivative) of μ with respect to base. This is a shorthand form for logdensity_rel(μ, base)

source
MeasureBase.massof — Method
massof(m)

Get the mass of a measure - that is, integrate the measure over its support.

massof 

massof(m, dom)

Integrate the measure m over the "domain" dom. Note that domains are not defined universally, but may be specific to a given measure. If m is <:AbstractMeasure, users can also write m(dom). For new measures, users should not add new "call" methods, but instead extend MeasureBase.massof.

For example, for many univariate measures m with rootmeasure(m) == LebesgueBase(), users can call massof(m, a_b) where a_b::IntervalSets.Interval.

massof often returns a Real. But in many cases we may only know the mass is finite, or we may know nothing at all about it. For these cases, it will return UnknownFiniteMass or UnknownMass, respectively. When no massof method exists, it defaults to UnknownMass.

source
MeasureBase.one_to — Method
MeasureBase.one_to(n::IntegerLike)

Creates a range from one to n.

Returns an instance of Base.OneTo or Static.SOneTo, depending on the type of n.

source
MeasureBase.paramnames — Function

paramnames(μ) returns the names of the parameters of μ. This is equivalent to 

paramnames(μ) == (keys ∘ params)(μ)

but depends only on the type. In particular, the default implementation is

paramnames(μ::M) where {M} = paramnames(M)

New ParameterizedMeasures will automatically have a paramnames method. For other measures, this method is optional, but can be added by defining

paramnames(::Type{M}) where {M} = ...

See also params

source
MeasureBase.params — Function

params(μ) returns the parameters of a measure μ, as a NamedTuple. The default method is

params(μ) = NamedTuple()

See also paramnames

source
MeasureBase.proxy — Function

function proxy end

It's often useful to delegate methods like logdensity and basemeasure to those of a different measure. For example, a Normal{(:μ,:σ)} is equivalent to an affine transformation of a Normal{()}.

We could just have calls like Normal(μ=2,σ=4) directly construct a transformed measure, but this would make dispatch awkward.

source
MeasureBase.pullback — Function
pullback(f, μ, volcorr = WithVolCorr())

A pullback is a dual concept to a pushforward. While a pushforward needs a map from the support of a measure, a pullback requires a map into the support of a measure. The log-density is then computed through function composition, together with a volume correction as needed.

This can be useful, since the log-density of a PushforwardMeasure is computing in terms of the inverse function; the "forward" function is not used at all. In some cases, we may be focusing on log-density (and not, for example, sampling).

To manually specify an inverse, call pullback(InverseFunctions.setinverse(f, finv), μ, volcorr).

source
MeasureBase.rebase — Method
rebase(μ, ν)

Express μ in terms of a density over ν. Satisfies

basemeasure(rebase(μ, ν)) == ν
+density(rebase(μ, ν)) == 𝒹(μ,ν)
source
MeasureBase.require_insupport — Function
MeasureBase.require_insupport(μ, x)::Nothing

Checks if x is in the support of distribution/measure μ, throws an ArgumentError if not.

source
MeasureBase.rootmeasure — Method
rootmeasure(μ::AbstractMeasure)

It's sometimes important to be able to find the fix point of a measure under basemeasure. That is, to start with some measure and apply basemeasure repeatedly until there's no change. That's what this does.

source
MeasureBase.schema — Function
schema(::Type)

schema turns a type into a value that's easier to work with. Example: julia> nt = (a=(b=[1,2],c=(d=[3,4],e=[5,6])),f=[7,8]); julia> NT = typeof(nt) NamedTuple{(:a, :f),Tuple{NamedTuple{(:b, :c),Tuple{Array{Int64,1},NamedTuple{(:d, :e),Tuple{Array{Int64,1},Array{Int64,1}}}}},Array{Int64,1}}} julia> schema(NT) (a = (b = Array{Int64,1}, c = (d = Array{Int64,1}, e = Array{Int64,1})), f = Array{Int64,1})

source
MeasureBase.smf — Function
smf(μ, x::Real) ::Real

Compute the Stieltjes measure function (SMF) of the measure μ at the point x.

The SMF is the measure-theoretic generalization of the cumulative distribution function (CDF) from probability theory. An SMF F(x) = smf(μ, x) must have the following properties:

  1. F is nondecreasing
  2. F is right-continuous: F(x) should be the same as lim_{δ→0} F(x + |δ|).
  3. μ((a,b]) = F(b) - F(a)

Note that unlike the CDF, an SMF is only determined up to addition by a constant. For many applications, this leads to a need to evaluate an SMF at -∞. It's therefore important that smf(μ, -Inf) be fast. In practice, this will usually be called as smf(μ, static(-Inf)). It's then easy to ensure speed and avoid complex control flow by adding a method smf(μ::M, ::StaticFloat64{-Inf}).

Users who pronounce sinh as "sinch" are advised to pronounce smf as "smurf".

source
MeasureBase.transport_def — Function
transport_def(ν, μ, x)

Transforms a value x distributed according to μ to a value y distributed according to ν.

If no specialized transport_def(::MU, ::NU, ...) is available then the default implementation oftransport_def(ν, μ, x) uses the following strategy:

  • Evaluate transport_origin for μ and ν. Transform between each and it's origin, if available, and use the origin(s) as intermediate measures for another transformation.

  • If all else fails, try to transform from μ to a standard multivariate uniform measure and then to ν.

See transport_to.

source
MeasureBase.transport_origin — Function
MeasureBase.transport_origin(ν)

Default measure to pullback to resp. pushforward from when transforming between ν and another measure.

source
MeasureBase.transport_to — Function
f = transport_to(ν, μ)

Generates a measurable function f that transforms a value x distributed according to measure μ to a value y = f(x) distributed according to a measure ν.

The pushforward measure from μ under f is is equivalent to ν.

If terms of random values this implies that f(rand(μ)) is equivalent to rand(ν) (if rand(μ) and rand(ν) are supported).

The resulting function f should support ChangesOfVariables.with_logabsdet_jacobian(f, x) if mathematically well-defined, so that densities of ν can be derived from densities of μ via f (using appropriate base measures).

Returns NoTransportOrigin{typeof(ν),typeof(μ)} if no transformation from μ to ν can be found.

To add transformation rules for a measure type MyMeasure, specialize

  • MeasureBase.transport_def(ν::SomeStdMeasure, μ::CustomMeasure, x) = ...
  • MeasureBase.transport_def(ν::MyMeasure, μ::SomeStdMeasure, x) = ...

and/or

  • MeasureBase.transport_origin(ν::MyMeasure) = SomeMeasure(...)
  • MeasureBase.from_origin(μ::MyMeasure, x) = y
  • MeasureBase.to_origin(μ::MyMeasure, y) = x

and ensure MeasureBase.getdof(μ::MyMeasure) is defined correctly.

A standard measure type like StdUniform, StdExponential or StdLogistic may also be used as the source or target of the transform:

f_to_uniform(StdUniform, μ)
+f_to_uniform(ν, StdUniform)

Depending on getdof(μ) (resp. ν), an instance of the standard distribution itself or a power of it (e.g. StdUniform() or StdUniform()^dof) will be chosen as the transformation partner.

source
MeasureBase.unsafe_logdensity_rel — Method
unsafe_logdensity_rel(m1, m2, x)

Compute the log-density of m1 relative to m2 at x, assuming x is known to be in the support of both m1 and m2.

See also logdensity_rel.

source
MeasureBase.unsafe_logdensityof — Method
unsafe_logdensityof(m, x)

Compute the log-density of the measure m at x relative to rootmeasure(m). This is "unsafe" because it does not check insupport(m, x).

See also logdensityof.

source
MeasureBase.∫ — Method
∫(f, base::AbstractMeasure)

Define a new measure in terms of a density f over some measure base.

source
MeasureBase.∫exp — Method
∫exp(f, base::AbstractMeasure)

Define a new measure in terms of a log-density f over some measure base.

source
MeasureBase.𝒹 — Method
𝒹(μ, base)

Compute the density (Radom-Nikodym derivative) of μ with respect to base. This is a shorthand form for density_rel(μ, base).

source
diff --git a/dev/api_measuretheory/index.html b/dev/api_measuretheory/index.html index 4f649835..567eafe4 100644 --- a/dev/api_measuretheory/index.html +++ b/dev/api_measuretheory/index.html @@ -29,4 +29,4 @@ par :: NamedTuple{N,T} end KeywordCalls.@kwstruct Normal(μ,σ) -Normal(μ,σ) = Normal((μ=μ, σ=σ))

See KeywordCalls.jl for details on @kwstruct.

source +Normal(μ,σ) = Normal((μ=μ, σ=σ))

See KeywordCalls.jl for details on @kwstruct.

source diff --git a/dev/index.html b/dev/index.html index 981a927a..63f86d54 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · MeasureTheory.jl

Home

MeasureTheory.jl is a package for building and reasoning about measures.

Why?

A distribution (as provided by Distributions.jl) is also called a probability measure, and carries with it the constraint of adding (or integrating) to one. Statistical work usually requires this "at the end of the day", but enforcing it at each step of a computation can have considerable overhead. For instance, Bayesian modeling often requires working with unnormalized posterior densities or improper priors.

As a generalization of the concept of volume, measures also have applications outside of probability theory.

Getting started

To install MeasureTheory.jl, open the Julia Pkg REPL (by typing ] in the standard REPL) and run

pkg> add MeasureTheory

To get an idea of the possibilities offered by this package, go to the documentation.

To know more about the underlying theory and its applications to probabilistic programming, check out our JuliaCon 2021 submission.

+Home · MeasureTheory.jl

Home

MeasureTheory.jl is a package for building and reasoning about measures.

Why?

A distribution (as provided by Distributions.jl) is also called a probability measure, and carries with it the constraint of adding (or integrating) to one. Statistical work usually requires this "at the end of the day", but enforcing it at each step of a computation can have considerable overhead. For instance, Bayesian modeling often requires working with unnormalized posterior densities or improper priors.

As a generalization of the concept of volume, measures also have applications outside of probability theory.

Getting started

To install MeasureTheory.jl, open the Julia Pkg REPL (by typing ] in the standard REPL) and run

pkg> add MeasureTheory

To get an idea of the possibilities offered by this package, go to the documentation.

To know more about the underlying theory and its applications to probabilistic programming, check out our JuliaCon 2021 submission.

diff --git a/dev/old_readme/index.html b/dev/old_readme/index.html index a162cfa4..8cfc8411 100644 --- a/dev/old_readme/index.html +++ b/dev/old_readme/index.html @@ -46,4 +46,4 @@ logdensity_def(d, x) = - (log(2) + log(π) - log(d.par.τ) + d.par.τ * (x - d.par.μ)^2) / 2 end

And another check:

julia> logdensity_def(Normal(μ=0.0, τ=4.0), 1.0)
 -2.2257913526447273

We can combine measures in a few ways, for now just scaling and superposition:

julia> 2.0*Lebesgue(Float64) + Normal(0.0,1.0)
-SuperpositionMeasure{Float64,2}((MeasureTheory.WeightedMeasure{Float64,Float64}(2.0, Lebesgue{Float64}()), Normal{NamedTuple{(:μ, :σ),Tuple{Float64,Float64}},Float64}((μ = 0.0, σ = 1.0))))

For an easy way to find expressions for the common log-densities, see this gist

+SuperpositionMeasure{Float64,2}((MeasureTheory.WeightedMeasure{Float64,Float64}(2.0, Lebesgue{Float64}()), Normal{NamedTuple{(:μ, :σ),Tuple{Float64,Float64}},Float64}((μ = 0.0, σ = 1.0))))

For an easy way to find expressions for the common log-densities, see this gist