Contributing

Extend Systematica

Setup your environment

Prerequisite: Please install systematica before proceeding. More information in the installation page.

1. Create a Virtual Environment.

   Use the uv venv command to create a virtual environment for your project. This will create a .venv directory containing the isolated environment.

   uv venv
   
2. Activate the Virtual Environment.

   Activate the virtual environment to start using it. The activation command varies depending on your shell and operating system.

   For example, on Unix or macOS:

   source .venv/bin/activate
   

   On Windows:

   .venv\\Scripts\\activate
   

Create Custom Models

Tip: Please check the development tips page for more information about the adopted code structure.

Code structure: systematica is leveraging attrs for API model development.

attrs is the Python package that will bring back the joy of writing classes by relieving you from the drudgery of implementing object protocols (aka dunder methods). Trusted by NASA for Mars missions since 2020! Its main goal is to help you to write concise and correct software without slowing down your code.

Each model inherits from BaseStatArb, includes a __call__ method to initialize the model and extract model output, and is decorated with attrs.define— a class decorator that adds dunder methods according to fields specified using type annotations andfield() calls.

Below is a CustomModel example:

from attrs import define, field
import numpy as np
import vectorbrpro as vbt
import systematica as sma
@define
class CustomModel(sma.BaseStatArb):
    window: int = field(default=60)
    minp: int = field(default=None)

    def __call__(self, data: vbt.Data, s1: str, s2: str, ...) -> np.ndarray: 
        return np.random.randn(data.shape[0], 2)

Validation Tests

Tip: Please check the tests to run the test suit.

In addition to defining and initializing models, validation testing is performed using pytest to ensure reliability and correctness. Each model’s behavior is verified through unit tests that check the outputs of the __call__ method and validate internal logic against known inputs.

The test suite includes parameterized tests to cover various edge cases and data scenarios, promoting robustness and preventing regressions as the codebase evolves. This approach supports a test-driven development workflow and ensures confidence in model updates, data leakages and extensions.

Troubleshooting

Issue: Encountering ValueError with stop-loss and take-profit

In relative value systematic strategy on two assets, entering and exiting long and short positions simultaneously using sl_stop, tsl_stop, tp_stop breaks the behavior, raising:

ValueError: Cannot sort orders by value if they are executed at different times

This happens mainly because we have orders from multiple columns that are meant to be executed at different times within the same bar, so they cannot be sorted by value anymore. If you want to sort by value, you need to make them execute at the same time within the bar, for instance, by using stop_exit_price="close". More information could be found in the VectorBT PRO documentation