Histogram

PortfolioOptimisers.Knuth Type

struct Knuth{__T_args, __T_kwargs} <: BinWidthBins

Histogram binning algorithm using Knuth's rule.

Knuth implements Knuth's rule for selecting the optimal number of bins in a histogram [7]. This method maximises the posterior probability of a piecewise-constant density model given the data, resulting in an adaptive binning strategy that balances bias and variance.

Constructors

Knuth(;
  args::Tuple = (Optim.NelderMead(),),
  kwargs::NamedTuple = (;)
) -> Knuth

Examples

julia> Knuth()
Knuth
    args ┼ Tuple{Optim.NelderMead{Optim.AffineSimplexer, Optim.AdaptiveParameters}}: (Optim.NelderMead{Optim.AffineSimplexer, Optim.AdaptiveParameters}(Optim.AffineSimplexer(0.025, 0.5), Optim.AdaptiveParameters(1.0, 1.0, 0.75, 1.0)),)
  kwargs ┴ @NamedTuple{}: NamedTuple()

Related

• BinWidthBins

• FreedmanDiaconis

• Scott

• HacineGharbiRavier

source

PortfolioOptimisers.FreedmanDiaconis Type

struct FreedmanDiaconis <: BinWidthBins

Histogram binning algorithm using the Freedman-Diaconis rule.

FreedmanDiaconis implements the Freedman-Diaconis rule for selecting the number of bins in a histogram [8]. This method determines bin width based on the interquartile range (IQR) and the number of data points, making it robust to outliers and suitable for skewed distributions.

Constructors

FreedmanDiaconis() -> FreedmanDiaconis

Examples

julia> FreedmanDiaconis()
FreedmanDiaconis()

Related

• BinWidthBins

• Knuth

• Scott

• HacineGharbiRavier

source

PortfolioOptimisers.Scott Type

struct Scott <: BinWidthBins

Histogram binning algorithm using Scott's rule.

Scott implements Scott's rule for selecting the number of bins in a histogram [9]. This method chooses bin width based on the standard deviation of the data and the number of observations, providing a good default for normally distributed data.

Constructors

Scott() -> Scott

Examples

julia> Scott()
Scott()

Related

• BinWidthBins

• Knuth

• FreedmanDiaconis

• HacineGharbiRavier

source

PortfolioOptimisers.HacineGharbiRavier Type

struct HacineGharbiRavier <: AbstractBins

Histogram binning algorithm using the Hacine-Gharbi–Ravier rule.

HacineGharbiRavier implements the Hacine-Gharbi–Ravier rule for selecting the number of bins in a histogram. This method adapts the bin count based on the correlation structure and sample size, and is particularly useful for information-theoretic measures such as mutual information and variation of information.

Constructors

HacineGharbiRavier() -> HacineGharbiRavier

Examples

julia> HacineGharbiRavier()
HacineGharbiRavier()

Related

• AbstractBins

• BinWidthBins

• Knuth

• FreedmanDiaconis

• Scott

source

PortfolioOptimisers.AbstractBins Type

abstract type AbstractBins <: AbstractAlgorithm

Abstract supertype for all histogram binning algorithms.

AbstractBins is the abstract type for all binning algorithm types used in histogram-based calculations within PortfolioOptimisers.jl, such as mutual information and variation of information analysis. Concrete subtypes implement specific binning strategies (e.g., Knuth, Freedman-Diaconis, Scott, Hacine-Gharbi-Ravier) and provide a consistent interface for bin selection.

Related

• BinWidthBins

• Knuth

• FreedmanDiaconis

• Scott

• HacineGharbiRavier

source

PortfolioOptimisers.BinWidthBins Type

abstract type BinWidthBins <: AbstractBins

Abstract supertype for all histogram binning algorithms based on a bin width selection rule.

BinWidthBins is the abstract type for all binning algorithm types that select the number of bins by first computing an optimal bin width from the data, such as Knuth, Freedman-Diaconis, and Scott. Concrete subtypes implement specific binning strategies and provide a consistent interface for bin selection in histogram-based calculations within PortfolioOptimisers.jl.

