nixtla-market-risk-analyzer

name	nixtla-market-risk-analyzer
description	Analyze market risk with VaR, volatility, and position sizing using forecast data. Use when assessing investment risk. Trigger with 'analyze market risk' or 'calculate VaR'.
version	1.0.0
author	Jeremy Longshore <[e-mail]>
license	MIT
allowed-tools	Read,Write,Bash(python:*),Glob,Grep

Market Risk Analyzer

Calculates key market risk metrics and recommends optimal position sizes using historical data analysis.

Overview

This skill analyzes market risk using historical price data to calculate Value at Risk (VaR), volatility metrics, maximum drawdown, Sharpe ratios, and optimal position sizing. Provides actionable insights for managing investment risk and optimizing portfolio allocation. Uses four specialized Python scripts for data preparation, risk analysis, position sizing, and report generation.

Prerequisites

Tools: Read, Write, Bash, Glob, Grep

Environment: Optional NIXTLA_TIMEGPT_API_KEY for volatility forecasting (not required for core analysis)

Packages:

pip install pandas numpy scipy matplotlib
# Optional for forecasting:
pip install nixtla

Input Data Format: CSV file with columns:

• Date column: ds, date, or timestamp
• Price column: y, price, or close

Instructions

Step 1: Prepare Price Data

Execute the data preparation script to load prices and calculate returns:

python {baseDir}/scripts/prepare_data.py prices.csv --method log --output returns.csv

Script: {baseDir}/scripts/prepare_data.py

• Loads price data from CSV
• Calculates log or simple returns
• Detects time series frequency
• Outputs: returns.csv

Step 2: Calculate Risk Metrics

Run comprehensive risk analysis on the price data:

python {baseDir}/scripts/risk_metrics.py prices.csv --output risk_metrics.json --risk-free-rate 0.05

Script: {baseDir}/scripts/risk_metrics.py

• Calculates VaR at 95% and 99% confidence levels
• Computes historical and rolling volatility
• Analyzes maximum drawdown and recovery periods
• Calculates Sharpe and Sortino ratios
• Outputs: risk_metrics.json

Key Metrics:

• VaR: Maximum expected loss at confidence level
• CVaR: Expected loss when VaR is exceeded
• Volatility: Daily and annualized, with regime classification
• Drawdown: Maximum loss from peak, recovery analysis
• Sharpe Ratio: Risk-adjusted return metric

Step 3: Calculate Position Sizing

Determine optimal position sizes using multiple methodologies:

python {baseDir}/scripts/position_sizing.py \
  --account-size 100000 \
  --risk-per-trade 0.02 \
  --stop-loss 0.05 \
  --target-volatility 0.15 \
  --asset-volatility 0.25 \
  --var-95 -0.02 \
  --max-var-loss 0.03 \
  --output position_sizing.json

Script: {baseDir}/scripts/position_sizing.py

• Fixed Fractional: Risk-based position sizing
• Volatility Adjusted: Targets specific portfolio volatility
• VaR-Based: Limits maximum VaR loss
• Kelly Criterion: Optimal bet sizing (full, half, quarter)
• Outputs: position_sizing.json with recommended conservative position

Step 4: Generate Risk Report

Create comprehensive markdown report with visualizations:

python {baseDir}/scripts/generate_report.py prices.csv \
  --risk-metrics risk_metrics.json \
  --position-sizing position_sizing.json \
  --output risk_report.md \
  --output-dir .

Script: {baseDir}/scripts/generate_report.py

• Generates markdown report with all metrics
• Creates three visualizations:
  • drawdown.png: Price history and drawdown chart
  • volatility.png: Rolling volatility over time
  • var.png: Return distribution with VaR levels
• Outputs: risk_report.md, PNG charts

Output

Generated Files:

• returns.csv: Calculated returns series
• risk_metrics.json: Complete risk metrics
• position_sizing.json: Position sizing recommendations
• risk_report.md: Comprehensive markdown report
• drawdown.png: Price and drawdown visualization
• volatility.png: Rolling volatility chart
• var.png: Return distribution with VaR markers

Key Report Sections:

1. Executive Summary (VaR, volatility, drawdown, Sharpe)
2. Value at Risk analysis (95%, 99% confidence)
3. Volatility metrics and regime classification
4. Drawdown analysis with recovery periods
5. Risk-adjusted returns (Sharpe, Sortino)
6. Position sizing recommendations with Kelly criterion
7. Visualizations and risk warnings

Error Handling

Error: No date column found Solution: Ensure CSV has column named ds, date, or timestamp

Error: No price column found Solution: Ensure CSV has column named y, price, or close

Error: Insufficient data for analysis Solution: Provide at least 30 price points for reliable statistical analysis

Error: Module not found: matplotlib Solution: Install visualization dependencies: pip install matplotlib

Error: NIXTLA_TIMEGPT_API_KEY not set Solution: Only needed for optional volatility forecasting. Core analysis works without it.

Examples

Example 1: Analyze Stock Risk

# Complete workflow for stock analysis
python {baseDir}/scripts/prepare_data.py AAPL_prices.csv
python {baseDir}/scripts/risk_metrics.py AAPL_prices.csv
python {baseDir}/scripts/position_sizing.py --account-size 100000 --asset-volatility 0.28
python {baseDir}/scripts/generate_report.py AAPL_prices.csv

# Expected output:
# VaR (95%): -2.15%
# Max Drawdown: -35.2%
# Sharpe Ratio: 0.95
# Recommended Position: $45,000 (45% of account)

Example 2: Prediction Market Contract Analysis

# High volatility asset with conservative sizing
python {baseDir}/scripts/risk_metrics.py contract_prices.csv --output contract_risk.json
python {baseDir}/scripts/position_sizing.py \
  --account-size 50000 \
  --risk-per-trade 0.01 \
  --asset-volatility 0.45 \
  --output contract_sizing.json

# Expected output:
# VaR (95%): -8.5%
# Volatility Regime: HIGH
# Recommended Position: $12,000 (24% of account)

Example 3: Custom Risk Parameters

# Conservative parameters for volatile market
python {baseDir}/scripts/position_sizing.py \
  --account-size 200000 \
  --risk-per-trade 0.01 \
  --stop-loss 0.03 \
  --target-volatility 0.10 \
  --max-var-loss 0.02

# Aggressive parameters for stable market
python {baseDir}/scripts/position_sizing.py \
  --account-size 200000 \
  --risk-per-trade 0.03 \
  --stop-loss 0.07 \
  --target-volatility 0.20 \
  --max-var-loss 0.05

Resources

Statistical Methods:

• VaR: Historical simulation, parametric (Gaussian), Monte Carlo
• Volatility: EWMA, GARCH models available in extension
• Drawdown: Peak-to-trough analysis with recovery tracking

Position Sizing Theory:

• Kelly Criterion: Optimal bet sizing for known edge
• Fixed Fractional: Fixed percentage risk per trade
• Volatility Targeting: Normalize risk across assets
• VaR-Based: Limit tail risk exposure

Best Practices:

• Use Half Kelly for practical trading (Full Kelly too aggressive)
• Combine multiple sizing methods, choose most conservative
• Adjust for liquidity constraints and execution costs
• Monitor regime changes (HIGH/NORMAL/LOW volatility)
• Rebalance positions when volatility regime shifts

References:

• VaR methodology: RiskMetrics Technical Document (J.P. Morgan)
• Kelly Criterion: Fortune's Formula (Poundstone)
• Sharpe Ratio: "The Sharpe Ratio" (Sharpe, 1994)
• Position Sizing: "Trade Your Way to Financial Freedom" (Tharp)