Internal Library
Documentation for structs
and functions not covered within User Interface documentation.
Structs
EllipseSampling.Ellipse
— TypeEllipse
Contains the information required to define an ellipse which may have been rotated and translated. See construct_ellipse
.
Fields
x_radius
: radius of the ellipse in the x axis (i.e. when the rotation,α
, is zero).y_radius
: radius of the ellipse in the y axis (i.e. when the rotation,α
, is zero).α
: an angle in radians (0 to 2π) that the ellipse has been rotated by. A positive value represents an anti-clockwise rotation.Cx
: the x coordinate of the centre of the ellipse (the translation of the ellipse in the x axis).Cy
: the y coordinate of the centre of the ellipse (the translation of the ellipse in the y axis).a
: the major radius of the ellipse.b
: the minor radius of the ellipse.m
: the eccentricity of the ellipse squared. SeeEllipseSampling.eccentricity_squared
.em
: complete elliptic integral of the second kind evaluated for the eccentricity squared of the ellipse:Elliptic.E(m)
. See: Elliptic.jl.circumference
: the circumference of the ellipse.
Functions
EllipseSampling.eccentricity_squared
— Functioneccentricity_squared(a::T, b::T) where T<:Float64
Computes m
, the eccentricity of the ellipse squared, $m=e^2$, where $m=1-\big(\frac{b}{a}\big)^2$.
Arguments
a
: the major radius of the ellipse.b
: the minor radius of the ellipse.
Details
This relationship between m and e is seen by considering the equation for e: $e=\frac{c}{a}$, where $c^2=\big(a^2-b^2\big)$ and $a>b$.
Replacing c in the equation for e:
\[e=\frac{\sqrt{a^2-b^2}}{a}\]
Substituting the equation for e into m:
\[m = \bigg(\frac{\sqrt{a^2-b^2}}{a}\bigg)^2 = \frac{a^2-b^2}{a^2} = 1 - \frac{b^2}{a^2} = 1 - \bigg(\frac{b}{a}\bigg)^2\]
EllipseSampling.circumference
— Functioncircumference(a::Float64, b::Float64)
Calculates the circumference of an ellipse using the elliptic integral of the second kind. Uses Elliptic.jl.
Arguments
a
: the major radius of the ellipse.b
: the minor radius of the ellipse.
EllipseSampling.assert_parameters_are_valid
— Functionassert_parameters_are_valid(a::T, b::T, x_radius::T, y_radius::T) where T<:Float64
Asserts that the parameters relate to a valid ellipse. I.e. that a ≥ b
and, x_radius
and y_radius
are positive. Note: a=max(x_radius, y_radius), b=min(x_radius, y_radius)
.
Arguments
a
: the major radius of the ellipse.b
: the minor radius of the ellipse.x_radius
: radius of the ellipse in the x axis (i.e. when the rotation,α
, is zero).y_radius
: radius of the ellipse in the y axis (i.e. when the rotation,α
, is zero).
EllipseSampling.E_inverse
— FunctionE_inverse(em::T, z::T, m::T) where T<:Float64
Julia version of the python function t_from_length
by John D. Cook.
Arguments
em
: complete elliptic integral of the second kind evaluated for the eccentricity squared of the ellipse:Elliptic.E(m)
. See: Elliptic.jl.z
: Difference betweenem
and the quotient of arc length and the major axis radius,em - arc_len/a
.m
: the eccentricity of the ellipse squared. SeeEllipseSampling.eccentricity_squared
.
EllipseSampling.ellipse_zero
— Functionellipse_zero(t::Float64, p::AbstractVector)
Used by EllipseSampling.E_inverse
to find the location t
where the function is zero. Equivalent to the anonymous function f(y) = Elliptic.E(y, m) - z
.
Arguments
x
: the argument optimised over.p
: a 2 element static array containing the values forz
andm
.
EllipseSampling.calculate_ellipse_parameters
— Functioncalculate_ellipse_parameters(Γ::Matrix{Float64}, ind1::Int, ind2::Int,
confidence_level::Float64, dof::Int)
Given a square matrix Γ, the inverse of the Hessian of a log-likelihood function at its maximum likelihood estimate, indexes of the two variables of interest, the confidence level and degrees of freedom used to define $\ell_c$, which constructs a 2D ellipse approximation of the log-likelihood function, return the parameters of that ellipse.
Arguments
Γ
: a square matrix which is the inverse of the Hessian of a log-likelihood function at its maximum likelihood estimate.ind1
: index of the first parameter of interest (corresponds to the row and column index ofΓ
)ind2
: index of the second parameter of interest (corresponds to the row and column index ofΓ
).confidence_level
: the confidence level ∈ [0.0,1.0] at which the ellipse approximation is constructed.dof
: integer degrees of freedom used for calculation of the asymptotic confidence threshold defining the ellipse. Default is2
.
Details
The parameters of interest are a
and b
, the radius of the major and minor axis respectively, x_radius
and y_radius
, the radius of the ellipse in the x and y axis respectively (i.e. the radius when the rotation α
is zero) and α
, an angle between 0 and π radians that the major axis of the ellipse has been rotated by from the positive x axis. a
is equal to the maximum of x_radius
and y_radius
, while b
is equal to the minimum of x_radius
and y_radius
.
Observed Fisher Information Matrix and Approximation of the Log-Likelihood Function
We can approximate a log-likelihood function from multiple parameters, $\theta$, by considering the observed Fisher information matrix (FIM). The observed FIM is a quadratic approximation of the curvature of the log-likelihood function at the maximum likelihood estimate, $\hat{\theta}$. The observed FIM is the matrix of second derivatives (the Hessian) of the log-likelihood function evaluated at the MLE with elements [1]:
\[H_{jk}(\hat{\theta}) \equiv -\frac{\partial^2}{\partial \theta_j \partial \theta_k} \ell (\hat{\theta} \, ; \, y_{1:I}^{\textrm{o}} ).\]
This then allows us to define the following approximation of the normalised log-likelihood function using a second-order Taylor expansion at the MLE [1]:
\[ \hat{\ell} (\theta \, ; \, y_{1:I}^{\textrm{o}} ) \approx -\frac{1}{2} (\theta-\hat{\theta})' H(\hat{\theta}) (\theta-\hat{\theta}).\]
Similarly, for two parameters, $\psi$, from a larger number of parameters, we first invert the observed FIM, $\Gamma(\hat{\theta}) = H^{-1}(\hat{\theta})$, and then select just the rows and columns relating to the parameters of interest, before again inverting the matrix:
\[ \hat{\ell}_p (\psi \, ; \, y_{1:I}^{\textrm{o}} ) \approx -\frac{1}{2} (\psi-\hat{\psi})' ([e_j, e_k]' \, \Gamma(\hat{\theta}) \, [e_j, e_k])^{-1} (\psi-\hat{\psi}), \hspace{0.2cm} \theta_j \cup \theta_k = \psi, \]
where $e_j$ and $e_k$ are the $j$th and $k$th canonical vectors of $\mathbb{R}^{|\theta|}$.
Obtaining Ellipse parameters
By normalising our log-likelihood approximation equation for two parameters by our target confidence threshold of interest $\ell_c$ (at confidence_level
, with dof
degrees of freedom, typically 2) so that one side of the equation is equal to 1 we obtain the equation of an ellipse [2]:
\[1 = -\frac{1}{2\ell_c} (\psi-\hat{\psi})' ([e_j, e_k]' \, \Gamma(\hat{\theta}) \, [e_j, e_k])^{-1} (\psi-\hat{\psi}) = (\psi-\hat{\psi})' \mathcal{C} (\psi-\hat{\psi}),\]
The major and minor axis radii, a
and b
respectively, can then be evaluated by considering the inverse of the square roots of the eigenvalues of $\mathcal{C}$ (ordered from largest to smallest) [2]. To determine the rotation, α
of the major axis of the ellipse from the positive $x$ axis we calculate the inverse tangent of the division of the $y$ and $x$ components of the eigenvector corresponding to the largest eigenvalue [2].