Cross-Sectional Factor Prior (a): private API

Types

PortfolioOptimisers.SplitReturnForecast — Type
struct SplitReturnForecast{__T_rf, __T_g, __T_ap, __T_hist}

The split of the Return Forecast of a CrossSectionalFactorPrior into its spanned and orthogonal parts.

This type is an implementation detail and is not intended for direct use. cross_sectional_return_forecast and the refit of scenario_prior make it. cross_sectional_calibration, cross_sectional_forecast_block and cross_sectional_moment_prior read it.

Fields

  • rf: rf: The Return Forecast Result, or nothing.
  • g: g: The spanned coefficients, or nothing.
  • ap: ap: The orthogonal part before the Orthogonal Forecast Scale, or nothing.
  • hist: hist: The Return Forecast history, or nothing when no Calibration Slot reads it.

Related

source
PortfolioOptimisers.CalibrationValues — Type
struct CalibrationValues{__T_lambda, __T_c}

The Spanned Shrinkage and the Orthogonal Forecast Scale of a CrossSectionalFactorPrior, resolved against its fit.

This type is an implementation detail and is not intended for direct use. cross_sectional_calibration makes it. cross_sectional_moment_prior reads it. The two fields are numbers, so a positional swap would be silent. They can have two types: a stated c keeps its type, such as the Int target of a ForecastCalibrationSlope on a short history.

Fields

  • lambda: lambda: The resolved Spanned Shrinkage, in [0, 1].
  • c: c: The resolved Orthogonal Forecast Scale, finite and non-negative.

Related

source
PortfolioOptimisers.ExposureSeries — Type
struct ExposureSeries{__T_amsk, __T_emsk, __T_mcap, __T_BW, __T_Xu, __T_cc, __T_Xl, __T_rde, __T_Ms, __T_nf, __T_fam, __T_xf, __T_rw}

The steps of the fit of a CrossSectionalFactorPrior that give a value per observation: the masks, the benchmark weights, the observed factors, the returns that the regression reads and the exposure history.

This type is an implementation detail and is not intended for direct use. cross_sectional_exposure_series makes it with no rw, and cross_sectional_exposure_stage gives it the rows after the Descriptor warm-up. The regression stage, the online step under a PinnedChoice and the carry fold read it.

Fields

  • amsk: amsk: The active mask, observations × assets.
  • emsk: emsk: The estimation mask, observations × assets.
  • mcap: mcap: The market capitalisation, or nothing.
  • BW: BW: The benchmark weights, observations × assets.
  • Xu: Xu: The returns that the universe and the warm-up read.
  • cc: cc: The observed factors, an ObservedFactors, or nothing. Its exposures hold the last n rows and the pe.lag rows before them, or every row.
  • Xl: Xl: The returns that the regression reads.
  • rde: rde: The returns data that the estimated members read.
  • Ms: Ms: The exposure history of the estimated factors over the last n rows or every row, assets × factors × observations.
  • nf: nf: Name of each estimated factor.
  • fam: fam: Factor Family label of each estimated factor.
  • xf: xf: The factor list, with the state of each Descriptor after the rows of the step.

Constructors

ExposureSeries(; amsk, emsk, mcap, BW, Xu, cc, Xl, rde, Ms, nf, fam, xf, rw) -> ExposureSeries

Keywords correspond to the struct's fields. rebuild_struct calls this form when cross_sectional_exposure_stage replaces rw.

Related

source
PortfolioOptimisers.BenchmarkSeries — Type
struct BenchmarkSeries{__T_amsk, __T_emsk, __T_mcap, __T_BW, __T_rdb, __T_Xu}

The masks, the benchmark weights and the rebuilt returns data of a CrossSectionalFactorPrior.

This type is an implementation detail and is not intended for direct use. cross_sectional_benchmark_stage makes it. cross_sectional_exposure_series and the forecast history of the carry fold read it.

Fields

  • amsk: amsk: The active mask, observations × assets.
  • emsk: emsk: The estimation mask, observations × assets.
  • mcap: mcap: The market capitalisation, or nothing.
  • BW: BW: The benchmark weights, observations × assets.
  • rdb: rdb: The returns data with the benchmark weights on its panel.
  • Xu: Xu: The returns that the universe and the warm-up read.

Related

source
PortfolioOptimisers.LiveRegression — Type
struct LiveRegression{__T_csr, __T_lv}

A cross-sectional regression on the factors that are not empty, and the mark of those factors.

This type is an implementation detail and is not intended for direct use. cross_sectional_live_regression and cross_sectional_fold_pass make it. The regression stage and the carry fold of a CrossSectionalFactorPrior read it.

