PortfolioOptimisers.jl

Appearance

18

Phylogeny Constraints ​

PortfolioOptimisers.SemiDefinitePhylogenyEstimator Type
julia
struct SemiDefinitePhylogenyEstimator{__T_pl, __T_p} <: AbstractPhylogenyConstraintEstimator

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

  • pl: Network estimator, phylogeny result, clustering estimator, or clustering result.

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

Constructors

julia
SemiDefinitePhylogenyEstimator(;
    pl::NwE_PlM_ClE_Cl = NetworkEstimator(),
    p::Number = 0.05
) -> SemiDefinitePhylogenyEstimator

Validation

  • p >= 0.

Examples

julia
julia> SemiDefinitePhylogenyEstimator()
SemiDefinitePhylogenyEstimator
  pl ┼ NetworkEstimator
     │    ce ┼ PortfolioOptimisersCovariance
     │       │   ce ┼ Covariance
     │       │      │    me ┼ SimpleExpectedReturns
     │       │      │       │   w ┴ nothing
     │       │      │    ce ┼ GeneralCovariance
     │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
     │       │      │       │    w ┴ nothing
     │       │      │   alg ┴ FullMoment()
     │       │   mp ┼ MatrixProcessing
     │       │      │     pdm ┼ Posdef
     │       │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton
     │       │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()
     │       │      │      dn ┼ nothing
     │       │      │      dt ┼ nothing
     │       │      │     alg ┼ nothing
     │       │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)
     │    de ┼ Distance
     │       │   power ┼ nothing
     │       │     alg ┴ CanonicalDistance()
     │   alg ┼ KruskalTree
     │       │     args ┼ Tuple{}: ()
     │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
     │     n ┴ Int64: 1
   p ┴ Float64: 0.05

Related

source
PortfolioOptimisers.SemiDefinitePhylogeny Type
julia
struct SemiDefinitePhylogeny{__T_A, __T_p} <: AbstractPhylogenyConstraintResult

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 constraint matrix.

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

Constructors

julia
SemiDefinitePhylogeny(;
    A::MatNum_PhRMatNum,
    p::Number = 0.05
) -> SemiDefinitePhylogeny

Validation

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

  • p >= 0.

Examples

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

Related

source
PortfolioOptimisers.IntegerPhylogenyEstimator Type
julia
struct IntegerPhylogenyEstimator{__T_pl, __T_B, __T_scale} <: AbstractPhylogenyConstraintEstimator

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

  • pl: Network estimator, phylogeny result, clustering estimator, or clustering result.

  • B: Group sizes or allocations vector.

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

Constructors

julia
IntegerPhylogenyEstimator(;
    pl::NwE_PlM_ClE_Cl = NetworkEstimator(),
    B::Int_VecInt = 1,
    scale::Number = 100_000.0
) -> IntegerPhylogenyEstimator

Validation

Examples

julia
julia> IntegerPhylogenyEstimator()
IntegerPhylogenyEstimator
     pl ┼ NetworkEstimator
        │    ce ┼ PortfolioOptimisersCovariance
        │       │   ce ┼ Covariance
        │       │      │    me ┼ SimpleExpectedReturns
        │       │      │       │   w ┴ nothing
        │       │      │    ce ┼ GeneralCovariance
        │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
        │       │      │       │    w ┴ nothing
        │       │      │   alg ┴ FullMoment()
        │       │   mp ┼ MatrixProcessing
        │       │      │     pdm ┼ Posdef
        │       │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton
        │       │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()
        │       │      │      dn ┼ nothing
        │       │      │      dt ┼ nothing
        │       │      │     alg ┼ nothing
        │       │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)
        │    de ┼ Distance
        │       │   power ┼ nothing
        │       │     alg ┴ CanonicalDistance()
        │   alg ┼ KruskalTree
        │       │     args ┼ Tuple{}: ()
        │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
        │     n ┴ Int64: 1
      B ┼ Int64: 1
  scale ┴ Float64: 100000.0

Related

source
PortfolioOptimisers.IntegerPhylogeny Type
julia
struct IntegerPhylogeny{__T_A, __T_B, __T_scale} <: AbstractPhylogenyConstraintResult

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 constraint matrix.

  • B: Group sizes or allocations vector.

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

Constructors

julia
IntegerPhylogeny(;
    A::MatNum_PhRMatNum,
    B::Int_VecInt = 1,
    scale::Number = 100_000.0
) -> IntegerPhylogeny

Validation

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

  • B is validated with assert_nonempty_nonneg_finite_val.

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

Examples

julia
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

source
PortfolioOptimisers.phylogeny_constraints Function
julia
phylogeny_constraints(plc::Option{<:PlCE_PlC}, X::MatNum; dims::Int = 1, kwargs...)
phylogeny_constraints(plcs::VecPlCE_PlC, args...; kwargs...)

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

