Metadata-Version: 2.4
Name: deltafq-crixus
Version: 0.1.0
Summary: A Python quantitative trading framework — data, factors, backtesting, and live execution.
Author: CrixusZeng
License: MIT
Project-URL: homepage, https://github.com/CrixusZ/my_deltafq
Project-URL: repository, https://github.com/CrixusZ/my_deltafq
Keywords: quantitative-finance,backtesting,trading,factor-model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: quant
Requires-Dist: cvxpy>=1.3; extra == "quant"
Requires-Dist: statsmodels>=0.14; extra == "quant"
Requires-Dist: scikit-learn>=1.3; extra == "quant"
Provides-Extra: jupyter
Requires-Dist: jupyter>=1.0; extra == "jupyter"
Requires-Dist: ipykernel>=6.0; extra == "jupyter"
Provides-Extra: all
Requires-Dist: deltafq[dev,jupyter,quant]; extra == "all"

# DeltaFQ - Quantitative Trading Framework

DeltaFQ is a Python quantitative trading library covering the full workflow:
data sourcing → factor research → portfolio construction → order execution → performance evaluation.

## Features

- **Data Layer** — Unified data sourcing with abstract provider interface, CSV/Parquet local storage, MultiIndex DataFrame (date, asset)
- **Factor Engine** — Factor base class, common alphas (momentum, reversal, volatility, turnover), custom factor expression algebra
- **Portfolio Management** — Weight optimization, rebalancing, constraint solving
- **Risk Modeling** — Covariance estimation, VaR/CVaR, attribution analysis
- **Backtesting** — Event-driven engine, slippage/commission/market-impact simulation, daily and intraday support
- **Paper Trading** — Simulated broker with market/limit/stop orders, configurable slippage and commission
- **Live Trading** — Broker adapter base class for real-market execution (CTP, IB, Binance, etc.)
- **Performance Evaluation** — Sharpe/Calmar/Max-Drawdown, IC/IR analysis, turnover tracking

## Installation

```bash
pip install -e .
```

## Usage Guide

### 1. Load Data

```python
from deltafq.core.data import DataFrameSource, CSVDataSource

# From in-memory DataFrame (requires date, asset, close columns at minimum)
src = DataFrameSource(df, name="mydata")
prices = src.get_close()         # wide (date x asset) DataFrame
returns = src.get_returns()      # daily returns
print(src.assets)                # ['AAPL', 'GOOG', ...]

# From CSV
src = CSVDataSource("data/daily_prices.csv")
df = src.load()                  # canonical (date, asset) MultiIndex
```

### 2. Compute Factors

```python
from deltafq.core.factor import (
    MomentumFactor, ReversalFactor, VolatilityFactor,
    RSI, MACD, cross_sectional_zscore, rank_normalize,
)

# Single factor
mom = MomentumFactor(window=20)
raw = mom.compute(prices)        # (date x asset) factor matrix

# Cross-sectional normalization
z = cross_sectional_zscore(raw)  # z-score per date
r = rank_normalize(raw)          # percentile rank, scaled to [-1, 1]

# Factor algebra
combo = 0.5 * MomentumFactor(20) + 0.3 * ReversalFactor(5)
signal = combo.compute(prices)
```

### 3. Build Portfolio

```python
from deltafq.core.portfolio import signal_weight, mean_variance, rebalance

# Signal-to-weight (auto clip + redistribute + normalize)
target_w = signal_weight(signal.iloc[-1], long_only=True, max_weight=0.10)

# Mean-variance optimization
target_w = mean_variance(returns.mean(), returns.cov(), risk_aversion=2.0)

# Rebalance (compute required trades + turnover control)
result = rebalance(target_w, current_w, max_turnover=0.3)
print(result.trades)             # buy/sell orders
print(result.turnover)           # actual one-way turnover
```

### 4. Risk Management

```python
from deltafq.core.risk import (
    shrinkage_covariance, historical_var, historical_cvar,
    portfolio_volatility, factor_exposure_attribution,
)

cov = shrinkage_covariance(returns, window=252, shrinkage=0.2)
var95 = historical_var(returns["AAPL"], confidence=0.95)
cvar95 = historical_cvar(returns["AAPL"], confidence=0.95)
vol = portfolio_volatility(target_w, cov)
```

### 5. Backtest — Full Pipeline

```python
from deltafq.core.backtest import BacktestEngine, BacktestConfig
from deltafq.core.factor import MomentumFactor, cross_sectional_zscore
from deltafq.core.portfolio import signal_weight

engine = BacktestEngine(BacktestConfig(
    initial_capital=1_000_000,
    commission_rate=0.0003,
    slippage_bps=1.0,
))

def my_strategy(date, history):
    """Called at each bar. Receives (timestamp, {asset: price_series})."""
    prices = pd.DataFrame({a: h for a, h in history.items()})
    factor = MomentumFactor(20).compute(prices)
    z = cross_sectional_zscore(factor).iloc[-1]
    return signal_weight(z, long_only=True, max_weight=0.10).to_dict()

result = engine.run(prices, my_strategy)

print(result.equity_curve.tail())         # daily equity
print(result.metrics["sharpe_ratio"])     # annualized Sharpe
print(result.metrics["max_drawdown"])     # max drawdown
print(len(result.trades))                 # total fills
```

### 6. Paper Trading

```python
from deltafq.trading import PaperBroker
from deltafq.trading.broker import Order, OrderSide, OrderType

broker = PaperBroker(initial_capital=500_000, slippage=2.0)
broker.load_market_data("AAPL", aapl_ohlcv)

# Market order
order = Order(asset="AAPL", side=OrderSide.BUY, order_type=OrderType.MARKET, quantity=100)
result = broker.submit_order(order)
print(result.status, result.avg_fill_price)

# Limit order (fills automatically when price crosses)
limit = Order(
    asset="AAPL", side=OrderSide.BUY, order_type=OrderType.LIMIT,
    quantity=200, limit_price=148.0,
)
broker.submit_order(limit)
broker.step(timestamp)                   # advance simulation, check triggers

# Account snapshot
acc = broker.get_account()
print(acc.cash, broker.get_positions())
```

### 7. Evaluate Performance

```python
from deltafq.core.evaluation import performance_report

report = performance_report(
    returns=daily_returns,
    equity=equity_curve,
    factor=factor_matrix,                # optional: IC analysis
    forward_returns=fwd_returns,         # optional: IC analysis
    weights=weights_history,             # optional: turnover analysis
)
print(report["sharpe_ratio"], report["max_drawdown"], report["calmar_ratio"])
```

### 8. Top-Level Imports

```python
from deltafq import (
    BacktestEngine, BacktestConfig,        # backtest
    MomentumFactor, cross_sectional_zscore,# factor
    PaperBroker,                            # trading
    performance_report, sharpe_ratio,       # evaluation
)
```

## Project Structure

```
deltafq/               # Core library
  core/                # Quant modules (data, factor, portfolio, risk, backtest, evaluation)
  trading/             # Execution layer (broker, paper, live)
  utils/               # Shared utilities
  examples/            # Usage examples & notebooks
tests/                 # Unit tests (91 passed, 1 skipped)
docs/                  # Documentation
```

## License

MIT