Fields

  • lv: lv: true at each factor that is not empty.

Related

source

Functions

PortfolioOptimisers.Num_SpanShrinkCal — Type
const Num_SpanShrinkCal = Union{AbstractSpannedShrinkageCalibrationAlgorithm,
                                Function, Number}

Field bound for the Spanned Shrinkage slot: the shrinkage itself, a rule of the family, or a plain function of the same five arguments.

The bound names one family, so a rule of the Orthogonal Forecast Scale family in the lambda slot is refused at construction. A function carries no family, so the name of the slot states the quantity there, as for Num_SigCal.

Related

source
PortfolioOptimisers.assert_forecast_history_rule — Function
assert_forecast_history_rule(slot, rfe::Nothing, key::Symbol)
assert_forecast_history_rule(slot, rfe::CustomValueReturnForecast, key::Symbol)
assert_forecast_history_rule(slot, rfe::AbstractReturnForecastEstimator, key::Symbol)

Refuse a rule that reads the Return Forecast history in a slot of a Cross-Sectional Factor Prior whose forecast has no history.

The constructor of CrossSectionalFactorPrior calls it on lambda and on c, so the refusal fires where the caller wrote the rule and not at the fit. A prior that states no Return Forecast Estimator has no forecast, and a CustomValueReturnForecast states one cross-section and fits none, so neither has a history. Every other member has one, and its method returns at once.

Arguments

  • slot: The occupant of the slot.
  • rfe: The Return Forecast Estimator of the prior, or nothing.
  • key: Name of the slot, for the message.

Validation

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_spanned_shrinkage — Function
assert_spanned_shrinkage(lambda::Number)
assert_spanned_shrinkage(lambda::UnresolvedValue)

Refuse a Spanned Shrinkage outside [0, 1].

The constructor of CrossSectionalFactorPrior calls it on the occupant of lambda, and cross_sectional_calibration calls it on the number a rule returns. A rule is checked once it is resolved, so the method for an UnresolvedValue, a calibration rule or a function, returns at once. Any other type is a MethodError.

Arguments

  • lambda: The Spanned Shrinkage, or the rule that computes it.

Validation

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_orthogonal_forecast_scale — Function
assert_orthogonal_forecast_scale(c::Number)
assert_orthogonal_forecast_scale(c::UnresolvedValue)

Refuse an Orthogonal Forecast Scale that is negative or not finite.

The scale multiplies the part of the Return Forecast that the factors do not span, so it lies in [0, ∞), and a value above one is a valid scale. The constructor of CrossSectionalFactorPrior calls it on the occupant of c, and cross_sectional_calibration calls it on the number a rule returns. A rule is checked once it is resolved, so the method for an UnresolvedValue, a calibration rule or a function, returns at once. Any other type is a MethodError.

Arguments

  • c: The Orthogonal Forecast Scale, or the rule that computes it.

Validation

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_orthogonal_forecast_fit — Function
assert_orthogonal_forecast_fit(ofit::AbstractOrthogonalForecastFit, rfe)
assert_orthogonal_forecast_fit(ofit::OrthogonalPartCalibration, rfe)

Refuse an Orthogonal Forecast Fit that the Return Forecast Estimator of a Cross-Sectional Factor Prior cannot run.

The constructor of CrossSectionalFactorPrior calls it on ofit and rfe, so the refusal fires where the caller wrote the rule and not at the fit. OrthogonalPartCalibration fits κ⊥ in the calibration of the member, so it needs a member that answers true to calibrates_orthogonal_part. Every other rule runs with every member, and its method returns at once.

Arguments

  • ofit: The Orthogonal Forecast Fit of the prior.
  • rfe: The Return Forecast Estimator of the prior, or nothing.

Validation

Returns

  • nothing.

Related

source
PortfolioOptimisers.string_key_pairs — Function
string_key_pairs(x::AbstractVector{<:Pair{String}}) -> x
string_key_pairs(x::Dict_VecPair) -> Vector{<:Pair{String}}

Return the Pairs of a vector or a dictionary as a vector of Pairs with String keys.

A vector whose keys are already String is returned itself, not a copy. So a rebuild of a CrossSectionalFactorPrior through its keyword constructor holds the vectors it was built from, and allocates nothing for them. Any other vector, and every dictionary, is collected into a new vector in its order of iteration. The fields of the prior are read by position, so a dictionary cannot be held as it is.

Arguments

  • x: The Pairs or the dictionary.

Returns

  • pr::AbstractVector{<:Pair{String}}: x itself, or the collected Pairs.

Examples

