Metadata-Version: 2.4
Name: dquant
Version: 1.1.1
Summary: dquant — это Python-библиотека с открытым исходным кодом для автоматического прогнозирования волатильности финансовых временных рядов. Она берёт на себя все этапы построения модели: от сырых цен до готового прогноза.
Author: Denis Makarov
Project-URL: Homepage, https://dquant.space
Project-URL: Repository, https://github.com/artrdon/dquant
Project-URL: Documentation, https://github.com/artrdon/dquant/blob/main/docs.md
Project-URL: Issues, https://github.com/artrdon/dquant/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cycler>=0.11.0
Requires-Dist: joblib>=1.2.0
Requires-Dist: lightgbm>=3.3.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: onnx>=1.14.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: skl2onnx>=1.14.0
Requires-Dist: xgboost>=1.7.0
Requires-Dist: onnxconverter-common>=1.9.0
Requires-Dist: onnxmltools>=1.11.0
Dynamic: license-file

<div align="center">
  <h1>dquant</h1>
  <p><strong>Автоматическое прогнозирование волатильности для трейдеров и аналитиков</strong></p>
  <br>
  <img src="https://github.com/artrdon/dquant/blob/main/logo.png?raw=true" alt="dquant demo" width="200">
  <br>
  <p><i>Прогноз волатильности с помощью dquant</i></p>
</div>

---

## О проекте

**dquant** — это Python-библиотека с открытым исходным кодом для автоматического прогнозирования волатильности финансовых временных рядов. Она берёт на себя все этапы построения модели: от сырых цен до готового прогноза.

### Ключевая идея
> **Трейдеру не нужно знать машинное обучение, чтобы использовать ИИ для прогнозирования волатильности.**

### Возможности

| | |
|---|---|
| **Автоматический feature engineering** | Из сырых цен (open, high, low, close, volume) создаются десятки признаков |
| **Целевая переменная без look-ahead bias** | Корректный расчёт реализованной волатильности |
| **3 модели на выбор** | Градиентный бустинг, XGBoost, LightGBM с ранней остановкой |
| **Визуализация обучения** | График ошибок на train/validation для контроля переобучения |
| **Сохранение и загрузка** | Обучил один раз — используй всегда |
| **Гибкая кастомизация** | Свои признаки, параметры модели, источники данных |
| **Интеграция с любыми данными** | Yahoo Finance, MetaTrader 5 |

### Для кого это

- **Алгоритмические трейдеры** — для калибровки моделей и управления рисками
- **Дискреционные трейдеры** — для оценки рыночного режима и размера позиции
- **Количественные аналитики** — для быстрого прототипирования
- **Разработчики** — для встраивания в торговые системы
- **Студенты** — как готовый бенчмарк и учебный пример

---

## Установка

### Требования
- Python 3.7 или выше
- pip


```bash
pip install dquant
```


### Проверка установки

```python
import dquant
print(dquant.__version__)  # Должно вывести версию
```

---

## Быстрый старт

### Минимальный рабочий пример с Bitcoin

```python
import pandas as pd
import yfinance as yf
from dquant.models import VolClustXGB 


# 1. Загружаем данные
df = yf.download("BTC-USD", start="2020-01-01", interval='1d')
df = pd.DataFrame({
    'open': df[('Open', 'BTC-USD')].values,
    'high': df[('High', 'BTC-USD')].values,
    'low': df[('Low', 'BTC-USD')].values,
    'close': df[('Close', 'BTC-USD')].values,
    'volume': df[('Volume', 'BTC-USD')].values
}, index=df.index)

# 2. Создаем модель
model = VolClustXGB({}, early_stopping=True)

# 3. Обучаем модель
features = [
    'TR',
    'returns',
    'abs_returns',
    'gap',
    'body',
    'shadow',
    'close_position',
    'roll_atr_14'
]
model.fit(df, feature_list=features, input_bars=70, horizon=20, trees_count=200, show_results=True)

# 4. Делаем прогноз
rez = model.forecast(df.iloc[-70:].copy(), show=True)

```

### Результат выполнения

