Distance

PortfolioOptimisers.Distance — Type
struct Distance{__T_power, __T_alg} <: AbstractDistanceEstimator

Pairs a distance algorithm with an optional integer power, and applies it to a correlation matrix or to the data.

Every clustering, network and phylogeny routine uses this estimator to get a distance matrix. alg selects the transform. power raises the input of that transform to the integer power $p$.

Note

power = 1 gives the base distance exactly, for every algorithm. Only $p \geq 2$ changes the result. power = nothing and power = 1 select different methods, so the base case never raises a matrix to a power.

Mathematical definition

The four correlation-based algorithms of RhoDistanceAlgorithm raise the correlation to $p$ inside their base formula.

\[\begin{align} _{g}d_{i,\,j}^{\mathrm{S}} &= \sqrt{\mathrm{clamp}\left(s\left(1 - \rho_{i,\,j}^{p}\right),\, 0,\, 1\right)}\\ _{g}d_{i,\,j}^{\mathrm{SA}} &= \sqrt{\mathrm{clamp}\left(1 - \lvert\rho_{i,\,j}\rvert^{p},\, 0,\, 1\right)}\\ _{g}d_{i,\,j}^{\mathrm{L}} &= \max\left(-\log{\lvert\rho_{i,\,j}\rvert^{p}},\, 0\right)\\ _{g}d_{i,\,j}^{\mathrm{C}} &= \sqrt{\mathrm{clamp}\left(1 - \rho_{i,\,j}^{p},\, 0,\, 1\right)}\\ s &= \begin{cases} 1/2 & \text{if } p \mod 2 \neq 0\\ 1 & \text{otherwise} \end{cases}\,, \end{align}\]

VariationInfoDistance has no correlation to raise, so it raises the distance itself.

\[\begin{align} _{g}d_{i,\,j}^{\mathrm{VI}} &= \left(d_{i,\,j}^{\mathrm{VI}}\right)^{p}\,, \end{align}\]

Where:

The two values of $s$ come from the range of $\rho_{i,\,j}^{p}$. $s$ keeps the radicand inside $[0,\,1]$, so $s = 1 / (1 - m)$, where $m$ is the smallest value that $\rho_{i,\,j}^{p}$ can take. An odd $p$ keeps the sign, so $m = -1$ and $s = 1/2$. At an even $p$, $\rho_{i,\,j}^{p}$ cannot be negative, so $m = 0$ and $s = 1$.

The clamp has no effect on the first two algorithms at any $p$, because $s(1 - \rho_{i,\,j}^{p})$ and $1 - \lvert\rho_{i,\,j}\rvert^{p}$ never leave $[0,\,1]$. It binds for CorrelationDistance at every odd $p$. There, $\rho_{i,\,j}^{p}$ keeps its sign and the radicand runs over $[0,\,2]$. The docstring of CorrelationDistance shows the truncation.

CanonicalDistance is a redirect and has no formula. It gives power to the algorithm that it selects.

`power` raises two different quantities

power is one field with two meanings. For a correlation-based algorithm, it raises the correlation inside the transform. For VariationInfoDistance, it raises the distance that the algorithm returns, because there is no correlation. So at $p = 2$, $_{g}d^{\mathrm{S}}$ is not $\left(d^{\mathrm{S}}\right)^{2}$, but $_{g}d^{\mathrm{VI}}$ is $\left(d^{\mathrm{VI}}\right)^{2}$.

The docstring of each algorithm states its base formula and its original source. The $p$ generalisation and the scale factor $s$ are this library's own extension of those formulas.

Fields

  • 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.
  • alg: The distance algorithm.

Constructors

Distance(;    power::Option{<:Integer} = nothing,    alg::AbstractDistanceAlgorithm = SimpleDistance()) -> Distance

Keywords correspond to the struct's fields.

Why the default `alg` is `SimpleDistance`

CanonicalDistance selects an algorithm from the covariance estimator. It uses SimpleDistance for every estimator outside its table. A bare Distance() also works at the matrix entry point distance(de, rho), which has no estimator to select from. So the two defaults agree, except on the estimators in the table of CanonicalDistance. A library entry point that always has a covariance estimator uses Distance(; alg = CanonicalDistance()) as its default, so that each estimator in the table gets its own algorithm.

