nanuquant 0.1.0

Institutional quantitative analytics at Polars speed.

NanuQuant

Institutional quantitative analytics at Polars speed.

---

DISCLAIMER: NanuQuant is for educational and research purposes only. Nothing in this library constitutes financial advice. Past performance does not guarantee future results. See DISCLAIMER.md for full legal notices.

---

About the Name

In Inuktitut, the language of the Inuit people, "nanuq" means polar bear. Since NanuQuant is built entirely on Polars for maximum speed and efficiency, we chose this name to honor the Inuit people while celebrating our foundation on the Polars ecosystem.

---

Overview

NanuQuant is a high-performance, native Polars library for quantitative finance. It replaces legacy Pandas-based tools with a vectorized engine capable of handling tick-level data and large-scale backtests without memory overhead.

It goes beyond standard metrics to provide institutional-grade robustness testing, volatility modeling, and execution analysis.

Why NanuQuant?

• Zero Pandas Dependency: Built purely on Polars for maximum speed and stability in production containers
• Institutional Rigor: Includes advanced metrics like Cornish-Fisher VaR, Ledoit-Wolf Shrinkage, and Deflated Sharpe Ratios
• Production Ready: Fully typed, rigorously tested against industry standards (QuantStats), and designed for high-frequency workflows
• Educational Focus: Comprehensive documentation explaining the mathematics behind every metric

---

Documentation

Document	Description
Installation Guide	Setup and configuration
Quick Start	Get started in minutes
Core API Reference	Returns, risk, performance metrics
Advanced API Reference	Trading system metrics
Institutional API Reference	PSR, DSR, GARCH, VaR extensions
Mathematical Foundations	Formulas and theory
Testing Methodology	How NanuQuant is validated
Use Cases	Practical examples with caveats
Full Disclaimer	Important legal notices

---

Installation

pip install nanuquant

For additional features:

# With HTML report generation
pip install nanuquant[reports]

# For development/testing
pip install nanuquant[dev]

# Everything
pip install nanuquant[all]

---

Quick Start

import polars as pl
import nanuquant as nq

# Load or create return data
returns = pl.Series("returns", [0.01, -0.02, 0.03, 0.01, -0.01, 0.02])

# Calculate core metrics
sharpe = nq.sharpe(returns, risk_free_rate=0.04)
sortino = nq.sortino(returns)
max_dd = nq.max_drawdown(returns)

print(f"Sharpe: {sharpe:.2f}")
print(f"Sortino: {sortino:.2f}")
print(f"Max Drawdown: {max_dd:.2%}")

Note: These metrics are for educational analysis only. See Use Cases for proper interpretation.

---

Features at a Glance

Core Metrics (60+)

Category	Metrics
Returns	CAGR, total return, avg win/loss, win rate, profit factor, payoff ratio
Risk	Volatility, VaR, CVaR, max drawdown, Ulcer Index, downside deviation
Performance	Sharpe, Sortino, Calmar, Omega, Information Ratio, Treynor, Alpha/Beta
Distribution	Skewness, kurtosis, Jarque-Bera test, outlier detection
Rolling	Rolling Sharpe, rolling volatility, rolling beta

Advanced Trading Metrics

• System Quality Number (SQN) - Trading system quality assessment
• Expectancy - Expected value per trade
• K-Ratio - Equity curve consistency
• Smart Sharpe/Sortino - Autocorrelation-adjusted ratios
• Risk of Ruin - Account depletion probability

Institutional-Grade Analytics

• Probabilistic Sharpe Ratio (PSR) - Statistical significance of Sharpe
• Deflated Sharpe Ratio (DSR) - Multiple testing adjustment
• GARCH Volatility - Conditional volatility modeling
• Cornish-Fisher VaR - Skewness/kurtosis-adjusted VaR
• Ledoit-Wolf Covariance - Shrinkage estimator for portfolios
• Absorption Ratio - Systemic risk measurement

---

Institutional Analysis Examples

Robustness Testing

Don't be fooled by random luck. Validate your strategies with statistical rigor:

from nanuquant import institutional

# Did you test 100 variations of your strategy? Adjust for selection bias.
dsr = institutional.deflated_sharpe_ratio(returns, n_trials=100)
print(f"Deflated Sharpe Probability: {dsr:.4f}")

# Check if Sharpe is statistically significant
psr = institutional.probabilistic_sharpe_ratio(returns, benchmark_sr=0.0)
print(f"Probability SR > 0: {psr.psr:.2%}")

Warning: Even statistically significant backtests can fail in live trading due to regime changes and overfitting.

Volatility Modeling

Detect volatility clustering and regime changes:

from nanuquant import institutional

# Test for ARCH effects (volatility clustering)
arch_test = institutional.arch_effect_test(returns)
if arch_test.has_arch_effects:
    print("Volatility Clustering Detected")

    # Fit GARCH model
    garch = institutional.garch_volatility(returns)
    print(f"Persistence: {garch.persistence:.4f}")
    print(f"Current Vol Forecast: {garch.forecast:.2%}")

