quantstats-js
Version:
Comprehensive portfolio analytics and professional tearsheet generation library for JavaScript/Node.js - create beautiful HTML reports with 14+ financial charts and 40+ metrics
976 lines (789 loc) • 37.8 kB
Markdown
# QuantStats JS 📊
[](https://badge.fury.io/js/quantstats)
[](https://opensource.org/licenses/Apache-2.0)
**Comprehensive portfolio analytics and professional tearsheet generation for JavaScript/Node.js**
Create stunning HTML reports with 13+ financial charts and 40+ metrics, bringing quantitative finance analysis to the JavaScript ecosystem.
## ✨ Features
- **🎯 Complete Python Compatibility**: 100% mathematically identical to Python QuantStats
- **📊 Professional HTML Reports**: Generate complete tearsheets with 13+ interactive charts
- **📈 Comprehensive Metrics**: Over 40 financial metrics and ratios
- **🎨 Interactive Visualizations**: Professional charts with responsive design
- **⚡ High Performance**: Optimized for speed with efficient algorithms
- **🛡️ Risk Analysis**: VaR, CVaR, drawdown analysis, and risk-adjusted returns
- **📋 Full Tearsheets**: Complete portfolio analysis reports matching Python QuantStats
- **🔢 Mathematical Precision**: All calculations validated against Python implementation
- **📱 Responsive Design**: Professional MUI-style reports that work on all devices
- **🚀 Zero Dependencies**: Core functionality uses only native JavaScript
## 🚀 Installation
```bash
npm install quantstats-js
```
## ⚡ Quick Start
```javascript
import * as qs from 'quantstats-js';
// Sample daily returns with dates
const returns = [0.01, -0.005, 0.02, -0.01, 0.015, -0.008, 0.025];
const dates = returns.map((_, i) => new Date(2023, 0, i + 1));
const returnsData = { values: returns, index: dates };
// Generate complete tearsheet (like Python QuantStats!)
const tearsheet = qs.reports.basic(returnsData, 'My Portfolio');
console.log('Professional tearsheet generated:', tearsheet.length, 'bytes');
// Get EVERYTHING - 50+ comprehensive metrics in one call!
const everything = qs.reports.calculateComprehensiveMetrics(returnsData, 0.02, 'full');
console.log('Period Returns:', everything['MTD %'], everything['YTD %']);
// Get core metrics quickly
const allMetrics = qs.reports.metrics(returns.values);
console.log('Sharpe:', allMetrics.sharpe, 'Max DD:', allMetrics.maxDrawdown);
// Or calculate individual metrics
const totalReturn = qs.stats.totalReturn(returns);
const sharpe = qs.stats.sharpe(returns);
const maxDrawdown = qs.stats.maxDrawdown(returns);
console.log(`Total Return: ${(totalReturn * 100).toFixed(2)}%`);
console.log(`Sharpe Ratio: ${sharpe.toFixed(2)}`);
console.log(`Max Drawdown: ${(maxDrawdown * 100).toFixed(2)}%`);
```
## 📊 Professional Tearsheet Generation
**NEW in v2.0.0**: Complete HTML tearsheet generation with professional charts!
```javascript
import * as qs from 'quantstats-js';
import fs from 'fs';
// Your portfolio returns with dates
const returns = {
values: [0.01, -0.005, 0.02, -0.01, 0.015, -0.008, 0.025, -0.012, 0.018],
index: [/* array of Date objects */]
};
// Generate complete tearsheet
const tearsheet = qs.reports.basic(returns, 'My Portfolio Strategy');
// Save professional HTML report
fs.writeFileSync('tearsheet.html', tearsheet);
```
## 🆚 Benchmark Comparison
**NEW in v2.1.0**: Compare your strategy against any benchmark!
```javascript
import * as qs from 'quantstats-js';
// Your strategy returns
const strategyReturns = {
values: [0.01, -0.005, 0.02, -0.01, 0.015],
index: [/* Date objects */]
};
// Benchmark returns (e.g., S&P 500)
const benchmarkReturns = {
values: [0.008, -0.003, 0.015, -0.008, 0.012],
index: [/* Date objects */]
};
// Generate tearsheet with benchmark comparison
const tearsheet = qs.reports.basic(
strategyReturns,
'My Strategy vs S&P 500',
0, // risk-free rate
false, // include NaNs
benchmarkReturns, // benchmark data
'S&P 500' // benchmark name
);
// Creates a 3-column table: Metric | S&P 500 | Strategy
// Shows "Benchmarked Against S&P 500" in header
```
### 🎨 What's Included in the Tearsheet
**📈 13+ Professional Charts:**
- **Cumulative Returns** - Portfolio growth over time
- **EOY Returns** - End-of-year performance bar chart
- **Monthly Distribution** - Histogram of monthly returns
- **Daily Returns** - Daily performance distribution
- **Rolling Sharpe** - 30-day rolling Sharpe ratio
- **Rolling Sortino** - 30-day rolling Sortino ratio
- **Rolling Volatility** - 30-day rolling volatility
- **Drawdowns** - Underwater plot showing drawdown periods
- **Monthly Returns Heatmap** - Calendar view of monthly performance
- **Volatility vs Returns** - Risk-return scatter plot
- **And more...**
**📊 40+ Comprehensive Metrics:**
- Performance: Total Return, CAGR, Sharpe, Sortino, Calmar
- Risk: Max Drawdown, Volatility, VaR, CVaR, Ulcer Index
- Trading: Win Rate, Profit Factor, Kelly Criterion, Recovery Factor
- Period Returns: MTD, 3M, 6M, YTD, 1Y, 3Y, 5Y, 10Y
- Best/Worst: Best/Worst Day/Month/Year performance
- And many more statistical measures
**🎨 Professional Design:**
- Clean, modern Material-UI inspired styling
- Responsive design that works on all devices
- Professional color scheme and typography
- Date-labeled time series charts
- Properly formatted percentage values
- Print-ready layout
## 📚 Core Modules
### 📊 Reports Module (NEW v2.0.0)
Complete tearsheet generation with professional visualizations:
```javascript
// Basic tearsheet (recommended)
const tearsheet = qs.reports.basic(returns, title, rfRate, nans);
// Just the metrics (no charts)
const metrics = qs.reports.metrics(returns, rfRate, nans);
// Generate comprehensive metrics object
const allMetrics = qs.reports.calculateComprehensiveMetrics(returns, rfRate, mode);
```
**Chart Functions Available:**
- `generateCumulativeReturnsChart()` - Equity curve
- `generateEOYReturnsChart()` - End-of-year returns
- `generateMonthlyDistChart()` - Monthly distribution histogram
- `generateDailyReturnsChart()` - Daily returns distribution
- `generateRollingSharpeChart()` - Rolling Sharpe ratio
- `generateRollingSortinoChart()` - Rolling Sortino ratio
- `generateRollingVolatilityChart()` - Rolling volatility
- `generateDrawdownsChart()` - Underwater plot
- `generateMonthlyHeatmapChart()` - Monthly returns heatmap
- `generateVolatilityReturnsChart()` - Risk vs return scatter
- `generateEOYTable()` - End-of-year returns table
#### 🚀 Get ALL Stats in One Call - The Ultimate Function
Want **EVERYTHING**? Use `reports.calculateComprehensiveMetrics()` - this is the powerhouse function that returns 50+ metrics:
```javascript
import * as qs from 'quantstats-js';
// Your returns data with dates (required for comprehensive analysis)
const returnsData = {
values: [0.01, -0.005, 0.02, -0.01, 0.015, -0.008, 0.025],
index: [/* array of Date objects */]
};
// Get EVERYTHING - 50+ metrics in one call!
const everything = qs.reports.calculateComprehensiveMetrics(returnsData, 0.02, 'full');
console.log(everything);
// Returns comprehensive object with ALL metrics:
// {
// 'Start Period': '2023-01-01',
// 'End Period': '2023-12-31',
// 'Risk-Free Rate %': '2.00%',
// 'Time in Market %': '100.00%',
// 'Cumulative Return %': '5.47%',
// 'CAGR%': '2.34%',
// 'Sharpe': '1.23',
// 'Prob. Sharpe Ratio %': '87.23%',
// 'Smart Sharpe': '1.23',
// 'Sortino': '1.45',
// 'Smart Sortino': '1.45',
// 'Volatility (ann.) %': '14.56%',
// 'Max Drawdown %': '-2.34%',
// 'Longest DD Days': 5,
// 'Calmar': '0.87',
// 'Skew': '0.23',
// 'Kurtosis': '2.45',
// 'Expected Daily %': '0.12%',
// 'Expected Monthly %': '2.45%',
// 'Expected Yearly %': '28.7%',
// 'Kelly Criterion %': '23.4%',
// 'Risk of Ruin %': '0.12%',
// 'Daily Value-at-Risk %': '-1.23%',
// 'Expected Shortfall (cVaR) %': '-1.56%',
// 'Gain/Loss Ratio': '1.45',
// 'Payoff Ratio': '1.23',
// 'Profit Factor': '1.67',
// 'Common Sense Ratio': '1.45',
// 'CPC Index': '1.08',
// 'Tail Ratio': '1.45',
// 'Outlier Win Ratio': '1.23',
// 'Outlier Loss Ratio': '1.23',
// 'Max Consecutive Wins': 3,
// 'Max Consecutive Losses': 2,
// 'MTD %': '1.23%',
// '3M %': '4.56%',
// '6M %': '7.89%',
// 'YTD %': '12.34%',
// '1Y (ann.) %': '12.34%',
// '3Y (ann.) %': '8.67%',
// '5Y (ann.) %': '9.12%',
// '10Y (ann.) %': '7.89%',
// 'All-time (ann.) %': '2.34%',
// 'Best Day %': '2.50%',
// 'Worst Day %': '-1.50%',
// 'Best Month %': '5.67%',
// 'Worst Month %': '-3.45%',
// 'Best Year %': '15.67%',
// 'Worst Year %': '-8.90%',
// 'Avg. Drawdown %': '-1.23%',
// 'Avg. Drawdown Days': 2,
// 'Recovery Factor': '2.34',
// 'Ulcer Index': '0.01',
// 'Serenity Index': '1.23',
// 'Avg. Up Month': '3.45%',
// 'Avg. Down Month': '-2.34%',
// 'Win Days %': '64.3%',
// 'Win Month %': '58.3%',
// 'Win Quarter %': '66.7%',
// 'Win Year %': '80.0%'
// // ... and more!
// }
```
**Parameters:**
- `returnsData` - Object with `{values: [...], index: [dates...]}`
- `rfRate` - Risk-free rate (default: 0.02 = 2%)
- `mode` - 'basic' or 'full' (full mode includes 20+ additional metrics)
**Benefits:**
- 🎯 **Most Comprehensive**: 50+ metrics including period returns, drawdown analysis, win rates
- 📊 **Professional Format**: Matches Python QuantStats exactly with % formatting
- 🔧 **Configurable Depth**: Basic vs Full mode for different analysis needs
- ⚡ **Single Call**: Everything you need for complete portfolio analysis
#### 📈 Quick Metrics Only
For just the core metrics without formatting, use `reports.metrics()`:
```javascript
// Get core metrics in simple object format (40+ metrics)
const coreMetrics = qs.reports.metrics(returns.values, 0.02, false);
```
#### 📉 Get Detailed Drawdown Analysis
Want comprehensive drawdown details for every single drawdown period? Use the utils module:
```javascript
import * as qs from 'quantstats-js';
// Your returns data with dates
const returnsData = {
values: [0.01, -0.005, 0.02, -0.01, 0.015, -0.008, 0.025, -0.012, 0.018],
index: [/* array of Date objects */]
};
// Get detailed analysis of EVERY drawdown period
const allDrawdowns = qs.utils.drawdownDetails(returnsData.values, returnsData.index);
console.log(allDrawdowns);
// Returns array with details of each drawdown period:
// [
// {
// 'start': Date('2023-01-02'), // When drawdown started
// 'valley': Date('2023-01-04'), // Lowest point
// 'end': Date('2023-01-06'), // When recovered
// 'days': 5, // Duration in days
// 'max drawdown': -0.0234, // Peak drawdown %
// '99% max drawdown': -0.0156 // 99% confidence level
// },
// {
// 'start': Date('2023-02-10'),
// 'valley': Date('2023-02-12'),
// 'end': Date('2023-02-15'),
// 'days': 6,
// 'max drawdown': -0.0189,
// '99% max drawdown': -0.0134
// }
// // ... every single drawdown period with full details
// ]
// Get the continuous drawdown series (daily drawdown values)
const ddSeries = qs.utils.toDrawdownSeries(returnsData.values);
console.log('Current drawdown:', ddSeries[ddSeries.length - 1]);
console.log('Max drawdown:', Math.min(...ddSeries));
// Quick drawdown stats from comprehensive metrics
const stats = qs.reports.calculateComprehensiveMetrics(returnsData, 0.02, 'full');
console.log('Longest DD Days:', stats['Longest DD Days']);
console.log('Avg DD Days:', stats['Avg. Drawdown Days']);
console.log('Recovery Factor:', stats['Recovery Factor']);
```
**Drawdown Analysis Features:**
- 📊 **Every Period**: Complete details for each individual drawdown
- 📅 **Full Timeline**: Start date, valley date, recovery date
- ⏱️ **Duration**: Days underwater for each period
- 📈 **Recovery Tracking**: When and how portfolio recovered
- 🎯 **Statistical Confidence**: 99% confidence intervals
### 📈 Stats Module
Financial metrics and risk calculations:
- `cagr()` - Compound Annual Growth Rate
- `sharpe()` - Sharpe Ratio
- `sortino()` - Sortino Ratio
- `calmar()` - Calmar Ratio
- `volatility()` - Annualized volatility
- `maxDrawdown()` - Maximum drawdown
- `valueAtRisk()` - Value at Risk
- `cvar()` - Conditional Value at Risk
- `beta()` - Beta coefficient
- `alpha()` - Alpha coefficient
- And many more...
### Utils Module
Data preparation and utility functions:
- `toReturns()` - Convert prices to returns
- `prepareReturns()` - Clean and prepare returns data
- `toDrawdownSeries()` - Calculate drawdown series
- `portfolioValue()` - Calculate portfolio value over time
- `aggregateReturns()` - Aggregate returns by period
- `resample()` - Resample returns to different frequencies
### Plots Module
Data generation for visualizations:
- `equityCurve()` - Equity curve data
- `drawdownPlot()` - Drawdown plot data
- `returnsDistribution()` - Returns histogram data
- `rollingStats()` - Rolling statistics data
- `monthlyHeatmap()` - Monthly returns heatmap data
- `dashboard()` - Complete dashboard data
### Reports Module
Comprehensive reporting functionality:
- `metrics()` - Generate all portfolio metrics
- `basic()` - Basic HTML report
- `full()` - Comprehensive HTML report
## 🎯 Usage Examples
### 📊 Generate Complete Tearsheet (NEW v2.0.0)
```javascript
import * as qs from 'quantstats-js';
import fs from 'fs';
// Your portfolio data (daily returns with dates)
const portfolioReturns = [
0.01, -0.005, 0.02, -0.01, 0.015, -0.008, 0.025, -0.012, 0.018, -0.003,
0.012, -0.015, 0.008, 0.022, -0.007, 0.013, -0.011, 0.016, -0.004, 0.009
];
// Create date index (required for time-series analysis)
const startDate = new Date('2023-01-01');
const dates = portfolioReturns.map((_, i) => {
const date = new Date(startDate);
date.setDate(date.getDate() + i);
return date;
});
// Format data for tearsheet generation
const returnsData = {
values: portfolioReturns,
index: dates
};
// Generate professional tearsheet
const tearsheet = qs.reports.basic(
returnsData,
'My Portfolio Strategy Analysis'
);
// Save as HTML file
fs.writeFileSync('portfolio_tearsheet.html', tearsheet);
console.log('✅ Professional tearsheet saved to portfolio_tearsheet.html');
// The tearsheet includes:
// - 13+ professional charts
// - 40+ comprehensive metrics
// - Publication-ready design
// - Responsive layout
// - Proper date labeling
// - Professional formatting
```
### 📈 Advanced Metrics Analysis
```javascript
// Get comprehensive metrics object
const metrics = qs.reports.calculateComprehensiveMetrics(returnsData);
console.log('📊 Performance Metrics:');
console.log(`Total Return: ${metrics['Cumulative Return %']}`);
console.log(`CAGR: ${metrics['CAGR%']}`);
console.log(`Sharpe Ratio: ${metrics['Sharpe']}`);
console.log(`Sortino Ratio: ${metrics['Sortino']}`);
console.log(`Max Drawdown: ${metrics['Max Drawdown %']}`);
console.log('🎯 Trading Metrics:');
console.log(`Win Rate: ${metrics['Win Rate %']}`);
console.log(`Profit Factor: ${metrics['Profit Factor']}`);
console.log(`Kelly Criterion: ${metrics['Kelly Criterion %']}`);
console.log('⚠️ Risk Metrics:');
console.log(`VaR (95%): ${metrics['Daily Value-at-Risk %']}`);
console.log(`CVaR (95%): ${metrics['Expected Shortfall (cVaR) %']}`);
console.log(`Volatility: ${metrics['Volatility (ann.) %']}`);
console.log('📅 Period Returns:');
console.log(`YTD: ${metrics['YTD %']}`);
console.log(`1Y: ${metrics['1Y (ann.) %']}`);
console.log(`3Y: ${metrics['3Y (ann.) %']}`);
```
### 🎨 Individual Chart Generation
```javascript
// Generate individual charts (returns SVG strings)
const cumulativeChart = qs.reports.generateCumulativeReturnsChart(
returnsData.values,
returnsData.index,
'Portfolio Growth'
);
const drawdownChart = qs.reports.generateDrawdownsChart(
returnsData.values,
returnsData.index,
'Drawdown Analysis'
);
const heatmapChart = qs.reports.generateMonthlyHeatmapChart(
returnsData.values,
returnsData.index,
'Monthly Returns'
);
// Charts are professional SVG graphics that can be:
// - Embedded in HTML
// - Saved as SVG files
// - Converted to PNG/PDF
// - Used in web applications
console.log('Charts generated:', {
cumulative: cumulativeChart.length,
drawdown: drawdownChart.length,
heatmap: heatmapChart.length
});
```
### 📊 Dashboard Data Generation
```javascript
// Generate data for custom dashboards
const plotData = qs.plots.dashboard(portfolioReturns);
// Use the data with your preferred charting library
console.log('Dashboard data:', {
equityCurve: plotData.equityCurve.data.length,
drawdown: plotData.drawdown.data.length,
monthlyHeatmap: plotData.monthlyHeatmap.data.length,
returnsDistribution: plotData.returnsDistribution.data.length
});
```
### Basic Portfolio Analysis
```javascript
import * as qs from 'quantstats-js';
// Convert prices to returns
const prices = [100, 102, 101, 105, 103, 108, 106, 112];
const returns = qs.utils.toReturns(prices);
// Calculate comprehensive metrics (simple array format)
const metrics = qs.reports.metrics(returns.values);
console.log('Portfolio Analysis:', {
totalReturn: `${(metrics.totalReturn * 100).toFixed(2)}%`,
cagr: `${(metrics.cagr * 100).toFixed(2)}%`,
sharpe: metrics.sharpe.toFixed(2),
maxDrawdown: `${(metrics.maxDrawdown * 100).toFixed(2)}%`,
winRate: `${(metrics.winRate * 100).toFixed(2)}%`
});
```
### Risk Analysis
```javascript
// Risk metrics
const var95 = qs.stats.valueAtRisk(returns, 0.05);
const cvar95 = qs.stats.cvar(returns, 0.05);
const skewness = qs.stats.skew(returns);
const kurtosis = qs.stats.kurtosis(returns);
console.log('Risk Analysis:', {
var95: `${(var95 * 100).toFixed(2)}%`,
cvar95: `${(cvar95 * 100).toFixed(2)}%`,
skewness: skewness.toFixed(2),
kurtosis: kurtosis.toFixed(2)
});
```
### Generate HTML Report
```javascript
// Create comprehensive HTML report
const htmlReport = qs.reports.basic(
returns,
'My Portfolio Analysis'
);
// Save to file (Node.js)
import fs from 'fs';
fs.writeFileSync('portfolio_report.html', htmlReport);
```
### Visualization Data
```javascript
// Generate data for charts
const plotData = qs.plots.dashboard(returns);
// Equity curve data
const equityCurve = plotData.equityCurve;
console.log('Equity curve data points:', equityCurve.data.length);
// Drawdown data
const drawdown = plotData.drawdown;
console.log('Max drawdown:', Math.min(...drawdown.data));
// Monthly returns heatmap
const heatmap = plotData.monthlyHeatmap;
console.log('Monthly data:', heatmap.data.length);
```
## 📊 Data Formats
### For Complete Tearsheets (Recommended)
```javascript
// Returns with dates (required for time-series analysis)
const returnsData = {
values: [0.01, -0.005, 0.02, -0.01, 0.015], // Daily returns array
index: [Date1, Date2, Date3, Date4, Date5] // Corresponding dates
};
// Generate professional tearsheet
const tearsheet = qs.reports.basic(returnsData, 'My Strategy');
```
### For Basic Calculations
```javascript
// Simple array format (for basic metrics only)
const returns = [0.01, -0.005, 0.02, -0.01, 0.015];
// Calculate basic metrics
const metrics = qs.reports.metrics(returns.values);
const sharpe = qs.stats.sharpe(returns);
```
### 📅 Date Handling
```javascript
// Create date array from start date
const createDateRange = (startDate, numDays) => {
return Array.from({length: numDays}, (_, i) => {
const date = new Date(startDate);
date.setDate(date.getDate() + i);
return date;
});
};
// Example usage
const dates = createDateRange(new Date('2023-01-01'), returns.length);
const returnsData = { values: returns, index: dates };
```
## 📈 Mathematical Accuracy
All calculations in QuantStats.js are mathematically identical to the Python QuantStats library:
- **Sharpe Ratio**: `(mean_return * √252) / (std_return * √252)`
- **Sortino Ratio**: `(mean_return * √252) / (downside_std * √252)`
- **CAGR**: `(ending_value / beginning_value) ^ (1/years) - 1`
- **Maximum Drawdown**: `min(cumulative_returns / running_max - 1)`
- **Value at Risk**: `percentile(returns, confidence_level)`
## Performance Optimizations
QuantStats.js is optimized for performance:
1. **Efficient Algorithms**: Uses optimized mathematical calculations
2. **Minimal Memory Usage**: Streaming calculations where possible
3. **Fast Array Operations**: Leverages JavaScript's native array methods
4. **Lazy Evaluation**: Calculations only performed when needed
5. **Caching**: Results cached for repeated calculations
## 📖 API Reference
### 📊 Reports Functions (NEW v2.0.0)
| Function | Description | Parameters |
|----------|-------------|------------|
| `basic(returnsData, title?)` | **Generate complete tearsheet** | returns with dates, optional title |
| `calculateComprehensiveMetrics(returnsData)` | **Calculate all 40+ metrics** | returns with dates object |
| `metrics(returns, rfRate?, nans?)` | Calculate basic metrics | returns array, risk-free rate, include NaNs |
### 🎨 Chart Generation Functions (NEW v2.0.0)
| Function | Description | Returns |
|----------|-------------|----------|
| `generateCumulativeReturnsChart(returns, dates, title?)` | Cumulative returns line chart | SVG string |
| `generateEOYReturnsChart(returns, dates, title?)` | End-of-year returns bar chart | SVG string |
| `generateMonthlyDistChart(returns, dates, title?)` | Monthly distribution histogram | SVG string |
| `generateDailyReturnsChart(returns, dates, title?)` | Daily returns distribution | SVG string |
| `generateRollingSharpeChart(returns, dates, title?)` | Rolling Sharpe ratio (30-day) | SVG string |
| `generateRollingSortinoChart(returns, dates, title?)` | Rolling Sortino ratio (30-day) | SVG string |
| `generateRollingVolatilityChart(returns, dates, title?)` | Rolling volatility (30-day) | SVG string |
| `generateDrawdownsChart(returns, dates, title?)` | Underwater drawdown plot | SVG string |
| `generateMonthlyHeatmapChart(returns, dates, title?)` | Monthly returns calendar heatmap | SVG string |
| `generateVolatilityReturnsChart(returns, dates, title?)` | Risk vs return scatter plot | SVG string |
| `generateEOYTable(returns)` | End-of-year returns data table | HTML string |
### 📈 Stats Functions
| Function | Description | Parameters |
|----------|-------------|------------|
| `cagr(returns, rfRate?, nans?, dates?)` | Compound Annual Growth Rate | returns, risk-free rate, include NaNs, dates |
| `sharpe(returns, rfRate?, nans?)` | Sharpe Ratio | returns, risk-free rate, include NaNs |
| `sortino(returns, rfRate?, nans?)` | Sortino Ratio | returns, risk-free rate, include NaNs |
| `volatility(returns, nans?)` | Annualized Volatility | returns, include NaNs |
| `maxDrawdown(returns, nans?)` | Maximum Drawdown | returns, include NaNs |
| `valueAtRisk(returns, confidence?, nans?)` | Value at Risk | returns, confidence level, include NaNs |
| `beta(returns, benchmark, nans?)` | Beta Coefficient | returns, benchmark, include NaNs |
| `alpha(returns, benchmark, rfRate?, nans?)` | Alpha Coefficient | returns, benchmark, risk-free rate, include NaNs |
| `omega(returns, rfRate?, requiredReturn?, periods?, nans?)` | Omega Ratio | returns, risk-free rate, required return, periods, include NaNs |
| `informationRatio(returns, benchmark, nans?)` | Information Ratio | returns, benchmark, include NaNs |
| `treynorRatio(returns, benchmark, rfRate?, nans?)` | Treynor Ratio | returns, benchmark, risk-free rate, include NaNs |
| `calmar(returns, rfRate?, nans?, dates?)` | Calmar Ratio | returns, risk-free rate, include NaNs, dates |
| `ulcerIndex(returns, nans?)` | Ulcer Index | returns, include NaNs |
| `smartSharpe(returns, rfRate?, periods?, nans?)` | Smart Sharpe (with autocorr penalty) | returns, risk-free rate, periods, include NaNs |
| `smartSortino(returns, rfRate?, periods?, nans?)` | Smart Sortino (with autocorr penalty) | returns, risk-free rate, periods, include NaNs |
| `kelly(returns, nans?)` | Kelly Criterion | returns, include NaNs |
| `skew(returns, nans?)` | Skewness | returns, include NaNs |
| `kurtosis(returns, nans?)` | Kurtosis | returns, include NaNs |
| `best(returns, nans?)` | Best Return | returns, include NaNs |
| `worst(returns, nans?)` | Worst Return | returns, include NaNs |
| `consecutiveWins(returns, nans?)` | Max Consecutive Wins | returns, include NaNs |
| `consecutiveLosses(returns, nans?)` | Max Consecutive Losses | returns, include NaNs |
| `exposure(returns, nans?)` | Market Exposure | returns, include NaNs |
| `winRate(returns, nans?)` | Win Rate | returns, include NaNs |
| `avgWin(returns, nans?)` | Average Win | returns, include NaNs |
| `avgLoss(returns, nans?)` | Average Loss | returns, include NaNs |
| `profitFactor(returns, nans?)` | Profit Factor | returns, include NaNs |
| `gainToPainRatio(returns, rfRate?, nans?)` | Gain to Pain Ratio | returns, risk-free rate, include NaNs |
| `riskOfRuin(returns, nans?)` | Risk of Ruin | returns, include NaNs |
| `outliers(returns, quantile?, nans?)` | Outliers | returns, quantile, include NaNs |
| `removeOutliers(returns, quantile?, nans?)` | Remove Outliers | returns, quantile, include NaNs |
### Utils Functions
| Function | Description | Parameters |
|----------|-------------|------------|
| `toReturns(prices, compound?)` | Convert prices to returns | prices array, compound returns |
| `prepareReturns(data, rfRate?, nans?)` | Prepare returns data | data, risk-free rate, include NaNs |
| `toDrawdownSeries(returns)` | Calculate drawdown series | returns array |
| `portfolioValue(returns, initial?)` | Calculate portfolio value | returns, initial value |
| `aggregateReturns(returns, period?)` | Aggregate by period | returns, period (monthly/yearly) |
| `toPrices(returns, base?)` | Convert returns to prices | returns, base price |
| `toLogReturns(returns, rfRate?)` | Convert to log returns | returns, risk-free rate |
| `toExcessReturns(returns, rfRate)` | Convert to excess returns | returns, risk-free rate |
| `rebase(prices, base?)` | Rebase prices to new base | prices, base value |
| `exponentialStdev(returns, window?, isHalflife?)` | Exponential standard deviation | returns, window, is halflife |
| `drawdownDetails(returns, dates?)` | Detailed drawdown periods | returns, dates (Python-compatible) |
| `resample(returns, frequency)` | Resample returns frequency | returns, frequency |
| `makePercentage(value, precision?)` | Format as percentage | value, decimal places |
| `makePosNeg(returns)` | Split positive/negative | returns array |
## Testing
Run the comprehensive test suite:
```bash
npm test
```
The test suite includes:
- Mathematical accuracy tests
- Edge case handling
- Performance benchmarks
- Integration tests
- Known value validation
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
Apache License 2.0 - see [LICENSE](LICENSE) file for details.
## 📝 Changelog
### v2.1.2 - Enhanced Tearsheet Layout & Design 🎨
**🎨 LAYOUT IMPROVEMENTS:**
**📐 Wider Tearsheet Design:**
- **80% Screen Width** - Increased container width from fixed 1200px to 80% of screen for better use of space
- **Better Grid Balance** - Updated layout from 2fr 1fr to 3fr 2fr (charts 60%, stats 40%) for better benchmark comparison viewing
- **Responsive Design** - Maintains professional look across different screen sizes
**📊 Enhanced EOY Returns Table:**
- **Benchmark Integration** - End of Year Returns table now includes benchmark comparison when provided
- **3-Column Layout** - Shows Year | Benchmark | Strategy for easy annual performance comparison
- **Automatic Detection** - Only shows benchmark column when benchmark data is provided
**🧹 Design Polish:**
- **Cleaner Headers** - Removed redundant "Benchmarked Against" subtitle since titles already include "vs Benchmark"
- **Professional Layout** - More space for metrics tables with multiple columns
- **Better Proportions** - Improved balance between charts and statistical analysis
**✅ Quality Assurance:**
- All 26 tests passing with 100% success rate
- Backward compatible - no API changes
- Professional appearance maintained
- Responsive design preserved
### v2.1.1 - Date Range Normalization for Benchmarks 📅
**🔧 CRITICAL FIX:**
**📅 Date Range Normalization:**
- **Automatic Date Alignment** - When comparing strategy vs benchmark, both series are automatically normalized to the same time period
- **Intersection Logic** - Uses the overlapping date range between strategy and benchmark data
- **All Charts Updated** - Ensures all visualizations use the normalized timeframe for accurate comparison
- **Console Logging** - Shows normalization details for transparency
**🎯 How It Works:**
```javascript
// If strategy has 100 days (2023-01-01 to 2023-04-10)
// And benchmark has 60 days (2023-01-20 to 2023-03-20)
// Both will be normalized to 60 days (2023-01-20 to 2023-03-20)
const report = qs.reports.basic(
strategyReturns, // 100 periods
'My Strategy',
0, false,
benchmarkReturns, // 60 periods (offset)
'S&P 500'
);
// Result: Both series use the same 60-day overlapping period
```
**✅ Quality Assurance:**
- All 26 tests passing with 100% success rate
- Backward compatible - no changes to existing API
- Automatic detection and normalization when benchmark provided
- Detailed logging shows original vs normalized date ranges
**🎯 Benefits:**
- Ensures fair comparison between strategy and benchmark
- Eliminates timeframe bias in performance analysis
- Maintains data integrity while maximizing comparable periods
- Professional-grade benchmark analysis
### v2.1.0 - Benchmark Comparison Feature 🆚
**🚀 NEW FEATURES:**
**🆚 Benchmark Comparison:**
- **Side-by-Side Metrics** - Compare your strategy against any benchmark (S&P 500, Bitcoin, etc.)
- **3-Column Table Layout** - Professional comparison: Metric | Benchmark | Strategy
- **Dynamic Headers** - Shows "Benchmarked Against [Benchmark Name]" in report title
- **Full Integration** - Works with both `basic()` and `html()` tearsheet functions
- **Backward Compatible** - All existing code continues to work unchanged
**🔧 Function Enhancements:**
- `qs.reports.basic(returns, title, rfRate, nans, benchmark, benchmarkTitle)` - Added optional benchmark parameters
- `qs.reports.html(returns, filename, title, rfRate, nans, benchmark, benchmarkTitle)` - Added optional benchmark parameters
- Enhanced `generateMetricsTable()` to handle 2-column or 3-column layouts automatically
**📊 Usage Examples:**
```javascript
// Without benchmark (works exactly as before)
const report = qs.reports.basic(returns, 'My Strategy');
// With benchmark comparison
const report = qs.reports.basic(
strategyReturns,
'My Strategy vs S&P 500',
0, false,
benchmarkReturns,
'S&P 500'
);
```
**✅ Quality Assurance:**
- All 26 tests passing with 100% success rate
- Zero breaking changes - fully backward compatible
- Professional presentation with clean table formatting
- Works with any benchmark data (stocks, crypto, bonds, etc.)
### v2.0.3 - Simplified API: Removed Benchmark Dependencies 🧹
**🔧 Breaking Changes:**
- **Simplified Function Signatures** - Removed benchmark parameters from all functions for cleaner API
- **Focused Portfolio Analysis** - Package now focuses purely on single portfolio analysis
- **Cleaner Codebase** - Removed unused benchmark calculation functions and complexity
**📦 What Changed:**
- `qs.reports.basic(returns, title, rfRate, nans)` - No longer accepts benchmark parameter
- `qs.reports.metrics(returns, rfRate, nans)` - No longer accepts benchmark parameter
- `qs.reports.calculateComprehensiveMetrics(returns, rfRate, mode)` - No longer accepts benchmark parameter
- Removed Rolling Beta chart and related benchmark comparison features
- Removed unused helper functions (`calculateCovariance`, `calculateVariance`, `calculateCorrelation`)
**✅ What Still Works:**
- All 26 tests passing with 100% success rate
- Complete tearsheet generation with 13+ professional charts
- 40+ comprehensive financial metrics and analysis
- Individual benchmark functions still available in `qs.stats` module for manual comparison
- All core portfolio analytics functionality preserved
**🎯 Benefits:**
- Simpler, cleaner API focused on portfolio analysis
- Smaller package size and reduced complexity
- Better performance without unused benchmark calculations
- Easier to use and understand for most use cases
### v2.0.2 - Bug Fix: Remove Non-existent Function Call 🐛
**🔧 Bug Fixes:**
- **Fixed trackingError Reference** - Removed call to `stats.trackingError()` which doesn't exist in the stats module
- **Improved Code Stability** - Eliminated undefined function call that could cause errors
- **Maintained Functionality** - All other benchmark metrics (beta, alpha, informationRatio) continue to work correctly
**✅ Quality Assurance:**
- All 26 tests passing with 100% success rate
- Clean codebase with no undefined function references
- Production-ready stability improvements
### v2.0.1 - Documentation & Discoverability Enhancements 📚
**🔧 Improvements:**
- **Enhanced Package Description** - More descriptive npm package summary highlighting key features
- **Expanded Keywords** - Added comprehensive keywords for better npm search discoverability
- **Professional Presentation** - Improved README introduction and feature descriptions
- **Search Optimization** - Better npm package metadata for community discovery
**📦 Package Quality:**
- All 26 tests passing with 100% coverage
- Zero dependencies for core functionality
- Production-ready codebase with comprehensive documentation
- Professional npm package presentation
### v2.0.0 - Major Release: Professional Tearsheet Generation 🎉
**🚀 MAJOR NEW FEATURES:**
**📊 Complete Tearsheet Generation:**
- **13+ Professional Charts** - Full visual analysis matching Python QuantStats
- **40+ Comprehensive Metrics** - Complete statistical analysis suite
- **Professional HTML Reports** - Publication-ready tearsheets with modern design
- **Responsive Design** - Works perfectly on desktop, tablet, and mobile
- **Date-Labeled Charts** - All time-series charts include proper date labeling
- **Percentage Formatting** - All percentage metrics properly formatted with % symbols
**🎨 Chart Library:**
- Cumulative Returns with date labels
- End-of-Year Returns bar chart with data table
- Monthly Distribution histogram
- Daily Returns distribution
- Rolling Sharpe (30-day) time series
- Rolling Sortino (30-day) time series
- Rolling Volatility (30-day) time series
- Drawdowns underwater plot
- Monthly Returns calendar heatmap
- Volatility vs Returns scatter plot
- Professional EOY returns table
**🔧 Technical Improvements:**
- Enhanced data format support (`{values: [], index: []}` structure)
- Professional Material-UI inspired styling
- Clean, production-ready codebase
- Comprehensive test suite (26 tests, 100% pass rate)
- Removed all debug and development files
**💥 Breaking Changes:**
- Reports module now expects data in `{values: [], index: []}` format for date-aware analysis
- Enhanced function signatures for better Python compatibility
### v1.3.0
🎉 **Complete Python Compatibility** - Now **100% structurally identical** to Python QuantStats!
- **Fixed Drawdown Details**: Now returns detailed period-by-period data like Python (not summary stats)
- **Added Missing Functions**: All Python functions now implemented (omega, informationRatio, greeks, etc.)
- **Enhanced Utility Functions**: Added toPrices, toLogReturns, toExcessReturns, rebase, exponentialStdev
- **Complete Function Parity**: Added outliers, removeOutliers, best, worst, consecutiveWins, consecutiveLosses, exposure, etc.
- **Data Structure Compatibility**: All return formats now match Python's DataFrame/Series structures exactly
- **Smart Ratios**: Added smartSharpe, smartSortino with autocorrelation penalty
**Breaking Changes**:
- `drawdownDetails()` now returns array of period objects instead of summary statistics
- All functions now have identical signatures and return formats as Python QuantStats
- Function names match Python exactly (camelCase to match JavaScript conventions)
### v1.2.0
🎉 **Major Accuracy Improvements** - Now **100% mathematically compatible** with Python QuantStats!
- **Fixed CAGR Calculation**: Now uses calendar days method (like Python) instead of trading days
- **Enhanced Max Drawdown**: Uses expanding maximum method matching Python's implementation exactly
- **Improved Time Handling**: Added optional dates parameter for precise time period calculations
- **Mathematical Precision**: All statistical functions now use sample standard deviation (ddof=1) like Python
- **Formula Alignment**: All calculations now match Python QuantStats formulas exactly
**Breaking Changes**:
- CAGR calculations may differ slightly from v1.1.0 due to improved accuracy
- Max drawdown calculations now use price-based method (more accurate)
- For exact backward compatibility, use trading days method: `cagr(returns)` (no dates)
## Support
- 📚 [Documentation](https://github.com/whsmacon/quantstats-js/wiki)
- 🐛 [Issue Tracker](https://github.com/whsmacon/quantstats-js/issues)
- 💬 [Discussions](https://github.com/whsmacon/quantstats-js/discussions)
## Related Projects
- [QuantStats (Python)](https://github.com/ranaroussi/quantstats) - Original Python library
- [Portfolio Analytics](https://github.com/topics/portfolio-analytics) - Related projects
---
**QuantStats.js** - Bringing professional portfolio analytics to the Node.js ecosystem with mathematical precision and high performance.