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

# Volatility

> systematica.api.models.volatility

Volatility factors analyze price volatility patterns across multiple time horizons to generate trading signals based on volatility regime changes and trends.

## Volatility Model Components

| Stage                  | Main Function                  | Subcomponents/Components                                              |
| ---------------------- | ------------------------------ | --------------------------------------------------------------------- |
| Dynamic Window         | `get_dynamic_window_nb()`      | `short_term`, `medium_term`, `long_term`                              |
| Volatility Computation | `get_volatilities_nb()`        | `short_vol`, `medium_vol`, `long_vol`                                 |
| Score Components       | `scores_nb()`                  | `medium_term_impact`, `long_term_impact`, `trend_impact`, `direction` |
| Final Scoring          | `weighted_average_scores_nb()` | `volatility_nb()` (with `tanh()` amplification)                       |

## Volatility API Classes

| Class                     | Description                         | Key Features                                 |
| ------------------------- | ----------------------------------- | -------------------------------------------- |
| `RollingVolatilityFactor` | Rolling window volatility analysis  | Dynamic window sizing, trend detection       |
| `VolatilityFactorCV`      | Cross-validated volatility analysis | Walk-forward validation, parameter stability |

## `RollingVolatilityFactor`

```python theme={null}
RollingVolatilityFactor(
    window: int = 365,
    minp: int = None,
    vol_window: int = 30,
    min_periods: int = 10,
    medium_term_weight: float = 0.5,
    long_term_weight: float = 0.2,
    trend_weight: float = 0.3,
    signal_impact_multiplier: float = 5.0,
)
```

Rolling Volatility variation factor.

* **Mutliple Dynamic Window**:
  Model is determines through three different time horizons -- short, medium
  and long-term horizons.
* **Volatility Insigths**:
  The standard deviations (volatilities) over the defined dynamic windows.
* **Scoring Mechanism**:
  Relative scores between periods, trend and direction are encapsulated.
* **Signal Calculation**:
  Aggregates signals and applies a hyperbolic tangent (tanh)

**Workflow**:

1. **Calculate Returns**:
   compute log returns from closing prices.

2. **Compute Volatility on Different Time Horizons**:
   Derive signals through weighted average standard deviation calculated on
   multiple periods

3. **Aggregate Signals**:
   Combine the individual signals using their mean and compute the hyperbolic
   tangent element-wise.

4. **Handling Multiple Symbols**:
   The process is repeated for each pair, offering a broader market view.

Method generated by attrs for class RollingVolatilityFactor.

### Ancestors

* `systematica.models.base.BaseStatArb`
* `abc.ABC`

### Instance variables

* `long_term_weight: float`: Long term weight coeff. Defaults to `0.2`.

* `medium_term_weight: float`: Medium term weight coeff. Defaults to `0.5`.

* `min_periods: int`: Mininim period for calculating volatility. Defaults to `10`.

* `minp: int`: Mininim period. Defaults to `None`, which means no minimum period is applied.

* `signal_impact_multiplier: float`: Signal impact multiplier. Defaults to `5.0`.

* `trend_weight: float`: Trend weights. Defaults to `0.3`.

* `vol_window: int`: Volatility window size. Defaults to `30`.

* `window: int`: The size of the rolling window. Defaults to `365`.

## `VolatilityFactorCV`

```python theme={null}
VolatilityFactorCV(
    training_window: int = 365,
    testing_window: int = 60,
    splitter: str = 'from_custom_rolling',
    custom_splitter: str | None = None,
    custom_splitter_kwargs: dict | None = None,
    vol_window: int = 30,
    min_periods: int = 10,
    medium_term_weight: float = 0.5,
    long_term_weight: float = 0.2,
    trend_weight: float = 0.3,
    signal_impact_multiplier: float = 5.0,
)
```

Volatility variation factor cross validation.

* **Mutliple Dynamic Window**:
  Model is determines through three different time horizons -- short, medium
  and long-term horizons.
* **Volatility Insigths**:
  The standard deviations (volatilities) over the defined dynamic windows.
* **Scoring Mechanism**:
  Relative scores between periods, trend and direction are encapsulated.
* **Signal Calculation**:
  Aggregates signals and applies a hyperbolic tangent (tanh)

**Workflow**:

1. **Calculate Returns**:
   compute log returns from closing prices.

2. **Compute Volatility on Different Time Horizons**:
   Derive signals through weighted average standard deviation calculated on
   multiple periods

3. **Aggregate Signals**:
   Combine the individual signals using their mean and compute the hyperbolic
   tangent element-wise.

4. **Handling Multiple Symbols**:
   The process is repeated for each pair, offering a broader market view.

Method generated by attrs for class VolatilityFactorCV.

### Ancestors

* `systematica.models.base.BaseStatArb`
* `abc.ABC`

### Instance variables

* `custom_splitter: str | None`: Custom splitter to use for data partitioning. Defaults to `None`, which means no custom splitter is used.

* `custom_splitter_kwargs: dict | None`: Additional keyword arguments for the custom splitter. Defaults to `None`, which means no additional arguments are passed.

* `long_term_weight: float`: Long term weight coefficient. Defaults to `0.2`. This is the weight applied to the long-term volatility in the final score calculation.

* `medium_term_weight: float`: Medium term weight coefficient. Defaults to `0.5`. This is the weight applied to the medium-term volatility in the final score calculation.

* `min_periods: int`: Mininim period for calculating volatility. Defaults to `10`. This is the minimum number of periods required to calculate volatility.

* `signal_impact_multiplier: float`: Signal impact multiplier. Defaults to `5.0`. This factor amplifies the impact of the signals in the final score calculation.

* `splitter: str`: Default splitter to be used if custom\_splitter is not passed.  Choices are `from_rolling`, `from_custom_rolling`, `from_expanding`,  `from_custom_expanding`. Defaults to `from_custom_rolling`.

* `testing_window: int`: The size of the testing window. Defaults to `60`.

* `training_window: int`: The size of the training window. Defaults to `365`.

* `trend_weight: float`: Trend weights. Defaults to `0.3`. This is the weight applied to the trend in the final score calculation.

* `vol_window: int`: Volatility window size. Defaults to `30`. This is the window size used for calculating volatility.