Validation

  • If power is not nothing, power >= 1.

Examples

julia> Distance()Distance  power ┼ nothing    alg ┴ SimpleDistance()

Related

source
PortfolioOptimisers.distance — Function
distance(de::Distance{<:Any,
                      <:Union{SimpleDistance, SimpleAbsoluteDistance, LogDistance,
                              CorrelationDistance, CanonicalDistance}},
         ce::StatsBase.CovarianceEstimator, X::MatNum; dims::Int = 1, kwargs...)

Compute the correlation matrix with ce and X, and transform it into a distance matrix with the algorithm de names.

This is the data entry point of the correlation-based family. cor_and_dist does the same computation and also returns the correlation, so a caller that needs both matrices computes the correlation once.

Algorithm

  1. Compute the correlation matrix from ce and X with Statistics.cor, along dims. The method gives kwargs to Statistics.cor, and Statistics.cor refuses a dims outside $(1,\, 2)$.
  2. Transform that correlation matrix with _dist_from_cor, under de.alg and de.power.

A CanonicalDistance de does one step first. It rebuilds de with SimpleDistance and keeps de.power, because the last row of the redirect table gives that algorithm to a plain StatsBase.CovarianceEstimator. The estimators of the other rows have their own methods, and the table on CanonicalDistance lists them.

Arguments

  • de: Distance estimator.

  • ce: Covariance estimator.

  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.

  • dims: Dimension along which the computation runs.

  • kwargs...: Keyword arguments that the method gives to Statistics.cor.

Validation

  • dims in (1, 2). This method does not do the check. Statistics.cor raises the DomainError.

Returns

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

Related

source
distance(de::Distance{Nothing, <:VariationInfoDistance}, ::Any, X::MatNum;
         dims::Int = 1, kwargs...)
distance(de::Distance{<:Integer, <:VariationInfoDistance}, ::Any, X::MatNum;
         dims::Int = 1, kwargs...)

Compute the variation of information distance matrix from the data matrix alone.

It is the one algorithm of the family that reads X and not a correlation matrix. So the covariance estimator is a placeholder, and the method ignores it.

`power` raises the distance here, not the correlation

The two signatures above are the two power cases. For a correlation-based algorithm, power raises the correlation inside the transform. Here there is no correlation, so power raises the distance that the algorithm returns. The result is variation_info(...) .^ de.power.

Algorithm

  1. Orient X with dims_oriented, which transposes it when dims is 2 and refuses any other value.
  2. Read de.alg.bins and de.alg.normalise off the algorithm, and pass both to variation_info, which builds the joint histograms and forms the distance. VariationInfoDistance states those steps.
  3. When de.power is an Integer, raise the distance matrix of step 2 to it entry by entry. When de.power is nothing, return that matrix unchanged.

Arguments

  • de: Distance estimator that holds the VariationInfoDistance algorithm.
  • ::Any: Placeholder for the covariance estimator, so that this method takes the same call as the other methods. The method ignores it.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: Keyword arguments that the method ignores. bins and normalise come from de.alg, never from a keyword.

Validation

  • dims in (1, 2). This method does not do the check. dims_oriented raises the DomainError.

Returns

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

Related

source
distance(::Distance{<:Any,
                    <:Union{SimpleDistance, SimpleAbsoluteDistance, LogDistance,
                            CorrelationDistance, CanonicalDistance}},
         rho::MatNum, args...; kwargs...)

Compute the distance matrix from a correlation matrix, or from a covariance matrix.

This is the matrix entry point of the correlation-based family, for a caller that already has the matrix. The diagonal tells a correlation matrix from a covariance matrix, as _as_correlation states. The result is the distance that the algorithm defines. It is not the Euclidean distance between the columns of the data. SimpleDistance and SimpleAbsoluteDistance return an angular distance, and LogDistance returns an unbounded dissimilarity.

Algorithm

  1. Convert rho to a correlation matrix with _as_correlation, which also checks that it is square.
  2. Transform that correlation matrix with _dist_from_cor, under de.alg and de.power.

A CanonicalDistance de does one step first. It rebuilds de with SimpleDistance and keeps de.power. Here there is no covariance estimator to select from, so the method uses the last row of the redirect table.

