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

# Volume Profile

> systematica.api.models.volume_profile

Volume profile factors analyze the relationship between price movements and trading volume to identify periods of unusual market activity and price-volume correlations.

## Volume Profile Components

| Component                | Description                                     | Calculation                           |
| ------------------------ | ----------------------------------------------- | ------------------------------------- |
| Volume Trend             | Short vs. long-term volume ratio                | `(short_avg / long_avg) - 1`          |
| Price-Volume Correlation | Correlation between volume and absolute returns | `nancorr_1d_nb(volume, abs(returns))` |
| Volume Surge             | Logarithmic volume increase detection           | `log1p(ratio) * surge_scale`          |

## Volume Profile API Classes

| Class                        | Description                     | Key Features                                 |
| ---------------------------- | ------------------------------- | -------------------------------------------- |
| `RollingVolumeProfileFactor` | Rolling window analysis         | Dynamic window sizing, trend detection       |
| `VolumeProfileFactorCV`      | Cross-validated volume analysis | Walk-forward validation, parameter stability |

## `RollingVolumeProfileFactor`

```python theme={null}
RollingVolumeProfileFactor(
    window: int = 365,
    minp: int = None,
    short_term_window: int = 30,
    surge_scale: float = 5.0,
    score_scale: float = 2.0,
)
```

Volume Profile variation factor over rolling window.

* **Volume Profile Variation** : This method calculates volume profile
  variation by combining volume-based signals with price movement (correlation between volume and price returns)
  over configurable time windows.
  It highlights volume surges and volume-price trends to generate an indicator.
* **Signal Calculation** : The signals are scaled and combined to give a
  final output by iterating over the historical data (closing prices and
  volume) using a rolling window.

**Workflow**:

1. **Calculate Volume and Trend** :
   calculates the average volume over two time periods: a short-term window
   and the entire window. It also computes the volume trend, defined as the
   ratio of short-term to long-term average volume.

2. **Volume-Price Correlation** :
   Calculates the correlation between volume -- smoothed over the short-term
   window -- and price returns over the same period. This helps determine if
   changes in volume are associated with price movement.

3. **Volume Surge Detection** :
   Detect volume surges by comparing the short-term volume with long-term
   volume. This surge is amplified by the `surge_scale` factor.

4. **Signal Combination** :
   Combine the volume trend, price-volume correlation, and volume surge to
   create a composite signal.

5. **Iterating Over Symbols** :
   Applies the volume and price trend calculations for each symbol.

6. **Final Signal Calculation** :
   Slice the closing prices and volume data to the most recent `volume_window`
   and computes the signals. The resulting signals are aggregated and scaled.
   Finally, the signal is passed through a hyperbolic tangent (`np.tanh`) for
   smoothing and amplified before returning the final value.

Method generated by attrs for class RollingVolumeProfileFactor.

### Ancestors

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

### Instance variables

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

* `score_scale: float`: Score scale coefficient. Defaults to `2.0`. This factor scales the final score output.

* `short_term_window: int`: Short term window. Defaults to `30`.

* `surge_scale: float`: Volume surge scale coefficient. Defaults to `5.0`. This factor amplifies the volume surge detection.

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

## `VolumeProfileFactorCV`

```python theme={null}
VolumeProfileFactorCV(
    training_window: int = 365,
    testing_window: int = 60,
    splitter: str = 'from_custom_rolling',
    custom_splitter: str | None = None,
    custom_splitter_kwargs: dict | None = None,
    short_term_window: int = 30,
    surge_scale: float = 5.0,
    score_scale: float = 2.0,
)
```

Volume Profile variation factor over cross-validation splits.

* **Volume Profile Variation** : This method calculates volume profile
  variation by combining volume-based signals with price movement (correlation between volume and price returns)
  over configurable time windows.
  It highlights volume surges and volume-price trends to generate an indicator.
* **Signal Calculation** : The signals are scaled and combined to give a
  final output by iterating over the historical data (closing prices and
  volume) using a cross-validation approach.

**Workflow**:

1. **Calculate Volume and Trend** :
   calculates the average volume over two time periods: a short-term window
   and the entire window. It also computes the volume trend, defined as the
   ratio of short-term to long-term average volume.

2. **Volume-Price Correlation** :
   Calculates the correlation between volume -- smoothed over the short-term
   window -- and price returns over the same period. This helps determine if
   changes in volume are associated with price movement.

3. **Volume Surge Detection** :
   Detect volume surges by comparing the short-term volume with long-term
   volume. This surge is amplified by the `surge_scale` factor.

4. **Signal Combination** :
   Combine the volume trend, price-volume correlation, and volume surge to
   create a composite signal.

5. **Iterating Over Symbols** :
   Applies the volume and price trend calculations for each symbol.

6. **Final Signal Calculation** :
   Slice the closing prices and volume data to the most recent `volume_window`
   and computes the signals. The resulting signals are aggregated and scaled.
   Finally, the signal is passed through a hyperbolic tangent (`np.tanh`) for
   smoothing and amplified before returning the final value.

Method generated by attrs for class VolumeProfileFactorCV.

### Ancestors

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

### Instance variables

* `custom_splitter: str | None`: Custom splitter to use for data partitioning. Defaults to `None`. If set, it should be a string that matches a custom splitter function.

* `custom_splitter_kwargs: dict | None`: Additional keyword arguments for the custom splitter. Defaults to `None`. If `custom_splitter` is set, this should contain any necessary parameters for the custom splitter function.

* `score_scale: float`: Score scale coefficient. Defaults to `2.0`. This factor scales the final score output.

* `short_term_window: int`: Short term window. Defaults to `30`. This is the window size used for short-term volume calculations.

* `splitter: str`: Default splitter to be used if `custom_splitter` is not passed.  Choices are `from_rolling`, `from_expanding`, `from_custom_rolling`,  `from_custom_expanding`. Defaults to "from\_custom\_rolling".

* `surge_scale: float`: Volume surge scale coefficient. Defaults to `5.0`. This factor amplifies the volume surge detection.

* `testing_window: int`: The size of the testing window. Defaults to `60`. This is the window size used for testing the model.

* `training_window: int`: The size of the training window. Defaults to `365`. This is the window size used for training the model.