Distance: private API

PortfolioOptimisers.RhoDistanceAlgorithm — Type
const RhoDistanceAlgorithm = Union{SimpleDistance, SimpleAbsoluteDistance,
                                   LogDistance, CorrelationDistance}

Union of the correlation-based distance algorithms. _dist_from_cor computes the distance matrix of each from a correlation matrix alone. The union does not include VariationInfoDistance, which reads the data matrix. It does not include CanonicalDistance either, which is a redirect that selects one of the other algorithms from the covariance estimator.

Related

source
PortfolioOptimisers._as_correlation — Function
_as_correlation(rho::MatNum, sym::Symbol = :rho) -> MatNum

Return a square matrix as a correlation matrix, and convert it from a covariance matrix when its diagonal is not all ones.

The values on the diagonal decide, and the type does not. If every diagonal entry is one, the function returns the same matrix. Otherwise it reads the diagonal as the variances of a covariance matrix. The matrix processing pipeline applies the same test, so the two layers agree on what a correlation matrix is. This function does the square-matrix check once, for the matrix entry point of every correlation-based algorithm.

The conversion round-trips. Build a covariance matrix from a correlation matrix and a vector of standard deviations. This function returns that correlation matrix again.

Algorithm

  1. Check that rho is square. A failure names the argument sym.
  2. Read the diagonal of rho into s. LinearAlgebra.diag allocates, so the function never writes to rho.
  3. When every entry of s is one, return rho itself. Steps 4 and 5 do not run.
  4. Otherwise replace s with its square roots. These are the standard deviations.
  5. Divide a copy of rho by the outer product of s with cov2cor_nan!. The result is a new correlation matrix. An asset with a zero variance, or with a NaN diagonal entry, gets a NaN row, its diagonal entry included, so a distance reader refuses it, see assert_distance_reader_rows. A correlation matrix with such a row passes this step too, and its other rows are divided by one, so they do not change.

Arguments

  • rho: Correlation matrix assets × assets, or the covariance matrix to convert. The function does not mutate it on either route. Step 2 copies the diagonal, and step 5 builds a new matrix.
  • sym: Name of the argument that the square-matrix failure reports.

Validation

  • rho is square.

Returns

  • rho::MatNum: Correlation matrix assets x assets.

Related

source
PortfolioOptimisers._absguard — Function
_absguard(rho::MatNum) -> MatNum

Supply the magnitude of rho to the two algorithms that read it, and allocate no copy when the magnitude is already rho.

The guard decides only the allocation, and it does not change the mathematics. abs.(rho) equals rho entry for entry when no entry of rho is negative. So both arms return the same numbers for every input, -0.0 included. SimpleAbsoluteDistance and LogDistance use it.

A NaN compares false against zero, so a matrix that holds a NaN takes the arm that allocates. abs(NaN) is NaN, so that entry is NaN on both arms.

Algorithm

  1. Compare every entry of rho with zero. The test reads the whole matrix, because both algorithms take the magnitude of every entry.
  2. When no entry is negative, return rho itself, the same object that the caller gave.
  3. Otherwise return abs.(rho), a new matrix. One negative entry is enough to allocate a copy of the whole matrix.

Arguments

  • rho: Correlation matrix assets × assets.

Returns

  • rho::MatNum: The magnitude of the argument. It is the argument itself when the argument holds no negative entry.

Related

source
PortfolioOptimisers._dist_from_cor — Function
_dist_from_cor(alg::RhoDistanceAlgorithm, power::Option{<:Integer}, rho::MatNum) -> MatNum

Turn a correlation matrix into a distance matrix, for one of the four correlation-based algorithms.

distance and cor_and_dist both call this kernel. The two entry points get rho in different ways, and they apply the same transform to it. Eight methods cover the four algorithms of RhoDistanceAlgorithm at each of the two power cases. Every method allocates its result, and clamp! writes only into that result, so rho does not change.

Mathematical definition

Distance states the eight closed forms and the scale factor $s$. The docstring of each algorithm states the base case and the range of the correlation that it reads.

Algorithm

power selects the method, so the base case never raises rho to a power.

  1. SimpleAbsoluteDistance and LogDistance replace rho with its magnitude through _absguard. SimpleDistance and CorrelationDistance do not, and read the signed correlation.
  2. When power is an Integer, raise rho to it entry by entry. When power is nothing, leave rho as it is.
  3. SimpleDistance scales the radicand by 1//2 for an odd power, by 1//1 for an even one, and by 1//2 in the base case. The scale is a Rational, so the result keeps the element type of rho. A Float32 correlation matrix gives a Float32 distance matrix, as it does under the other three algorithms. The other three algorithms apply no scale.
  4. The three square-root algorithms clamp the radicand into $[0,\,1]$ with clamp! and take its square root. LogDistance instead takes $-\log$ and floors the result at zero with max.

Arguments

  • alg: The distance algorithm.
  • power: Optional integer exponent, which the distance algorithm applies entry by entry. Distance states which quantity it raises. nothing and 1 both give the base distance, so only power >= 2 changes the result.
  • rho: Correlation matrix assets × assets.

Returns

  • D::MatNum: Distance matrix assets x assets, in the units the distance algorithm defines.

Related

source
PortfolioOptimisers.assert_dims — Function
assert_dims(dims::Integer)
assert_dims(
    dims::Integer,
    sym::Union{AbstractString, Symbol}
)

Assert that dims selects a valid matrix dimension (dims in (1, 2)).

Arguments

  • dims: Dimension selector to check.
  • sym: Symbolic name used in the error message.

Validation

  • dims in (1, 2), which raises a DomainError that names sym and dims.

Returns

  • nothing.

Related

source
PortfolioOptimisers.dims_oriented — Function
dims_oriented(
    dims::Integer,
    A::Union{Nothing, AbstractMatrix}
) -> Any

Check dims, and return the matrices with the observations along the rows.

The check and the orientation are one call, so a caller cannot orient a matrix and skip the check of dims. All callers use this one function. A caller that writes the check and the transpose itself can omit the check, and then return the raw input for a dims of 3.

Algorithm

  1. Check dims with assert_dims.
  2. Return each matrix unchanged when dims is 1, because the observations are already along the rows.
  3. Return the transpose of each matrix when dims is 2. A nothing passes through unchanged.

Arguments

  • dims: The dimension that holds the observations.
  • A, B, Cs...: The matrices to orient. A nothing passes through unchanged, so an optional matrix needs no branch of its own.

Validation

Returns

  • A: The oriented matrix, when one matrix is given.
  • (A, B, Cs...): A tuple of the oriented matrices, when more than one is given.

Related

source