```
[0.0016554 0.0018979 0.0015921 0.0014239 0.0013767 0.0011586 0.0013139
 0.0009813 0.0007931 0.0012909 0.0013664 0.0016466 0.0014836 0.0011577
 0.0008737 0.0007213 0.0008084 0.0012699 0.0015358 0.0014748]
```
<img src="https://github.com/artrdon/dquant/blob/main/readmeforecast.png?raw=true">

Красным показана волатильность за предыдущие свечи, а зеленым - будущая волатильность.

---

## Документация

| Ресурс | Описание |
|:-------|:---------|
| [**Полная документация**](https://github.com/artrdon/dquant/blob/main/docs.md) | Все классы, методы, параметры |



---

## Примеры использования

### С Yahoo Finance

```python
import pandas as pd
import yfinance as yf
from dquant.models import VolClustXGB 


# 1. Загружаем данные
df = yf.download("BTC-USD", start="2020-01-01", interval='1d')
df = pd.DataFrame({
    'open': df[('Open', 'BTC-USD')].values,
    'high': df[('High', 'BTC-USD')].values,
    'low': df[('Low', 'BTC-USD')].values,
    'close': df[('Close', 'BTC-USD')].values,
    'volume': df[('Volume', 'BTC-USD')].values
}, index=df.index)

# 2. Создаем модель
model = VolClustXGB({}, early_stopping=True)

# 3. Обучаем модель
features = [
    'TR',
    'returns',
    'abs_returns',
    'gap',
    'body',
    'shadow',
    'close_position',
    'roll_atr_14'
]
model.fit(df, feature_list=features, input_bars=70, horizon=20, trees_count=200, show_results=True)


# 4. Делаем прогноз
rez = model.forecast(df.iloc[-70:].copy(), show=True)
```

### С MetaTrader 5

```python
import pandas as pd
import MetaTrader5 as mt5
from dquant.models import VolClustXGB 


symbol = "EURUSD"          # какой символ смотреть
timeframe = mt5.TIMEFRAME_H1   # M1, M5, M15, H1, D1 и т.д.
days_back = 1000             # сколько дней истории загрузить

# Подключаемся к MT5
if not mt5.initialize():
    print("Не удалось подключиться к MetaTrader5")
    quit()

# Проверяем, что символ доступен
if not mt5.symbol_select(symbol, True):
    print(f"Символ {symbol} не найден или не включён")
    mt5.shutdown()
    quit()

# Вычисляем даты
to_date = dt.datetime.now() + dt.timedelta(hours=3)
from_date = to_date - dt.timedelta(days=days_back)

# Загружаем бары
rates = mt5.copy_rates_range(symbol, timeframe, from_date, to_date)

mt5.shutdown()  # больше не нужен терминал

if rates is None or len(rates) == 0:
    print("Нет данных!")
    quit()

# Превращаем в DataFrame
df = pd.DataFrame(rates)
df['time'] = pd.to_datetime(df['time'], unit='s')


df.rename(columns={
    'tick_volume': 'volume'
}, inplace=True)

# Создаем модель
model = VolClustXGB({}, early_stopping=True)

# Обучаем модель
features = [
    'TR',
    'returns',
    'abs_returns',
    'gap',
    'body',
    'shadow',
    'close_position',
    'roll_atr_14'
]
model.fit(df, feature_list=features, input_bars=70, horizon=20, trees_count=200, show_results=True)

# Делаем прогноз
rez = model.forecast(df.iloc[-70:].copy(), show=True)
```
---
## Создание индикатора для Meta Trader 5

Сразу после обучения модели её можно экспортировать в рабочий индикатор на mql5. Нужна еще одна строка кода:
```python
model.save('indicator_name', type_to_save='mql5')
```
Готово! Теперь вы можете использовать вами обученные модели в Meta Trader 5.

---

## Лицензия

Проект распространяется под лицензией MIT. Подробнее в файле [LICENSE](https://github.com/artrdon/dquant/blob/main/LICENSE).

---

## Контакты

**Автор:** Денис Макаров

- Telegram: [@Denchik_ai](https://t.me/Denchik_ai)
- GitHub: [@artrdon](https://github.com/artrdon)
- Сайт проекта: [dquant.space](https://dquant.space)

---

