Returns buffer state

What an optimiser stores between updates

When you update an optimiser with partial_fit!, it passes the asset returns to its prior. It stores the rest of the ReturnsResult in a PortfolioOptimisers.ReturnsBufferState. The benchmark returns and the timestamps each go in a buffer of their own. The factor returns go in a buffer here only when the prior does not read them, or when the optimiser has no prior. The state also stores the asset names and the static asset panel of the first update. The prior holds the asset returns, and this state stores them only when the optimiser has no prior. PortfolioOptimisers.returns_result rebuilds the ReturnsResult that a batch fit over the same observations would read.

PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    state::ReturnsBufferState,
    rd::ReturnsResult;
    own_returns,
    own_factors,
    own_exogenous
) -> ReturnsBufferState

Folds the observations of a ReturnsResult into a ReturnsBufferState.

The step of the state itself. The optimiser decides once which columns the state owns. own_returns is true for a head that holds no prior, and for an optimiser whose prior folds the returns in excess of the benchmark, because its buffer then holds no raw row. A state whose prior keeps the raw rows appends no X and no mask. own_factors is false when the prior's tree reads F. The prior's buffer then records the factor column, and its own first-append rule refuses a column that comes and goes, so this state does not keep F and does not check its presence. own_exogenous is false when the prior's tree reads the Exogenous Series. The prior's buffer then records every column of the series and its names, so this state keeps neither E nor ne, and the buffer pins the names.

A head that holds no prior keeps the active mask of a time-varying panel and nothing else of that panel. The estimation mask and the Panel Fields do not reach the state, and no such head reads them. An optimiser with a prior refuses returns data that holds a part its route cannot record, in fold_prior. The implied volatilities and ivpa travel with the returns, so the buffer that holds the rows records them: the prior's buffer, or the state's own X for a head that holds no prior.

Algorithm

  1. Refuse an rd with no returns.
  2. Read n, the number of observations the state holds, and pnl, which is the panel when it is static and nothing when it is time-varying.
  3. On the first step, when n is zero and no names are pinned, pin nx, nf, nb and pnl, and pin ne when the state owns the series.
  4. On every later step, refuse an rd whose names or static panel differ from the pinned ones, and an rd that adds or drops a column the state owns.
  5. When the state owns the rows, append X with fold_column_masked, with the active mask of a time-varying panel, and with rd.iv and rd.ivpa.
  6. When the state owns the factor column, append F with fold_column. When it owns the series, append E with fold_column.
  7. Append B and ts with fold_column, and return the new state.

Arguments

  • state: The state to fold into.
  • rd: The returns data of one or more observations, observations × assets.
  • own_returns: Whether the state keeps the returns. It is true for a head that holds no prior, and for an optimiser whose prior states x_src = ExcessSource() and so folds the returns in excess of the benchmark. It is false otherwise.
  • own_factors: Whether the state keeps the factor column. It is true for a head that holds no prior and for an optimiser whose prior's tree never reads F, and false otherwise.
  • own_exogenous: Whether the state keeps the Exogenous Series and its names. It is true for a head that holds no prior and for an optimiser whose prior's tree never reads the series, and false otherwise.

Validation

  • rd.X is not nothing. An IsNothingError is thrown otherwise.
  • After the first step, the names, the static panel and the presence of each column the state owns agree with the first step. An ArgumentError is thrown otherwise.
  • Every refusal of partial_fit! on a SampleBufferState holds for the matrix columns.

Returns

  • state::ReturnsBufferState: The state after the last observation.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    x::ReturnsBufferState,
    i,
    args...
) -> ReturnsBufferState

Slices a ReturnsBufferState to the selected assets.

The asset axis runs through nx, X, a matrix benchmark with its names, and the panel. The factors, the Exogenous Series, the timestamps and a single-column benchmark have no asset axis, so the slice copies them unchanged. A later fold on the sliced state appends to these vectors in place, and a shared vector would change the state that the slice came from, as port_opt_view on a SampleBufferState explains for its factor rows. The names and the panel come back as views, because no step writes into pinned context.

Algorithm

  1. Slice nx and the panel to i as views, and slice X with port_opt_view on its buffer.
  2. When B is a SampleBufferState, slice nb and B to i. Otherwise, copy both.
  3. Copy nf, F, ne, E and ts, and return the new state.

Arguments

  • x: The state to slice.
  • i: Indices of the assets to keep, as a vector or a range. A single integer is not accepted, because the names must stay a vector.
  • args...: More positional arguments, which go to the slice of the returns buffer.

Returns

  • state::ReturnsBufferState: The state of the same observations over the selected assets.

Related

source
PortfolioOptimisers.merge_states — Method
merge_states(
    a::ReturnsBufferState,
    b::ReturnsBufferState
) -> ReturnsBufferState

Folds two ReturnsBufferState fitted on disjoint blocks into the state of the concatenated block.

The two states must describe one run, so their pinned context, their cap and the set of columns they keep must agree. Each column then merges as its own buffer merges, by concatenation, and the cap keeps the last max_history rows of every column, so the merged columns hold one number of observations.

Algorithm

  1. Refuse two states whose names or static panels differ.
  2. Refuse two states whose caps differ.
  3. Refuse two states that do not keep the same columns.
  4. Merge each column with merge_column, and return the new state.

Arguments

  • a: The state of the first block of observations.
  • b: The state of the second block of observations.

Validation

  • The pinned context of a and b agrees. An ArgumentError is thrown otherwise.
  • a.max_history == b.max_history. An ArgumentError is thrown otherwise.
  • a and b keep the same columns. An ArgumentError is thrown otherwise.
  • Every refusal of merge_states on a SampleBufferState holds for the matrix columns.

Returns

  • state::ReturnsBufferState: The state that the two blocks give when they are folded as one block.

Related

source