Exposure constraint generation: private API

PortfolioOptimisers.factor_space_regression — Function
factor_space_regression(re::Option{<:RegE_Reg}, rr::Option{<:AbstractLoadingsRegressionResult},
                        rd::Option{<:ReturnsResult})
    -> Option{<:AbstractLoadingsRegressionResult}

Apply the precedence of resolve_factor_regression to the three sources of loadings of a FactorSpace. Return nothing when no source holds loadings.

FactorRiskContribution uses the same precedence. At x_src = nothing, a stated result comes first, then the rr of the prior, then a refit. resolve_factor_regression gives the order for each other source. This function calls the same two parts as that function, source_loadings and refit_factor_regression, and does not repeat them. The sources are different. Constraint generation receives the loadings as rr, which the caller already read from the prior. The prior arm reads that argument, not a field. Both re and rd are optional here, because a space that names no source and a route with no returns are both ordinary.

The function returns nothing and does not throw, by design. constraint_space_basis diagnoses the case with no basis, because it knows that it assembles a constraint.

Algorithm

  1. Return re when it is a precomputed Regression. The caller stated the basis, and no data is necessary.
  2. Otherwise return rr when re is nothing. This is the behaviour of FactorSpace(). When rr is also nothing, no source holds a basis, and constraint_space_basis writes the diagnosis.
  3. Otherwise re is an estimator. Return the loadings that source_loadings takes from rr under the source of re, when they are not nothing. At x_src = nothing the loadings are rr, and PriorSource refuses rr === nothing.
  4. Otherwise raise when rd is nothing. When rd is present, return refit_factor_regression(re, rd). It refits the loadings from the returns that the source of re names, which are rd.X, or rd.X - rd.B under ExcessSource.

Step 4 is a capability of the field, not a fallback. With FactorSpace(; re = StepwiseRegression()), a factor mandate works on a prior that holds no loadings.

Arguments

  • re::Option{<:RegE_Reg}: The source of the basis that the space states, or nothing to read rr.
  • rr::Option{<:AbstractLoadingsRegressionResult}: The loadings of the prior, or nothing.
  • rd::Option{<:ReturnsResult}: Returns from which to refit, or nothing on the standalone route.

Validation

  • The rule of source_loadings. An estimator in re at x_src = PriorSource() with rr === nothing throws an ArgumentError.
  • An estimator in re that must refit with no rd throws an IsNothingError that names the three fixes. The refit needs the returns. A JuMPOptimiser and a Pipeline step pass the returns and can refit. The standalone linear_constraints route receives no returns and cannot refit.

Returns

  • rr::Option{<:AbstractLoadingsRegressionResult}: The loadings of the source with the highest rank, or nothing when no source holds loadings.

Related

source
PortfolioOptimisers.project_linear_constraint — Function
project_linear_constraint(lc::LinearConstraint, M::MatNum; strict::Bool = false)
    -> Option{<:LinearConstraint}
project_linear_constraint(plc::PartialLinearConstraint, M::MatNum; strict::Bool = false)
    -> Option{<:PartialLinearConstraint}
project_linear_constraint(::Nothing, ::MatNum; kwargs...) -> Nothing

Re-base an assembled constraint by the projection of its coefficient matrix, A * transpose(M).

The estimator route projects term by term, and this function is the half of the projection for a precomputed constraint. It is the one place where linear_constraints does more than pass a LinearConstraint through. A precomputed constraint that reaches the optimiser through an ExposureConstraintEstimator is written in the wrapped basis, so it still needs a re-basis. The right-hand side does not change, because a change of basis acts on the row and not on the bound.

The function checks size(A, 2) == size(M, 2) and does not assume it. A precomputed constraint holds no names. Without this check, a matrix over the assets given to a FactorSpace wrapper goes through when the numbers of assets and factors differ.

A re-based row whose coefficients are all zero does not depend on the weights, so the function drops it. The estimator route drops such a row in get_linear_constraints too. The loadings make such a row when every factor that the row weights has zero loadings.

Algorithm