Arguments

  • de: Distance estimator.

  • rho: Correlation or covariance matrix. _as_correlation converts a covariance matrix into a new matrix with StatsBase.cov2cor, and does not write into the argument.

  • args...: Arguments that the method ignores. They let this method and the ce-and-X method above take the same call.

  • kwargs...: Keyword arguments that the method ignores. They let this method and the ce-and-X method above take the same call.

Validation

  • rho is square.

Returns

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

Related

source
distance(de::Distance{<:Any, <:CanonicalDistance},
         ce::Union{MutualInfoCovariance,
                   AllInternalMutualInfoCov,
                   LTDCov_AllInternalLTDCov,
                   DistCov_AllInternalDistCov},
         X::MatNum; dims::Int = 1, kwargs...)

Rebuild de with the distance algorithm that fits the range of the covariance estimator, and call distance again.

The redirect has no formula. It sends each codependence measure to the transform that fits its range. A signed correlation needs the factor $1/2$. A mutual information has no correlation to transform. A tail dependence coefficient needs an unbounded distance. The selected algorithm gets de.power unchanged.

Covariance estimatorAlgorithm selectedRead from ce
MutualInfoCovarianceVariationInfoDistancece.bins, ce.normalise
PortfolioOptimisersCovariance that wraps itVariationInfoDistancece.ce.bins, ce.ce.normalise
LowerTailDependenceCovariance, wrapped or notLogDistancenothing
DistanceCovariance, wrapped or notCorrelationDistancenothing
any other StatsBase.CovarianceEstimatorSimpleDistancenothing

The last row is the fallback. On every estimator of that row, the redirect and a bare Distance with SimpleDistance give the same result.

Algorithm

  1. Select the row of the table above by the type of ce. Dispatch does the selection, so a wrapper reaches the same row as the estimator that it wraps.
  2. Build a new Distance with de.power and the algorithm of that row.
  3. On the two mutual information rows, copy bins and normalise from ce to the new VariationInfoDistance. For the wrapper, read them from ce.ce. The signature does not show this step, but the result depends on it. A MutualInfoCovariance with a non-default bins gives a different distance matrix from one with the default bins.
  4. Call distance with the rebuilt estimator, the same ce, and the same X, dims and kwargs.

Arguments

  • de: Distance estimator that holds the CanonicalDistance algorithm.
  • ce: Covariance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: Keyword arguments that the method gives to the distance method of the selected algorithm.

Returns

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

Related

source
distance(de::DistanceDistance, ce::StatsBase.CovarianceEstimator, X::MatNum;
         dims::Int = 1, kwargs...)

Compute the distance-of-distances matrix from a covariance estimator and a data matrix.

Algorithm

  1. Build a base Distance with de.power and de.alg. Call distance on it with ce, X, dims and kwargs. The result is the base distance matrix D.
  2. Apply de.metric to D with Distances.pairwise, and give it the fields de.args and de.kwargs. The result is the distance-of-distances matrix.

When alg is a CanonicalDistance, step 1 selects the algorithm of D by the type of ce. The metric runs after that selection. distance holds the redirect table.

Distances.pairwise reads each column of D as one observation. The call passes dims = 2 before the splat of de.kwargs, so a dims in de.kwargs replaces it. The axis does not change the result, because a base distance matrix is symmetric. The axis matters only when de.args holds a second matrix of a different shape.

Arguments

  • de: The distance-of-distances estimator.
  • ce: The covariance estimator.
  • X: The data matrix, with one row per observation and one column per asset when dims = 1.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments for the base distance of step 1. They do not reach Distances.pairwise, which reads the field de.kwargs.

Returns

  • D::Matrix{<:Number}: The matrix of the pairwise distances of distances.

Related

source
distance(de::DistanceDistance, rho::MatNum, args...; kwargs...)

Compute the distance-of-distances matrix from a correlation or covariance matrix.

Algorithm

  1. Build a base Distance with de.power and de.alg. Call distance on it with rho, args and kwargs. The result is the base distance matrix D.
  2. Apply de.metric to D with Distances.pairwise, and give it the fields de.args and de.kwargs. The result is the distance-of-distances matrix.

When alg is a CanonicalDistance, the base distance replaces it with SimpleDistance before step 1. This route has no covariance estimator, so the redirect table cannot select a row, and the base distance takes the fallback of the table.