julia> x = ["style" => "industry"];julia> PortfolioOptimisers.string_key_pairs(x) === xtruejulia> PortfolioOptimisers.string_key_pairs([:style => "industry"])1-element Vector{Pair{String, String}}: "style" => "industry"

Related

source
PortfolioOptimisers.cross_sectional_assemble — Function
cross_sectional_assemble(pe::CrossSectionalFactorPrior, f_pr::FactorPriorMoments,
                         ca::AppendedFactorModel, fit::NamedTuple, rde::ReturnsResult;
                         cache_reg::Bool = false, kwargs...) -> LowOrderPrior

Builds the Prior Result of a CrossSectionalFactorPrior from its fitted regression, its idiosyncratic variance history and its factor moments.

The returns-matrix method of prior calls it after the variance history. The call with no data of the carry fold calls it with the histories it carries and the factor moments of its folded factor prior. So the two routes build the result with one code, and they differ only in how they reach its inputs.

Algorithm

  1. Record the degrees of freedom and the divisor of each variance with cross_sectional_variance_counts, from the count cnt.
  2. Standardise the idiosyncratic returns by vs with cross_sectional_standardised_residuals, giving S, unless fit carries them. Take the latest idiosyncratic covariance esigma with cross_sectional_idiosyncratic_covariance, from the same residuals with no fill, so a gap stays a gap for the correlation, and repair it under pe.pdm. When fit carries the ce that the carry fold folded over those residuals, read the covariance from its state instead.
  3. Build the CrossSectionalFactorModel block csfm, with the raw exposures of the latest observation in M, the reduced ones L beside them, a zero b, and the Unseen Member rule pe.unseen, which the diagnostics and the attribution read. Under a family re-basis, expand the factor returns onto the raw axis with cross_sectional_expand, each row with the basis of its lagged exposures, and store them in fr.
  4. Fit the Return Forecast under the Orthogonal Forecast Fit pe.ofit with cross_sectional_return_forecast on rde, giving the spanned coefficients g, the orthogonal part ap before c, and the history when a slot answers true to reads_forecast_history. The history extends the rows hist of fit when the carry fold carries them. The forecast is the Result rf of fit when the carry fold carries it. Store the cache of the refit on the block with cross_sectional_stored_cache: the active mask and the history, when cache_reg is true.
  5. Rebuild the asset return scenarios Xs with cross_sectional_scenarios, and take the base-currency returns of the rows that they keep.
  6. Run the steps that read the factor moments with cross_sectional_moment_prior: the refusal of a fit that determines no asset, the Calibration Slots, the blend, the expansion, the investable assets and the lift.

Arguments

  • pe: Cross-Sectional Factor Prior estimator.
  • f_pr: The factor moments that cross_sectional_factor_moments states over the combined reduced factor returns.
  • ca: The estimated factors with the observed factors appended, an AppendedFactorModel from cross_sectional_observed_append.
  • fit: The fitted observations: csr, the regression; W, its weights; vs, the idiosyncratic variance history; cnt, the answer of variance_count on the residuals; amr, the active mask; bwr, the benchmark weights; Xo, the base-currency returns; r, the fitted rows among the rows after the Descriptor warm-up; hist, the rows of the Return Forecast history that the carry fold carries, or nothing; S and Sc, the standardised idiosyncratic returns with and with no fill that the carry fold carries, or nothing; ce, the covariance estimator ce of the prior that the carry fold folded over Sc, or nothing; idx, the position of each fitted row in the returns data; ts, the timestamp of each fitted row, or nothing; and rf, the Return Forecast Result that the carry fold of a forecast that folds carries, or nothing.
  • rde: The returns data that the estimated members read, which the Return Forecast reads.
  • cache_reg: If true, the block stores the cache that the refit of scenario_prior reads: the active mask and, when a slot reads it, the Return Forecast history.
  • kwargs...: Additional keyword arguments passed to cross_sectional_lift.

Validation

Returns

  • pr::LowOrderPrior: The prior on the full asset universe, as prior states it.

Related

source
PortfolioOptimisers.cross_sectional_calibration — Function
cross_sectional_calibration(pe::CrossSectionalFactorPrior, f_pr::FactorPriorMoments,
                            csfm::CrossSectionalFactorModel, sp::SplitReturnForecast)
    -> CalibrationValues

Resolves the Spanned Shrinkage lambda and the Orthogonal Forecast Scale c of a CrossSectionalFactorPrior against its fit.

cross_sectional_assemble calls it after the split of the Return Forecast and before the mean, so the batch fit, the refit and each online step of the carry fold resolve the two slots alike. A stated number passes through resolve_calibration_slot unchanged, and the range check then applies to it as to the number of a rule.

