Listing Span
The listing span
The listing span of an asset is the range of observations over which the asset is listed. listing_span finds one span per asset column from the position of each gap in the prices. A run of gaps at the start of a column means that the asset is not listed yet. A run of gaps at the end means that the asset was delisted. A gap with prices on both sides is a suspension or a holiday, and the asset is still listed and still held. With this rule, you can derive the universe from the prices alone, without a listing calendar.
universe_masks moves the spans onto the dates of the returns and makes the two universe masks that an AssetPanel carries. The active mask marks the assets that are listed at each observation. The estimation mask is the active mask where the return is also finite. A return needs the earlier price of its pair. A span from first to last on the prices therefore becomes [first + 1, last] on padded returns, and [first, last - 1] on returns without padding. The active mask then starts at the first return whose two prices are both in the listing, so the first price of an asset never shows as a missing return. The two masks differ only at a return that reads a gap with prices on both sides. This is also true when the gap is next to the first or the last price of the listing. There the asset is listed but has no return, and a cross-validation fold that holds the asset reports the observation and counts its return as zero.
Both functions take plain arrays, and neither needs an estimator. universe_masks also accepts your own AbstractMatrix{Bool} in place of the spans, such as a listing calendar or the membership of an index that an asset leaves and joins again. Your matrix takes the place of the derived spans, and universe_masks moves it onto the dates of the returns in the same way. You cannot give the estimation mask. universe_masks always derives it from the active mask and the returns, so the estimation mask never marks a cell that the active mask leaves out.
PortfolioOptimisers.listing_span — Function
listing_span(X::AbstractMatrix{<:Union{Missing, Real}}) -> ListingSpanDerive the Listing Span of every asset column of a price panel by the Span Rule.
The Span Rule reads the position of a gap in a price column, so a caller who holds only prices can state a universe. A leading run of gaps is an asset that is not listed yet, and a trailing run is a delisting. An interior gap, with prices on both sides, is a suspension or a holiday on an asset that is still listed and still held. The first two fall outside the span and the third falls inside it. A cell counts as priced when it is neither missing nor non-finite, so the two spellings of an absent price read alike.
The derivation runs once over the whole panel, not once per window. A listing calendar is a fact about the instruments and not an estimate from returns, so one derivation serves every window. A derivation over one window reads a gap that runs past the end of the window as a delisting, although the asset resumes after the window and is still held.
Mathematical definition
\[\begin{align} \mathcal{P}_{i} &= \left\{t \in \{1, \ldots, n\} : \text{asset } i \text{ is priced at observation } t\right\}\,, \\ f_{i} &= \min \mathcal{P}_{i}\,, \\ l_{i} &= \max \mathcal{P}_{i}\,. \end{align}\]
An asset with an empty $\mathcal{P}_{i}$ takes an empty interval, $f_{i} > l_{i}$. Every observation from $f_{i}$ to $l_{i}$ is listed, so an interior gap stays inside the listing.
Where:
- $\mathcal{P}_{i}$: Priced observations of asset $i$, those at which its price is neither
missingnor non-finite. - $f_{i}$: First observation of the Listing Span of asset $i$, on the price clock.
- $l_{i}$: Last observation of the Listing Span of asset $i$, on the price clock.
- $n$: Price clock length, the number of price observations.
Algorithm
- For each asset column, find the first and the last observation whose price is neither
missingnor non-finite. - A column with no priced observation takes the empty interval,
first = 1andlast = 0. - Return the two bound vectors as a
PortfolioOptimisers.ListingSpanover the price clock.
Arguments
X: The price panel,observations × assets. A source spells an absent price asmissingor as a non-finite value.
Validation
Xis not empty. Raises anIsEmptyError.
Returns
span::ListingSpan: The Listing Span of each asset column, on the price clock.
Examples
julia> X = [NaN 1.0 3.0 1.0 NaN 3.1 1.1 2.0 NaN];julia> span = listing_span(X)ListingSpan(3 × 3)julia> Matrix(span)3×3 Matrix{Bool}: 0 1 1 1 1 1 1 1 0Related
PortfolioOptimisers.universe_masks — Function
universe_masks(
span::AbstractMatrix{Bool},
R::AbstractMatrix{<:Union{Missing, Real}}
) -> Tuple{AbstractMatrix{Bool}, BitMatrix}Project a listing statement onto the returns clock and intersect it with finiteness to make the two universe masks of an Asset Panel.
The active mask states which assets are in the universe at each observation. It is span projected by PortfolioOptimisers.project_span. A caller who passes their own AbstractMatrix{Bool} in place of a derived PortfolioOptimisers.ListingSpan replaces the answer of the Span Rule, and the function does not change that answer. The estimation mask is the active mask intersected with the finiteness of the returns. An asset inside a Held Gap is active, because it is still listed and still held, but it has no return at that observation, so it cannot enter the cross-section of that observation. A caller cannot state the estimation mask. The function always derives it, so emsk ⊆ amsk holds by construction, and the mask always agrees with the returns that the conversion made.
The estimation mask is a copy of the finiteness of R when the function runs, not a view of R. A later step that rewrites a return thus does not change the estimation universe of a fold that already has a score.
The function reads the padding convention off the two row counts, and no other function does. size(span, 1) == size(R, 1) is the padded case, where the first observation stays with a non-finite return. size(span, 1) == size(R, 1) + 1 is the unpadded case.
Mathematical definition
\[\begin{align} e_{t,\,i} &= \tilde{a}_{t,\,i} \wedge \mathbb{1}\left[x_{t,\,i} \text{ is present and finite}\right]\,, \quad t = 1, \ldots, m\,, \\ o &\in \{0, 1\}\,. \end{align}\]
It follows that $e_{t,\,i} \leq \tilde{a}_{t,\,i}$ at every observation.
Where:
- $e_{t,\,i}$: Estimation mask entry of asset $i$ at observation $t$ of the returns clock.
- $\tilde{a}_{t,\,i}$: Active mask entry of asset $i$ at observation $t$ of the returns clock, $1$ when both prices of the return lie inside the listing of the asset.
- $x_{t,\,i}$: Return of asset $i$ at observation $t$.
- $o = n - m$: Clock offset, $0$ when padding keeps the first observation and $1$ when it does not.
- $n$: Price clock length, the number of price observations.
- $m$: Returns clock length, the number of return observations.
Algorithm
- Read the padding convention off the row counts of
spanandR. - Project
spanonto the returns clock withPortfolioOptimisers.project_span, giving the active maskamsk. - Intersect
amskwith the finiteness ofR, giving the estimation maskemsk.
Arguments
span: The listing statement,price observations × assets. APortfolioOptimisers.ListingSpanfromlisting_span, or a caller's own declaration.R: The returns panel the conversion produced,observations × assets. An absent return ismissingor a non-finite value.
Validation
size(span, 2) == size(R, 2). Raises aDimensionMismatch.size(span, 1)issize(R, 1)orsize(R, 1) + 1. Raises aDimensionMismatch.
Returns
amsk: The active mask,observations × assetson the returns clock. APortfolioOptimisers.ListingSpanwhenspanis one, and aBitMatrixotherwise.emsk::BitMatrix: The estimation mask,observations × assetson the returns clock.
Examples
julia> X = [NaN 1.0 3.0 1.0 NaN 3.1 1.1 2.0 NaN];julia> R = [NaN NaN NaN NaN NaN 0.1 0.1 NaN NaN];julia> amsk, emsk = universe_masks(listing_span(X), R);julia> Matrix(amsk)3×3 Matrix{Bool}: 0 0 0 0 1 1 1 1 0julia> emsk3×3 BitMatrix: 0 0 0 0 0 1 1 0 0Related