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, ornothing.
g:g: The spanned coefficients, ornothing.
ap:ap: The orthogonal part before the Orthogonal Forecast Scale, ornothing.
hist:hist: The Return Forecast history, ornothingwhen no Calibration Slot reads it.
Related
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
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, ornothing.
BW:BW: The benchmark weights,observations × assets.
Xu:Xu: The returns that the universe and the warm-up read.
cc:cc: The observed factors, anObservedFactors, ornothing. Its exposures hold the lastnrows and thepe.lagrows 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 lastnrows 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.
rw:rw: The rows after the Descriptor warm-up, ornothingbeforecross_sectional_exposure_stagetakes them.
Constructors
ExposureSeries(; amsk, emsk, mcap, BW, Xu, cc, Xl, rde, Ms, nf, fam, xf, rw) -> ExposureSeriesKeywords correspond to the struct's fields. rebuild_struct calls this form when cross_sectional_exposure_stage replaces rw.
Related
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, ornothing.
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
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
csr:csr: The regression on every factor, aCrossSectionalRegression, withlvin its field of the same name.
lv:lv:trueat each factor that is not empty.
Related
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
PortfolioOptimisers.Num_OrthFcScaleCal — Type
const Num_OrthFcScaleCal = Union{AbstractOrthogonalForecastScaleCalibrationAlgorithm,
Function, Number}Field bound for the Orthogonal Forecast Scale slot: the scale itself, a rule of the family, or a plain function of the same five arguments. It is the counterpart of Num_SpanShrinkCal, and carries its reading unchanged.
Related
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, ornothing.key: Name of the slot, for the message.
Validation
reads_forecast_historyanswersfalseforslotwhenrfeisnothingor aCustomValueReturnForecast. Raises anArgumentErrorthat names the slot and the forecast.
Returns
nothing.
Related
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
- A number lies in
[0, 1], byassert_closed_unit_interval. Raises aDomainError.
Returns
nothing.
Related
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
- A number is finite, by
assert_finite. Raises aDomainError. - A number is
>= 0, byassert_nonneg. Raises aDomainError.
Returns
nothing.
Related
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, ornothing.
Validation
- Under
OrthogonalPartCalibration,calibrates_orthogonal_partanswerstrueforrfe. Raises anArgumentErrorthat names the default rule and the rule of the forecast history.
Returns
nothing.
Related
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}}:xitself, 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
PortfolioOptimisers.cross_sectional_assemble — Function
cross_sectional_assemble(pe::CrossSectionalFactorPrior, f_pr::FactorPriorMoments,
ca::AppendedFactorModel, fit::NamedTuple, rde::ReturnsResult;
cache_reg::Bool = false, kwargs...) -> LowOrderPriorBuilds 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
- Record the degrees of freedom and the divisor of each variance with
cross_sectional_variance_counts, from the countcnt. - Standardise the idiosyncratic returns by
vswithcross_sectional_standardised_residuals, givingS, unlessfitcarries them. Take the latest idiosyncratic covarianceesigmawithcross_sectional_idiosyncratic_covariance, from the same residuals with no fill, so a gap stays a gap for the correlation, and repair it underpe.pdm. Whenfitcarries thecethat the carry fold folded over those residuals, read the covariance from its state instead. - Build the
CrossSectionalFactorModelblockcsfm, with the raw exposures of the latest observation inM, the reduced onesLbeside them, a zerob, and the Unseen Member rulepe.unseen, which the diagnostics and the attribution read. Under a family re-basis, expand the factor returns onto the raw axis withcross_sectional_expand, each row with the basis of its lagged exposures, and store them infr. - Fit the Return Forecast under the Orthogonal Forecast Fit
pe.ofitwithcross_sectional_return_forecastonrde, giving the spanned coefficientsg, the orthogonal partapbeforec, and the history when a slot answerstruetoreads_forecast_history. The history extends the rowshistoffitwhen the carry fold carries them. The forecast is the Resultrfoffitwhen the carry fold carries it. Store the cache of the refit on the block withcross_sectional_stored_cache: the active mask and the history, whencache_registrue. - Rebuild the asset return scenarios
Xswithcross_sectional_scenarios, and take the base-currency returns of the rows that they keep. - 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 thatcross_sectional_factor_momentsstates over the combined reduced factor returns.ca: The estimated factors with the observed factors appended, anAppendedFactorModelfromcross_sectional_observed_append.fit: The fitted observations:csr, the regression;W, its weights;vs, the idiosyncratic variance history;cnt, the answer ofvariance_counton 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, ornothing;SandSc, the standardised idiosyncratic returns with and with no fill that the carry fold carries, ornothing;ce, the covariance estimatorceof the prior that the carry fold folded overSc, ornothing;idx, the position of each fitted row in the returns data;ts, the timestamp of each fitted row, ornothing; andrf, the Return Forecast Result that the carry fold of a forecast that folds carries, ornothing.rde: The returns data that the estimated members read, which the Return Forecast reads.cache_reg: Iftrue, the block stores the cache that the refit ofscenario_priorreads: the active mask and, when a slot reads it, the Return Forecast history.kwargs...: Additional keyword arguments passed tocross_sectional_lift.
Validation
- The rules of
cross_sectional_moment_prior, and of every other verb the algorithm names.
Returns
pr::LowOrderPrior: The prior on the full asset universe, aspriorstates it.
Related
PortfolioOptimisers.cross_sectional_calibration — Function
cross_sectional_calibration(pe::CrossSectionalFactorPrior, f_pr::FactorPriorMoments,
csfm::CrossSectionalFactorModel, sp::SplitReturnForecast)
-> CalibrationValuesResolves 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
- Put the factor moments
f_printo aLowOrderPriorpr, on the reduced factor axis of the estimated factors and the observed factors. - Build a
CalibrationContextwhosecsholds the spanned coefficientsg, the unscaled orthogonal partapand the historyhistofsp, the blockcsfm, and the Cross-Sectional Regression Estimatorcreof the prior, which splits a row of the history. - Resolve
pe.lambdaunder the key:lambdaandpe.cunder the key:cwithresolve_calibration_slot, againstpr, its observation weightspr.w, no solver, and the context. - Refuse a resolved
lambdaoutside[0, 1]withassert_spanned_shrinkage, and a resolvedcthat is negative or not finite withassert_orthogonal_forecast_scale.
Arguments
pe: Cross-Sectional Factor Prior estimator.f_pr: The factor moments thatcross_sectional_factor_momentsstates over the combined reduced factor returns.csfm: The factor-model block, with a zeroband no Return Forecast.sp: The split of the Return Forecast, aSplitReturnForecast, ascross_sectional_return_forecaststates it.
Validation
- Each slot resolves to a number. Raises a
TypeErrorotherwise. - The rules of
assert_spanned_shrinkageandassert_orthogonal_forecast_scaleon the resolved numbers.
Returns
cv::CalibrationValues: The resolved Spanned Shrinkagelambdaand the resolved Orthogonal Forecast Scalec.
Related
PortfolioOptimisers.cross_sectional_forecast_block — Function
cross_sectional_forecast_block(csfm::CrossSectionalFactorModel,
sp::SplitReturnForecast, lambda::Number, c::Number)
-> CrossSectionalFactorModelWrite 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,
NaNat an asset whose forecast or whose latest exposures are not finite.cross_sectional_alpha_splitstates it.
Algorithm
- Take
b = c * sp.ap, or the zerobofcsfmwhen the prior states no Return Forecast Estimator. - Rebuild the block with
b, withsp.rfin its fieldrf, and withlambdaandcin its fields of the same names, throughrebuild_struct. It reads every field withgetfield. The propertyLofCrossSectionalFactorModelgivesMwhenLis unset, and the rebuilt block would then holdMas a setL. 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 zeroband no Return Forecast.sp: The split of the Return Forecast, aSplitReturnForecast, ascross_sectional_return_forecaststates it.lambda: The resolved Spanned Shrinkage.c: The resolved Orthogonal Forecast Scale.
Validation
- The rules of
CrossSectionalFactorModel.
Returns
rr::CrossSectionalFactorModel: The block, withb,rf,lambdaandcset.
Related
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 ofMsand then the columns ofZo. The refusal names the factors whose exposure history holds no finite value.Zo: The exposure history of the observed factors, on the axes ofMs, ornothing. Its factors join the factors of the definition beside those ofMs, so a caller that holds the two histories apart does not join them to test them.
Validation
nfholds one name per factor ofMsandZo. Raises aDimensionMismatch.- The rules of
cross_sectional_eligible. - At least one observation is not cold. Raises an
ArgumentErrorthat names the factors whose exposure history holds no finite value.
Returns
n::Int: The count of leading cold observations.
Related
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) -> ExposureSeriesRuns 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
- 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. - Take the rows
rwafter the Descriptor warm-up withcross_sectional_warmup, on the estimated and the observed exposures together.
Arguments
pe: Cross-Sectional Factor Prior estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2. It holds one observation per row.F: Data matrixobservations × factorsif thedimskeyword does not exist ordims = 1,factors × observationswhendims = 2. The steps do not read it. They write it onto the rebuilt returns data.pnl: Time-varying Asset Panel of the rows ofX.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
st::ExposureSeries: The record ofcross_sectional_exposure_series, withrw, the rows after the warm-up.
Related
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) -> ExposureSeriesRuns 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
- Rebuild the returns data, take the two universe masks and build the benchmark weights
BWwithcross_sectional_benchmark_stage. Split the factor listxf, or the one ofpe, into estimated and observed members withcross_sectional_factor_partition. - Read the observed factors with
cross_sectional_observed, and take the returns the regression reads,Xl, withcross_sectional_local_returns. Both copy the rows ofkeptand derive the rows after them. Whennis an integer, the observed members fold the rows of the step and compute their exposures alone. - When
nis an integer, fold the rows of the step into the Descriptors of the estimated members that carry a state withcross_sectional_descriptor_carry. - Build every estimated Factor Exposure with
cross_sectional_exposure_history, on the returns datardewhose returns areXl. 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. - 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 matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2. It holds one observation per row.F: Data matrixobservations × factorsif thedimskeyword does not exist ordims = 1,factors × observationswhendims = 2. The steps do not read it. They write it onto the rebuilt returns data.pnl: Time-varying Asset Panel of the rows ofX.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 ofXand the observed exposures of the lastpe.lagof them,(; Xn, Xl, Zo)as the fieldderof aCrossSectionalCarryStateholds them, ornothing.g0: Number of observations before the first row ofX.n: Number of last rows ofXwhose exposure history to compute, ornothingfor every row. The carry fold gives the number of rows of a step.xf: The factor list as the carry fold folded it, ornothingfor the factor list ofpe.
Validation
- The rules of every verb the algorithm names.
Returns
st::ExposureSeries: The fieldsamskandemsk, the active mask and the estimation mask;mcap, the market capitalisation ornothing;BW, the benchmark weights;Xu, the returns that the universe and the warm-up read;cc, the observed factors ornothing, whose exposures hold the lastnrows and thepe.lagrows before them, or every row;Xl, the returns the regression reads;rde, the returns data that the estimated members read;Ms,nfandfam, the exposure history of the estimated factors over the lastnrows 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; andrw = nothing.
Related
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) -> nothingReturn 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.
- No observed factor: return
nothing. - Every row of the batch fit,
n = nothing: returncc.Z. - The rows of a step of the carry fold: return
nothing.
Arguments
cc: The observed factors, ascross_sectional_observedreturns them, ornothing.n: Number of last rows of the step, ornothingfor every row.
Returns
Zo::Option{<:AbstractArray}: The observed exposures, ornothing.
Related
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})
-> ObservedFactorsPut 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.
- No observed exposures: return
cc. - Observed exposures: return
ccwithZ = Zo.
Arguments
cc: The observed factors, ascross_sectional_observedreturns them, ornothing.Zo: The observed exposures thatcross_sectional_exposure_historyreturns, ornothing.
Returns
cc::Option{<:ObservedFactors}: The observed factors, anObservedFactors.
Related
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) -> BenchmarkSeriesRebuilds 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
- Rebuild the returns data that the Descriptors read, from
X,F,ne,E,pnl,ivandivpa. The names of the assets are the column numbers. Take the two universe masks offpnlwithcross_sectional_panel_masks. - Take the returns
Xuthat the universe and the warm-up read:X, or the named net returns underpe.lx. - Build the benchmark weights
BWwithcross_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. - Write
BWonto a copy of the Asset Panel withcross_sectional_benchmark_returns.
Arguments
pe: Cross-Sectional Factor Prior estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2. It holds one observation per row.F: Data matrixobservations × factorsif thedimskeyword does not exist ordims = 1,factors × observationswhendims = 2. The steps do not read it. They write it onto the rebuilt returns data.pnl: Time-varying Asset Panel of the rows ofX.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 fieldsamskandemsk, the active mask and the estimation mask;mcap, the market capitalisation ornothing;BW, the benchmark weights;rdb, the returns data with the benchmark weights on its panel; andXu, the returns that the universe and the warm-up read.
Related
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, ormax(2K, 30)when it isnothing.
Related
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
- Without
lv, mark the factors that are not empty withcross_sectional_live_factors, givinglv. - If every factor is in
lv, regress onZwithcross_sectional_block_regressionaftert0observations, recordlvin the field of the same name of the regression, and return. - Otherwise, regress on the columns of
Zatlv, givingcsl. Write its factor returns into the columns atlvof a zero matrixf, keep its residuals, its counts and its intercept, and recordlv.
Arguments
cre: Cross-sectional regression estimator.Z: Exposure tensorassets × factors × observations.X: Asset returns matrixobservations × assets.W: Cross-sectional weights matrixobservations × assets.lv:trueat each factor to regress on.t0: Number of fitted observations before the first row ofX, which a refusal adds to the row it names.
Validation
- Without
lv, at least one factor is not empty. Raises anArgumentError. - The rules of
cross_sectional_design_maskand ofcross_sectional_regression.
Returns
lr::LiveRegression: The regressioncsron every factor ofZ, withlvin its field of the same name, andlv,trueat each factor that is not empty.
Related
PortfolioOptimisers.cross_sectional_pin_choice — Function
cross_sectional_pin_choice(choice::BatchChoice, pe::CrossSectionalFactorPrior) -> CrossSectionalFactorPrior
cross_sectional_pin_choice(choice::PinnedChoice, pe::CrossSectionalFactorPrior) -> CrossSectionalFactorPriorApplies 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.
BatchChoice: returnpe.PinnedChoice: take the families withcross_sectional_pinned_families. Returnpewhen it answersnothing, and otherwiseperebuilt with those families.
Arguments
choice: The Choice Rule ofpe.pe: The prior after the fold of the step.
Validation
- The rules of
cross_sectional_pinned_families.
Returns
pe::CrossSectionalFactorPrior: The prior that the step returns.
Related
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
- Answer
nothingwhenpe.familiesisnothing, or names the dropped member of every family. Nothing is left to pin. - Answer
nothingwhen every observation of the buffer has a Shared Series gap, because the fit keeps none, whichbuffer_fits_noneanswers. Otherwise drop the observations with a gap from the buffer and from a copy ofpewithshared_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, andpekeeps its weights. - Answer
nothingwhen the buffer records no Asset Panel. The call with no data refuses that buffer, so no fit is made. - Run
cross_sectional_exposure_stageover the rows of the buffer, with the Exogenous Series that the buffer records. Answernothingwhen fewer thanpe.lag + 2rows remain after the Descriptor warm-up, because the fit refuses them, so no first fit is made yet. - Neutralise the exposures after the warm-up with
neutralise_exposures!, and build the Factor Family Basis withfactor_family_basis. - Name the dropped member of each family in the order of
pe.families.
Arguments
pe: Cross-Sectional Factor Prior estimator whosecacheholds aSampleBufferState.
Validation
- The rules of every verb the algorithm names.
Returns
families::Option{<:Vector{<:Pair}}: Pairs offamily label => dropped member, ornothing.
Related
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 offactor name => Exposure Estimator.
Returns
pr::Vector{<:Pair}: The Pairs of the axis.
Related
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 butcache.
Related