Phylogeny Constraints

PortfolioOptimisers.SemiDefinitePhylogenyEstimator Type

struct SemiDefinitePhylogenyEstimator{T1, T2} <: AbstractPhylogenyConstraintEstimator
    pe::T1
    p::T2
end

Estimator for generating semi-definite phylogeny-based constraints in PortfolioOptimisers.jl.

SemiDefinitePhylogenyEstimator constructs constraints based on phylogenetic or clustering structures among assets, using a semi-definite matrix representation. The estimator wraps a phylogeny or clustering estimator and a non-negative penalty parameter p, which controls the strength of the constraint.

Fields

• pe: Phylogeny or clustering estimator.

• p: Non-negative penalty parameter for the constraint.

Constructor

SemiDefinitePhylogenyEstimator(;
                               pe::Union{<:AbstractPhylogenyEstimator,
                                         <:AbstractClusteringResult} = NetworkEstimator(),
                               p::Real = 0.05)

Validation

• p >= 0.

Examples

julia> SemiDefinitePhylogenyEstimator()
SemiDefinitePhylogenyEstimator
  pe ┼ NetworkEstimator
     │    ce ┼ PortfolioOptimisersCovariance
     │       │   ce ┼ Covariance
     │       │      │    me ┼ SimpleExpectedReturns
     │       │      │       │   w ┴ nothing
     │       │      │    ce ┼ GeneralCovariance
     │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
     │       │      │       │    w ┴ nothing
     │       │      │   alg ┴ Full()
     │       │   mp ┼ DefaultMatrixProcessing
     │       │      │       pdm ┼ Posdef
     │       │      │           │   alg ┴ UnionAll: NearestCorrelationMatrix.Newton
     │       │      │   denoise ┼ nothing
     │       │      │    detone ┼ nothing
     │       │      │       alg ┴ nothing
     │    de ┼ Distance
     │       │   power ┼ nothing
     │       │     alg ┴ CanonicalDistance()
     │   alg ┼ KruskalTree
     │       │     args ┼ Tuple{}: ()
     │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
     │     n ┴ Int64: 1
   p ┴ Float64: 0.05

Related

• SemiDefinitePhylogeny

• AbstractPhylogenyEstimator

• AbstractClusteringResult

• phylogeny_constraints

source

PortfolioOptimisers.SemiDefinitePhylogeny Type

struct SemiDefinitePhylogeny{T1, T2} <: AbstractPhylogenyConstraintResult
    A::T1
    p::T2
end

Container for the result of semi-definite phylogeny-based constraint generation.

SemiDefinitePhylogeny stores the constraint matrix A and penalty parameter p resulting from a semi-definite phylogeny constraint estimator. This type is used to encapsulate the output of phylogeny-based constraint routines, enabling composable and modular constraint handling in portfolio optimisation workflows.

Fields

• A: Phylogeny matrix encoding a relationship graph.

• p: Non-negative penalty parameter controlling the strength of the constraint.

Constructor

SemiDefinitePhylogeny(;
                      A::Union{<:PhylogenyResult{<:AbstractMatrix{<:Real}},
                               <:AbstractMatrix{<:Real}}, p::Real = 0.05)

Validation

• issymmetric(A) and all(iszero, diag(A)).

• p >= 0.

Examples

julia> SemiDefinitePhylogeny([0.0 1.0; 1.0 0.0], 0.05)
SemiDefinitePhylogeny
  A ┼ 2×2 Matrix{Float64}
  p ┴ Float64: 0.05

Related

• SemiDefinitePhylogenyEstimator

• AbstractPhylogenyConstraintResult

• phylogeny_constraints

source

PortfolioOptimisers.IntegerPhylogenyEstimator Type

struct IntegerPhylogenyEstimator{T1, T2, T3} <: AbstractPhylogenyConstraintEstimator
    pe::T1
    B::T2
    scale::T3
end

Estimator for generating integer phylogeny-based constraints in PortfolioOptimisers.jl.

IntegerPhylogenyEstimator constructs constraints based on phylogenetic or clustering structures among assets, using integer or discrete representations. The estimator wraps a phylogeny or clustering estimator, a non-negative integer or vector of integers B specifying group sizes or allocations, and a big-M parameter scale used for formulating the MIP constraints.

