> ## Documentation Index
> Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Base
> systematica.api.base
## `BaseStatArb`
```python theme={null}
BaseStatArb()
```
Base Statistical Arbitrage class.
### Ancestors
* `abc.ABC`
### Descendants
* `systematica.api.models.arbitrage_index.ArbitrageBaseIndex`
* `systematica.api.models.arbitrage_index.ArbitrageClipIndex`
* `systematica.api.models.arbitrage_index.ArbitrageCumulativeIndex`
* `systematica.api.models.arbitrage_index.ArbitrageResetIndex`
* `systematica.api.models.arbitrage_index.ArbitrageRollingZscoreIndex`
* `systematica.api.models.meta_model.MetaModel`
* `systematica.api.models.momentum.AverageMomentumFactorCV`
* `systematica.api.models.momentum.RollingAverageMomentumFactor`
* `systematica.api.models.ou_process.RollingOUProcess`
* `systematica.api.models.range_breakout.RangeBreakout`
* `systematica.api.models.range_breakout.RangeMeanReversion`
* `systematica.api.models.volatility.RollingVolatilityFactor`
* `systematica.api.models.volatility.VolatilityFactorCV`
* `systematica.api.models.volume_profile.RollingVolumeProfileFactor`
* `systematica.api.models.volume_profile.VolumeProfileFactorCV`
### Static methods
#### `is_valid`
```python theme={null}
is_valid(
model_params: Dict[str, Any],
signal_params: Dict[str, Any],
)
```
Validate model parameters.
This method checks if the model parameters are valid for the statistical arbitrage model.
It should be implemented in subclasses and decorated with `staticmethod` to allow calling it without an instance.
If the model does not require validation, it can be implemented as a no-op method with the `@staticmethod` decorator.
**Examples**:
To implement this method, define it in the subclass and use the `@staticmethod` decorator
like so:
```python theme={null}
>>> @staticmethod
>>> def is_valid(model_params: tp.Kwargs, signal_params: tp.Kwargs):
... # Implement validation logic here
... pass
```
**Parameters**:
| Name | Type | Default | Description |
| --------------- | ----------- | ------- | ------------------ |
| `model_params` | `tp.Kwargs` | `--` | Model parameters. |
| `signal_params` | `tp.Kwargs` | `--` | Signal parameters. |
#### `run_report`
```python theme={null}
run_report(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
use_close: bool = True,
freq: str = 'auto',
use_rolling: bool = False,
**model_params,
) ‑> systematica.api.base.BaseReportMixin
```
Analyzes model using rolling or cross-validation techniques.
**Parameters**:
| Name | Type | Default | Description |
| -------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Input data containing time series data. |
| `s1` | `str` | `--` | First symbol. |
| `s2` | `str` | `--` | Second symbol. |
| `use_close` | `bool` | `True` | Whether to use closing prices (`True`) or opening prices (`False`). |
| `freq` | `str` | `auto` | Frequency of the index used in `BaseReportCV`. If `auto`, try infer frequency from the index. Ignored in `BaseRollingReport`. Defaults to `auto`. |
| `use_rolling` | `bool` | `False` | Flag to use rolling method via `BaseRollingReport`. Note that both rolling and cv models can be passed. Fallbacks to `BaseReportCV` if model is not using `from_rolling` splitter without error message. Defaults to `False`. |
| `model_params` | `tp.Kwargs` | `--` | Parameters to pass to the model constructor. |
**Returns**:
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `BaseReportMixin` | An instance of `BaseRollingReport` or `BaseReportCV` depending on the model and parameters. |
#### `get_report_metrics`
```python theme={null}
get_report_metrics(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
use_close: bool = True,
metrics: str | List[str] = 'sharpe_ratio',
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
to_numpy: bool = False,
validate_metrics: bool = True,
validate_model: bool = True,
use_rolling: bool = False,
freq: str = 'auto',
portfolio_kwargs: Dict[str, Any] = None,
**model_params,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray
```
Run report: Analyzes model using rolling or cross-validation techniques.
**Parameters**:
| Name | Type | Default | Description |
| ------------------ | ---------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Input data containing time series data. |
| `s1` | `str` | `--` | First symbol. |
| `s2` | `str` | `--` | Second symbol. |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `use_close` | `bool, optional` | `--` | Whether to use 'Close' prices if `True` or 'Open' prices if `False. Default to `True\`. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `to_numpy` | `bool` | `False` | If `True`, returns a `np.ndarray`. Default is `False`, returning a `pd.DataFrame`. |
| `validate_metrics` | `bool` | `True` | Check if `metric` is valid in the registry. Defaults to `True`. |
| `validate_model` | `bool` | `True` | Check if model parameters are valid. Defaults to `True`. |
| `use_rolling` | `bool` | `False` | Flag to use rolling method via `BaseRollingReport`. Note that both rolling and cv models can be passed. Fallbacks to `BaseReportCV` if model is not using `from_rolling` splitter without error message. Defaults to `False`. |
| `freq` | `str` | `auto` | Frequency of the index used in `BaseReportCV`. If `auto`, try infer frequency from the index. Ignored in `BaseRollingReport`. Defaults to `auto`. |
| `portfolio_kwargs` | `tp.Kwargs` | `None` | Additional arguments for portfolio simulation. |
| `model_params` | `tp.Kwargs` | `--` | Parameters to pass to the model constructor. |
**Returns**:
| Type | Description |
| -------------------------- | ------------------------------------------------------------ |
| `pd.DataFrame \| tp.Array` | DataFrame or array containing portfolio performance metrics. |
#### `run_analyzer`
```python theme={null}
run_analyzer(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
use_close: bool = True,
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
portfolio_kwargs: Dict[str, Any] = None,
validate_model: bool = True,
**model_params,
) ‑> systematica.portfolio.analyzers.base.PortfolioAnalyzer
```
Executes the portfolio analyzer.
Combines scoring, signal generation, and portfolio simulation into a
single pipeline for streamlined backtesting.
**Parameters**:
| Name | Type | Default | Description |
| ------------------ | ----------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Input vbt.Data containing time series data. |
| `s1` | `str` | `--` | Symbol. |
| `s2` | `str` | `--` | Symbol. |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `portfolio_kwargs` | `tp.Kwargs` | `None` | Additional arguments for portfolio simulation. |
| `to_numpy` | `bool` | `False` | If `True`, returns a `np.ndarray`. Default is `False`, returning a `pd.DataFrame`. |
| `validate_model` | `bool` | `True` | Check if model parameters are valid. Defaults to `True`. |
| `model_params` | `tp.Kwargs` | `--` | Additional parameters for `model_func`. |
**Returns**:
| Type | Description |
| ------------------- | -------------------------------------------------------------------------- |
| `PortfolioAnalyzer` | An instance of `PortfolioAnalyzer` containing the results of the backtest. |
#### `run_model`
```python theme={null}
run_model(
cls,
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
use_close: bool = True,
**model_params,
) ‑> pandas.core.frame.DataFrame
```
Run parameterized scores generation.
The method utilizes parameterization to run scores over various parameter
combinations. The results can be merged and accessed as a single output
object.
**Parameters**:
| Name | Type | Default | Description |
| -------------- | ----------- | ------- | ---------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Input vbt.Data containing time series data. |
| `s1` | `str` | `--` | First symbol. |
| `s2` | `str` | `--` | Second symbol. |
| `use_close` | `bool` | `True` | Use close price if `True`, otherwise use open price. |
| `model_params` | `tp.Kwargs` | `--` | Model arguments. |
**Returns**:
| Type | Description |
| -------------- | -------------------------------------- |
| `pd.DataFrame` | Scores for each parameter combination. |
#### `run_signals`
```python theme={null}
run_signals(
cls,
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int = None,
use_close: bool = True,
validate_model: bool = True,
**model_params,
) ‑> pandas.core.frame.DataFrame
```
Run parametrized signals generation.
The method utilizes parameterization to run signal generation over
various parameter combinations. The results can be merged and accessed
as a single output object.
**Parameters**:
| Name | Type | Default | Description |
| ---------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Input vbt.Data containing time series data. |
| `s1` | `str` | `--` | Symbol. |
| `s2` | `str` | `--` | Symbol. |
| `signal_model` | `str` | `--` | Model or parameter for generating trading signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `use_close` | `bool` | `True` | Use close price if `True`, otherwise use open price. |
| `validate_model` | `bool` | `True` | Validate model parameters. Defaults to `True`. |
| `model_params` | `tp.Kwargs` | `--` | Model arguments. |
**Returns**:
| Type | Description |
| -------------- | --------------------------------------- |
| `pd.DataFrame` | Signals for each parameter combination. |
#### `run_pipeline`
```python theme={null}
run_pipeline(
cls,
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
metrics: str | List[str] = None,
use_rolling: bool = False,
metric_registry_kwargs: Dict[str, Any] = None,
use_close: bool = True,
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
portfolio_kwargs: Dict[str, Any] = None,
to_numpy: bool = False,
validate_metrics: bool = True,
validate_model: bool = True,
**model_params,
) ‑> vectorbtpro.portfolio.base.Portfolio | collections.OrderedDict | pandas.core.frame.DataFrame | numpy.ndarray
```
Executes the portfolio pipeline. Method is parametrizable.
Combines scoring, signal generation, and portfolio simulation into a
single pipeline for streamlined backtesting.
**Parameters**:
| Name | Type | Default | Description |
| ------------------------ | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data` | `vbt.Data` | `--` | Input vbt.Data containing time series data. |
| `s1` | `str` | `--` | First symbol. |
| `s2` | `str` | `--` | Second symbol. |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `use_rolling` | `bool` | `False` | Flag to use rolling method via `BaseRollingReport`. Note that both rolling and cv models can be passed. Fallbacks to `BaseReportCV` if model is not using `from_rolling` splitter without error message. Defaults to `False`. |
| `metric_registry_kwargs` | `tp.Kwargs` | `None` | Parameters for metric registry. If `None`, uses default parameters based on the model type. This is used to specify parameters such as `window` or `minp` for rolling metrics. If using cross-validation, this should be set to `None` as it is not applicable. If using rolling metrics, this should be set to a dictionary with parameters for the metric registry. For example, `{"window": 20}`. Defaults to `None`. |
| `use_close` | `bool, optional` | `--` | Whether to use 'Close' prices if `True` or 'Open' prices if `False. Default to `True\`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `portfolio_kwargs` | `tp.Kwargs` | `None` | Additional keyword arguments for the portfolio simulation. |
| `to_numpy` | `bool` | `False` | If `True`, returns a `np.ndarray`. Default is `False`, returning a `pd.DataFrame`. |
| `validate_metrics` | `bool` | `True` | Check if `metric` is valid in the registry. Defaults to `True`. |
| `validate_model` | `bool` | `True` | Check if model parameters are valid. Defaults to `True`. |
| `model_params` | `tp.Kwargs` | `--` | Additional parameters for `model_func`. |
**Returns**:
| Type | Description |
| --------------------------------------------------- | ------------------------------------------ |
| `vbt.PF \| OrderedDict \| pd.DataFrame \| tp.Array` | Backtested portfolio or requested metrics. |
#### `run_optuna_study`
```python theme={null}
run_optuna_study(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
*,
select_symbols: str | int | list[str | int] = None,
use_close: bool = True,
metrics: str | List[str] = 'sharpe_ratio',
metric_registry_kwargs: Dict[str, Any] = None,
pruner: optuna.pruners._base.BasePruner = None,
sampler: optuna.samplers._base.BaseSampler = None,
direction: str | List[str] = 'maximize',
create_study_kwargs: Dict[str, Any] = None,
n_trials: int = 100,
n_completed_trials: int = None,
n_jobs: int = -1,
gc_after_trial: bool = False,
optimize_kwargs: Dict[str, Any] = None,
verbose: bool = True,
tracker: ~BaseTracker = None,
cross_validate: bool = False,
reduce_func: Callable = None,
use_rolling: bool = False,
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
portfolio_kwargs: Dict[str, Any] = None,
freq: str = None,
**model_params,
) ‑> optuna.study.study.Study
```
Run hyperparameter optimization using `optuna` for a signal-based trading
strategy.
* Optuna is used for hyperparameter tuning and efficiently finds the
best parameters.
* The study prunes trials with poor results to accelerate the search
process.
**References**:
* [Optuna Documentation](https://optuna.org/)
* [Pruning Trials](https://optuna.readthedocs.io/en/stable/tutorial/pruning.html)
**Parameters**:
| Name | Type | Default | Description |
| ------------------------ | ----------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `vbt.Data` | `--` | Market data used for generating trading signals and backtesting. |
| `s1` | `str` | `--` | First symbol. |
| `s2` | `str` | `--` | Second symbol. |
| `signal_model` | `str` | `--` | The signal generation model that determines entry and exit points. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `use_close` | `bool, optional` | `--` | Whether to use 'Close' prices if `True` or 'Open' prices if `False. Default to `True\`. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `metric_registry_kwargs` | `tp.Kwargs` | `None` | Parameters for metric registry. If `None`, uses default parameters based on the model type. This is used to specify parameters such as `window` or `minp` for rolling metrics. If using cross-validation, this should be set to `None` as it is not applicable. If using rolling metrics, this should be set to a dictionary with parameters for the metric registry. For example, `{"window": 20}`. Defaults to `None`. |
| `pruner` | `optuna.pruners.BasePruner` | `None` | Optuna Pruner. If `None`, defaults to Asynchronous Successive Halving Algorithm. Defaults to `None`. |
| `sampler` | `optuna.samplers.BaseSampler` | `--` | Optuna Sampler. If `None`, defaults to TPE (Tree-structured Parzen Estimator) algorithm. Defaults to `None`. |
| `direction` | `str` | `maximize` | Optimization objective, either `minimize` or `maximize`, default is `maximize`. |
| `create_study_kwargs` | `tp.Kwargs` | `None` | Additional arguments for `optuna.create_study`, default is `None`. |
| `n_trials` | `int` | `100` | The number of trials for the optimization. This is the maximum number of trials that will be run. If `n_completed_trials` is set, the optimization will stop when the number of completed trials reaches this value. If `n_completed_trials` is not set, the optimization will run for `n_trials` trials. If `n_trials` is set to `None`, it will run indefinitely until `n_completed_trials` is reached. If `n_trials` is set to `0`, it will not run any trials. If `n_trials` is set to a negative value, it will run indefinitely until `n_completed_trials` is reached. Defaults to `100`. |
| `n_completed_trials` | `int` | `None` | The number of successfully completed trials before stopping the optimization. If `None`, it will run for `n_trials` trials. TO be effective, the number of trials should be higher than the number of completed trials. default is `None`. |
| `n_jobs` | `int` | `-1` | Number of parallel jobs for optimization (`-1` for using all available `CPUs` cores), default is `-1`. |
| `gc_after_trial` | `bool` | `False` | Flag to determine whether to automatically run garbage collection after each trial. Set to `True` to run the garbage collection, `False` otherwise. It runs a full collection by internally calling `gc.collect`. If you see an increase in memory consumption over several trials, try setting this flag to `True`. Defaults to `False`. |
| `optimize_kwargs` | `dict` | `None` | Additional arguments for `study.optimize`, default is `None`. |
| `verbose` | `bool` | `True` | Whether to print Optuna logs during the optimization process. If True, prints logs to the console. Default is `True`. |
| `tracker` | `BaseTracker` | `None` | Tracker instance for logging and monitoring the optimization process. If `None`, no tracking is performed. If you want to use a tracker, you can pass an instance of a tracker class that inherits from `BaseTracker`. For example, you can use `NeptuneTracker`. This tracker will log the optimization process and metrics to the tracker service. Default to None. |
| `cross_validate` | `bool` | `False` | If `True`, uses cross-validation analytics through `run_report`, wrapping `BaseReportCV` instead of `_apply_pipeline`. If `False`, uses data history as a whole. This is useful for optimizing the model using cross-validation. Defaults to `False`. |
| `reduce_func` | `tp.Callable` | `None` | Function to reduce the results of the cross-validation. This function should take a 2D array of shape (n\_trials, n\_metrics) and return a 1D array of shape (n\_metrics). This is used to reduce the results of the cross-validation to a single value for each metric. If `None`, defaults to `vbt.nb.nanmedian_nb`, which computes the median of the cross-validation results while ignoring NaN values. Defaults to None. |
| `use_rolling` | `bool` | `False` | Flag to use rolling method via `BaseRollingReport`. Note that both rolling and cv models can be passed. Fallbacks to `BaseReportCV` if model is not using "from\_rolling" splitter without error message. Defaults to `False`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `portfolio_kwargs` | `tp.Kwargs` | `None` | Additional keyword arguments for the portfolio simulation. |
| `freq` | `str` | `None` | Frequency of the data. Used when `cross_validate` is `True`. Defaults to `None`. |
| `model_params` | `tp.Kwargs` | `--` | Additional model parameters to optimize. |
**Returns**:
| Type | Description |
| -------------- | -------------------------------------------------------- |
| `optuna.Study` | The Optuna study object containing optimization results. |
### Methods
#### `get_signals`
```python theme={null}
get_signals(
self,
model_output: numpy.ndarray,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
) ‑> systematica.signals.base.Signals
```
Generate trading signals based on scores.
**Parameters**:
| Name | Type | Default | Description |
| ---------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `model_output` | `tp.Array` | `--` | Model output used for signal generation. |
| `signal_model` | `str` | `--` | Signal model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
**Returns**:
| Type | Description |
| --------- | ------------------ |
| `Signals` | Generated signals. |
## `BaseReportMixin`
```python theme={null}
BaseReportMixin()
```
Report mixin used in both **rolling** and **cross-validated** versions.
### Ancestors
* `abc.ABC`
### Descendants
* `systematica.api.base.BaseReportCV`
* `systematica.api.base.BaseRollingReport`
### Instance variables
* `all_metrics: List[str]`: Get all available metrics
* `price_data`: Retrieves price data for the specified symbols.
* `non_tunable_metrics: List[str]`: Retrieves all non-tunable metrics from registry
### Methods
#### `get_annualized_return`
```python theme={null}
get_annualized_return(
self,
) ‑> pandas.core.frame.DataFrame
```
Computes the rolling (annualized) returns.
**Returns**:
| Type | Description |
| -------------- | ------------------------------------------------ |
| `pd.DataFrame` | DataFrame containing rolling annualized returns. |
#### `get_portfolio_metric`
```python theme={null}
get_portfolio_metric(
self,
**kwargs,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray
```
Computes portfolio performance metrics for different test sets.
**Parameters**:
| Name | Type | Default | Description |
| -------- | ----------- | ------- | ----------------------------------------- |
| `kwargs` | `tp.Kwargs` | `--` | Additional arguments to run the pipeline. |
**Returns**:
| Type | Description |
| -------------------------- | ------------------------------------------------------------ |
| `pd.DataFrame \| tp.Array` | DataFrame or array containing portfolio performance metrics. |
#### `get_model_output`
```python theme={null}
get_model_output(
self,
to_numpy: bool = False,
) ‑> numpy.ndarray | pandas.core.series.Series | pandas.core.frame.DataFrame
```
Computes the model output.
**Parameters**:
| Name | Type | Default | Description |
| ---------- | ------ | ------- | ------------------------------------------------------------------------------------------- |
| `to_numpy` | `bool` | `False` | If `True`, converts output to a `np.array`. Default is `False`, returning a `pd.DataFrame`. |
**Returns**:
| Type | Description |
| ---------------------------- | ------------------ |
| `np.ndarray or pd.DataFrame` | Model output data. |
#### `set_labels`
```python theme={null}
set_labels(
self,
group_by: bool,
metrics: str | List[str],
) ‑> List[str]
```
Generate column labels for the output DataFrame.
**Parameters**:
| Name | Type | Default | Description |
| ---------- | ------ | ------- | ----------------------------------- |
| `group_by` | `bool` | `--` | Whether to group results by symbol. |
| `metrics` | `str` | `--` | List of metrics to compute. |
**Returns**:
| Type | Description |
| ------ | --------------------- |
| `List` | List of column names. |
#### `plot_annualized_return`
```python theme={null}
plot_annualized_return(
self,
fig: vectorbtpro.utils.figure.FigureWidget = None,
**layout_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget
```
Plots total returns over time.
**Parameters**:
| Name | Type | Default | Description |
| --------------- | ------------------ | ------- | ----------------------------------------- |
| `fig` | `vbt.FigureWidget` | `None` | Existing figure to update. |
| `layout_kwargs` | `tp.Kwargs` | `--` | Additional layout arguments for the plot. |
**Returns**:
| Type | Description |
| ------------------ | -------------------------------------- |
| `vbt.FigureWidget` | Figure with the plotted total returns. |
#### `plot_model_output`
```python theme={null}
plot_model_output(
self,
fig: vectorbtpro.utils.figure.FigureWidget = None,
**layout_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget
```
Plots model output over time.
**Parameters**:
| Name | Type | Default | Description |
| --------------- | ------------------ | ------- | ----------------------------------------- |
| `fig` | `vbt.FigureWidget` | `None` | Existing figure to update. |
| `layout_kwargs` | `tp.Kwargs` | `--` | Additional layout arguments for the plot. |
**Returns**:
| Type | Description |
| ------------------ | ------------------------------------- |
| `vbt.FigureWidget` | Figure with the plotted model output. |
#### `plot_portfolio_metric`
```python theme={null}
plot_portfolio_metric(
self,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
metrics: str | List[str] = 'sharpe_ratio',
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
fig: vectorbtpro.utils.figure.FigureWidget = None,
layout_kwargs: Dict[str, Any] = None,
**portfolio_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget
```
Plot portfolio performance metrics over time.
**Parameters**:
| Name | Type | Default | Description |
| ------------------ | ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `fig` | `vbt.FigureWidget` | `None` | Existing figure to update. If `None`, a new figure is created. Defaults to `None`. |
| `layout_kwargs` | `dict` | `None` | Additional layout arguments for the plot. If `None`, uses default layout settings. Defaults to `None`. |
| `portfolio_kwargs` | `tp.Kwargs` | `--` | Additional arguments for portfolio simulation. |
**Returns**:
| Type | Description |
| ------------------ | ------------------------------------------------------ |
| `vbt.FigureWidget` | Figure with the plotted portfolio performance metrics. |
## `BaseReportCV`
```python theme={null}
BaseReportCV(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
model: ~BaseStatArb,
use_close: bool = True,
freq: str = 'auto',
)
```
Analyzes a statistical arbitrage model using **cross-validation**.
Method generated by attrs for class BaseReportCV.
### Ancestors
* `systematica.api.base.BaseReportMixin`
* `abc.ABC`
### Descendants
* `systematica.api.reports.arbitrage_index.ArbitrageIndexReport`
* `systematica.api.reports.meta_model.MetaModelCVReport`
* `systematica.api.reports.momentum.AverageMomentumFactorCVReport`
* `systematica.api.reports.momentum.MomentumFactorCVReport`
* `systematica.api.reports.ou_process.OUProcessCVReport`
* `systematica.api.reports.range_breakout.RangeBreakoutReport`
* `systematica.api.reports.volatility.VolatilityFactorCVReport`
* `systematica.api.reports.volume_profile.VolumeProfileFactorCVReport`
### Instance variables
* `splitter: systematica.utils.custom_splitter.CustomSplitter`: Split arrays or matrices into specified train and test subsets.
* `splits: pandas.core.frame.DataFrame`: Retrieves data splits based on the cross-validation splitter.
* `index_test: pandas.core.indexes.base.Index`: Computes and returns the test set index of the dataset. The test set index is derived from the end bounds values returned by the `splitter`.
* `all_metrics: List[str]`: Get available cross-validation metrics.
* `data: vectorbtpro.data.base.Data`: Input data containing time series data.
* `freq: str`: Set frequency. Default is `auto`, which infers frequency from the data index.
* `model: ~BaseStatArb`: Model to analyse.
* `s1: str`: Symbol.
* `s2: str`: Symbol.
* `use_close: bool`: Price close or open. Default is `True`, using close prices.
### Methods
#### `check`
```python theme={null}
check(
self,
attribute: Type,
value: Any,
)
```
Validates `CV` model.
**Parameters**:
| Name | Type | Default | Description |
| ----------- | --------- | ------- | ------------------------------ |
| `attribute` | `tp.Type` | `--` | The attribute being validated. |
| `value` | `tp.Any` | `--` | The model instance. |
**Raises**:
| Type | Description |
| ---------------- | ---------------------------------------------------- |
| `AttributeError` | If the model does not use `splitter` as a parameter. |
#### `price_reset_stacked_by_set`
```python theme={null}
price_reset_stacked_by_set(
self,
) ‑> pandas.core.frame.DataFrame
```
Resets the price data stacked by set and attaches bounds to the index.
This method uses the `splitter` to reset the price data, stacking it by
set and attaching bounds to the index.
**Returns**:
| Type | Description |
| -------------- | ---------------------------------------------------------------------- |
| `pd.DataFrame` | The reset price data stacked by set with bounds attached to the index. |
#### `model_reset_stacked_by_set`
```python theme={null}
model_reset_stacked_by_set(
self,
) ‑> pandas.core.frame.DataFrame
```
Resets the model output stacked by set and attaches bounds to the index.
This method uses the `splitter` to reset the model output, stacking it by
set and attaching bounds to the index.
**Returns**:
| Type | Description |
| -------------- | ------------------------------------------------------------------------ |
| `pd.DataFrame` | The reset model output stacked by set with bounds attached to the index. |
#### `get_annualized_return`
```python theme={null}
get_annualized_return(
self,
) ‑> pandas.core.series.Series
```
Computes the annualized returns for the test set.
**Returns**:
| Type | Description |
| ----------- | ---------------------------------------------------------- |
| `pd.Series` | Series containing the annualized returns for the test set. |
#### `get_portfolio_metric`
```python theme={null}
get_portfolio_metric(
self,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
metrics: str | List[str] = 'sharpe_ratio',
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
to_numpy: bool = False,
validate_metrics: bool = True,
validate_model: bool = True,
**portfolio_kwargs,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray
```
Computes portfolio performance metrics for different test sets.
**Parameters**:
| Name | Type | Default | Description |
| ------------------ | ----------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `to_numpy` | `bool` | `False` | If `True`, returns a `np.ndarray`. Default is `False`, returning a `pd.DataFrame`. |
| `validate_metrics` | `bool` | `True` | Check if `metric` is valid in the registry. Defaults to `True`. |
| `validate_model` | `bool` | `True` | Check if model parameters are valid. Defaults to `True`. |
| `portfolio_kwargs` | `tp.Kwargs` | `--` | Additional arguments for portfolio simulation. |
**Returns**:
| Type | Description |
| -------------------------- | ------------------------------ |
| `pd.DataFrame \| tp.Array` | Portfolio performance metrics. |
## `BaseRollingReport`
```python theme={null}
BaseRollingReport(
data: vectorbtpro.data.base.Data,
s1: str,
s2: str,
model: ~BaseStatArb,
use_close: bool = True,
freq: str = 'auto',
)
```
Analyzes a statistical arbitrage model using **rolling metrics**.
Method generated by attrs for class BaseRollingReport.
### Ancestors
* `systematica.api.base.BaseReportMixin`
* `abc.ABC`
### Descendants
* `systematica.api.reports.meta_model.RollingMetaModelReport`
* `systematica.api.reports.momentum.RollingAverageMomentumFactorReport`
* `systematica.api.reports.momentum.RollingMomentumFactorReport`
* `systematica.api.reports.ou_process.RollingOUProcessReport`
* `systematica.api.reports.volatility.RollingVolatilityFactorReport`
* `systematica.api.reports.volume_profile.RollingVolumeProfileFactorReport`
### Instance variables
* `window: int`: Window size.
* `minp: None | int`: Minimum number of observations required.
* `all_metrics: List[str]`: Get available rolling metrics.
* `data: vectorbtpro.data.base.Data`: Input data containing time series data.
* `freq: str`: Set frequency.
* `model: ~BaseStatArb`: Model to analyse.
* `s1: str`: Symbol.
* `s2: str`: Symbol.
* `use_close: bool`: Price close or open.
### Methods
#### `check`
```python theme={null}
check(
self,
attribute: Type,
value: Any,
)
```
Validates that the model has the necessary parameters for the strategy.
Specifically, the model must have either:
* Both `window` and `minp` attributes, or
* Both `train_window` and `splitter` (set to `*_rolling`).
**Parameters**:
| Name | Type | Default | Description |
| ----------- | --------- | ------- | ------------------------------------------------- |
| `attribute` | `tp.Type` | `--` | The attribute being validated. |
| `value` | `tp.Any` | `--` | The value being set (not used in this validator). |
**Raises**:
| Type | Description |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `ValueError` | If the model does not have either `window` and `minp` or `train_window` and `splitter=="*_rolling"`). |
#### `get_portfolio_metric`
```python theme={null}
get_portfolio_metric(
self,
signal_model: str,
long_entries: float,
long_exits: float,
short_entries: float,
short_exits: float,
select_symbols: str | int | list[str | int] = None,
metrics: str | List[str] = 'sharpe_ratio',
size: float | numpy.ndarray = 50,
size_type: str | numpy.ndarray = 'valuepercent100',
allow_partial: float | numpy.ndarray = None,
fees: float | numpy.ndarray = None,
fixed_fees: float | numpy.ndarray = None,
slippage: float | numpy.ndarray = None,
min_size: float | numpy.ndarray = None,
max_size: float | numpy.ndarray = None,
size_granularity: float | numpy.ndarray = None,
sl_stop: float | numpy.ndarray = None,
tsl_stop: float | numpy.ndarray = None,
tp_stop: float | numpy.ndarray = None,
accumulate: bool | str | numpy.ndarray = None,
init_cash: float | numpy.ndarray = None,
cash_sharing: bool = True,
group_by: bool = True,
call_seq: str | bool = 'auto',
fill_pos_info: bool = False,
log: bool | numpy.ndarray = None,
to_numpy: bool = False,
validate_metrics: bool = True,
validate_model: bool = True,
**portfolio_kwargs,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray
```
Computes portfolio performance metrics on a rolling basis.
**Parameters**:
| Name | Type | Default | Description |
| ------------------ | ----------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `signal_model` | `str` | `--` | Model used for generating signals. |
| `long_entries` | `float` | `--` | Long entry signals. |
| `long_exits` | `float` | `--` | Long exit signals. |
| `short_entries` | `float` | `--` | Short entry signals. |
| `short_exits` | `float` | `--` | Short exit signals. |
| `select_symbols` | `str` | `None` | Symbol name (e.g., `BTCUSDT` or `ETHUSDT`) or column index (e.g., `0` or `1`) to keep. If `None`, no filtering. |
| `metrics` | `str` | `sharpe_ratio` | Performance metrics to compute. Defaults to `sharpe_ratio`. |
| `size` | `float` | `50` | Size of each order. Defaults to `50`. |
| `size_type` | `str` | `valuepercent100` | Type of size. Defaults to `valuepercent100`. |
| `allow_partial` | `float` | `None` | Whether to allow partial fills. Defaults to `None`. |
| `fees` | `float` | `None` | Fees per order. Defaults to `None`. |
| `fixed_fees` | `float` | `None` | Fixed fees per order. Defaults to `None`. |
| `slippage` | `float` | `None` | Slippage per order. Defaults to `None`. |
| `min_size` | `float` | `None` | Minimum size of each order. Defaults to `None`. |
| `max_size` | `float` | `None` | Maximum size of each order. Defaults to `None`. |
| `size_granularity` | `float` | `None` | Granularity of size. Defaults to `None`. |
| `sl_stop` | `float` | `None` | Stop-loss level. Defaults to `None`. |
| `tsl_stop` | `float` | `None` | Trailing stop-loss level. Defaults to `None`. |
| `tp_stop` | `float` | `None` | Take-profit level. Defaults to `None`. |
| `accumulate` | `bool` | `None` | Whether to accumulate orders. Defaults to `None`. |
| `init_cash` | `float` | `None` | Initial cash. Defaults to `None`. |
| `cash_sharing` | `bool` | `True` | Whether to share cash between assets. Defaults to `True`. |
| `group_by` | `bool` | `True` | Whether to group by symbol. Defaults to `True`. |
| `call_seq` | `bool` | `auto` | Call sequence. Defaults to `auto`. |
| `fill_pos_info` | `bool` | `False` | Whether to fill position info. Defaults to `False`. |
| `log` | `bool` | `None` | Whether to log orders. Defaults to `None`. |
| `to_numpy` | `bool` | `False` | If `True`, returns a `np.ndarray`. Default is `False`, returning a `pd.DataFrame`. |
| `validate_metrics` | `bool` | `True` | Check if `metric` is valid in the registry. Defaults to `True`. |
| `validate_model` | `bool` | `True` | Check if model parameters are valid. Defaults to `True`. |
| `portfolio_kwargs` | `tp.Kwargs` | `--` | Additional arguments for portfolio simulation. |
**Returns**:
| Type | Description |
| -------------------------- | ------------------------------------------------------------ |
| `pd.DataFrame \| tp.Array` | DataFrame or array containing portfolio performance metrics. |
## `BaseSignal`
```python theme={null}
BaseSignal()
```
Abstract base class for signal generation.
### Ancestors
* `abc.ABC`
### Descendants
* `systematica.api.signals.cross_spread.CrossSpread`
* `systematica.api.signals.crossover.Crossover`
* `systematica.api.signals.crossover.Crossover1d`
* `systematica.api.signals.spread.Spread`
* `systematica.api.signals.twin_spread.TwinSpread`
### Static methods
#### `run`
```python theme={null}
run(
*arg,
**kwargs,
)
```
Run the signal generation process.
**Parameters**:
| Name | Type | Default | Description |
| -------- | ----------- | ------- | --------------------- |
| `arg` | `tuple` | `--` | Positional arguments. |
| `kwargs` | `tp.Kwargs` | `--` | Keyword arguments. |