Algorithm

  1. Put the factor moments f_pr into a LowOrderPrior pr, on the reduced factor axis of the estimated factors and the observed factors.
  2. Build a CalibrationContext whose cs holds the spanned coefficients g, the unscaled orthogonal part ap and the history hist of sp, the block csfm, and the Cross-Sectional Regression Estimator cre of the prior, which splits a row of the history.
  3. Resolve pe.lambda under the key :lambda and pe.c under the key :c with resolve_calibration_slot, against pr, its observation weights pr.w, no solver, and the context.
  4. Refuse a resolved lambda outside [0, 1] with assert_spanned_shrinkage, and a resolved c that is negative or not finite with assert_orthogonal_forecast_scale.

Arguments

Validation

Returns

  • cv::CalibrationValues: The resolved Spanned Shrinkage lambda and the resolved Orthogonal Forecast Scale c.

Related

source
PortfolioOptimisers.cross_sectional_forecast_block — Function
cross_sectional_forecast_block(csfm::CrossSectionalFactorModel,
                               sp::SplitReturnForecast, lambda::Number, c::Number)
    -> CrossSectionalFactorModel

Write the scaled orthogonal part of the Return Forecast, the Return Forecast Result and the resolved Calibration Slots onto the block of a CrossSectionalFactorPrior.

Mathematical definition

\[\begin{align} \boldsymbol{b} &= c_{\alpha} \, \boldsymbol{\alpha}^{\perp}\,. \end{align}\]

Where:

  • $\boldsymbol{b}$: Factor-orthogonal expected return of the block, one entry per asset.
  • $c_{\alpha}$: Orthogonal Forecast Scale, the resolved c.
  • $\boldsymbol{\alpha}^{\perp}$: Orthogonal part of a Return Forecast, one entry per asset, NaN at an asset whose forecast or whose latest exposures are not finite. cross_sectional_alpha_split states it.

Algorithm

  1. Take b = c * sp.ap, or the zero b of csfm when the prior states no Return Forecast Estimator.
  2. Rebuild the block with b, with sp.rf in its field rf, and with lambda and c in its fields of the same names, through rebuild_struct. It reads every field with getfield. The property L of CrossSectionalFactorModel gives M when L is unset, and the rebuilt block would then hold M as a set L. Every other field passes through, so the refit of an entropy pooling prior keeps the cache of the block.

Arguments

  • csfm: The factor-model block, built with a zero b and no Return Forecast.
  • sp: The split of the Return Forecast, a SplitReturnForecast, as cross_sectional_return_forecast states it.
  • lambda: The resolved Spanned Shrinkage.
  • c: The resolved Orthogonal Forecast Scale.

Validation

Returns

  • rr::CrossSectionalFactorModel: The block, with b, rf, lambda and c set.

Related

source
PortfolioOptimisers.cross_sectional_warmup — Function
cross_sectional_warmup(
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    Ms::AbstractArray{<:Union{Number, AbstractJuMPScalar}, 3},
    emsk::AbstractMatrix{Bool},
    nf::AbstractVector{<:AbstractString}
) -> Int64
cross_sectional_warmup(
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    Ms::AbstractArray{<:Union{Number, AbstractJuMPScalar}, 3},
    emsk::AbstractMatrix{Bool},
    nf::AbstractVector{<:AbstractString},
    Zo::Union{Nothing, AbstractArray{<:Union{Number, AbstractJuMPScalar}, 3}}
) -> Int64

Return the number of leading observations a Cross-Sectional Factor Prior discards.

A Descriptor warms up, so the first observations of an exposure history carry no usable asset. An observation is cold when no asset of the estimation universe carries both a finite return and a finite Factor Exposure to every factor. The prior fits from the first observation that is not cold.

Mathematical definition

\[\begin{align} n &= \min\left\{t : \exists\, i,\ e_{ti} = 1,\ x_{t,\,i} \in \mathbb{R},\ B_{tik} \in \mathbb{R} \ \forall k \in \{1, \ldots, K\}\right\} - 1\,. \end{align}\]

Where:

  • $n$: Count of the leading cold observations.
  • $e_{ti}$: Estimation flag of asset $i$ at observation $t$, $1$ when the estimation mask of the Asset Panel holds the asset and $0$ when it does not.
  • $x_{t,\,i}$: Return of asset $i$ at observation $t$.
  • $B_{tik}$: Exposure of asset $i$ to factor $k$ at observation $t$.
  • $K$: Number of factors.