Fields

• pe: Phylogeny or clustering estimator.

• B: Non-negative integer or vector of integers specifying group sizes or allocations.

• scale: Non-negative big-M parameter for the MIP formulation.

Constructor

IntegerPhylogenyEstimator(;
                          pe::Union{<:AbstractPhylogenyEstimator,
                                    <:AbstractClusteringResult} = NetworkEstimator(),
                          B::Union{<:Integer, <:AbstractVector{<:Integer}} = 1,
                          scale::Real = 100_000.0)

Validation

• B is validated with assert_nonneg_finite_val.
  • AbstractVector: it is additionally validated with validate_length_integer_phylogeny_constraint_B.

Examples

julia> IntegerPhylogenyEstimator()
IntegerPhylogenyEstimator
     pe ┼ NetworkEstimator
        │    ce ┼ PortfolioOptimisersCovariance
        │       │   ce ┼ Covariance
        │       │      │    me ┼ SimpleExpectedReturns
        │       │      │       │   w ┴ nothing
        │       │      │    ce ┼ GeneralCovariance
        │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
        │       │      │       │    w ┴ nothing
        │       │      │   alg ┴ Full()
        │       │   mp ┼ DefaultMatrixProcessing
        │       │      │       pdm ┼ Posdef
        │       │      │           │   alg ┴ UnionAll: NearestCorrelationMatrix.Newton
        │       │      │   denoise ┼ nothing
        │       │      │    detone ┼ nothing
        │       │      │       alg ┴ nothing
        │    de ┼ Distance
        │       │   power ┼ nothing
        │       │     alg ┴ CanonicalDistance()
        │   alg ┼ KruskalTree
        │       │     args ┼ Tuple{}: ()
        │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
        │     n ┴ Int64: 1
      B ┼ Int64: 1
  scale ┴ Float64: 100000.0

Related

• IntegerPhylogeny

• AbstractPhylogenyConstraintEstimator

• AbstractClusteringResult

• phylogeny_constraints

source

PortfolioOptimisers.IntegerPhylogeny Type

struct IntegerPhylogeny{T1, T2, T3} <: AbstractPhylogenyConstraintResult
    A::T1
    B::T2
    scale::T3
end

Container for the result of integer phylogeny-based constraint generation.

IntegerPhylogeny stores the constraint matrix A, group sizes or allocations B, and scaling parameter scale resulting from an integer phylogeny constraint estimator. This type encapsulates the output of integer/discrete phylogeny-based constraint routines, enabling composable and modular constraint handling in portfolio optimisation workflows.

Fields

• A: Phylogeny matrix encoding asset relationships.

• B: Non-negative integer or vector of integers specifying group sizes or allocations.

• scale: Non-negative scaling parameter (big-M) for the constraint.

Constructor

IntegerPhylogeny(;
                 A::Union{<:PhylogenyResult{<:AbstractMatrix{<:Real}},
                          <:AbstractMatrix{<:Real}},
                 B::Union{<:Integer, <:AbstractVector{<:Integer}} = 1,
                 scale::Real = 100_000.0)

Validation

• issymmetric(A) and all(iszero, diag(A)).

• B is validated with assert_nonneg_finite_val.

  • AbstractVector: size(unique(A + I; dims = 1), 1) == length(B).

Examples

julia> IntegerPhylogeny(; A = [0.0 1.0; 1.0 0.0], B = 2, scale = 100_000.0)
IntegerPhylogeny
      A ┼ 1×2 Matrix{Float64}
      B ┼ Int64: 2
  scale ┴ Float64: 100000.0

Related

• IntegerPhylogenyEstimator

• AbstractPhylogenyConstraintResult

• phylogeny_constraints

source

PortfolioOptimisers.phylogeny_constraints Function

phylogeny_constraints(est::Union{<:SemiDefinitePhylogenyEstimator,
                                 <:IntegerPhylogenyEstimator, <:SemiDefinitePhylogeny,
                                 <:IntegerPhylogeny, Nothing}, X::AbstractMatrix;
                      dims::Int = 1, kwargs...)

Generate phylogeny-based portfolio constraints from an estimator or result.