The PartialLinearConstraint method does the computation, and the LinearConstraint method applies it to the two halves.

  1. Check that plc.A has one column per factor, size(plc.A, 2) == size(M, 2).
  2. Project the coefficient matrix, A = plc.A * transpose(M).
  3. Report each row of A whose coefficients are all zero through strict_diagnostic with IsZeroError, and drop it with its entry of plc.B.
  4. Return a PartialLinearConstraint of the rows that remain, with their entries of plc.B unchanged. Return nothing when no row remains.
  5. For a whole LinearConstraint, apply steps 1 to 4 to ineq and to eq, and rebuild the constraint from the two. A half that is nothing stays nothing, through the Nothing method. Return nothing when both halves are nothing.

Arguments

  • lc: The assembled LinearConstraint, written over the factors.
  • plc: One half of it, a PartialLinearConstraint.
  • M: The loadings, Na × Nf.
  • strict: If true, a re-based row whose coefficients are all zero raises an IsZeroError. If false, it warns. The row is dropped either way.

Validation

  • size(plc.A, 2) == size(M, 2). Otherwise a DimensionMismatch names both counts.
  • A re-based row whose coefficients are all zero raises an IsZeroError when strict is true, and warns otherwise. The row is dropped either way.

Returns

  • lc::Option{<:LinearConstraint} or plc::Option{<:PartialLinearConstraint}: The same shape over the assets, or nothing when the function dropped every row. A is re-based, and B is the B of the input.

Related

source
PortfolioOptimisers.rebase_linear_constraints — Function
rebase_linear_constraints(lce, sets::UniverseSets, basis, key; datatype, strict, bl_flag)

Re-base one wrapped shape. The method depends on the shape that the ExposureConstraintEstimator wraps:

Algorithm

The two single-shape methods reach the same row by two routes. The estimator route builds the row term by term, and the precomputed route projects a finished row.

  1. For a LinearConstraintEstimator, pick the key: lce.key when the wrapped estimator states one, and key otherwise.
  2. Call linear_constraints on lce.val against that key, with basis passed as rr. constraint_row_term then sums the selected columns of basis.M for each named term, which is the projection done one term at a time.
  3. For a precomputed LinearConstraint, call project_linear_constraint on it with basis.M and strict, which projects the assembled coefficient matrix in one product. basis.M is the only field of the basis either route reads, so the regression's intercept never enters.
  4. For a vector, apply steps 1 to 3 to each element in turn and return the results in the order of the input.

Arguments

  • lce: The wrapped shape. It is a LinearConstraintEstimator, a LinearConstraint, or a vector of either.
  • sets: The declared universe the names resolve against.
  • basis: The loadings that constraint_space_basis resolved.
  • key: The key against which the names resolve, when the wrapped estimator states no key.
  • datatype: Data type of the assembled row.
  • strict: If true, a name that the universe does not resolve throws, and a row whose coefficients are all zero raises an IsZeroError. If false, each case warns. The function drops the row in both cases.
  • bl_flag: If true, a group expands to the mean over its members, as the Black-Litterman views need. If false, it expands to the sum.

Returns

  • lc: A LinearConstraint over the assets, nothing when the function dropped every row, or a vector of either in the order of lce.

Related

source
PortfolioOptimisers.reader_frames — Method
reader_frames(space::FactorSpace, path::AbstractString, refit::Bool)
reader_frames(ece::ExposureConstraintEstimator, path::AbstractString, refit::Bool)

Return the frames that the regression reader of a constraint space adds to the group of the optimiser that holds the constraint.

A FactorSpace holds its reader in re, and an ExposureConstraintEstimator holds the space in space. Each method reads the field at its path, so the warning of warn_raw_readers names a reader with its path, for example "lcse.space.re". A precomputed Regression and re = nothing are not readers, and they add no frames.

Arguments

  • space, ece: The constraint space, or the constraint estimator that holds it.
  • path: The path of the value from the head, for example "pe", "cle" or "r[2].pe". A warning names a reader by its path.
  • refit: true when a regression reader at x_src = nothing in the group fits its regression on the raw returns data. refits_regression finds the value.

Returns

  • fr::ReturnsFrames: The frames of the reader in the field.

Related

source