Distances.pairwise reads the columns of D, as it does on the route of the covariance estimator above. The call passes dims = 2, and a dims in de.kwargs replaces it.

Arguments

  • de: The distance-of-distances estimator.
  • rho: The correlation or covariance matrix.
  • args...: More positional arguments. The method gives them to the base distance of step 1, which ignores them. They are not the field de.args, which goes to Distances.pairwise.
  • kwargs...: More keyword arguments for the base distance of step 1. They do not reach Distances.pairwise, which reads the field de.kwargs.

Returns

  • D::Matrix{<:Number}: The matrix of the pairwise distances of distances.

Related

source
distance(de::FeatureDistance, Z::MatNum; dims::Int = 1, amsk = nothing, nx = nothing,
         kwargs...)
distance(de::FeatureDistance, Z::Arr3Num; dims::Int = 1, amsk = nothing, nx = nothing,
         kwargs...)

Compute the distance matrix from a feature matrix.

The 2-D method collapses nothing. A static feature matrix has no observation axis, so the collapse algorithm reads its one row. Its amsk is 1 × assets. The mask marks the assets whose every value column holds data, and the method refuses an asset that the mask marks false. The 3-D method dispatches on the collapse algorithm. An asset whose feature vector is all zero takes the convention that patch_zero_feature_vectors! states.

The 3-D method reads the mask amsk of the window. A collapse then reads each asset, or each pair of assets, at its own active rows, as each member of AbstractFeatureCollapseAlgorithm states. A window with no inactive cell gives the same result as no mask. The checks read the same cells as the collapse, so the value of a cell that amsk marks false changes neither the distance nor a refusal.

Algorithm

  1. Check dims with assert_dims.
  2. On the 2-D method, check the one-row mask with static_window and assert_feature_readable. Validate Z with assert_feature_matrix, and pass de.metric and Z to the kernel.
  3. On the 3-D method, check the mask with active_window, and check that the collapse can read each asset with assert_feature_readable.
  4. With no inactive cell, validate Z with assert_feature_matrix. Pass de and Z to feature_distance, which selects the method that de.alg names.
  5. Otherwise, put a zero at each inactive cell of a copy of Z with blank_unreadable. Validate the copy with assert_feature_matrix, and pass it to active_feature_distance.

Arguments

  • de: Feature distance estimator.
  • Z: Feature matrix, assets × features when dims = 1 and features × assets when dims = 2. It can also be a 3-D array of time-varying features, whose last axis is always the observation axis: assets × features × observations when dims = 1, and features × assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • amsk: The mask of readable cells of the window, observations × assets on the 3-D method and 1 × assets on the 2-D method, or nothing when every cell is readable.
  • nx: The asset names that a refusal quotes, or nothing to quote positions.
  • kwargs...: Additional keyword arguments (ignored).

Validation

  • dims in (1, 2).
  • amsk is observations × assets on the 3-D method and 1 × assets on the 2-D method, and the collapse can read each asset. See assert_feature_readable.
  • !isempty(Z).
  • Each cell of Z that amsk marks readable is finite and lies in the domain of de.metric. See assert_metric_domain. The check reads no cell that amsk marks false.
  • On the 3-D method, a pair of assets with no shared active row takes the rule of the pair field of AggregateDistances and StackObservations.

Returns

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

Examples

julia> Z = [1.0 0.0; 0.0 1.0; 1.0 1.0];julia> distance(FeatureDistance(), Z)3×3 Matrix{Float64}: 0.0   0.5   0.25 0.5   0.0   0.25 0.25  0.25  0.0

Related

source
distance(de::FeatureDistance, ::Any, X; pr = nothing, rd = nothing, kwargs...)

Compute the distance matrix of the Feature Matrix that feature_matrix stacks from pr and rd, for the clustering and network estimators.

Each consumer in the clustering and network estimators calls cor_and_dist(de, ce, X; …) or distance(de, pl, X; …), with a covariance estimator and a returns matrix. logo! passes a similarity matrix in place of the covariance estimator, so the type of the second positional argument is ::Any. FeatureDistance does not read that argument. It reads X, because a producer measures it.

The prior result and the returns data arrive as the keywords pr and rd. feature_window resolves the panel from them and from de.ape. A caller that takes a prior result passes both. Preselection passes rd alone.