phylogeny_constraints constructs constraint objects based on phylogenetic, res, 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 plc is nothing, returns nothing.

If plcs is a vector, this method broadcasts over each element, returning a vector of constraint results.

Arguments

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

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

  • dims: Dimension along which to perform the computation.

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

Returns

  • res: Constraint result.

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

    • IntegerPhylogeny: For integer constraint estimators/results.

    • nothing: If est is nothing.

Related

source
julia
phylogeny_constraints(
    plc::AbstractPhylogenyConstraintEstimator,
    pr::Union{AbstractPriorResult, ReturnsResult};
    rd,
    cle_pr,
    kwargs...
) -> Union{IntegerPhylogeny, SemiDefinitePhylogeny{<:AbstractMatrix{var"#s30"}, <:Number} where var"#s30"<:(Union{var"#s29", var"#s28"} where {var"#s29"<:Number, var"#s28"<:AbstractJuMPScalar})}

Compute phylogeny constraints from asset returns in a prior result using a phylogeny constraint estimator.

phylogeny_constraints delegates to the asset-returns variant by extracting X from pr (or rd if provided and cle_pr is false).

Arguments

  • plc: Phylogeny constraint estimator.

  • pr: Prior result or returns result object.

  • rd: Optional returns result (used when cle_pr = false).

  • cle_pr: If true, use asset returns from pr; otherwise, use rd. Default is true.

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

Returns

  • Phylogeny constraint result.

Related

source
PortfolioOptimisers.AbstractCentralityConstraint Type
julia
abstract type AbstractCentralityConstraint <: AbstractConstraintEstimator

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

All concrete types implementing centrality-based portfolio constraints should be subtypes of AbstractCentralityConstraint.

Related

source
PortfolioOptimisers.CentralityConstraint Type
julia
struct CentralityConstraint{__T_A, __T_B, __T_comp} <: AbstractCentralityConstraint

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 VectorToScalarMeasure measure or threshold B, and a comparison operator comp ComparisonOperator.

Fields

  • A: Centrality estimator.

  • B: Centrality threshold or reduction measure.

  • comp: Comparison operator for the centrality constraint.

Constructors

julia
CentralityConstraint(;
    A::CentralityEstimator = CentralityEstimator(),
    B::Num_VecToScaM = MinValue(),
    comp::ComparisonOperator = <=
) -> CentralityConstraint

Examples

julia
julia> CentralityConstraint()
CentralityConstraint
     A ┼ CentralityEstimator
       │   pl ┼ NetworkEstimator
       │      │    ce ┼ PortfolioOptimisersCovariance
       │      │       │   ce ┼ Covariance
       │      │       │      │    me ┼ SimpleExpectedReturns
       │      │       │      │       │   w ┴ nothing
       │      │       │      │    ce ┼ GeneralCovariance
       │      │       │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
       │      │       │      │       │    w ┴ nothing
       │      │       │      │   alg ┴ FullMoment()
       │      │       │   mp ┼ MatrixProcessing
       │      │       │      │     pdm ┼ Posdef
       │      │       │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton
       │      │       │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()
       │      │       │      │      dn ┼ nothing
       │      │       │      │      dt ┼ nothing
       │      │       │      │     alg ┼ nothing
       │      │       │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)
       │      │    de ┼ Distance
       │      │       │   power ┼ nothing
       │      │       │     alg ┴ CanonicalDistance()
       │      │   alg ┼ KruskalTree
       │      │       │     args ┼ Tuple{}: ()
       │      │       │   kwargs ┴ @NamedTuple{}: NamedTuple()
       │      │     n ┴ Int64: 1
       │   ct ┼ DegreeCentrality
       │      │     kind ┼ Int64: 0
       │      │   kwargs ┴ @NamedTuple{}: NamedTuple()
     B ┼ MinValue()
  comp ┴ typeof(<=): <=

Related

source
PortfolioOptimisers.VecCC Type
julia
const VecCC = AbstractVector{<:CentralityConstraint}

Alias for a vector of CentralityConstraint objects.

Represents a collection of centrality-based portfolio constraints.

Related

source
PortfolioOptimisers.CC_VecCC Type
julia
const CC_VecCC = Union{<:CentralityConstraint, <:VecCC}

Alias for a single or vector of CentralityConstraint objects.

Matches either a single CentralityConstraint or a vector of them (VecCC).

Related

