Listing Span: private API

Types

PortfolioOptimisers.ListingSpan — Type
struct ListingSpan <: AbstractMatrix{Bool}

Stores the listing interval of each asset as two integers and reads it as a matrix of booleans.

ListingSpan holds the Listing Span of each asset, the interval of the price clock from the first priced observation of the asset to its last. size answers (observations, assets), and getindex(s, t, i) answers first[i] <= t <= last[i], so every reader sees an ordinary AbstractMatrix{Bool}. The type holds two integers per asset in place of one boolean per cell. The compression is exact, because the Span Rule keeps an interior gap inside the listing, so the active set of an asset is one interval. A column that is a gap throughout takes the empty interval, first[i] > last[i].

The type is unexported. It owns size, getindex, IndexStyle and show. PortfolioOptimisers.project_span and PortfolioOptimisers.listing_span_view carry a library-internal fast path for it, which keeps the two integers per asset through a projection and through a window. A caller writes against the public bound, AbstractMatrix{Bool}, and a caller's own declaration, such as a listing calendar or a constituency that leaves and joins again, enters under that bound.

Mathematical definition

\[\begin{align} a_{t,\,i} &= \begin{cases} 1 & f_{i} \leq t \leq l_{i} \\ 0 & \text{otherwise} \end{cases}\,, \quad t = 1, \ldots, n\,. \end{align}\]

An empty interval, $f_{i} > l_{i}$, gives $a_{t,\,i} = 0$ at every observation.

Where:

  • $a_{t,\,i}$: Listing indicator of asset $i$ at observation $t$ of the price clock, $1$ when the asset is listed and $0$ when it is not.
  • $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.

Fields

  • first: Index of the first priced observation of each asset, on the clock of the span. A window of a longer clock puts this bound at zero or below for an asset that is listed before the window opens.
  • last: Index of the last priced observation of each asset, on the clock of the span. An asset that is a gap throughout carries last[i] < first[i], the empty interval. A window of a longer clock puts this bound above n for an asset that is still listed when the window closes.
  • n: Length of the clock of the span, in observations.

Constructors

ListingSpan(first::VecInt, last::VecInt, n::Integer) -> ListingSpan

Validation

  • length(first) == length(last). Raises a DimensionMismatch.
  • n >= 0. Raises a DomainError.

Examples

julia> PortfolioOptimisers.ListingSpan([1, 2], [3, 3], 3)ListingSpan(3 × 2)

Related

source

Functions

PortfolioOptimisers.project_span — Function
project_span(span::ListingSpan, m::Integer) -> ListingSpan
project_span(span::AbstractMatrix{Bool}, m::Integer) -> BitMatrix

Project a price-clock listing statement onto a returns clock of m observations.

A return is the change between two consecutive prices, so a return is active when both prices of its pair lie inside the listing of the asset. The projection follows from that rule under either padding convention. With padding, the two clocks align row for row and return t reads prices t - 1 and t, so the first row is active for no asset. Without padding, the returns clock is one observation shorter and return t reads prices t and t + 1. The active mask thus starts at the first return whose two prices lie inside the listing, and it stops at the last one. The first return of an asset is therefore never a Held Gap. An interior gap next to either end of the listing does make one, because the asset is still listed there.

On a PortfolioOptimisers.ListingSpan the projection moves the two bounds, so the two integers per asset stay two integers. A bound lies outside the clock when the span is a window of a longer clock, and the projection clamps the opening bound to the clock before it moves it. The projection of a window thus equals the projection of the matrix of booleans that the window holds. An asset with one priced observation gets the empty interval, because one price gives no return. On any other AbstractMatrix{Bool}, which is how a caller's own declaration enters, the rule applies cell by cell, so a constituency that leaves and joins again books no return across its absence.

Mathematical definition

\[\begin{align} \tilde{a}_{t,\,i} &= a_{t+o-1,\,i} \wedge a_{t+o,\,i}\,, \quad t = 1, \ldots, m\,, \\ \tilde{f}_{i} &= \max(f_{i}, 1) + 1 - o\,, \\ \tilde{l}_{i} &= l_{i} - o\,. \end{align}\]

The first line is the rule for a matrix of booleans, with $a_{0,\,i} = 0$. The second and the third lines are the same rule on an interval: $\tilde{a}_{t,\,i} = 1$ exactly when $\tilde{f}_{i} \leq t \leq \tilde{l}_{i}$. Under padding, $\tilde{a}_{1,\,i} = 0$ for every asset, because the first return reads a price before the clock.

Where:

  • $\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.
  • $a_{t,\,i}$: Listing indicator of asset $i$ at observation $t$ of the price clock, $1$ when the asset is listed and $0$ when it is not.
  • $\tilde{f}_{i}$, $\tilde{l}_{i}$: First and last active observation of asset $i$, on the returns clock.
  • $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.
  • $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

The method that Julia selects is the algorithm.

  1. PortfolioOptimisers.ListingSpan: read the clock offset o off the two row counts. Clamp each opening bound to the clock and move it up by 1 - o, and move each closing bound down by o. Return the moved bounds as a ListingSpan of length m.
  2. Any other AbstractMatrix{Bool}: read the clock offset o off the two row counts, and write span[a, i] && span[a + 1, i] into row a + 1 - o of amsk.

Arguments

  • span: The listing statement, price observations × assets.
  • m::Integer: Length of the returns clock to project onto.

Returns

  • amsk: The active mask, m × assets, on the returns clock.

Related

source