Fees: private API
PortfolioOptimisers.AbstractFeeAmortisation — Type
abstract type AbstractFeeAmortisation <: AbstractAlgorithmSupertype for the algorithms that name the clock a one-off fee charge falls on.
Fees and FeesEstimator each carry this family in their fa field, bound to Option{<:AbstractFeeAmortisation}. The field decides which observations of a return series carry the fixed charges fl, fs and flq. It affects no other term, because l, s, tn and lq are rates per period and charge on every observation. The family has two leaves. FirstObservationFees charges the two fixed amounts one time, on the first observation, and AmortisedFees spreads them evenly over a horizon instead. A nothing fa is the default, and it names the first-observation clock.
Every site that reads the field dispatches on the leaf it holds, not on this supertype. A third clock added to the family therefore raises a MethodError until someone writes its methods. The supertype groups the clocks and implements none of them.
The cross-validation schemes hold the same family in a field of the same name. There it overrides the fee's own clock for a fold's realised series. fold_evaluation reads that field, and a nothing there inherits the clock of the fee.
Related
PortfolioOptimisers.FeesE_Fees — Type
const FeesE_Fees = Union{Fees, FeesEstimator}Union type for fee constraint objects and estimators.
There is no vector counterpart, and fees_constraints has no vector method. Fees already combines every fee component in one object, so an optimiser holds exactly one. See RkbE_Rkb for why some constraint families are singular and others are not.
Related
PortfolioOptimisers.calc_periodic_fees — Function
calc_periodic_fees(w::VecNum, fees::Fees)Charge the terms of a fee that fall on every observation.
l, s, tn and lq are rates per period, so each of them charges one time per observation of a return series. fees.fa affects none of the four. calc_fees adds this number to the one-off terms of calc_one_off_fees, and calc_total_fees multiplies it by the horizon. Fees states the closed form as $F_{\text{r}}$.
Algorithm
- Charge the long proportional term with
calc_feesonfees.lunder.>=. - Charge the short proportional term with the same verb on
fees.sunder.<, and negate it.wis negative on that side, so the negation makes the term a charge under a non-negativesand a credit under a negative one. - Charge the turnover term with
calc_feesonfees.tn. - Charge the proportional forced exit with
calc_liquidation_feesonfees.lq. - Return the sum of the four terms.
Arguments
w: Portfolio weights.fees:Feesstructure.
Returns
val::Number: The per period charge, before the one-off terms.
Examples
julia> fees = Fees(; l = 0.01, fl = 5.0, tn = Turnover(; w = [0.0, 0.0], val = 0.002));julia> PortfolioOptimisers.calc_periodic_fees([0.5, 0.5], fees)0.012Related
PortfolioOptimisers.calc_one_off_fees — Function
calc_one_off_fees(w::VecNum, fees::Fees)Charge the terms of a fee that fall one time over a holding period.
fl and fs charge each non-zero position, and flq each position a forced exit sold, one time for the whole holding period. They are the only terms fees.fa affects. Fees states the closed form as $F_{\text{o}}$. On the weights this method takes, each charge is a fraction of capital. The method takes no price, because a fixed fee does not scale with the size of the position.
Algorithm
- Charge the long fixed term with
calc_fixed_feesonfees.flunder.>=. - Charge the short fixed term with the same verb on
fees.fsunder.<. - Charge the fixed forced exit with
calc_fixed_liquidation_feesonfees.flq. - Return the sum of the three terms.
Arguments
w: Portfolio weights.fees:Feesstructure.
Returns
val::Number: The charge of one holding period.
Examples
julia> fees = Fees(; l = 0.01, fl = 5.0, tn = Turnover(; w = [0.0, 0.0], val = 0.002));julia> PortfolioOptimisers.calc_one_off_fees([0.5, 0.5], fees)10.0Related
PortfolioOptimisers.calc_asset_periodic_fees — Function
calc_asset_periodic_fees(w::VecNum, fees::Fees)Split over the assets the terms of a fee that fall on every observation.
This is the per asset counterpart of calc_periodic_fees. Its entries sum to that number, up to the order of summation.
Algorithm
- Charge the long proportional term with
calc_asset_feesonfees.lunder.>=. - Charge the short proportional term with the same verb on
fees.sunder.<, and negate it. - Charge the turnover term with
calc_asset_feesonfees.tn. - Charge the proportional forced exit with
calc_asset_liquidation_feesonfees.lq.lqis a rate, so it falls on every period besidel,sandtn, and no clock affects it. - Return the pair: the elementwise sum of the three vectors of steps 1 to 3, and the vector of step 4.
Arguments
w: Portfolio weights.fees:Feesstructure.
Returns
The verb returns a pair, one entry per axis of a reduced Fees.
investable::VecNum: The per period charge of each asset that stayed, froml,sandtn, whichinvestable_fees_viewsliced to the Investable Mask.liquidation::VecNum: The per period charge of each asset that left, fromlq, whichinvestable_fees_viewsliced to the mask's complement. It is empty whenlqis unset, because the axis has no length to build a vector of zeros from.
Examples
julia> fees = Fees(; l = 0.01, fl = 5.0, tn = Turnover(; w = [0.0, 0.0], val = 0.002));julia> PortfolioOptimisers.calc_asset_periodic_fees([0.5, 0.5], fees)([0.006, 0.006], Float64[])Related
PortfolioOptimisers.calc_asset_one_off_fees — Function
calc_asset_one_off_fees(w::VecNum, fees::Fees)Split over the assets the terms of a fee that fall one time over a holding period.
This is the per asset counterpart of calc_one_off_fees. Its entries sum to that number, up to the order of summation.
Algorithm
- Charge the long fixed term with
calc_asset_fixed_feesonfees.flunder.>=. - Charge the short fixed term with the same verb on
fees.fsunder.<. - Charge the fixed forced exit with
calc_asset_fixed_liquidation_feesonfees.flq.flqcharges one time per position, so it falls on the clockfees.fanames, besideflandfs. - Return the pair: the elementwise sum of the two vectors of steps 1 and 2, and the vector of step 3.
Arguments
w: Portfolio weights.fees:Feesstructure.
Returns
The verb returns a pair, one entry per axis of a reduced Fees.
investable::VecNum: The one-off charge of each asset that stayed, fromflandfs, whichinvestable_fees_viewsliced to the Investable Mask.liquidation::VecNum: The one-off charge of each asset that left, fromflq, whichinvestable_fees_viewsliced to the mask's complement. It is empty whenflqis unset, because the axis has no length to build a vector of zeros from.
Examples
julia> fees = Fees(; l = 0.01, fl = 5.0, tn = Turnover(; w = [0.0, 0.0], val = 0.002));julia> PortfolioOptimisers.calc_asset_one_off_fees([0.5, 0.5], fees)([5.0, 5.0], Float64[])Related
PortfolioOptimisers.calc_liquidation_fees — Function
calc_liquidation_fees(::Nothing)
calc_liquidation_fees(lq::Turnover{<:Any, <:Number})
calc_liquidation_fees(lq::Turnover{<:Any, <:VecNum})Charge the proportional cost of the positions a forced exit sells.
lq is on the complement of the Investable Mask, so its entries are the assets that left, never the assets the programme holds. A forced exit is a trade to zero. The target weight of every entry is therefore zero, the turnover |target - lq.w| is abs.(lq.w), and the charge is the rate times the absolute previous weight. lq is the only input, so the verb needs no weight vector and takes none.
The charge is a rate, so it falls on every period beside l, s and tn, and calc_periodic_fees adds it there.
Algorithm
- On a
nothinglq, returnfalse. No asset left the universe, so the charge is zero, and aBoolzero adds to a charge of any element type without widening it. - On a scalar rate, return
lq.val * sum(abs, lq.w). - On a per asset rate, return
dot(lq.val, abs.(lq.w)).
Arguments
lq: The proportional liquidation rate, ornothing.
Returns
val::Number: The proportional charge of the forced exit.
Examples
julia> PortfolioOptimisers.calc_liquidation_fees(nothing)falsejulia> PortfolioOptimisers.calc_liquidation_fees(Turnover(; w = [0.25], val = [0.01]))0.0025Related
PortfolioOptimisers.calc_fixed_liquidation_fees — Function
calc_fixed_liquidation_fees(::Nothing, ::NamedTuple)
calc_fixed_liquidation_fees(flq::Turnover, kwargs::NamedTuple)Charge the fixed cost of the positions a forced exit sells.
This is the fixed counterpart of calc_liquidation_fees, and it takes no weight vector for the same reason. flq is on the complement of the Investable Mask. The verb charges its amount once for each entry whose absolute previous weight is not isapprox to zero under kwargs, the threshold fl and fs already use.
A liquidated short is a trade as much as a liquidated long, so the verb charges both sides. It calls calc_fixed_fees twice against flq.w, once under .>= and once under .<. calc_one_off_fees uses the same pattern for fl and fs, and here one rate serves both sides. The two selections are disjoint, so no entry pays twice.
The charge is fixed per position, so it falls one time for the whole holding period beside fl and fs, on the clock fees.fa names. It is a fraction of capital on a return series and in the JuMP model, and a currency amount in the finite allocation.
Algorithm
- On a
nothingflq, returnfalse, the sameBoolzerocalc_liquidation_feesreturns. - Otherwise charge
calc_fixed_feesonflq.wandflq.valunder.>=, the liquidated long positions. - Charge the same under
.<, the liquidated short positions. - Return the sum of the two.
Arguments
flq: The fixed liquidation charge, ornothing.kwargs: Forwarded toisapproxto decide how near zero counts as zero.
Returns
val::Number: The fixed charge of the forced exit.
Examples
julia> PortfolioOptimisers.calc_fixed_liquidation_fees(nothing, (; atol = 1e-8))falsejulia> PortfolioOptimisers.calc_fixed_liquidation_fees(Turnover(; w = [0.25, -0.4], val = [5.0, 7.0]), (; atol = 1e-8))12.0Related
PortfolioOptimisers.calc_asset_liquidation_fees — Function
calc_asset_liquidation_fees(w::VecNum, ::Nothing)
calc_asset_liquidation_fees(w::VecNum, lq::Turnover)Split the proportional cost of a forced exit over the assets that left.
This is the per asset counterpart of calc_liquidation_fees. Its entries sum to that number, and they are on the complement of the Investable Mask. There is one entry per asset that left, in the order that lq holds them, so each charge maps to the asset that caused it.
nothing gives an empty vector rather than a vector of zeros, because the complement is empty when no asset exited. A reader can then tell "no asset left" from "an asset left and owed nothing".
Algorithm
- On a
nothinglq, return an empty vector in the element type ofw. - Otherwise call
calc_asset_feesonlqagainst a zero vector the length oflq.w. The result islq.val .* abs.(lq.w).
Arguments
w: Portfolio weights, read for their element type.lq: The proportional liquidation rate, ornothing.
Returns
val::VecNum: The proportional charge per liquidated asset.
Examples
julia> PortfolioOptimisers.calc_asset_liquidation_fees([0.5, 0.5], Turnover(; w = [-0.4, 0.25], val = [0.002, 0.010]))2-element Vector{Float64}: 0.0008 0.0025Related
PortfolioOptimisers.calc_asset_fixed_liquidation_fees — Function
calc_asset_fixed_liquidation_fees(w::VecNum, ::Nothing, ::NamedTuple)
calc_asset_fixed_liquidation_fees(w::VecNum, flq::Turnover, kwargs::NamedTuple)Split the fixed cost of a forced exit over the assets that left.
This is the per asset counterpart of calc_fixed_liquidation_fees. It is on the complement axis, and it is empty when no asset exited. The verb charges both liquidated sides, so it sums the two selections of calc_asset_fixed_fees. They are disjoint, so no entry pays twice.
Algorithm
- On a
nothingflq, return an empty vector in the element type ofw. - Otherwise charge
calc_asset_fixed_feesonflq.wandflq.valunder.>=and again under.<, and return the elementwise sum.
Arguments
w: Portfolio weights, read for their element type.flq: The fixed liquidation charge, ornothing.kwargs: Forwarded toisapproxto decide how near zero counts as zero.
Returns
val::VecNum: The fixed charge per liquidated asset.
Examples
julia> PortfolioOptimisers.calc_asset_fixed_liquidation_fees([0.5, 0.5], Turnover(; w = [-0.4, 0.25], val = [7.0, 5.0]), (; atol = 1e-8))2-element Vector{Float64}: 7.0 5.0Related
PortfolioOptimisers.add_liquidation_terms — Function
add_liquidation_terms(a::VecNum, b::VecNum)Add the two terms of the liquidation axis, when either term can be unset.
A caller sets lq and flq independently. The verb that prices an unset liquidation charge returns an empty vector, not a vector of zeros, because it has no length to build one from. The axis is the complement of the Investable Mask, and that verb takes no mask. So a Fees that sets flq and no lq gives one term over the complement and one empty term. An elementwise sum of the two raises a DimensionMismatch on a correct fee.
An empty term charges nothing, so the sum is the other term. Two set terms span the same complement and add elementwise. The investable axis needs no such verb, because its terms come from w and always span it.
Algorithm
- On an empty
a, returnb. - On an empty
b, returna. - Otherwise return the elementwise sum
a + b.
Arguments
a: One term of the axis.b: The other term of the axis.
Returns
val::VecNum: The two terms summed, or whichever of them is set.
Related
PortfolioOptimisers.assert_short_fee_convex — Function
assert_short_fee_convex(l::Option{<:Num_VecNum}, s::Nothing)
assert_short_fee_convex(l::Nothing, s::Num_VecNum)
assert_short_fee_convex(l::Num_VecNum, s::Num_VecNum)Check that the short proportional rate s of a Fees keeps the proportional fee convex.
Per asset, the proportional fee is $\phi(w) = l \max(w, 0) - s \min(w, 0)$. Its slope is $l$ for $w > 0$ and $-s$ for $w < 0$, so $\phi$ is convex if and only if $s \geq -l$. Convexity keeps every JuMP model that charges the fee convex. A negative s is a credit on a short position. At $s = -l$ the fee is the linear $l w$ on either sign. This models an expense ratio that the instrument holds, and a short position earns it.
Algorithm
- On a
nothings, check nothing. - On a
nothingl, readlas zero, sosmust be non-negative. - Otherwise check
s .>= -lentry by entry. A scalar applies to every asset.
Arguments
l: The long proportional rate, ornothing.s: The short proportional rate, ornothing.
Validation
all(s .>= -l), which raises aDomainErrorthat names the convexity bound.
Returns
nothing.
Related
PortfolioOptimisers.override_fee_amortisation — Function
override_fee_amortisation(fees::Option{<:Fees}, fa::Nothing)
override_fee_amortisation(fees::Nothing, fa::AbstractFeeAmortisation)
override_fee_amortisation(fees::Fees, fa::AbstractFeeAmortisation)Return the fee a report charges, from the fee a fit saw and the clock the report states.
The fa field of a Fees names the clock the fixed charges fl, fs and flq fall on. A cross-validation scheme has a field of the same name, and the two clocks need not agree. The optimiser prices a fixed fee the way the objective requires, and the report charges it the way the fund paid it. This verb resolves the pair, and it affects only the fold's realised series.
A nothing fa on the scheme inherits the fee's clock, so the verb returns the fee unchanged and builds no object. A stated fa rebuilds the fee with that clock and leaves every other field of it alone. The rate fields l, s, tn and lq charge on every observation whatever the clock is, so the override changes none of their numbers.
Algorithm
- On a
nothingfa, returnfeesunchanged, whether it is aFeesornothing. - On a stated
faand anothingfees, returnnothing. There is no fee to charge, so there is no clock to state. - On a stated
faand aFees, rebuild the fee with thatfawithrebuild_struct. The five fee fields, the two liquidation chargeslqandflq,kwargsand the markimskstay the same.
Arguments
fees: The fee the fit saw, ornothing.fa: The clock the scheme states, ornothingto inherit the fee's own.
Returns
Option{<:Fees}: The fee the report charges.
Related
PortfolioOptimisers.two_axis_fees_view — Function
two_axis_fees_view(fees::Fees, i, n::Integer)Sub-select a resolved fee to the assets an optimisation keeps, on both of its axes, from the index it keeps and the width of the unreduced universe.
This is the only verb that splits a Fees across its two axes. tn, l, s, fl and fs price the positions the portfolio holds, so they are on the investable axis and the verb slices them at i. lq and flq price the positions the portfolio must sell, so they are on the complement of that axis and the verb slices them at the assets i leaves out. The verb derives the complement from i and n and never stores it.
The width is a number rather than a matrix because the two callers hold different things. A fit passes the unreduced returns matrix to port_opt_view, which takes size(X, 2) from it. result_investable_view also calls investable_fees_view. It meets a caller's full-universe fee beside a result whose own prior is already reduced, so no full-width matrix exists there, and the width is the length of the mask.
The view writes no imsk, so it returns an unmarked fee. The view is a slice, and a cluster of a nested optimiser takes it the same way investable_fees_view does. A mark here makes an inner fit treat the complement of a cluster as the assets that left. investable_fees_view is the only verb that marks a fee, and it does so after this view returns.
Algorithm
- Build
j, the complement ofiin1:n. - Slice
tnatithroughport_opt_view, whose@vproptags slicewand a vectorvaland leave a scalar or dictionaryvalalone. - Slice
l,s,flandfsatithroughnothing_scalar_array_view. - On an empty
jno asset left the universe, so setlqandflqtonothing. There is nothing to liquidate, and aTurnoverrefuses an emptywin any case. Otherwise slice both atjwith the same verb as step 2. - Rebuild through the keyword constructor. Keep
faandkwargs, and setimsktonothing.
Arguments
fees: The fee to reduce.i: Indices of the assets the optimisation keeps.n: The width of the unreduced universe.
Returns
fees::Fees: The fee on the two reduced axes, unmarked.
Related
PortfolioOptimisers.strip_liquidation_charges — Function
strip_liquidation_charges(fees, imsk::Nothing)Drop the two liquidation charges, lq and flq, when no asset left the universe.
A caller states lq and flq over the full universe, because the caller cannot know in advance which asset will delist. port_opt_view narrows them to the complement of the Investable Mask. But a window in which every asset is investable derives no mask. The nothing sentinel then skips port_opt_view, so that the all-investable path allocates nothing. Without this verb, lq and flq keep their full width, and the fee charges them in full for assets that never left.
This verb drops lq and flq in that case. It does not take the view on the common path, so the nothing mask stays allocation-free. It returns unchanged a fee that holds neither liquidation charge, so it allocates nothing for a caller who states no liquidation. A derived mask means that port_opt_view has already put lq and flq on the right axis, so the verb takes no mask but nothing.
The verb does not check the mark fees.imsk. Under a nothing mask it drops lq and flq of any fee it receives. A hierarchical fit uses this when it prices the risk of a cluster from a fee that investable_fees_view has already reduced. Only the result charges the exit, so no sub-problem can charge it.
investable_fees_view is the verb that tells a fee that the caller states over the full universe from the reduced fee of a result. It checks fees.imsk and calls this verb for an unmarked fee only. This verb keeps the mark, so a reduced fee stays reduced with lq and flq gone.
Algorithm
- On a
nothingfees, returnnothing. - On a fee with
lqandflqalreadynothing, returnfeesunchanged, so the common case allocates nothing. - Otherwise rebuild the fee with
lqandflqset tonothing, and keep every other field.
Arguments
fees: The fee to strip, ornothing.imsk:nothing, the Investable Mask of a window in which every asset is investable.
Returns
fees::Option{<:Fees}: The fee, with no liquidation charge when none can apply.
Related
PortfolioOptimisers.mark_fees — Function
mark_fees(fees::Nothing, imsk)
mark_fees(fees::Fees, imsk::Nothing)
mark_fees(fees::Fees, imsk::BitVector)Reconcile a fee with the Investable Mask a caller states beside it, so that the fee alone records the axes it is on.
A FiniteAllocationInput takes a fee and a mask as two keywords, and a caller can state either without the other. A result passes both. A caller who reduced a fee by hand states the mask alone, and a caller who passes a result's fee states no mask. lift_fees reads the fee's own imsk, so the fee and the mask must agree before the constructor builds the input. A stated mask marks an unmarked fee, a marked fee supplies a missing mask, and the verb refuses a pair that disagrees.
Algorithm
- On a
nothingfee, return it with the stated mask. - On a
nothingmask, return the fee with its own mark, which can benothing. - On an unmarked fee and a
BitVectormask, rebuild the fee with that mask as its mark. - On a marked fee and a
BitVectormask, raise anArgumentErrorthat names both when they differ, and return the pair otherwise.
Arguments
fees: The fee, ornothing.imsk: The Investable Mask the caller states, ornothing.
Validation
- The verb refuses a fee marked with a
BitVectorother thanimsk, with anArgumentErrorthat names the two masks.
Returns
(fees, imsk): The fee, marked with the mask when there is one, and the mask.
Related
PortfolioOptimisers.lift_fees — Function
lift_fees(fees::Nothing)
lift_fees(fees::Fees)Put a fee that investable_fees_view reduced back onto the full universe, on both of its axes.
This verb is the inverse of investable_fees_view. An optimisation reduced to its Investable Mask expands the solved weights back to the caller's universe. Its result then pairs a full-length w with a fee on two reduced axes, with tn, l, s, fl and fs on the investable assets and lq and flq on the complement. A consumer that indexes the fee by the full-length weights meets a four-element field and a five-element selector, and fails on the index.
This verb moves the fee onto the axis of the weights. It lifts at the mask the fee holds in imsk, which investable_fees_view wrote when it reduced the fee, so the fee alone records the axes it is on.
Every per-asset field comes back with length length(imsk), with a zero wherever the field states nothing. The five holding fields hold a zero at each asset that left, and lq and flq hold a zero at each asset that stayed. A zero rate charges nothing and a zero reference weight trades nothing, so the lift changes no charge of the reduced fee. A scalar rate applies to every asset whatever the axis is, so the verb returns it untouched. The lifted fee is unmarked, because it is on the full universe again.
Algorithm
- On a
nothingfees, or an unmarked one, returnfeesunchanged. An unmarked fee is a caller's statement on the full universe, or the fee of an optimisation that reduced on nothing, and either is on the full universe already. - Lift
tnatfees.imskwithlift_turnover, andl,s,flandfswithlift_fee_rate. - Lift
lqandflqat.!fees.imsk, the complement thatlqandflqare on, with the same verb as step 2. - Rebuild through the keyword constructor. Keep
faandkwargs, and setimsktonothing.
Arguments
fees: The fee to lift, ornothing.
Returns
fees::Option{<:Fees}: The fee on the full universe, unmarked.
Examples
julia> fees = Fees(; l = [0.001, 0.002], lq = Turnover(; w = [0.25], val = [0.01]), imsk = BitVector([true, false, true]));julia> PortfolioOptimisers.lift_fees(fees).l3-element Vector{Float64}: 0.001 0.0 0.002julia> PortfolioOptimisers.lift_fees(fees).lq.w3-element Vector{Float64}: 0.0 0.25 0.0julia> PortfolioOptimisers.lift_fees(fees).imskRelated
PortfolioOptimisers.lift_fee_rate — Function
lift_fee_rate(x::Number, ::BitVector)
lift_fee_rate(x::Option{<:VecNum}, imsk::BitVector)Put one per-asset fee rate back onto the full universe, zero where the mask is false.
This is the per-field step of lift_fees. A nothing field states no fee and a scalar field states one rate for every asset, so neither is on an axis and the verb returns both untouched. A vector field holds one entry per asset of the reduced axis, so the verb expands it with expand_investable_weights.
Algorithm
- On a
Numberx, returnx. - On a
VecNumor anothingx, returnexpand_investable_weightsofxatimsk. Entry $k$ ofxgoes to the position of the $k$-thtrueofimsk, and everyfalseposition holds a zero. That function returnsnothingfornothing.
Arguments
x: The rate to lift:nothing, a scalar, or one entry per asset of the reduced axis.imsk: The mask thatinvestable_fees_viewreduced the rate on.
Returns
x: The rate on the full universe.
Related
PortfolioOptimisers.lift_turnover — Function
lift_turnover(tn::Nothing, ::BitVector)
lift_turnover(tn::Turnover, imsk::BitVector)Put a Turnover back onto the full universe, zero where the mask is false.
This is the nested step of lift_fees. A Turnover holds a reference weight per asset and a rate that is either a scalar or one entry per asset, so w always expands and val expands through lift_fee_rate. A zero reference weight trades nothing, so the fee charges nothing for an asset that the mask leaves out.
Algorithm
- On a
nothingtn, returnnothing. - Expand
tn.watimskwithexpand_investable_weights, andtn.valwithlift_fee_rate. - Rebuild the
Turnoverfrom the two expanded fields, withtn.fixedunchanged.
Arguments
tn: The turnover to lift, ornothing.imsk: The mask thatinvestable_fees_viewreduced the turnover on.
Returns
tn: The turnover on the full universe, ornothing.
Related