Black-Litterman Views Generation: private API
PortfolioOptimisers.Lc_BLV — Type
const Lc_BLV = Union{LinearConstraintEstimator, BlackLittermanViews}Alias for the union of the two shapes of Black-Litterman views: a LinearConstraintEstimator of view equations, and a precomputed BlackLittermanViews.
Related
PortfolioOptimisers.get_black_litterman_views — Function
get_black_litterman_views(lcs::PR_VecPR, sets::UniverseSets,
key::Option{<:AbstractString} = nothing;
datatype::DataType = Float64, strict::Bool = false,
ledger::Option{<:AbstractVector} = nothing)Assemble parsed Black-Litterman view equations into a BlackLittermanViews.
The function reads one or more ParsingResult objects from parse_equation. It resolves each name against one universe of a UniverseSets, and it writes one row of P and one entry of Q for each view that it keeps.
key selects the universe that the names resolve against, as it does for get_linear_constraints. If key is nothing, the universe is sets.dict[sets.xkey]. The function does not re-base a view. The estimator that owns the views selects the distribution that they update, and it passes the matching key. P has one row for each kept view and length(sets.dict[key]) columns. The message for a name that does not resolve names the axis, which universe_axis reads.
The function drops a view that it cannot assemble, and it does not refuse it. The index of the view goes into excl, and the other rows keep their order. The indices count over all the views that the caller wrote, so excl can be longer than Q. remove_excl_views removes the matching entries of a confidence vector. When the function drops every view, no row is left and it returns nothing. The caller, bl_preroll, decides what that result means.
The function drops a full row. A view is one statement about several names, with one right-hand side. Thus a name that does not resolve removes the full row, and not only its own term. Without c, the view a + c == 0.05 becomes a == 0.05, which is a different and stronger statement than the caller wrote.
The cause of the failure decides only whether the function reports the drop. counterpart_axis_names reads the counterpart axis. In practice it is the Non-Investable Axis, which investable_views makes for the caller that derives the Investable Mask. A name on the counterpart axis was correct over the universe that the caller received, and the data removed it. The function drops its row with no report, under both settings of strict. The caller that derives the Investable Mask reports the departure once, through announce_non_investable. A name on neither axis is a typo, and the function reports it through strict_diagnostic.
Algorithm
- When
lcsis a vector, check that it is not empty. - Find the universe key
k, which iskeywhen it is notnothingandsets.xkeyotherwise. Read the universenx = sets.dict[k]. Read its axisaxisfor the messages withuniverse_axis, and read the counterpart axis withcounterpart_axis_names. - For each parsed view
lc, in the order that the caller wrote them, set each of thelength(nx)coefficients of the row accumulatorAtto zero, mark the view as kept, and do steps 4 to 7. - For each pair
(v, c)of a variable and its coefficient inlc, build the indicatorAi = (nx .== v). WhenAiselects no entry, mark the row as dropped. Ifvis not on the counterpart axis, report it throughstrict_diagnostic. If it is, record the row inledgerwithrecord_non_investable_drop!, once for each row. Otherwise addAi * ctoAt. The function reads each name of the row, so it reports both typos of a row that holds two. - When the row is marked as dropped, push the index
iof the view ontoexcl, and go to the next view. - When each entry of
Atis zero, each name of the view resolved and the coefficients cancel. Report the row throughstrict_diagnostic, pushiontoexcl, and go to the next view. Do not write a row. - Append
AttoPandlc.rhstoQ. - When
Pholds at least one row, reshape it tolength(nx)rows and transpose it, so each row ofPis one view. Return aBlackLittermanViewsofP,Qandexcl, withnothingin place of an emptyexcl. WhenPis empty, returnnothing.
Arguments
lcs: OneParsingResultor a vector of them, the parsed view equations.sets: TheUniverseSetsthat the names resolve against.key: Key of the universe insets.dictthat names resolve against. Ifnothing, the caller reads the key fromsets.xkey, or from the key of another declared axis when the caller is written against that axis.datatype: The numeric type of the coefficients and of the view returns.strict: Iftrue, a name that resolves against neither axis raises anArgumentError, and a row whose coefficients cancel raises anIsZeroError. Iffalse, both warn.ledger: The Departure Ledger of the entry of the fit, ornothingwhen no caller collects the drops. The function records in it each row that it drops for a name on the counterpart axis, throughrecord_non_investable_drop!.
Validation
- When
lcsis a vector,!isempty(lcs). - A name that matches no entry of
sets.dict[key]and no name of the counterpart axis raises an error throughstrict_diagnosticwhenstrictistrue, and warns otherwise. The message names the axis. The function drops the row in both cases. - A name on the counterpart axis drops its row with no report, under both settings of
strict. - A view whose names all resolve and whose coefficients cancel raises an
IsZeroErrorwhenstrictistrue, and warns otherwise. The function drops the row in both cases. - The assembled pair passes the checks of the
BlackLittermanViewsconstructor.
Returns
blv::Option{<:BlackLittermanViews}: The assembled views:P, with one row for each kept view andlength(sets.dict[key])columns, the view returnsQ, and the indicesexclof the dropped views, ornothinginexclwhen the function drops no view. The result isnothingwhen the function drops every view.
Examples
julia> sets = UniverseSets(; xkey = "nx", dict = Dict("nx" => ["A", "B", "C"]));julia> lcs = parse_equation(["A + B == 0.05", "C == 0.02"]);julia> PortfolioOptimisers.get_black_litterman_views(lcs, sets)BlackLittermanViews P ┼ 2×3 LinearAlgebra.Transpose{Float64, Matrix{Float64}} Q ┼ Vector{Float64}: [0.05, 0.02] excl ┴ nothingRelated
BlackLittermanViewsparse_equationUniverseSetsstrict_diagnosticDecides whether an unresolved name raises or warns.universe_axiscounterpart_axis_namesrecord_non_investable_drop!investable_viewsremove_excl_viewsDrops the confidences of the views this function excluded.bl_prerollThe caller that decides what anothinganswer means.
PortfolioOptimisers.assert_bl_views_conf — Function
assert_bl_views_conf(::Nothing, args...)
assert_bl_views_conf(views_conf::Number, ::EqnType)
assert_bl_views_conf(views_conf::VecNum, val::EqnType)
assert_bl_views_conf(views_conf::Num_VecNum, views::LinearConstraintEstimator)
assert_bl_views_conf(views_conf::Num_VecNum, views::BlackLittermanViews)Check the view confidences of a Black-Litterman prior estimator against its views.
Each confidence must lie strictly in (0, 1). A scalar is one confidence for all the views, for any number of views. A vector holds one confidence for each view that the caller wrote, so the function counts only a vector against the views. A scalar $v$ and the constant vector of $v$ give the same $\mathbf{\Omega}$ in calc_omega.
A precomputed BlackLittermanViews with excl holds length(Q) + length(excl) views that the caller wrote. remove_excl_views then removes the confidences of the views in excl, so one confidence remains for each row of P.
The bound is necessary. calc_omega changes a confidence $v$ into the scale $1/v - 1$, which is negative for each $v > 1$ and each $v < 0$. A view uncertainty matrix with a negative diagonal entry is not a covariance. Without the bound, the estimator returns a result made from such a matrix, and it raises no error. calc_omega states why the bound also refuses the two endpoints.
Arguments
views_conf: One confidence, or a vector of confidences.views: The views, aLinearConstraintEstimatoror aBlackLittermanViews.val: The equations of aLinearConstraintEstimator.
Validation
Each method selects one shape of views_conf and one shape of views, and refuses the input that the pair does not accept.
(::Nothing, args...): There is no confidence, so the method checks nothing.(::Number, ::EqnType):0 < views_conf < 1, throughassert_unit_interval. The method does not check the count, because one scalar is for any number of equations.(::VecNum, ::EqnType): Whenvalis a vector of equations,length(val) == length(views_conf). Whenvalis one equation,length(views_conf) == 1. Thenall(x -> 0 < x < 1, views_conf).(::Num_VecNum, ::LinearConstraintEstimator): The method checks nothing itself, and sendsviews.valto the two methods above.(::Num_VecNum, ::BlackLittermanViews): Whenviews_confis a vector,length(views_conf) == length(views.Q) + length(views.excl), with noexclterm whenviews.exclisnothing. Thenall(x -> 0 < x < 1, views_conf). A precomputed pair resolves no name, so this is the only site that sees its confidences.
Returns
nothing.
Related
PortfolioOptimisers.assert_bl — Function
assert_bl(
views::Union{BlackLittermanViews, LinearConstraintEstimator},
sets::Union{Nothing, UniverseSets},
views_conf::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
tau::Union{Nothing, Number}
)
Check the views, the sets, the view confidences and tau of a Black-Litterman prior estimator.
Each Black-Litterman constructor calls this guard, so the four members refuse the same input. The guard does not read the returns matrix, because the constructor does not have it. assert_bl_views_axis checks the universe against X in prior, and bl_preroll checks the width of P against the covariance.
Validation
- When
viewsis aLinearConstraintEstimator,!isnothing(sets), because the names of such a view resolve against a universe. Raises anIsNothingError. assert_bl_views_confchecksviews_confagainst the shape ofviews.- When
tauis notnothing,tau > 0. Raises aDomainError. The guard acceptsnothing, andbl_prerollchanges it to1/T.
Related