Cross-Sectional Idiosyncratic Diagnostics: private API
Types
PortfolioOptimisers.RowMoments — Type
struct RowMoments{__T_n, __T_m2, __T_m3, __T_m4}Holds the count and the three central moments of one cross-section of standardised idiosyncratic returns.
This type is an implementation detail and is not intended for direct use. idio_row_moments makes it, and idio_calibration, idio_kurtosis and idio_skewness read it. The three moments are numbers of one type, so a record names them where a plain tuple would let a swap pass silently.
Fields
n:n: Number of assets at which the standardised return is finite.
m2:m2: Second central moment, orNaNwhennis zero.
m3:m3: Third central moment, orNaNwhennis zero.
m4:m4: Fourth central moment, orNaNwhennis zero.
Related
Functions
PortfolioOptimisers.standardised_idio_value — Function
standardised_idio_value(e::Real, v::Real)Return one standardised idiosyncratic return.
The verb divides the idiosyncratic return by the standard deviation the fit predicted for it. The answer is NaN where the division has no meaning. A variance that is not positive, a variance that is not finite, and a return that is not finite each give NaN. A negative variance counts as zero, so a variance estimate that undershot gives NaN and does not raise.
Mathematical definition
\[\begin{align} z_{ti} &= \begin{cases} \dfrac{\varepsilon_{ti}}{\hat{\sigma}_{ti}} & \text{if } \hat{\sigma}_{ti} > 0 \text{ and the ratio is finite}\,, \\ \mathrm{NaN} & \text{otherwise}\,. \end{cases} \end{align}\]
Where:
- $z_{ti}$: Standardised idiosyncratic return of asset $i$ at observation $t$.
- $\varepsilon_{ti}$: Idiosyncratic return of asset $i$ at observation $t$.
- $\hat{\sigma}_{ti} = \sqrt{\max(v_{ti}, 0)}$: Predicted idiosyncratic volatility of asset $i$ at observation $t$. A negative variance counts as zero.
- $v_{ti}$: Idiosyncratic variance of asset $i$ that the fit estimated from the observations up to $t$, so it is the forecast for observation $t + 1$.
Arguments
e: One idiosyncratic return.v: The idiosyncratic variance predicted for it.
Returns
z::Real: The standardised return, orNaN.
Related
PortfolioOptimisers.idio_predicted_volatility — Function
idio_predicted_volatility(vs::MatNum)Return the idiosyncratic volatility history the fit predicted.
A negative variance counts as zero, so a variance estimate that undershot gives 0 and does not raise. The two dependence series rank the assets by this quantity.
Mathematical definition
\[\begin{align} \hat{\sigma}_{ti} &= \sqrt{\max(v_{ti}, 0)}\,. \end{align}\]
Where:
- $\hat{\sigma}_{ti} = \sqrt{\max(v_{ti}, 0)}$: Predicted idiosyncratic volatility of asset $i$ at observation $t$. A negative variance counts as zero.
- $v_{ti}$: Idiosyncratic variance of asset $i$ that the fit estimated from the observations up to $t$, so it is the forecast for observation $t + 1$.
Arguments
vs: Idiosyncratic variance historyobservations × assets.
Returns
s::Matrix{<:Real}: Predicted volatilityobservations × assets, of a floating-point type. A variance that is not finite givesNaN.
Related
PortfolioOptimisers.idio_row_moments — Function
idio_row_moments(z::MatNum, t::Integer) -> RowMomentsReturn the count and the three central moments of one cross-section of standardised idiosyncratic returns.
The calibration, the excess kurtosis and the skewness are each a function of these four numbers alone. So the verb makes its two passes over the cross-section once, and three series read the answer. An entry that is not finite enters neither the count nor a moment.
Mathematical definition
\[\begin{align} \bar{z}_{t} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{F}_{t}} z_{ti}\,, \\ m_{pt} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{F}_{t}} \left( z_{ti} - \bar{z}_{t} \right)^{p}\,, \quad p \in \{2, 3, 4\}\,. \end{align}\]
Where:
- $\bar{z}_{t}$: Mean of the finite standardised returns of observation $t$.
- $m_{pt}$: Central moment of order $p$ of the finite standardised returns of observation $t$.
- $z_{ti}$: Standardised idiosyncratic return of asset $i$ at observation $t$.
- $\mathcal{F}_{t}$: Finite cross-section of observation $t$, the assets whose standardised return $z_{ti}$ is finite.
- $n_{t}$: Count of the assets in $\mathcal{F}_{t}$.
A cross-section whose finite entries are all equal has $m_{pt} = 0$ for every $p$.
Algorithm
- Pass over row
tofzonce. Over the finite entries, find the countn, the sums, the least entryloand the greatest entryhi. - When
nis zero, returnNaNfor the three moments. - Divide
sbynand clamp the answer to[lo, hi], giving the meanm. A mean of equal values can carry round-off, so without the clamp a constant cross-section would give a tiny positivem2in place of zero. With the clamp,mequals the common value exactly, and every deviation is zero. - Pass over row
tagain. Sum the second, third and fourth powers of the deviations fromm, and divide each sum byn, givingm2,m3andm4.
Arguments
z: Standardised idiosyncratic returnsobservations × assets.t: Position of the observation.
Returns
m::RowMoments: The countnand the momentsm2,m3andm4, asRowMomentsstates them.nis anInt, and each moment isNaNwhennis zero.
Related
PortfolioOptimisers.idio_vol_dependence — Function
idio_vol_dependence(eps::MatNum, vs::MatNum, standardise::Bool, ties::Symbol)Return the rank correlation of the predicted idiosyncratic volatility against the next observation's absolute idiosyncratic return, standardised or not.
It does the work of idio_vol_ic and of idio_vol_residual_dependence. The two read the same two cross-sections, and differ only in whether they divide the target by the predicted volatility. Both score the volatility the fit predicted at observation $t$ against what the asset realised at observation $t + 1$, so the series has one entry fewer than the history. Those two docstrings state the mathematics.
Algorithm
- Check that
epsis not empty, thatvshas its size, and that it has more than one observation. - Compute the predicted volatility
sigwithidio_predicted_volatility. - For each observation
tbut the last, fillawith rowtofsig. Fillbwith the absolute idiosyncratic returns of observationt + 1. Whenstandardiseistrue, divide each entry ofbby the volatility predicted at observationt, throughstandardised_idio_value. - Correlate
aandbwithcs_spearman_correlationundermin_count = 5andties, giving entrytofc.
Arguments
eps: Idiosyncratic return historyobservations × assets.vs: Idiosyncratic variance historyobservations × assets.standardise: Divide the absolute return of observation $t + 1$ by the volatility predicted at observation $t$.ties: Rule that ranks the equal values of a cross-section.:averagegives each value of a tie the mean of the positions the tie takes, so a rank correlation does not read the order of the assets, and a constant cross-section has no rank correlation.:ordinalgives the values of a tie consecutive positions, in the order of the asset axis. The two rules give the same ranks to a cross-section with no tie.
Validation
!isempty(eps).size(vs) == size(eps).size(eps, 1) > 1.- The rules of
cs_ranks.
Returns
c::Vector{<:Real}: The series,observations - 1entries. Entrytreads observationstandt + 1. An observation that shares fewer than five finite assets isNaN.
Related
PortfolioOptimisers.idio_nan_mean — Function
idio_nan_mean(v::VecNum)Return the mean of the finite entries of a series.
A diagnostic series is NaN at an observation that had too few assets, and the summary reads the observations that answered. This verb states that rule once for the four means the summary takes.
Mathematical definition
\[\begin{align} \bar{a} &= \frac{1}{|\mathcal{A}|} \sum_{t \in \mathcal{A}} a_{t}\,. \end{align}\]
Where:
- $\bar{a}$: Mean of the finite entries.
- $a_{t}$: Diagnostic series value at observation $t$.
- $\mathcal{A}$: Finite observations of a diagnostic series, those at which $a_{t}$ is finite.
The mean is not defined for an empty $\mathcal{A}$.
Arguments
v: The series.
Returns
m::Real: The mean of the finite entries, orNaNwhen the series has none.
Related
PortfolioOptimisers.idio_nan_median — Function
idio_nan_median(v::VecNum)Return the median of the finite entries of a series.
The summary reads the median of the calibration series beside its mean. One observation with a cross-section that is almost constant moves the mean, but not the median.
Mathematical definition
\[\begin{align} \tilde{a} &= \operatorname{median} \left\{ a_{t} : t \in \mathcal{A} \right\}\,. \end{align}\]
Where:
- $\tilde{a}$: Median of the finite entries. For an even count it is the mean of the two middle entries.
- $a_{t}$: Diagnostic series value at observation $t$.
- $\mathcal{A}$: Finite observations of a diagnostic series, those at which $a_{t}$ is finite.
The median is not defined for an empty $\mathcal{A}$.
Arguments
v: The series.
Returns
m::Real: The median of the finite entries, orNaNwhen the series has none.
Related
PortfolioOptimisers.idio_diagnostic_data — Function
idio_diagnostic_data(csfm::CrossSectionalFactorModel)
idio_diagnostic_data(csr::Nothing, vs::Option{<:MatNum})
idio_diagnostic_data(csr::CrossSectionalRegression, vs::Nothing)
idio_diagnostic_data(csr::CrossSectionalRegression, vs::MatNum)Return the idiosyncratic return history and the idiosyncratic variance history that an idiosyncratic diagnostic reads off a factor model block.
The group reads the residual of the fit against the variance the fit predicted for it. Neither history has a factor axis, so the group takes no lag and no family re-basis, and it reads the two histories as the block wrote them. Dispatch, not a branch, selects the absent case, and its message names the field the caller must populate.
A pair that the h1 field of the regression marks has a leverage of one: the design fitted its return exactly, so its residual is zero by construction and its variance under the design is zero too. Its standardised return is $0 / 0$, which is not defined, so the verb writes NaN over its residual and every verb of the group leaves the pair out. The verb writes NaN over its variance too, as forecast_idiosyncratic_variances does, because a variance that read such residuals is not a forecast of the next return: under ahead = true the first unmarked row after a marked row would divide by it, and idio_vol_ic would rank it. A variance that read only such residuals and that the mask does not reach is zero, and standardised_idio_value answers NaN for it.
Arguments
csfm: A cross-sectional factor model block.csr: Thecsrfield of the block, ornothing.vs: Thevsfield of the block, ornothing.
Validation
csfm.csris notnothing, else the verb raises anIsNothingErrorthat namescsr.csfm.vsis notnothing, else the verb raises anIsNothingErrorthat namesvs.
Returns
eps::MatNum: Idiosyncratic return historyobservations × assets,NaNat a pair thath1marks.vs::MatNum: Idiosyncratic variance historyobservations × assets,NaNat a pair thath1marks.
Related