Arguments

  • X: Asset returns, observations × assets.
  • Ms: The exposure history, assets × factors × observations.
  • emsk: The estimation mask, observations × assets.
  • nf: The name of each factor, the columns of Ms and then the columns of Zo. The refusal names the factors whose exposure history holds no finite value.
  • Zo: The exposure history of the observed factors, on the axes of Ms, or nothing. Its factors join the factors of the definition beside those of Ms, so a caller that holds the two histories apart does not join them to test them.

Validation

  • nf holds one name per factor of Ms and Zo. Raises a DimensionMismatch.
  • The rules of cross_sectional_eligible.
  • At least one observation is not cold. Raises an ArgumentError that names the factors whose exposure history holds no finite value.

Returns

  • n::Int: The count of leading cold observations.

Related

source
PortfolioOptimisers.cross_sectional_exposure_stage — Function
cross_sectional_exposure_stage(pe::CrossSectionalFactorPrior, X::MatNum,
                               F::Option{<:MatNum}, pnl::AssetPanel;
                               ne::Option{<:VecStr} = nothing,
                               E::Option{<:MatNum} = nothing,
                               iv::Option{<:MatNum} = nothing,
                               ivpa::Option{<:Num_VecNum} = nothing) -> ExposureSeries

Runs the steps of the fit of a CrossSectionalFactorPrior that read the whole history: the benchmark weights, the observed factors, the returns that the regression reads, the exposure history, and the rows after the Descriptor warm-up.

The returns-matrix method of prior and the online step under a PinnedChoice both read these steps. So the choice that the step pins is the choice that the fit over the same rows makes.

Algorithm

  1. Run the steps that give a value per observation with cross_sectional_exposure_series: the benchmark weights, the observed factors, the returns the regression reads and the exposure history.
  2. Take the rows rw after the Descriptor warm-up with cross_sectional_warmup, on the estimated and the observed exposures together.

Arguments

  • pe: Cross-Sectional Factor Prior estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2. It holds one observation per row.
  • F: Data matrix observations × factors if the dims keyword does not exist or dims = 1, factors × observations when dims = 2. The steps do not read it. They write it onto the rebuilt returns data.
  • pnl: Time-varying Asset Panel of the rows of X.
  • ne: Names of the Exogenous Series.
  • E: The Exogenous Series, one observation per row. The observed factors read their returns from it.
  • iv: Implied volatilities, written onto the rebuilt returns data.
  • ivpa: Implied-volatility risk-premium adjustment, written onto the rebuilt returns data.

Validation

  • The rules of every verb the algorithm names.

Returns

Related

source
PortfolioOptimisers.cross_sectional_exposure_series — Function
cross_sectional_exposure_series(pe::CrossSectionalFactorPrior, X::MatNum,
                                F::Option{<:MatNum}, pnl::AssetPanel;
                                ne::Option{<:VecStr} = nothing,
                                E::Option{<:MatNum} = nothing,
                                iv::Option{<:MatNum} = nothing,
                                ivpa::Option{<:Num_VecNum} = nothing,
                                kept::Option{<:NamedTuple} = nothing,
                                g0::Integer = 0,
                                n::Option{<:Integer} = nothing,
                                xf::Option{<:AbstractVector} = nothing) -> ExposureSeries

Runs the steps of the fit of a CrossSectionalFactorPrior that give a value per observation: the benchmark weights, the observed factors, the returns that the regression reads, and the exposure history.

cross_sectional_exposure_stage runs it over every observation, and then drops the Descriptor warm-up. The carry fold runs it over the rows that it carries and the rows of a step. The returns net of the observed factors are derived series: the batch fit derives each row from the observed exposures of the row pe.lag observations before it, and the first pe.lag rows of the sample from the exposure of the same row. So the carry gives the derived rows of its carried rows in kept, and the function derives the rows of the step alone. The carry gives the number of rows of the step in n too, so the exposure history and the observed exposures hold those rows alone. A Descriptor that carries a state reads the rows of the step alone: the carry gives the members as it folded them in xf, and the function folds the rows of the step into them with cross_sectional_descriptor_carry and cross_sectional_observed.

Algorithm

  1. Rebuild the returns data, take the two universe masks and build the benchmark weights BW with cross_sectional_benchmark_stage. Split the factor list xf, or the one of pe, into estimated and observed members with cross_sectional_factor_partition.
  2. Read the observed factors with cross_sectional_observed, and take the returns the regression reads, Xl, with cross_sectional_local_returns. Both copy the rows of kept and derive the rows after them. When n is an integer, the observed members fold the rows of the step and compute their exposures alone.
  3. When n is an integer, fold the rows of the step into the Descriptors of the estimated members that carry a state with cross_sectional_descriptor_carry.
  4. Build every estimated Factor Exposure with cross_sectional_exposure_history, on the returns data rde whose returns are Xl. Under observed factors those are the net returns, so a Descriptor of the returns measures the move of an asset net of its currency, and not the move of the currency it holds.
  5. Join the folded members of both parts in the order of the factor list with cross_sectional_factor_join.