phylogeny_constraints constructs constraint objects based on phylogenetic, clustering, or network structures among assets. It supports both semi-definite and integer constraint forms, accepting either an estimator (which wraps a phylogeny or clustering model and penalty parameters) or a precomputed result. If est is nothing, returns nothing.

Arguments

• est: A phylogeny constraint estimator, result, or nothing.

• X: Data matrix of asset features or returns (ignored when est is not an estimator).

• dims: Dimension along which to compute the phylogeny (ignored when est is not an estimator).

• kwargs...: Additional keyword arguments passed to the underlying phylogeny matrix routine (ignored when est is not an estimator).

Returns

• SemiDefinitePhylogeny: For semi-definite constraint estimators/results.

• IntegerPhylogeny: For integer constraint estimators/results.

• nothing: If est is nothing.

Details

• est:

  • Union{<:SemiDefinitePhylogenyEstimator, <:IntegerPhylogenyEstimator}: computes the phylogeny matrix using the estimator.

  • Union{Nothing, <:SemiDefinitePhylogeny, <:IntegerPhylogeny}: returns it unchanged.

Related

• SemiDefinitePhylogenyEstimator

• IntegerPhylogenyEstimator

• SemiDefinitePhylogeny

• IntegerPhylogeny

• AbstractPhylogenyConstraintEstimator

• AbstractPhylogenyConstraintResult

• phylogeny_matrix

source

PortfolioOptimisers.MinValue Type

struct MinValue <: VectorToRealMeasure end

Algorithm for reducing a vector of real values to its minimum.

MinValue is a concrete subtype of VectorToRealMeasure that returns the minimum value of a vector. It is used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics by their minimum.

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MinValue(), [1.2, 3.4, 0.7])
0.7

Related

• VectorToRealMeasure

• MeanValue

• MedianValue

• MaxValue

• vec_to_real_measure

source

PortfolioOptimisers.MeanValue Type

struct MeanValue <: VectorToRealMeasure end

Algorithm for reducing a vector of real values to its mean.

MeanValue is a concrete subtype of VectorToRealMeasure that returns the mean (average) value of a vector. It is used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics by their mean.

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MeanValue(), [1.2, 3.4, 0.7])
1.7666666666666666

Related

• VectorToRealMeasure

• MinValue

• MedianValue

• MaxValue

• vec_to_real_measure

source

PortfolioOptimisers.MedianValue Type

struct MedianValue <: VectorToRealMeasure end

Algorithm for reducing a vector of real values to its median.

MedianValue is a concrete subtype of VectorToRealMeasure that returns the median value of a vector. It is used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics by their median.

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MedianValue(), [1.2, 3.4, 0.7])
1.2

Related

• VectorToRealMeasure

• MinValue

• MeanValue

• MaxValue

• vec_to_real_measure

source

PortfolioOptimisers.MaxValue Type

struct MaxValue <: VectorToRealMeasure end

Algorithm for reducing a vector of real values to its maximum.

MaxValue is a concrete subtype of VectorToRealMeasure that returns the maximum value of a vector. It is used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics by their maximum.

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MaxValue(), [1.2, 3.4, 0.7])
3.4

Related

• VectorToRealMeasure

• MinValue

• MeanValue

• MedianValue

• vec_to_real_measure

source

PortfolioOptimisers.CentralityConstraint Type

struct CentralityConstraint{T1, T2, T3} <: AbstractPhylogenyConstraintEstimator
    A::T1
    B::T2
    comp::T3
end

Estimator for generating centrality-based portfolio constraints.

CentralityConstraint constructs constraints based on asset centrality measures within a phylogeny or network structure. It wraps a centrality estimator A, a VectorToRealMeasure measure or threshold B, and a comparison operator comp ComparisonOperator. This enables flexible constraint generation based on asset centrality, supporting both inequality and equality forms.

Fields

• A: Centrality estimator.

• B: Real value or reduction measure.

• comp: Comparison operator.

Constructor

CentralityConstraint(; A::CentralityEstimator = CentralityEstimator(),
                     B::Union{<:Real, <:VectorToRealMeasure} = MinValue(),
                     comp::ComparisonOperator = LEQ())

