> ## 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.

# Quickstart

> General use cases.

## Setup your environment

<Info>
  **Prerequisite**: Please install `systematica` before proceeding. More information in the [installation](installation) page.
</Info>

<Steps>
  <Step title="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.

    ```sh theme={null}
    uv venv
    ```
  </Step>

  <Step title="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:

    ```sh theme={null}
    source .venv/bin/activate
    ```

    On Windows:

    ```sh theme={null}
    .venv\\Scripts\\activate
    ```
  </Step>
</Steps>

## Use Cases

<img className="block dark:hidden" src="https://mintcdn.com/systematica/pAElWApsyiJCuX__/diagrams/model-api-light.png?fit=max&auto=format&n=pAElWApsyiJCuX__&q=85&s=33f5d6e616533d9339c787e35c274ad0" alt="Hero Light" width="2740" height="1026" data-path="diagrams/model-api-light.png" />

<img className="hidden dark:block" src="https://mintcdn.com/systematica/pAElWApsyiJCuX__/diagrams/model-api-dark.png?fit=max&auto=format&n=pAElWApsyiJCuX__&q=85&s=273ba16a5f8e08b793b0334120eaffce" alt="Hero Dark" width="2740" height="1026" data-path="diagrams/model-api-dark.png" />

<Steps>
  <Step title="Import depedencies">
    ```python theme={null}
    import systematica as sma 
    ```
  </Step>

  <Step title="Get data.">
    ```python theme={null}
    data = sma.load_clean_data('1d')
    s1, s2 = data.symbols
    ```
  </Step>

  <Step title="Get model output">
    ```python theme={null}
    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)>
    ```
  </Step>

  <Step title="Get signals">
    ```python theme={null}
    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(...)
    ```
  </Step>

  <Step title="Run pipeline">
    Get `vbt.Portfolio` instance:

    ```python theme={null}
    sma.ArbitrageClipIndex.run_pipeline(loader_or_data=data, s1=s1, s2=s2, ...)
    # <vectorbtpro.portfolio.base.Portfolio object at 0x30bf7bcb0>
    ```

    Get metrics:

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

    Get rolling metrics:

    ```python theme={null}
    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]
    ```
  </Step>

  <Step title="Run optuna">
    ```python theme={null}
    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.
    ```
  </Step>

  <Step title="Run analyzer">
    ```python theme={null}
    sma.ArbitrageClipIndex.run_analyzer(data, s1, s2, ...)
    # <systematica.portfolio.integration.analyzers.base.PortfolioAnalyzer object at 0x16f7b3b60>
    ```
  </Step>

  <Step title="Run report">
    ```python theme={null}
    sma.ArbitrageClipIndex.run_report(data, s1, s2, ...)
    # BaseReportCV(...)
    ```
  </Step>
</Steps>