Arbitrage Index

systematica.api.analytics.arbitrage_index

ArbitrageIndexCV

ArbitrageIndexCV(
    id: str = None,
    loader_or_data: Callable = <function load_clean_data>,
    timeframe: str = '1d',
    start: str = None,
    end: str = None,
    s1: str = 'BTCUSDT',
    s2: str = 'ETHUSDT',
    suffix: str = 'h5',
    use_close: bool = True,
    freq: str = None,
    signal_model: str = None,
    long_entries: float = nan,
    long_exits: float = nan,
    short_entries: float = nan,
    short_exits: float = nan,
    clean: bool = True,
    select_symbols: str | int | List[str | int] = None,
    portfolio_config: Dict[str, Any] = _Nothing.NOTHING,
    model_params: Dict[str, Any] = _Nothing.NOTHING,
    metrics: str | List[str] = None,
    metrics_kwargs: Dict[str, Any] = _Nothing.NOTHING,
    use_rolling: bool = False,
    storage: str | optuna.storages._base.BaseStorage = None,
    pruner: optuna.pruners._base.BasePruner = <optuna.pruners._successive_halving.SuccessiveHalvingPruner object>,
    sampler: optuna.samplers._base.BaseSampler = <optuna.samplers._tpe.sampler.TPESampler object>,
    study_name: str = None,
    direction: str | List[str] = 'maximize',
    load_if_exists: bool = False,
    n_trials: int = 100,
    n_completed_trials: int = None,
    timeout: float = None,
    n_jobs: int = 1,
    catch: Iterable[Type[Exception]] | Type[Exception] = _Nothing.NOTHING,
    callbacks: Iterable[Callable[[optuna.study.study.Study, optuna.trial._frozen.FrozenTrial], None]] | None = None,
    gc_after_trial: bool = False,
    show_progress_bar: bool = False,
    verbose: bool = True,
    tracker: Type = None,
    model: Any = None,
    preprocess_func: Callable = None,
)

Breakdown analysis for arbitrage index models, extending WalkForwardCV. Includes methods to compute Kendall’s Tau, determine the best copula, and extract copula parameters.

Method generated by attrs for class WalkForwardCV.

Ancestors

• systematica.walk_forward.cv.WalkForwardCV
• systematica.walk_forward.base.BaseWalkForward
• abc.ABC
• systematica.generic.base.Model
• systematica.generic.base.Feature

Methods

get_kendall_tau

get_kendall_tau(
    self,
    key: str = 'train',
    raw_output: bool = True,
    set_datetime_index: bool = True,
) ‑> pandas.core.series.Series

Compute Kendall’s Tau correlation coefficient in each split.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
raw_output	bool	True	If True, returns raw results. Default is True, which returns processed results.
set_datetime_index	bool	True	If True, set end-test datetime index. Ignored otherwise. Defaults to True.

Returns:

Type	Description
pd.Series	Series containing Kendall’s Tau values.

get_ecdf

get_ecdf(
    self,
    key: str = 'test',
    raw_output: bool = True,
    set_datetime_index: bool = True,
) ‑> pandas.core.frame.DataFrame

Compute ECDF object in each set.

Retrieves processed data splits based on the cross-validation splitter.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
raw_output	bool	True	If True, returns raw results. Default is True, which returns processed results.
set_datetime_index	bool	True	If True, set end-test datetime index. Ignored otherwise. Defaults to True.

Returns:

Type	Description
pd.DataFrame	DataFrame containing ECDF objects, indexed by the test set index.

get_copula

get_copula(
    self,
    key: str = 'train',
    raw_output: bool = True,
    set_datetime_index: bool = True,
) ‑> pandas.core.series.Series

Identify the best-fitting copula.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
raw_output	bool	True	If True, returns raw results. Default is True, which returns processed results.
set_datetime_index	bool	True	If True, set end-test datetime index. Ignored otherwise. Defaults to True.

Returns:

Type	Description
pd.Series	Series containing the names of the best-fitting copula models.

get_dependence

get_dependence(
    self,
    key: str = 'train',
    raw_output: bool = True,
    set_datetime_index: bool = True,
) ‑> pandas.core.series.Series

Compute the dependence parameter) for the best-fitting copula in each set.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
raw_output	bool	True	If True, returns raw results. Default is True, which returns processed results.
set_datetime_index	bool	True	If True, set end-test datetime index. Ignored otherwise. Defaults to True.