Examples

julia> CentralityConstraint()
CentralityConstraint
     A ┼ CentralityEstimator
       │     ne ┼ NetworkEstimator
       │        │    ce ┼ PortfolioOptimisersCovariance
       │        │       │   ce ┼ Covariance
       │        │       │      │    me ┼ SimpleExpectedReturns
       │        │       │      │       │   w ┴ nothing
       │        │       │      │    ce ┼ GeneralCovariance
       │        │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
       │        │       │      │       │    w ┴ nothing
       │        │       │      │   alg ┴ Full()
       │        │       │   mp ┼ DefaultMatrixProcessing
       │        │       │      │       pdm ┼ Posdef
       │        │       │      │           │   alg ┴ UnionAll: NearestCorrelationMatrix.Newton
       │        │       │      │   denoise ┼ nothing
       │        │       │      │    detone ┼ nothing
       │        │       │      │       alg ┴ nothing
       │        │    de ┼ Distance
       │        │       │   power ┼ nothing
       │        │       │     alg ┴ CanonicalDistance()
       │        │   alg ┼ KruskalTree
       │        │       │     args ┼ Tuple{}: ()
       │        │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
       │        │     n ┴ Int64: 1
       │   cent ┼ DegreeCentrality
       │        │     kind ┼ Int64: 0
       │        │   kwargs ┴ @NamedTuple{}: NamedTuple()
     B ┼ MinValue()
  comp ┴ LEQ: LEQ()

Related

• CentralityEstimator

• VectorToRealMeasure

• ComparisonOperator

• centrality_constraints

source

PortfolioOptimisers.centrality_constraints Function

centrality_constraints(ccs::Union{<:CentralityConstraint,
                                  <:AbstractVector{<:CentralityConstraint}},
                       X::AbstractMatrix; dims::Int = 1, kwargs...)

Generate centrality-based linear constraints from one or more CentralityConstraint estimators.

centrality_constraints constructs linear constraints for portfolio optimisation based on asset centrality measures within a phylogeny or network structure. It accepts one or more CentralityConstraint estimators, computes centrality vectors for the given data matrix X, applies the specified reduction measure or threshold, and assembles the resulting constraints into a LinearConstraint object.

Arguments

• ccs: A single CentralityConstraint or a vector of such estimators.

• X: Data matrix of asset features or returns.

• dims: Dimension along which to compute centrality.

• kwargs...: Additional keyword arguments passed to the centrality estimator.

Returns

• lc::Union{Nothing, <:LinearConstraint}: An object containing the assembled inequality and equality constraints, or nothing if no constraints are present.

Details

• For each constraint, computes the centrality vector using the estimator in cc.A.

• Applies the comparison operator and reduction measure or threshold in cc.B and cc.comp.

• Aggregates constraints into equality and inequality forms.

• Returns nothing if no valid constraints are generated.

Related

• CentralityConstraint

• LinearConstraint

• PartialLinearConstraint

• centrality_vector

source

centrality_constraints(ccs::Union{Nothing, <:LinearConstraint}, args...; kwargs...)

No-op fallback for centrality-based constraint propagation.

This method returns the input LinearConstraint object or nothing unchanged. It is used to pass through an already constructed centrality-based constraint object, enabling composability and uniform interface handling in constraint generation workflows.

Arguments

• ccs: An existing LinearConstraint object or nothing.

• args...: Additional positional arguments (ignored).

• kwargs...: Additional keyword arguments (ignored).

Returns

• ccs: The input constraint object or nothing, unchanged.

Related

• CentralityConstraint

• LinearConstraint

• centrality_constraints

source

PortfolioOptimisers.AbstractPhylogenyConstraintEstimator Type

abstract type AbstractPhylogenyConstraintEstimator <: AbstractConstraintEstimator end

Abstract supertype for all phylogeny-based constraint estimators in PortfolioOptimisers.jl.

All concrete types representing phylogeny-based constraint estimators should subtype AbstractPhylogenyConstraintEstimator. This enables a consistent, composable interface for generating constraints based on phylogenetic, clustering, or network structures among assets.

Related

• SemiDefinitePhylogenyEstimator

• IntegerPhylogenyEstimator

• CentralityConstraint