Arguments

  • pe: Cross-Sectional Factor Prior estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2. It holds one observation per row.
  • F: Data matrix observations × factors if the dims keyword does not exist or dims = 1, factors × observations when dims = 2. The steps do not read it. They write it onto the rebuilt returns data.
  • pnl: Time-varying Asset Panel of the rows of X.
  • ne: Names of the Exogenous Series.
  • E: The Exogenous Series, one observation per row. The observed factors read their returns from it.
  • iv: Implied volatilities, written onto the rebuilt returns data.
  • ivpa: Implied-volatility risk-premium adjustment, written onto the rebuilt returns data.
  • kept: The derived rows of the first rows of X and the observed exposures of the last pe.lag of them, (; Xn, Xl, Zo) as the field der of a CrossSectionalCarryState holds them, or nothing.
  • g0: Number of observations before the first row of X.
  • n: Number of last rows of X whose exposure history to compute, or nothing for every row. The carry fold gives the number of rows of a step.
  • xf: The factor list as the carry fold folded it, or nothing for the factor list of pe.

Validation

  • The rules of every verb the algorithm names.

Returns

  • st::ExposureSeries: The fields amsk and emsk, the active mask and the estimation mask; mcap, the market capitalisation or nothing; BW, the benchmark weights; Xu, the returns that the universe and the warm-up read; cc, the observed factors or nothing, whose exposures hold the last n rows and the pe.lag rows before them, or every row; Xl, the returns the regression reads; rde, the returns data that the estimated members read; Ms, nf and fam, the exposure history of the estimated factors over the last n rows or every row, with their names and Factor Family labels; xf, the factor list with the state of each Descriptor after the rows of the step; and rw = nothing.

Related

source
PortfolioOptimisers.cross_sectional_history_observed — Function
cross_sectional_history_observed(cc::Nothing, n) -> nothing
cross_sectional_history_observed(cc::ObservedFactors, n::Nothing) -> AbstractArray
cross_sectional_history_observed(cc::ObservedFactors, n::Integer) -> nothing

Return the observed exposures that the exposure history of cross_sectional_exposure_series shares a backing with, or nothing.

The batch fit joins the observed exposures to the history after its regression, so the two can share one backing, as cross_sectional_history_backing states. The carry fold computes the rows of a step alone, and its observed exposures hold pe.lag more rows than its history, so the two keep their own arrays.

Algorithm

The method that Julia selects is the algorithm.

  1. No observed factor: return nothing.
  2. Every row of the batch fit, n = nothing: return cc.Z.
  3. The rows of a step of the carry fold: return nothing.

Arguments

  • cc: The observed factors, as cross_sectional_observed returns them, or nothing.
  • n: Number of last rows of the step, or nothing for every row.

Returns

  • Zo::Option{<:AbstractArray}: The observed exposures, or nothing.

Related

source
PortfolioOptimisers.cross_sectional_observed_rebacked — Function
cross_sectional_observed_rebacked(cc, Zo::Nothing) -> Option{<:ObservedFactors}
cross_sectional_observed_rebacked(cc::ObservedFactors, Zo::AbstractArray{<:Any, 3})
    -> ObservedFactors

Put the observed exposures that the exposure history returns into the observed factors cc.

When the history shares a backing with the observed exposures, it returns them as a view of that backing, and the observed factors carry the view, so the later join of the two is a view too. With no shared backing, the observed factors are unchanged.

Algorithm

The method that Julia selects is the algorithm.

  1. No observed exposures: return cc.
  2. Observed exposures: return cc with Z = Zo.

Arguments

Returns

Related

source
PortfolioOptimisers.cross_sectional_benchmark_stage — Function
cross_sectional_benchmark_stage(pe::CrossSectionalFactorPrior, X::MatNum,
                                F::Option{<:MatNum}, pnl::AssetPanel;
                                ne::Option{<:VecStr} = nothing,
                                E::Option{<:MatNum} = nothing,
                                iv::Option{<:MatNum} = nothing,
                                ivpa::Option{<:Num_VecNum} = nothing) -> BenchmarkSeries

Rebuilds the returns data of a CrossSectionalFactorPrior, and writes its benchmark weights onto the Asset Panel.

cross_sectional_exposure_stage runs it first. The carry fold runs it on the rows that it carries, because each of its outputs is a value per row: the benchmark weights of a row read the market capitalisation and the returns of that row alone.

