Black-Litterman Views Generation: private API

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

  1. When lcs is a vector, check that it is not empty.
  2. Find the universe key k, which is key when it is not nothing and sets.xkey otherwise. Read the universe nx = sets.dict[k]. Read its axis axis for the messages with universe_axis, and read the counterpart axis with counterpart_axis_names.
  3. For each parsed view lc, in the order that the caller wrote them, set each of the length(nx) coefficients of the row accumulator At to zero, mark the view as kept, and do steps 4 to 7.
  4. For each pair (v, c) of a variable and its coefficient in lc, build the indicator Ai = (nx .== v). When Ai selects no entry, mark the row as dropped. If v is not on the counterpart axis, report it through strict_diagnostic. If it is, record the row in ledger with record_non_investable_drop!, once for each row. Otherwise add Ai * c to At. The function reads each name of the row, so it reports both typos of a row that holds two.
  5. When the row is marked as dropped, push the index i of the view onto excl, and go to the next view.
  6. When each entry of At is zero, each name of the view resolved and the coefficients cancel. Report the row through strict_diagnostic, push i onto excl, and go to the next view. Do not write a row.
  7. Append At to P and lc.rhs to Q.
  8. When P holds at least one row, reshape it to length(nx) rows and transpose it, so each row of P is one view. Return a BlackLittermanViews of P, Q and excl, with nothing in place of an empty excl. When P is empty, return nothing.

Arguments

  • lcs: One ParsingResult or a vector of them, the parsed view equations.
  • sets: The UniverseSets that the names resolve against.
  • key: Key of the universe in sets.dict that names resolve against. If nothing, the caller reads the key from sets.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: If true, a name that resolves against neither axis raises an ArgumentError, and a row whose coefficients cancel raises an IsZeroError. If false, both warn.
  • ledger: The Departure Ledger of the entry of the fit, or nothing when no caller collects the drops. The function records in it each row that it drops for a name on the counterpart axis, through record_non_investable_drop!.

Validation

  • When lcs is a vector, !isempty(lcs).
  • A name that matches no entry of sets.dict[key] and no name of the counterpart axis raises an error through strict_diagnostic when strict is true, 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 IsZeroError when strict is true, and warns otherwise. The function drops the row in both cases.
  • The assembled pair passes the checks of the BlackLittermanViews constructor.

Returns

  • blv::Option{<:BlackLittermanViews}: The assembled views: P, with one row for each kept view and length(sets.dict[key]) columns, the view returns Q, and the indices excl of the dropped views, or nothing in excl when the function drops no view. The result is nothing when 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 ┴ nothing

Related

source
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

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, through assert_unit_interval. The method does not check the count, because one scalar is for any number of equations.
  • (::VecNum, ::EqnType): When val is a vector of equations, length(val) == length(views_conf). When val is one equation, length(views_conf) == 1. Then all(x -> 0 < x < 1, views_conf).
  • (::Num_VecNum, ::LinearConstraintEstimator): The method checks nothing itself, and sends views.val to the two methods above.
  • (::Num_VecNum, ::BlackLittermanViews): When views_conf is a vector, length(views_conf) == length(views.Q) + length(views.excl), with no excl term when views.excl is nothing. Then all(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

source
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

Related

source