Related

• Knuth

• FreedmanDiaconis

• Scott

• AbstractBins

source

PortfolioOptimisers.Int_Bin Type

const Int_Bin = Union{<:AbstractBins, <:Integer}

Alias for a histogram binning algorithm or an integer number of bins.

Matches either an AbstractBins algorithm (auto-selecting bin counts) or a plain Integer (fixed number of bins). Used in histogram-based mutual information and variation of information calculations.

Related

• AbstractBins

• mutual_variation_info

source

PortfolioOptimisers.bin_width Function

bin_width(::Scott, x::VecNum)

Compute the optimal histogram bin width for x using Scott's rule [9].

Mathematical definition

$$\begin{array}{rl}{\mathrm{\Delta }}_x& ={\sigma }_x{\left(\frac{24\sqrt{\pi }}{n}\right)}^{1/3}.\end{array}$$

Where:

• ${\mathrm{\Delta }}_x$: Bin width.

• ${\sigma }_x$: Uncorrected standard deviation of the data.

• $n$: Number of observations.

Arguments

• x: Data vector.

Returns

• dx::Number: The optimal bin width.

Related

• Scott

• calc_num_bins

source

bin_width(::FreedmanDiaconis, x::VecNum)

Compute the optimal histogram bin width for x using the Freedman-Diaconis rule [8].

Mathematical definition

$$\begin{array}{rl}{\mathrm{\Delta }}_x& =\frac{2\mathrm{IQR}(x)}{n^{1/3}}.\end{array}$$

Where:

• ${\mathrm{\Delta }}_x$: Bin width.

• $\mathrm{IQR}(x)$: Interquartile range of the data.

• $n$: Number of observations.

Arguments

• x: Data vector.

Returns

• dx::Number: The optimal bin width.

Related

• FreedmanDiaconis

• calc_num_bins

source

bin_width(bins::Knuth, x::VecNum)

Compute the optimal histogram bin width for x using Knuth's rule [7].

Maximises the marginal posterior probability of a piecewise-constant density model with $M$ equal-width bins over the data range,

$$\begin{array}{rl}F(M)& =n\log M+\log \mathrm{\Gamma }\left(\frac{M}{2}\right)-M\log \mathrm{\Gamma }\left(\frac{1}{2}\right)-\log \mathrm{\Gamma }(n+\frac{M}{2})+\sum _{k=1}^M\log \mathrm{\Gamma }(n_k+\frac{1}{2}).\end{array}$$

Where:

• $M$: Number of bins.

• $n$: Number of observations.

• $n_k$: Number of observations in bin $k$.

Arguments

• x: Data vector.

Returns

• dx::Number: The optimal bin width.

Details

• The optimisation is performed with Nelder-Mead over a continuous relaxation of $M$ (evaluated at $\lfloor M\rfloor$), started at the bin count implied by the Freedman-Diaconis rule.

Related

• Knuth

• calc_num_bins

source

PortfolioOptimisers.calc_num_bins Function

calc_num_bins(bins::Int_Bin, xj::VecNum,
              xi::VecNum, j::Integer, i::Integer, bin_width_func, T::Integer)

Compute the number of histogram bins for a pair of variables using a specified binning algorithm.

This function determines the number of bins to use for histogram-based calculations (such as mutual information or variation of information) between two variables, based on the selected binning strategy. It dispatches on the binning algorithm type and uses the appropriate method for each:

• For BinWidthBins, it computes the bin width using the provided bin_width_func and computes the number of bins as the range divided by the bin width, rounding to the nearest integer. For off-diagonal pairs, it uses the maximum of the two variables' bin counts.

• For HacineGharbiRavier, it uses the Hacine-Gharbi–Ravier rule, which adapts the bin count based on the correlation and sample size.

• For an integer, it returns the specified number of bins directly.

Arguments

• bins: Binning algorithm/number.