This method ignores dims and calls the kernel with dims = 1. The dims of the caller describes the returns matrix X, and the stacked Feature Matrix always has the layout of dims = 1. dims has a meaning only at the entry point for a raw matrix, distance(de, Z; dims).

Algorithm

  1. Stack the Feature Matrix with feature_window, which resolves the panel and cuts it to de.sel and to the observation rows that de.alg reads. It also returns the mask of the readable cells of those rows. A cell is readable when the asset is active and every value column of de.sel holds data, observed or filled.
  2. Compute the distance matrix D of that stack with the two-argument method at dims = 1, with that mask and the asset names from feature_asset_names.

Arguments

  • de: Feature distance estimator.
  • The second positional argument: ignored. It exists so that this method matches the signature that every consumer calls.
  • X: Returns matrix of the subproblem, observations × assets. A producer reads it.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use.
  • kwargs...: Additional keyword arguments (ignored), dims among them.

Validation

  • The panel resolves. asset_panel raises an IsNothingError that names the site when it does not.
  • Under de.strict = true, every entry of de.sel names a Panel Field, a level, a label or a group that the panel holds. Raises an ArgumentError. Under de.strict = false, such an entry warns, and the estimator drops it.
  • The stacked Feature Matrix passes assert_feature_matrix at dims = 1 at its readable cells. It is not empty, and each cell that the mask marks readable is finite and lies in the domain of de.metric. The value of an unreadable cell causes no refusal.
  • The collapse can read each asset at the readable rows of the window. See assert_feature_readable. A pair with no shared readable row takes the pair rule of its collapse. A fit drops an unreadable asset at its entry with feature_readable_mask, and this call refuses it.

Returns

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

Related

source
PortfolioOptimisers.cor_and_dist — Function
cor_and_dist(de::Distance{<:Any,
                          <:Union{SimpleDistance, SimpleAbsoluteDistance,
                                  LogDistance, CorrelationDistance,
                                  VariationInfoDistance, CanonicalDistance}},
             ce::StatsBase.CovarianceEstimator, X::MatNum; dims::Int = 1, kwargs...)

Compute the correlation matrix and the distance matrix in one call.

It returns the same D that distance returns for the same arguments. Use it when the caller needs both matrices, because a correlation-based algorithm then computes the correlation once and not twice. The returned rho is the correlation that ce computes, with no transform. It is not the magnitude that SimpleAbsoluteDistance and LogDistance take, and de.power does not raise it.

Algorithm

de.alg selects one of three routes.

  1. A correlation-based algorithm computes the correlation matrix with Statistics.cor. Then it transforms that same matrix with _dist_from_cor. On this route the correlation is computed once.
  2. VariationInfoDistance checks dims with assert_dims, computes the correlation matrix for the caller, and calls distance for the distance. The distance reads X and not the correlation, so the two computations share nothing.
  3. CanonicalDistance rebuilds de with the algorithm that its redirect table names for ce. Then it enters route 1 or route 2. The CanonicalDistance method of distance gives the table and the fields that the rebuild copies.

Arguments

  • de: Distance estimator.
  • ce: Covariance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: Keyword arguments that the method gives to Statistics.cor.

Validation

  • dims in (1, 2). Route 2 does the check with assert_dims. On route 1, Statistics.cor does the check and raises the same DomainError.

Returns

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

Related

source
cor_and_dist(de::DistanceDistance, ce::StatsBase.CovarianceEstimator, X::MatNum;
             dims::Int = 1, kwargs...)

Compute the correlation matrix and the distance-of-distances matrix from a covariance estimator and a data matrix.

Algorithm

  1. Build a base Distance with de.power and de.alg. Call cor_and_dist on it with ce, X, dims and kwargs. One pass gives the correlation matrix rho and the base distance matrix D.
  2. Apply de.metric to D with Distances.pairwise, and give it the fields de.args and de.kwargs. The result is the distance-of-distances matrix.
  3. Return rho without a change, together with that matrix. The metric reads the distance matrix alone, so the method returns the correlation of the base estimator.

The second element is the matrix that distance returns for the same de, ce and X. A caller that needs the two matrices then computes one correlation, not two.

