Quickstart

General use cases.

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
   

Use Cases

1. Import depedencies

   import systematica as sma 
   
2. Get data.

   data = sma.load_clean_data('1d')
   s1, s2 = data.symbols
   
3. Get model output

   model = sma.ArbitrageClipIndex(training_window=365, testing_window=60)
   model_output = model(data, s1, s2)
   vbt.pprint(model_output)
   # <numpy.ndarray object at 0x15bd0a850 with shape (2637, 2)>
   
4. Get signals

   signals = model.get_signals(model_output, signal_model='twin_spread', long_entries=0.9, long_exits= 0.0, short_entries=-0.9, short_exits=0.0)
   vbt.pprint(signals)
   # Signals(...)
   
5. Run pipeline

   Get vbt.Portfolio instance:

   sma.ArbitrageClipIndex.run_pipeline(loader_or_data=data, s1=s1, s2=s2, ...)
   # <vectorbtpro.portfolio.base.Portfolio object at 0x30bf7bcb0>
   

   Get metrics:

   sma.ArbitrageClipIndex.run_pipeline(
     data, 
     s1, 
     s2, 
     ..., 
     metrics='sharpe_ratio'
   )
   # {'Sharpe Ratio': np.float64(0.24471785688706227)}
   

   Get rolling metrics:

   sma.ArbitrageClipIndex.run_pipeline(
     data, 
     s1, 
     s2, 
     ..., 
     metrics='sharpe_ratio', 
     use_rolling=True
   )
   #                            Sharpe Ratio
   # Open time                              
   # 2018-01-01 00:00:00+00:00           NaN
   # 2018-01-02 00:00:00+00:00           NaN
   # 2018-01-03 00:00:00+00:00           NaN
   # 2018-01-04 00:00:00+00:00           NaN
   # 2018-01-05 00:00:00+00:00           NaN
   # ...                                 ...
   # 2025-03-17 00:00:00+00:00      0.286009
   # 2025-03-18 00:00:00+00:00      0.286009
   # 2025-03-19 00:00:00+00:00      0.353324
   # 2025-03-20 00:00:00+00:00      0.304297
   # 2025-03-21 00:00:00+00:00      0.206504
   
   # [2637 rows x 1 columns]
   
6. Run optuna

   sma.ArbitrageClipIndex.run_optuna_study(
     data, 
     s1,
     s2, 
     ..., 
     metrics='sharpe_ratio', 
     direction='maximize', 
     n_trials=10,
     training_window=sma.Int('training_window', low=20, high=500, step=10)
   )
   # [I 2025-06-26 11:17:34,082] A new study created in memory ...
   # [I 2025-06-26 11:17:48,496] Trial 0 finished with value: 0.53 ...
   # ...
   # [W 2025-06-26 11:17:50,054] Timer @ 5.97 seconds & RAM @ 7.3 MB.
   
7. Run analyzer

   sma.ArbitrageClipIndex.run_analyzer(data, s1, s2, ...)
   # <systematica.portfolio.integration.analyzers.base.PortfolioAnalyzer object at 0x16f7b3b60>
   
8. Run report

   sma.ArbitrageClipIndex.run_report(data, s1, s2, ...)
   # BaseReportCV(...)