• xj: Data vector for variable j.

• xi: Data vector for variable i.

• j: Index of variable j.

• i: Index of variable i.

• T: Number of observations (used by some algorithms).

Returns

• nbins::Int: The computed number of bins for the variable pair.

Related

• Knuth

• FreedmanDiaconis

• Scott

• HacineGharbiRavier

• bin_width

source

PortfolioOptimisers.calc_hist_data Function

calc_hist_data(xj::VecNum, xi::VecNum, bins::Integer)

Compute histogram-based marginal and joint distributions for two variables.

This function computes the normalised histograms (probability mass functions) for two variables xj and xi using the specified number of bins, as well as their joint histogram. It returns the marginal entropies and the joint histogram, which are used in mutual information and variation of information calculations.

Arguments

• xj: Data vector for variable j.

• xi: Data vector for variable i.

• bins: Number of bins to use for the histograms.

Returns

• ex::Number: Entropy of xj.

• ey::Number: Entropy of xi.

• hxy::Matrix{<:Number}: Joint histogram (counts, not normalised to probability).

Details

• The histograms are computed using StatsAPI.fit(StatsBase.Histogram, ...) over the range of each variable, with bin edges expanded slightly using eps to ensure all data is included.

• The marginal histograms are normalised to sum to 1 before entropy calculation.

• The joint histogram is not normalised, as it is used directly in mutual information calculations.

Related

• variation_info

• mutual_info

source

PortfolioOptimisers.intrinsic_mutual_info Function

intrinsic_mutual_info(X::MatNum)

Compute the intrinsic mutual information from a joint histogram.

This function computes the mutual information between two variables given their joint histogram matrix X. It is used as a core step in information-theoretic measures such as mutual information and variation of information.

Mathematical definition

Given the joint histogram $\mathbf{X}$ (unnormalised counts), with marginals $p_i=\sum _j{X}_{ij}/n$ and $p_j=\sum _i{X}_{ij}/n$:

$$\begin{array}{rl}\hat{I}(X;Y)& =\sum _{i,j:X_{ij}>0}\frac{X_{ij}}{n}\log \left(\frac{X_{ij}/n}{p_i{p}_j}\right).\end{array}$$

Where:

• $\hat{I}(X;Y)$: Estimated mutual information between $X$ and $Y$.

• $X_{ij}$: Joint histogram count at bin $(i,j)$.

• $n=\sum _{i,j}{X}_{ij}$: Total count.

• $p_i=\sum _j{X}_{ij}/n$, $p_j=\sum _i{X}_{ij}/n$: Marginal probabilities.

Arguments

• X: Joint histogram matrix.

Returns

• mi::Number: The intrinsic mutual information between the two variables.

Details

• The function computes marginal distributions by summing over rows and columns.

• Only nonzero entries in the joint histogram are considered.

• The mutual information is computed as the sum over all nonzero joint probabilities of p(x, y) * log(p(x, y) / (p(x) * p(y))), with careful handling of log and normalisation.

Related

• calc_hist_data

• variation_info

• mutual_info

source

PortfolioOptimisers.variation_info Function

variation_info(X::MatNum;
               bins::Int_Bin = HacineGharbiRavier(),
               normalise::Bool = true)

Compute the variation of information (VI) matrix for a set of variables.

This function computes the pairwise variation of information between all columns of the data matrix X, using histogram-based entropy and mutual information estimates. VI quantifies the amount of information lost and gained when moving from one variable to another, and is a true metric on the space of discrete distributions.

Mathematical definition

Let $H(X)$, $H(Y)$ denote the marginal Shannon entropies and $I(X;Y)$ the mutual information. The variation of information is:

$$\begin{array}{rl}\mathrm{VI}(X,Y)& =H(X)+H(Y)-2I(X;Y).\end{array}$$

Where:

• $\mathrm{VI}(X,Y)$: Variation of information between $X$ and $Y$.

• $H(X)$, $H(Y)$: Marginal Shannon entropies.