• AbstractConstraintEstimator

source

PortfolioOptimisers.AbstractPhylogenyConstraintResult Type

abstract type AbstractPhylogenyConstraintResult <: AbstractConstraintResult end

Abstract supertype for all phylogeny-based constraint result types in PortfolioOptimisers.jl.

All concrete types representing the results of phylogeny-based constraint generation should subtype AbstractPhylogenyConstraintResult. This enables a consistent, composable interface for storing and propagating constraint matrices, vectors, or other outputs derived from phylogenetic, clustering, or network structures among assets.

Related

• SemiDefinitePhylogeny

• IntegerPhylogeny

• CentralityConstraint

• AbstractConstraintResult

source

PortfolioOptimisers._validate_length_integer_phylogeny_constraint_B Function

_validate_length_integer_phylogeny_constraint_B(alg::Union{Nothing, <:Integer},
                                                B::AbstractVector)

Validate that the length of the vector B does not exceed the integer value alg.

This function is used internally to ensure that the number of groups or allocations specified by B does not exceed the allowed maximum defined by alg. If the validation fails, a DomainError is thrown.

Arguments

• alg:

  • Nothing: No validation is performed.

  • Integer: specifying the maximum allowed length for B.

• B: Vector of integers representing group sizes or allocations.

Returns

• nothing: Returns nothing if validation passes.

Validation

• Throws DomainError if length(B) > alg.

Details

• Checks that length(B) <= alg.

• Used in the construction and validation of integer phylogeny constraints.

Related

• validate_length_integer_phylogeny_constraint_B

• IntegerPhylogenyEstimator

source

PortfolioOptimisers.validate_length_integer_phylogeny_constraint_B Function

validate_length_integer_phylogeny_constraint_B(pe::ClusteringEstimator, B::AbstractVector)
validate_length_integer_phylogeny_constraint_B(args...)

Validate that the length of the vector B does not exceed the maximum allowed by the clustering estimator pe.

Arguments

• pe: Clustering estimator containing algorithm and maximum group information.

• B: Vector of integers representing group sizes or allocations.

• args...: No validation is performed.

Returns

• nothing: Returns nothing if validation passes.

Validation

• Throws DomainError if length(B) > pe.onc.max_k (when max_k is set).

• Calls internal _validate_length_integer_phylogeny_constraint_B for further checks.

Details

• Checks if pe.onc.max_k is set and validates length(B) accordingly.

• Delegates to _validate_length_integer_phylogeny_constraint_B for algorithm-specific validation.

• Used in the construction and validation of integer phylogeny constraints.

Related

• _validate_length_integer_phylogeny_constraint_B

• IntegerPhylogenyEstimator

source

PortfolioOptimisers.VectorToRealMeasure Type

abstract type VectorToRealMeasure <: AbstractAlgorithm end

Abstract supertype for algorithms mapping a vector of real values to a single real value.

VectorToRealMeasure provides a unified interface for algorithms that reduce a vector of real numbers to a scalar, such as minimum, mean, median, or maximum. These are used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics.

Related

• MinValue

• MeanValue

• MedianValue

• MaxValue

• CentralityConstraint

• vec_to_real_measure

source

PortfolioOptimisers.vec_to_real_measure Function

vec_to_real_measure(measure::Union{<:VectorToRealMeasure, <:Real}, val::AbstractVector)

Reduce a vector of real values to a single real value using a specified measure.

vec_to_real_measure applies a reduction algorithm (such as minimum, mean, median, or maximum) to a vector of real numbers, as specified by the concrete subtype of VectorToRealMeasure. This is used in constraint generation and centrality-based portfolio constraints to aggregate asset-level metrics.

Arguments

• measure: An instance of a concrete subtype of VectorToRealMeasure, or the predefined value to return.

• val: A vector of real values to be reduced (ignored if measure is a Real).

Returns

• score::Real: computed value according to measure.

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MaxValue(), [1.2, 3.4, 0.7])
3.4

julia> PortfolioOptimisers.vec_to_real_measure(0.9, [1.2, 3.4, 0.7])
0.9

Related

• VectorToRealMeasure

• MinValue

• MeanValue

• MedianValue

• MaxValue

source