Algorithm

  1. Rebuild the returns data that the Descriptors read, from X, F, ne, E, pnl, iv and ivpa. The names of the assets are the column numbers. Take the two universe masks off pnl with cross_sectional_panel_masks.
  2. Take the returns Xu that the universe and the warm-up read: X, or the named net returns under pe.lx.
  3. Build the benchmark weights BW with cross_sectional_cap_weights, over the assets of the estimation universe whose return and market capitalisation are finite. A benchmark power of zero reads no market capitalisation.
  4. Write BW onto a copy of the Asset Panel with cross_sectional_benchmark_returns.

Arguments

  • pe: Cross-Sectional Factor Prior estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2. It holds one observation per row.
  • F: Data matrix observations × factors if the dims keyword does not exist or dims = 1, factors × observations when dims = 2. The steps do not read it. They write it onto the rebuilt returns data.
  • pnl: Time-varying Asset Panel of the rows of X.
  • ne: Names of the Exogenous Series.
  • E: The Exogenous Series, one observation per row.
  • iv: Implied volatilities, written onto the rebuilt returns data.
  • ivpa: Implied-volatility risk-premium adjustment, written onto the rebuilt returns data.

Validation

  • The rules of every verb the algorithm names.

Returns

  • st::BenchmarkSeries: The fields amsk and emsk, the active mask and the estimation mask; mcap, the market capitalisation or nothing; BW, the benchmark weights; rdb, the returns data with the benchmark weights on its panel; and Xu, the returns that the universe and the warm-up read.

Related

source
PortfolioOptimisers.cross_sectional_minra — Function
cross_sectional_minra(
    pe::CrossSectionalFactorPrior,
    K::Integer
) -> Integer

Returns the smallest eligible asset count of an observation of a Cross-Sectional Factor Prior.

The batch fit and the carry fold refuse an observation with fewer eligible assets, through assert_cross_sectional_coverage.

Arguments

  • pe: Cross-Sectional Factor Prior estimator.
  • K: Number of factors on the reduced factor axis.

Returns

  • minra::Integer: pe.minra, or max(2K, 30) when it is nothing.

Related

source
PortfolioOptimisers.cross_sectional_live_regression — Function
cross_sectional_live_regression(
    cre::AbstractCrossSectionalRegressionEstimator,
    Z::AbstractArray{<:Union{Number, AbstractJuMPScalar}, 3},
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    W::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
) -> LiveRegression{__T_csr, BitVector} where __T_csr<:CrossSectionalRegression

Regress each observation on the factors that are not empty, and give every Empty Factor a return of zero.

A factor is empty when its exposure is zero at every pair of positive weight, which are the pairs that the regression reads. A sub-universe with no asset in one level of a one-hot factor leaves the factor of that level empty, and a meta-optimiser gives its sub-problems such sub-universes. The data then state nothing about the return of the factor. The function regresses on the other factors and writes a zero return, so the answer does not depend on how the solve algorithm of cre treats a rank-deficient design.

Mathematical definition

\[\begin{align} \mathcal{E} &= \left\{k : B_{tik} = 0 \ \forall (t, i) : u_{ti} > 0\right\}\,, \\ f_{tk} &= 0\,, \quad k \in \mathcal{E}\,,\ t = 1, \ldots, T\,. \end{align}\]

Where:

  • $\mathcal{E}$: Empty Factors.
  • $B_{tik}$: Exposure of asset $i$ to factor $k$ at observation $t$.
  • $u_{ti}$: Cross-sectional weight of asset $i$ at observation $t$.
  • $\boldsymbol{f}_{t}$: Factor returns of observation $t$, $K \times 1$, with entry $f_{tk}$ for factor $k$.
  • $T$: Number of observations.

A zero column of the design adds nothing to the fit, so the returns of the other factors are the returns of the regression on every factor. The minimum-norm solution of that regression gives the same zero to an Empty Factor.

Algorithm

The method with lv regresses on the factors that a caller marks. The carry fold of a CrossSectionalFactorPrior calls it on its new observations, with the mark of every observation it fitted, so a factor that is empty at the new observations alone keeps its column, as it does in the batch fit. The fold also gives the number t0 of observations it fitted before them, so a refusal names the observation that the batch fit names.

Algorithm

  1. Without lv, mark the factors that are not empty with cross_sectional_live_factors, giving lv.
  2. If every factor is in lv, regress on Z with cross_sectional_block_regression after t0 observations, record lv in the field of the same name of the regression, and return.
  3. Otherwise, regress on the columns of Z at lv, giving csl. Write its factor returns into the columns at lv of a zero matrix f, keep its residuals, its counts and its intercept, and record lv.

