quantlab.label.forward.Forward#

class quantlab.label.forward.Forward(config)[source]#

Bases: Component

A factor shifted delay + span bars earlier, used as a label.

read and compute ask the wrapped factor for the requested range plus lookahead_bars() bars after it, counted on the factor calendar (the bars of the factor’s output, Factor.bar_after) and stopping at the calendar’s last bar, then shift the panel and trim it back to the request. A factor resampled from minute bars to daily counts its lookahead in trading days. The last bars of a request are therefore filled wherever the factor has later bars, and NaN only past the calendar’s end. A Forward owns no store: read reads the wrapped factor’s, so one factor store serves as a feature and, wrapped, as a label.

Parameters:

configForwardConfig: The factor to shift, its span and its delay.

Raises:

ValueError: If span is below 1, delay is negative, or the factor is in stream mode.

Examples

With momentum a 5-bar momentum factor over 60 daily bars ending on 2024-02-29:

>>> label = Forward(ForwardConfig(factor=momentum, span=5))
>>> label.lookahead_bars(), label.span_bars()
(6, 5)
>>> Forward(ForwardConfig(factor=momentum, span=0))
Traceback (most recent call last):
ValueError: Forward: span must be at least 1, got 0.

build(start, end)[source]#

Build the factor store the label needs to read start to end.

The wrapped factor’s store is built from start to lookahead_bars() factor bars after end, or to the factor’s last bar when fewer follow; store_range then reports that later end.

Parameters:

start, endstr, datetime.date or pd.Timestamp: The range the label will be read over.

Returns:

Forward: self, for chaining.

Examples

>>> label.build("2024-01-01", "2024-01-20").store_range()
('2024-01-01', '2024-01-26T00:00:00')

property class_name#

Bare class name, used in log and error messages.

Examples

>>> label.class_name
'Forward'

compute(start, end)[source]#

Compute the label from start to end, both inclusive.

The factor is computed from start (with its own warm-up) to lookahead_bars() factor bars after end.

Parameters:

start, endstr, datetime.date or pd.Timestamp: The range to return. A date-only end includes every bar of that day.

Returns:

xr.Dataset: The label panel on (timestamp, symbol), in memory.

Raises:

ValueError: If start is after end.

Examples

The dataset ends on 2024-02-29, so only the bars up to 2024-02-23 have six later bars; the last six are NaN:

>>> panel = label.compute("2024-02-20", "2024-02-29")
>>> dict(panel.sizes)
{'timestamp': 10, 'symbol': 8}
>>> int(panel["momentum_5"].isnull().any("symbol").sum())
6

config_cls#

Config class the label is built from and rebuilt with (from_config).

alias of ForwardConfig

delay_bars()[source]#

Return how many bars pass before the first bar the label counts: delay.

Examples

>>> label.delay_bars()
1

extend(end)[source]#

Extend the factor store so the label can be read up to end.

The wrapped factor’s store is extended to lookahead_bars() factor bars after end, or to the factor’s last bar when fewer follow.

Parameters:

endstr, datetime.date or pd.Timestamp: The new last date the label will be read up to.

Returns:

Forward: self, for chaining.

Examples

>>> label.extend("2024-02-10").store_range()
('2024-01-01', '2024-02-16T00:00:00')

get_factor_names()[source]#

Return the names of the label’s variables, which are the wrapped factor’s.

Examples

>>> label.get_factor_names()
('momentum_5',)

kind = 'return'#: What the label measures: "return", or "volatility" for a label whose predicted level is used as a volatility. Model evaluation reads it to add level metrics, never the label’s class.

lookahead_bars()[source]#

Return how many bars past t the label at t reads: delay + span.

Every split boundary purges this many bars from the earlier segment.

Examples

>>> label.lookahead_bars()
6

read(start, end)[source]#

Return the label from start to end, read from the factor’s store.

The factor store must cover start to lookahead_bars() factor bars after end, or to the factor’s last bar when fewer follow.

Parameters:

start, endstr, datetime.date or pd.Timestamp: The range to return. A date-only end includes every bar of that day.

Returns:

xr.Dataset: The label panel on (timestamp, symbol).

Raises:

ValueError: If start is after end, or the factor store does not cover the range the label needs; the message names extend.

Examples

>>> momentum.build("2024-01-01", "2024-02-29").store_range()
('2024-01-01', '2024-02-29')
>>> dict(label.read("2024-02-01", "2024-02-10").sizes)
{'timestamp': 10, 'symbol': 8}

span_bars()[source]#

Return how many bars the label accumulates over: span.

Examples

>>> label.span_bars()
5

store_range()[source]#

Return the (start, end) the wrapped factor’s store was built for.

The end is lookahead_bars() bars past the last date the label can be read up to. None when the store was not written by build.

Examples

>>> label.build("2024-01-01", "2024-01-20").store_range()
('2024-01-01', '2024-01-26T00:00:00')