• $I(X;Y)$: Mutual information.

When normalise = true, it is divided by the joint entropy $H(X,Y)=H(X)+H(Y)-I(X;Y)$:

$$\begin{array}{rl}\widetilde{\mathrm{VI}}(X,Y)& =\frac{H(X)+H(Y)-2I(X;Y)}{H(X)+H(Y)-I(X;Y)}.\end{array}$$

Where:

• $\widetilde{\mathrm{VI}}(X,Y)$: Normalised variation of information.

• $H(X,Y)=H(X)+H(Y)-I(X;Y)$: Joint entropy.

Arguments

• X: Data matrix (observations × variables).

• bins: Binning algorithm or fixed number of bins.

• normalise: Whether to normalise the VI by the joint entropy.

Returns

• var_mtx::Matrix{<:Number}: Symmetric matrix of pairwise variation of information values.

Details

• For each pair of variables, the function computes marginal entropies and the joint histogram using calc_hist_data.

• The mutual information is computed using intrinsic_mutual_info.

• VI is calculated as H(X) + H(Y) - 2 * LinearAlgebra.I(X, Y). If normalise is true, it is divided by the joint entropy.

• The result is clamped to [0, typemax(eltype(X))] and is symmetric.

Related

• mutual_info

• calc_hist_data

• intrinsic_mutual_info

source

PortfolioOptimisers.mutual_info Function

mutual_info(X::MatNum;
            bins::Int_Bin = HacineGharbiRavier(),
            normalise::Bool = true)

Compute the mutual information (MI) matrix for a set of variables.

This function computes the pairwise mutual information between all columns of the data matrix X, using histogram-based entropy and mutual information estimates. MI quantifies the amount of shared information between pairs of variables, and is widely used in information-theoretic analysis of dependencies.

Mathematical definition

Mutual information between assets $i$ and $j$:

$$\begin{array}{rl}I(X_i;X_j)& =H(X_i)+H(X_j)-H(X_i,X_j)=\sum _{x,y}p(x,y)\log \frac{p(x,y)}{p(x)p(y)}.\end{array}$$

Where:

• $I(X_i;X_j)$: Mutual information between assets $i$ and $j$.

• $H(X_i)$, $H(X_j)$: Marginal Shannon entropies.

• $H(X_i,X_j)$: Joint entropy.

• $p(x,y)$: Joint probability mass function.

When normalise = true, the MI is normalised by the minimum marginal entropy:

$$\begin{array}{rl}\tilde{I}(X_i;X_j)& =\frac{I(X_i;X_j)}{min(H(X_i),H(X_j))}.\end{array}$$

Where:

• $\tilde{I}(X_i;X_j)$: Normalised mutual information.

Arguments

• X: Data matrix (observations × variables).

• bins: Binning algorithm or fixed number of bins.

• normalise: Whether to normalise the MI by the minimum marginal entropy.

Returns

• mut_mtx::Matrix{<:Number}: Symmetric matrix of pairwise mutual information values.

Details

• For each pair of variables, the function computes marginal entropies and the joint histogram using calc_hist_data.

• The mutual information is computed using intrinsic_mutual_info.

• If normalise is true, the MI is divided by the minimum of the two marginal entropies.

• The result is clamped to [0, typemax(eltype(X))] and is symmetric.

Related

• variation_info

• calc_hist_data

• intrinsic_mutual_info

source

PortfolioOptimisers.mutual_variation_info Function

mutual_variation_info(X::MatNum, bins::Int_Bin = Knuth(), normalise::Bool = true)

Compute the pairwise mutual information and variation of information matrices from a data matrix.

Arguments

• X: Data matrix of shape (T, N) (observations × assets).

• bins: Binning algorithm or integer number of bins for histogram computation.

• normalise: If true, normalises the mutual information and variation of information.

Returns

• (mut_mtx, var_mtx): Tuple of symmetric matrices for mutual information and variation of information.

Related

• Int_Bin

• AbstractBins

source