Arguments

  • cre: Cross-sectional regression estimator.
  • Z: Exposure tensor assets × factors × observations.
  • X: Asset returns matrix observations × assets.
  • W: Cross-sectional weights matrix observations × assets.
  • lv: true at each factor to regress on.
  • t0: Number of fitted observations before the first row of X, which a refusal adds to the row it names.

Validation

Returns

  • lr::LiveRegression: The regression csr on every factor of Z, with lv in its field of the same name, and lv, true at each factor that is not empty.

Related

source
PortfolioOptimisers.cross_sectional_pin_choice — Function
cross_sectional_pin_choice(choice::BatchChoice, pe::CrossSectionalFactorPrior) -> CrossSectionalFactorPrior
cross_sectional_pin_choice(choice::PinnedChoice, pe::CrossSectionalFactorPrior) -> CrossSectionalFactorPrior

Applies the Choice Rule of a Cross-Sectional Factor Prior after an online step.

A batch choice chooses again at each call with no data, so the step returns pe unchanged. A pinned choice writes the dropped member of each Factor Family into families, once the buffer holds the rows of a first fit.

Algorithm

The method that Julia selects is the algorithm.

  1. BatchChoice: return pe.
  2. PinnedChoice: take the families with cross_sectional_pinned_families. Return pe when it answers nothing, and otherwise pe rebuilt with those families.

Arguments

  • choice: The Choice Rule of pe.
  • pe: The prior after the fold of the step.

Validation

Returns

  • pe::CrossSectionalFactorPrior: The prior that the step returns.

Related

source
PortfolioOptimisers.cross_sectional_pinned_families — Function
cross_sectional_pinned_families(
    pe::CrossSectionalFactorPrior
) -> Any

Returns the Factor Families of a Cross-Sectional Factor Prior with the dropped member of each one named, as the fit over the rows of its buffer chooses it, or nothing when there is nothing to pin yet.

This is the step of a PinnedChoice. It runs the steps of the fit that the choice reads, with cross_sectional_exposure_stage, the Neutralisation and factor_family_basis, over the rows of the buffer. So the name it writes is the member that the call with no data after the same step drops, and every later call with no data drops it too.

Algorithm

  1. Answer nothing when pe.families is nothing, or names the dropped member of every family. Nothing is left to pin.
  2. Answer nothing when every observation of the buffer has a Shared Series gap, because the fit keeps none, which buffer_fits_none answers. Otherwise drop the observations with a gap from the buffer and from a copy of pe with shared_series_buffer_fit, as the call with no data drops them. A fixed weight vector of the copy loses the weights of the dropped observations. The later steps read the copy, and pe keeps its weights.
  3. Answer nothing when the buffer records no Asset Panel. The call with no data refuses that buffer, so no fit is made.
  4. Run cross_sectional_exposure_stage over the rows of the buffer, with the Exogenous Series that the buffer records. Answer nothing when fewer than pe.lag + 2 rows remain after the Descriptor warm-up, because the fit refuses them, so no first fit is made yet.
  5. Neutralise the exposures after the warm-up with neutralise_exposures!, and build the Factor Family Basis with factor_family_basis.
  6. Name the dropped member of each family in the order of pe.families.

Arguments

Validation

  • The rules of every verb the algorithm names.

Returns

  • families::Option{<:Vector{<:Pair}}: Pairs of family label => dropped member, or nothing.

Related

source
PortfolioOptimisers.cross_sectional_axis_pairs — Function
cross_sectional_axis_pairs(
    factors::AbstractVector{<:Pair}
) -> Any

Return the Pairs whose factor axis a CrossSectionalFactorPrior produces: its estimated members, then its observed members.

The fit puts the observed factors after the estimated factors, so the axis declared before the fit puts them in the same place.

Arguments

  • factors: Pairs of factor name => Exposure Estimator.

Returns

  • pr::Vector{<:Pair}: The Pairs of the axis.

Related

source
PortfolioOptimisers.show_fields — Method
show_fields(
    _::CrossSectionalFactorPrior
) -> NTuple{30, Symbol}

Renders every field of a CrossSectionalFactorPrior except cache.

The state a cache holds is the running detail of an incremental fit, not the configuration a reader looks the type up for. Set set_show_nothing_fields!(:CrossSectionalFactorPrior, true) to render it.

Arguments

  • ::CrossSectionalFactorPrior: Prior estimator, read for its type alone.

Returns

  • fields::Tuple: The field names to render, every field but cache.

Related

source