---

DataFrame Namespace

Import nanuquant to register the .metrics namespace on Polars expressions:

import polars as pl
import nanuquant as nq  # Registers the .metrics accessor

df = pl.DataFrame({
    "returns": [0.01, -0.02, 0.015, -0.01, 0.02] * 50
})

# Single metric
result = df.select(pl.col("returns").metrics.sharpe())

# Multiple metrics in one pass
metrics_df = df.select([
    pl.col("returns").metrics.sharpe().alias("sharpe"),
    pl.col("returns").metrics.sortino().alias("sortino"),
    pl.col("returns").metrics.max_drawdown().alias("max_dd"),
])

# Rolling metrics
df_rolling = df.with_columns([
    pl.col("returns").metrics.rolling_volatility().alias("rolling_vol"),
    pl.col("returns").metrics.rolling_sharpe().alias("rolling_sharpe"),
])

---

Null Handling

NanuQuant follows QuantStats/pandas conventions by dropping null values before calculations:

# Nulls are dropped automatically
returns_with_nulls = pl.Series([0.01, None, -0.02, None, 0.015])
sharpe = nq.sharpe(returns_with_nulls)  # Calculates using [0.01, -0.02, 0.015]

---

Available Metrics

Returns (12)

comp, cagr, avg_return, avg_win, avg_loss, best, worst, win_rate, payoff_ratio, profit_factor, consecutive_wins, consecutive_losses

Risk (7)

volatility, var, cvar, max_drawdown, to_drawdown_series, ulcer_index, downside_deviation

Performance (16)

sharpe, sortino, calmar, omega, gain_to_pain_ratio, ulcer_performance_index, kelly_criterion, tail_ratio, common_sense_ratio, risk_return_ratio, recovery_factor, greeks, information_ratio, r_squared, treynor_ratio, benchmark_correlation

Distribution (12)

skewness, kurtosis, jarque_bera, shapiro_wilk, outlier_win_ratio, outlier_loss_ratio, expected_return, geometric_mean, outliers, outliers_iqr, remove_outliers, remove_outliers_iqr

Rolling (5)

rolling_volatility, rolling_sharpe, rolling_sortino, rolling_beta, rolling_greeks

Trading (12)

exposure, ghpr, rar, cpc_index, serenity_index, risk_of_ruin, adjusted_sortino, smart_sharpe, smart_sortino, sqn, expectancy, k_ratio

Institutional (15+)

probabilistic_sharpe_ratio, deflated_sharpe_ratio, minimum_track_record_length, arch_effect_test, garch_volatility, cornish_fisher_var, modified_var, entropic_var, marginal_contribution_to_risk, ledoit_wolf_covariance, absorption_ratio, lower_tail_dependence, implementation_shortfall, market_impact_estimate

---

Known Differences from QuantStats

NanuQuant intentionally differs from QuantStats in some areas for improved consistency:

Aspect	NanuQuant	Rationale
CAGR/Calmar	Periods-based calculation	Works with any time series, not just datetime-indexed
Treynor Ratio	CAGR / Beta	Standard academic definition
Omega Ratio	Correct implementation	Fixes bug in some QuantStats versions
CPC Index	PF x WR x PR	Standard trading literature formula
Smart Sharpe	Lo (2002) adjustment	Established academic reference

See Mathematics for detailed formula explanations.

---

Testing and Validation

NanuQuant is rigorously tested:

• Differential tests against QuantStats for consistency
• Real market data fixtures (SPY, QQQ, BND)
• Edge case coverage (empty data, nulls, all positive/negative)
• Statistical tests validation
• Type checking with strict mypy

# Run all tests
pytest

# Run differential tests
pytest tests/test_vs_quantstats.py -v

# Run integration tests with real market data
pytest -m integration

# Type checking
mypy nanuquant

See Testing Methodology for details.

---

Development

# Clone and install
git clone https://github.com/launchstack-dev/nanuquant.git
cd nanuquant
pip install -e ".[dev]"

# Run tests
pytest

# Type check
mypy nanuquant

---

Important Notices

Not Financial Advice

NanuQuant is designed for:

• Educational purposes - Learning about quantitative finance
• Research - Academic and professional analysis
• Strategy development - Initial screening of trading ideas

NanuQuant is NOT designed for:

• Automated trading without human oversight
• Sole basis for investment decisions
• Regulatory compliance calculations

Limitations

• Past performance does not predict future results
• Backtests suffer from survivorship bias, look-ahead bias, and overfitting
• Statistical models assume conditions that may not hold in real markets
• Transaction costs and market impact are not automatically included

Always consult a qualified financial professional before making investment decisions.

---

License

MIT License. See LICENSE for details.

---

Links

• GitHub Repository
• PyPI Package
• Issue Tracker
• Changelog