source
PortfolioOptimisers.centrality_constraints Function
julia
centrality_constraints(ccs::CC_VecCC,
                       X::MatNum; 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 perform the computation.

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

Returns

  • lc::Option{<: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

source
julia
centrality_constraints(ccs::Option{<: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::Option{<:LinearConstraint}: The input constraint object or nothing, unchanged.

Related

source
julia
centrality_constraints(
    ccs::Union{CentralityConstraint, AbstractVector{<:CentralityConstraint}},
    pr::Union{AbstractPriorResult, ReturnsResult};
    rd,
    cle_pr,
    kwargs...
) -> Union{Nothing, LinearConstraint}

Compute centrality constraints from asset returns in a prior result using a centrality constraint estimator.

centrality_constraints delegates to the asset-returns variant by extracting X from pr (or rd if provided and cle_pr is false).

Arguments

  • ccs: Centrality constraint estimator or vector thereof.

  • pr: Prior result or returns result object.

  • rd: Optional returns result (used when cle_pr = false).

  • cle_pr: If true, use asset returns from pr; otherwise, use rd. Default is true.

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

Returns

  • Centrality constraint result.

Related

source
PortfolioOptimisers.AbstractPhylogenyConstraintEstimator Type
julia
abstract type AbstractPhylogenyConstraintEstimator <: AbstractConstraintEstimator

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

All concrete and/or abstract types representing phylogeny-based constraint estimators should be subtypes of AbstractPhylogenyConstraintEstimator.

Related

source
PortfolioOptimisers.AbstractPhylogenyConstraintResult Type
julia
abstract type AbstractPhylogenyConstraintResult <: AbstractConstraintResult

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

All concrete and/or abstract types representing the results of phylogeny-based constraint generation should be subtypes of AbstractPhylogenyConstraintResult.

Related

source
PortfolioOptimisers.PlCE_PlC Type
julia
const PlCE_PlC = Union{<:AbstractPhylogenyConstraintEstimator,
                       <:AbstractPhylogenyConstraintResult}

Alias for a phylogeny constraint estimator or result.

Matches either a AbstractPhylogenyConstraintEstimator or a AbstractPhylogenyConstraintResult. Used internally for dispatch in phylogeny-based constraint generation.

Related

source
PortfolioOptimisers.VecPlC Type
julia
const VecPlC = AbstractVector{<:AbstractPhylogenyConstraintResult}

Alias for a vector of phylogeny constraint results.

Represents a collection of AbstractPhylogenyConstraintResult objects.

Related

source
PortfolioOptimisers.PlC_VecPlC Type
julia
const PlC_VecPlC = Union{<:AbstractPhylogenyConstraintResult, <:VecPlC}

Alias for a single or vector of phylogeny constraint results.

Matches either a single AbstractPhylogenyConstraintResult or a vector of them (VecPlC).

Related

source
PortfolioOptimisers.VecPlCE_PlC Type
julia
const VecPlCE_PlC = AbstractVector{<:PlCE_PlC}

Alias for a vector of phylogeny constraint estimators or results.

Represents a collection of PlCE_PlC objects, enabling batch processing of multiple phylogeny-based constraint estimators or results.

Related

source
PortfolioOptimisers.PlCE_PhC_VecPlCE_PlC Type
julia
const PlCE_PhC_VecPlCE_PlC = Union{<:PlCE_PlC, <:VecPlCE_PlC}

Alias for a single or vector of phylogeny constraint estimators or results.

Matches either a single PlCE_PlC or a vector of them (VecPlCE_PlC). Used internally for dispatch on phylogeny-based constraint generation that accepts one or many constraints.

Related

source
PortfolioOptimisers.MatNum_PhRMatNum Type
julia
const MatNum_PhRMatNum = Union{<:PhylogenyResult{<:MatNum}, <:MatNum}

Alias for a phylogeny result wrapping a numeric matrix or a numeric matrix directly.

Used internally to accept either a PhylogenyResult containing a numeric matrix or a plain numeric matrix as a constraint matrix input.

Related

source
PortfolioOptimisers.Lc_CC_VecCC Type
julia
const Lc_CC_VecCC = Union{<:CC_VecCC, <:LinearConstraint}

Alias for a centrality constraint or linear constraint.

Matches either a CentralityConstraint, a vector of them, or a LinearConstraint. Used for dispatch in centrality-based constraint generation that also accepts linear constraints.

Related

source
PortfolioOptimisers._validate_length_integer_phylogeny_constraint_B Function
julia
_validate_length_integer_phylogeny_constraint_B(alg::Option{<:Integer},
                                                B::VecNum)

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.

Validation

  • Throws DomainError if length(B) > alg.

Details

  • Checks that length(B) <= alg.

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

Related

source
PortfolioOptimisers.validate_length_integer_phylogeny_constraint_B Function
julia
validate_length_integer_phylogeny_constraint_B(cle::ClustersEstimator, B::VecNum)
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 cle.

Arguments

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

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

  • args...: No validation is performed.

Returns

  • nothing.

Validation

Details

  • Checks if cle.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

source