Arguments

  • de: The distance-of-distances estimator.
  • ce: The covariance estimator.
  • X: The data matrix, with one row per observation and one column per asset when dims = 1.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments for the base distance of step 1. They do not reach Distances.pairwise, which reads the field de.kwargs.

Returns

  • (rho::Matrix{<:Number}, D::Matrix{<:Number}): The tuple of the correlation matrix and the distance-of-distances matrix.

Related

source
cor_and_dist(de::FeatureDistance, Z::MatNum; dims::Int = 1, kwargs...)
cor_and_dist(de::FeatureDistance, Z::Arr3Num; dims::Int = 1, kwargs...)

Compute the similarity and distance matrices from a feature matrix.

The similarity is distance_to_similarity(de.sim; D = D), which the call computes from the distance matrix that it returns. S and D come from one measurement, not from two independent estimates. Under AggregateDistances, the similarity comes from the aggregated distance, so the convention for a zero feature vector holds in S too, because $\mathrm{mean}(\cos(\pi D_{t})) \neq \cos(\pi\,\mathrm{mean}(D_{t}))$.

Algorithm

  1. Compute the distance matrix D with distance, which also validates Z and dims.
  2. Transform D with distance_to_similarity under de.sim to get S.

Arguments

  • de: Feature distance estimator.
  • Z: Feature matrix, assets × features when dims = 1 and features × assets when dims = 2. It can also be a 3-D array of time-varying features, whose last axis is always the observation axis: assets × features × observations when dims = 1, and features × assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: Additional keyword arguments (ignored).

Validation

  • The checks of distance: the mask, !isempty(Z), and each readable cell of Z is finite and lies in the domain of de.metric. See assert_metric_domain.

Returns

  • S::Matrix{<:Number}: Similarity matrix, assets × assets.
  • D::MatNum: Distance matrix assets x assets, in the units the distance algorithm defines.

Examples

julia> Z = [1.0 0.0; 0.0 1.0; 1.0 1.0];julia> S, D = cor_and_dist(FeatureDistance(), Z);julia> S3×3 Matrix{Float64}: 1.0          6.12323e-17  0.707107 6.12323e-17  1.0          0.707107 0.707107     0.707107     1.0

Related

source
cor_and_dist(de::FeatureDistance, ::Any, X; pr = nothing, rd = nothing, kwargs...)

Compute the similarity and distance matrices of the Feature Matrix that feature_matrix stacks from pr and rd, for the clustering and network estimators.

clusterise and the network estimators call this method. It reads its arguments as the three-argument distance method does. It ignores the second positional argument and dims, it passes X to a producer, and it resolves the panel from pr and rd.

Algorithm

  1. Stack the Feature Matrix with feature_window, which resolves the panel and cuts it to de.sel and to the observation rows that de.alg reads. It also returns the mask of the readable cells of those rows. A cell is readable when the asset is active and every value column of de.sel holds data, observed or filled.
  2. Compute the similarity matrix S and the distance matrix D of that stack with the two-argument method at dims = 1, with that mask and the asset names from feature_asset_names.

Arguments

  • de: Feature distance estimator.
  • The second positional argument: ignored. It exists so that this method matches the signature that every consumer calls.
  • X: Returns matrix of the subproblem, observations × assets. A producer reads it.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use.
  • kwargs...: Additional keyword arguments (ignored), dims among them.

Validation

  • The panel resolves. asset_panel raises an IsNothingError that names the site when it does not.
  • Under de.strict = true, every entry of de.sel names a Panel Field, a level, a label or a group that the panel holds. Raises an ArgumentError. Under de.strict = false, such an entry warns, and the estimator drops it.
  • The stacked Feature Matrix passes assert_feature_matrix at dims = 1 at its readable cells. It is not empty, and each cell that the mask marks readable is finite and lies in the domain of de.metric. The value of an unreadable cell causes no refusal.
  • The collapse can read each asset at the readable rows of the window. See assert_feature_readable. A pair with no shared readable row takes the pair rule of its collapse. A fit drops an unreadable asset at its entry with feature_readable_mask, and this call refuses it.

Returns

  • S::Matrix{<:Number}: Similarity matrix, assets × assets, derived from D under de.sim.
  • D::MatNum: Distance matrix assets x assets, in the units the distance algorithm defines.

Related

source