Returns:

Type	Description
pd.Series	Series containing the dependence parameter.

iter_transform_output

iter_transform_output(
    self,
    key: str = 'train',
    apply_transform: bool = False,
    reset_stacked_by_set: bool = False,
    to_numpy: bool = False,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray

Get model output, either transformed or as partial derivatives.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
apply_transform	bool	False	If True, applies the model transformation to the output. Defaults to False.
reset_stacked_by_set	bool	False	If True, resets the index stacked by set. Defaults to False.
to_numpy	bool	False	If True, returns a NumPy array instead of a DataFrame. Defaults to False.

Returns:

Type	Description
pd.DataFrame	The model output.

get_marginals

get_marginals(
    self,
    key: str = 'train',
    reset_stacked_by_set: bool = False,
    to_numpy: bool = False,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray

Get model marginals.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
reset_stacked_by_set	bool	False	If True, resets the index stacked by set. Defaults to False.
to_numpy	bool	False	If True, returns a NumPy array instead of a DataFrame. Defaults to False.

Returns:

Type	Description
pd.DataFrame	The model marginals.

get_partial_derivative

get_partial_derivative(
    self,
    key: str = 'train',
    reset_stacked_by_set: bool = False,
    to_numpy: bool = False,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray

Get model partial derivatives.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
reset_stacked_by_set	bool	False	If True, resets the index stacked by set. Defaults to False.
to_numpy	bool	False	If True, returns a NumPy array instead of a DataFrame. Defaults to False.

Returns:

Type	Description
pd.DataFrame	The model partial derivatives.

get_transform

get_transform(
    self,
    key: str = 'train',
    reset_stacked_by_set: bool = False,
    to_numpy: bool = False,
) ‑> pandas.core.frame.DataFrame | numpy.ndarray

Get model output after applying the transformation. Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
reset_stacked_by_set	bool	False	If True, resets the index stacked by set. Defaults to False.
to_numpy	bool	False	If True, returns a NumPy array instead of a DataFrame. Defaults to False.

Returns:

Type	Description
pd.DataFrame	The model output after applying the transformation.

get_all_metrics

get_all_metrics(
    self,
    key: str,
    level_names: List[str] = None,
    reset_stacked_by_set: bool = False,
    to_numpy: bool = False,
) ‑> Dict[str, pandas.core.frame.DataFrame]

Get all metrics in a single iteration through splits.

This method performs one iteration through all walk-forward splits, computing all required metrics simultaneously. This avoids redundant copula fitting that occurs when calling get_kendall_tau(), get_dependence(), get_copula(), get_transform(), etc. separately.

Parameters:

Name	Type	Default	Description
key	str	--	Dataset to use, either ‘train’ or ‘test’.
level_names	tp.List[str, str], default None“	--	Names for the levels in the resulting hierarchical index. if None defaults to ['field', 'symbol']. Defaults to None
reset_stacked_by_set	bool	False	If True, resets the index stacked by set. Defaults to False.
to_numpy	bool	False	If True, returns a NumPy array instead of a DataFrame. Defaults to False.

Returns:

Type	Description
pd.DataFrame	All metrics

Notes:

This is the performance-critical method. By computing all metrics in one pass, we reduce complexity from O(6n) to O(n) where n is the number of splits.

run_portfolio

run_portfolio(
    self,
    key: str = 'train',
    validate_model: bool = True,
) ‑> vectorbtpro.portfolio.base.Portfolio

Generate a vectobtpro portfolio object.

Parameters:

Name	Type	Default	Description
key	str, optional	--	Dataset to use, either ‘train’ or ‘test’. Default is ‘train’.
validate_model	bool, optional	--	If True, validate model parameters before processing. Default is True.

Returns:

Type	Description
vbt.Portfolio	A vbt portfolio object.

run_report

run_report(
    self,
    key: str = 'train',
    validate_model: bool = True,
) ‑> pandas.core.frame.DataFrame

Generate a report DataFrame with model inputs, outputs, and metrics.

This optimized version computes all metrics in a single pass through the walk-forward splits, reducing redundant copula fitting.

Parameters:

Name	Type	Default	Description
key	str	'train'	Dataset to use, either ‘train’ or ‘test’.
validate_model	bool	True	If True, validate model parameters before processing.

Returns:

Type	Description
pd.DataFrame	A DataFrame containing model metrics, signals, and trade history, all aligned on a common index.

Notes:

Performance optimization: This method performs a single iteration through all splits, computing all metrics simultaneously to avoid redundant copula fitting operations.

plot_kendall_tau

plot_kendall_tau(
    self,
    key: str = 'train',
    fig: vectorbtpro.utils.figure.FigureWidget = None,
    **layout_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget

Plot Kendall’s Tau values.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
fig	vbt.FigureWidget	None	Existing figure to update, by default None.
layout_kwargs	tp.Kwargs	--	Additional layout keyword arguments for customization.

Returns:

Type	Description
vbt.FigureWidget	The figure displaying Kendall’s Tau values.

plot_copula

plot_copula(
    self,
    key: str = 'train',
    fig: vectorbtpro.utils.figure.FigureWidget = None,
    **layout_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget

Plot the best-fitting copula models.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
fig	vbt.FigureWidget	None	Existing figure to update, by default None.
layout_kwargs	tp.Kwargs	--	Additional layout keyword arguments for customization.

Returns:

Type	Description
vbt.FigureWidget	The figure displaying the best-fitting copula models.

plot_dependence

plot_dependence(
    self,
    key: str = 'train',
    fig: vectorbtpro.utils.figure.FigureWidget = None,
    **layout_kwargs,
) ‑> vectorbtpro.utils.figure.FigureWidget

Plot the dependence parameter values.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
fig	vbt.FigureWidget	None	Existing figure to update, by default None.
layout_kwargs	tp.Kwargs	--	Additional layout keyword arguments for customization.

Returns:

Type	Description
vbt.FigureWidget	The figure displaying dependence values.

plot_tail_concentration

plot_tail_concentration(
    self,
    key: str = 'train',
    set_datetime_index: bool = True,
    title: str | None = None,
    smoothing: float | None = 1.3,
) ‑> pandas.core.series.Series

Container with copula tail concentration figure object.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
set_datetime_index	bool	True	It True, set output datetime index. Note that it is indexed by the test set index inferred from get_best_copula. Defaults to True.
title	str	None	The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
smoothing	float	1.3	Smoothing parameter for the spline line shape. If provided, the curves will be smoothed using a spline interpolation.

Returns:

Type	Description
pd.Series	Copula ail concentration figures.

plot_heatmap

plot_heatmap(
    self,
    key: str = 'train',
    set_datetime_index: bool = True,
    title: str | None = None,
) ‑> pandas.core.series.Series

Container with copula heatmap figure object.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
set_datetime_index	bool	True	It True, set output datetime index. Note that it is indexed by the test set index inferred from get_best_copula. Defaults to True.
title	str	None	The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.

Returns:

Type	Description
pd.Series	Copula heatmap figures.

plot_surface

plot_surface(
    self,
    key: str = True,
    set_datetime_index: bool = True,
    title: str | None = None,
) ‑> pandas.core.series.Series

Container with copula surface figure object.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
set_datetime_index	bool	True	It True, set output datetime index. Note that it is indexed by the test set index inferred from get_best_copula. Defaults to True.
title	str	None	The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.

Returns:

Type	Description
pd.Series	Copula surface figures.

plot_contour

plot_contour(
    self,
    key: str = 'train',
    set_datetime_index: bool = True,
    show_latest_point: bool = False,
    alpha: float = 0.5,
    opacity: float = 0.2,
    title: str | None = None,
    showlegend: bool = True,
    fig: plotly.basedatatypes.BaseFigure = None,
    **layout_kwargs,
) ‑> pandas.core.series.Series

Container with copula contour figure object.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
set_datetime_index	bool	True	It True, set output datetime index. Note that it is indexed by the test set index inferred from get_best_copula. Defaults to True.
show_latest_point	bool, Default True“	--	If True, show latest values as red dot. Defaults to True.
alpha	float	0.5	Contour alpha size. Defaults to 0.5.
opacity	float	0.2	Point opacity. Defaults to 0.2.
title	str	None	The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
showlegend	bool	True	Show legend. Defaults to True.
fig	tp.BaseFigure	None	Existing figure to update. If None, a new figure is created. Defaults to None.
layout_kwargs	tp.Kwargs	--	Additional keyword arguments for customizing the layout.

Returns:

Type	Description
pd.Series	Copula surface figures.

plot_all

plot_all(
    self,
    key: str = 'train',
    in_outputs: str | List[str] | None = None,
    select_signals: Literal[{'short_exits', 'short_entries', 'long_entries', 'long_exits'}] = None,
    set_datetime_index: bool = True,
    show_latest_point: bool = False,
    show_contour: bool = True,
    alpha: float = 0.5,
    opacity: float = 0.2,
    title: str | None = None,
    showlegend: bool = True,
    fig: plotly.basedatatypes.BaseFigure = None,
    **layout_kwargs,
) ‑> pandas.core.series.Series

Container with copula contour, marginal and signals figure object.

Parameters:

Name	Type	Default	Description
key	str	train	If train, extract train-set. If test, extract test-set. Defaults to train.
in_outputs	None	--	| str | tp.List[str], default None Report data. Defaults to None.
select_signals	tp.Literal[VALID_SIGNALS]	None	Filter Signals by a signal (e.g. long_entries). If None, It is ignored. Defaults to None.
set_datetime_index	bool	True	It True, set output datetime index. Note that it is indexed by the test set index inferred from get_best_copula. Defaults to True.
show_contour	bool	True	Show contour if True. Defaults to True.
show_latest_point	bool, Default True“	--	If True, show latest values as red dot. Defaults to True.
alpha	float	0.5	Contour alpha size. Defaults to 0.5.
opacity	float	0.2	Point opacity. Defaults to 0.2.
title	str	None	The title for the plot. If not provided, a default title based on the fitted copula’s representation is used.
showlegend	bool	True	Show legend. Defaults to True.
fig	tp.BaseFigure	None	Existing figure to update. If None, a new figure is created. Defaults to None.
layout_kwargs	tp.Kwargs	--	Additional keyword arguments for customizing the layout.

Returns:

Type	Description
pd.Series	Copula surface figures.

ArbitrageIndexRolling

ArbitrageIndexRolling(
    id: str = None,
    loader_or_data: Callable = <function load_clean_data>,
    timeframe: str = '1d',
    start: str = None,
    end: str = None,
    s1: str = 'BTCUSDT',
    s2: str = 'ETHUSDT',
    suffix: str = 'h5',
    use_close: bool = True,
    freq: str = None,
    signal_model: str = None,
    long_entries: float = nan,
    long_exits: float = nan,
    short_entries: float = nan,
    short_exits: float = nan,
    clean: bool = True,
    select_symbols: str | int | List[str | int] = None,
    portfolio_config: Dict[str, Any] = _Nothing.NOTHING,
    model_params: Dict[str, Any] = _Nothing.NOTHING,
    metrics: str | List[str] = None,
    metrics_kwargs: Dict[str, Any] = _Nothing.NOTHING,
    use_rolling: bool = False,
    storage: str | optuna.storages._base.BaseStorage = None,
    pruner: optuna.pruners._base.BasePruner = <optuna.pruners._successive_halving.SuccessiveHalvingPruner object>,
    sampler: optuna.samplers._base.BaseSampler = <optuna.samplers._tpe.sampler.TPESampler object>,
    study_name: str = None,
    direction: str | List[str] = 'maximize',
    load_if_exists: bool = False,
    n_trials: int = 100,
    n_completed_trials: int = None,
    timeout: float = None,
    n_jobs: int = 1,
    catch: Iterable[Type[Exception]] | Type[Exception] = _Nothing.NOTHING,
    callbacks: Iterable[Callable[[optuna.study.study.Study, optuna.trial._frozen.FrozenTrial], None]] | None = None,
    gc_after_trial: bool = False,
    show_progress_bar: bool = False,
    verbose: bool = True,
    tracker: Type = None,
    model: Any = None,
    preprocess_func: Callable = None,
)

Breakdown analysis for arbitrage index models, extending BaseRollingWalkForward. Includes methods to compute Kendall’s Tau, determine the best copula, and extract copula parameters.

Method generated by attrs for class ArbitrageIndexRolling.

Ancestors

• systematica.walk_forward.rolling.RollingWalkForward
• systematica.walk_forward.base.BaseWalkForward
• abc.ABC
• systematica.generic.base.Model
• systematica.generic.base.Feature