https://github.com/kamaleddin/cryptoinvestor
Statistical analysis toolkit comparing Bitcoin DCA strategies. 378 simulations with risk metrics. Proves Simple DCA outperforms (p=0.008).
https://github.com/kamaleddin/cryptoinvestor
bitcoin cryptocurrency dca dollar-cost-averaging investment-analysis portfolio-optimization statistical-analysis
Last synced: 2 months ago
JSON representation
Statistical analysis toolkit comparing Bitcoin DCA strategies. 378 simulations with risk metrics. Proves Simple DCA outperforms (p=0.008).
- Host: GitHub
- URL: https://github.com/kamaleddin/cryptoinvestor
- Owner: kamaleddin
- Created: 2025-09-20T14:21:44.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-02T02:38:23.000Z (9 months ago)
- Last Synced: 2025-10-02T04:21:59.279Z (9 months ago)
- Topics: bitcoin, cryptocurrency, dca, dollar-cost-averaging, investment-analysis, portfolio-optimization, statistical-analysis
- Language: Python
- Homepage:
- Size: 2.24 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CryptoInvestor - DCA Strategy Analysis Suite v2.5
A comprehensive cryptocurrency investment analysis toolkit implementing and comparing multiple Dollar Cost Averaging (DCA) strategies with **statistically rigorous** performance evaluation.
> **v2.5 Update**: PERFECT Excel matching achieved! Fixed sell signal logic, implemented negative cash reserves (margin/borrowing), and corrected net investment calculation. Now achieves exact 463.2% return with 2.268 BTC on test case (100% accuracy). Added configurable `allow_negative_cash` parameter for flexible capital management.
---
## Key Features
### **Five Analysis Approaches**
- **Duration Simulator**: 1,512 simulations for pattern exploration
- **Balanced Rolling** : Recommended for standard analysis with risk metrics
- **Advanced Non-Overlapping**: Academic-grade statistical rigor
- **Enhanced Statistical Analyzer** : Block bootstrap, fat-tailed distributions, regime detection
- **Paired Strategy Comparison** : Maximum statistical power through paired testing
### **Optimum DCA Strategy Features (v2.5)**
- **100% Excel Accuracy**: Exact match - 463.2% return, 2.268 BTC, $46,771 net investment
- **Negative Cash Reserves**: Configurable margin/borrowing capability (matches Excel behavior)
- **Fixed Sell Logic**: Correctly triggers sells when investment_multiple < 1
- **Correct Net Investment**: Calculated as Initial Capital - Final Cash Reserve
- **Cash Reserve System**: Dynamic reserves based on 2×σ (return volatility)
- **Portfolio Tracking**: Complete tracking of BTC balance, cash reserves, and net investment
- **Flexible Configuration**: `allow_negative_cash` parameter controls capital management mode
- **Flexible Date Ranges**: Test any period from 2014 onwards
### **Comprehensive Metrics**
- Raw returns (mean, median, volatility)
- Risk-adjusted performance (Sharpe, Sortino, Calmar, Omega ratios)
- Tail risk analysis (VaR, CVaR, maximum drawdown, Ulcer Index)
- Statistical significance testing (paired t-tests, Wilcoxon, effect sizes)
- Block bootstrap confidence intervals for time series
- Autocorrelation and stationarity testing
- Volatility regime detection
- Fat-tailed distribution fitting (t-distribution)
- **NEW**: Net investment tracking (can go negative with profitable sells)
- **NEW**: Cash reserve balance throughout simulation
- **NEW**: Complete portfolio value (BTC + cash)
### **Production Ready**
- Standalone implementation (no Excel dependency)
- **Fully tested (95 comprehensive tests, 100% pass rate)**
- Professional documentation and methodology papers
- Clean project structure following Python best practices
- Advanced statistical methods validated by comprehensive test suites
- **BTC balance protection** preventing impossible negative holdings
- **Reserve-based investing** matching Excel capital management
---
## Quick Start
### Installation
```bash
# Clone repository
git clone
cd CryptoInvestor
# Install dependencies
pip install -r requirements/base.txt
# Optional: Install development dependencies
pip install -r requirements/dev.txt
```
### Run Analysis (Choose One)
```bash
# RECOMMENDED: Paired testing for maximum statistical power
python tools/paired_strategy_comparison.py
# Enhanced statistical analysis with advanced methods
python tools/enhanced_statistical_analyzer.py
# Balanced approach with risk metrics
python tools/balanced_rolling_analyzer.py
# Exploration: Maximum historical data
python tools/duration_simulator.py
# Academic rigor: Perfect statistical independence
python tools/advanced_duration_analyzer.py
# Compare all methods
python tools/comprehensive_comparison.py
```
### View Results
```bash
# Main comparison report
cat reports/comparisons/COMPREHENSIVE_COMPARISON_REPORT.txt
# Tool selection guide
cat docs/guides/ANALYSIS_TOOL_GUIDE.md
# Statistical methodology
cat docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md
```
---
## What's New in v2.5
### Perfect Excel Matching Achieved!
**Critical Bug Fixes**
- **Sell Logic Fixed**: Changed condition from `investment_multiple < 0` to `investment_multiple < 1`
- Now correctly triggers sells when investment_multiple is between 0 and 1
- Matches Excel's sell signal behavior exactly
- **Negative Cash Reserves**: Implemented margin/borrowing capability
- Excel allows cash reserves to go negative (as low as -$6,328 in test case)
- Enables full investment deployment even when reserve is exhausted
- Configurable via `allow_negative_cash` parameter (default: True)
- **Net Investment Calculation**: Fixed to match Excel's formula
- Changed from `sum of transactions` to `Initial Capital - Final Cash Reserve`
- Correctly represents total capital deployed
- Now matches Excel exactly: $46,771.40
**Perfect Test Case Results**
- **Return**: 463.2% (exact match ✅)
- **BTC Accumulated**: 2.26791587 (exact match ✅)
- **Net Investment**: $46,771.40 (exact match ✅)
- **Final Cash Reserve**: $5,228.60 (exact match ✅)
- **Portfolio Value**: $268,663.16
**New Configuration Options**
```python
analyzer = FlexibleOptimumDCA(
weekly_budget=250.0,
allow_negative_cash=True, # Enable margin/borrowing (default)
verbose=True
)
```
- `allow_negative_cash=True`: Matches Excel behavior (allows margin trading)
- `allow_negative_cash=False`: Conservative mode (limits to available cash)
---
## Key Findings
### **Revolutionary Finding: Simple DCA Significantly Outperforms**
Using enhanced statistical methods (paired testing, block bootstrap, fat-tailed distributions), we discovered that **Simple DCA significantly outperforms Optimum DCA** across all investment horizons. This is a complete reversal from the Excel test case results.
### **Performance Summary** (Paired Testing v2.2 - NEW)
| Duration | Optimum Avg | Simple Avg | Difference | Information Ratio | P-Value | Winner |
|----------|-------------|------------|------------|-------------------|---------|---------|
| **1-Year** | 1,184% | 2,441% | -1,257pp | -0.165 | 0.081 | **Simple** |
| **2-Year** | 632% | 1,847% | -1,214pp | -0.377 | 0.0003 | **Simple** |
| **3-Year** | 604% | 1,632% | -1,027pp | -0.368 | 0.0009 | **Simple** |
| **4-Year** | 376% | 1,526% | -1,150pp | -0.477 | 0.0001 | **Simple** |
= Statistically significant | = Not statistically significant | pp = percentage points
** Breakthrough**: Simple DCA **massively outperforms** by 1,000-1,200 percentage points with statistical significance!
### **Risk Analysis**
**Optimum DCA Characteristics:**
- Better downside protection (lower VaR: -27.7% vs -40.3% at 1-year)
- Superior Sortino ratios (downside-risk-adjusted returns)
- Lower maximum drawdowns in most periods
- Extremely high volatility (362% vs 118% at 1-year)
- Low win rates (18-39% vs Simple's 77-100%)
**Simple DCA Characteristics:**
- Superior Sharpe ratios (0.421-0.586 vs Optimum's 0.140-0.195)
- More consistent returns (lower standard deviation)
- Higher win rates (77-100% success rate)
- Much lower volatility
- Higher tail risk in extreme downturns
### **Practical Recommendations**
**Choose Simple DCA if you:**
- Want predictable, consistent returns
- Prefer lower volatility (risk-averse)
- Have 2-4 year investment horizon
- Value simplicity in execution
- Need reliable performance metrics
**Consider Optimum DCA if you:**
- Can tolerate extreme volatility (362%+ annual)
- Want tail risk protection
- Seek potential for extreme upside (lottery-ticket returns)
- Have very short horizons during confirmed bull markets
- Can actively monitor and adjust positions
### **Enhanced Statistical Analysis (v2.2)**
Our new statistical tools revealed critical insights:
**Market Characteristics:**
- **Fat-tailed distributions**: Bitcoin has df=1.56 (extreme tail risk)
- **3 volatility regimes**: High (33%), Medium (34%), Low (33%)
- **Non-stationary prices**: Random walk behavior
- **98% autocorrelation**: Weekly data has extreme overlap
**Statistical Improvements:**
1. **Paired Testing**: 2-3x more statistical power
2. **Block Bootstrap**: Preserves time series structure
3. **Multiple Comparison Correction**: Controls Type I errors
4. **Fat-tailed Monte Carlo**: Uses t-distribution not normal
**Key Discovery**: The Excel test case (2022-2025) was an anomaly. Full historical analysis shows Simple DCA dominates.
### **Final Verdict**
**Simple DCA is the clear winner** for virtually all investors:
- **Massively outperforms** by 1,000-1,200pp across all horizons
- **Statistically significant** advantage (p < 0.001 for 2-4 year periods)
- **Negative Information Ratio** for Optimum DCA (-0.165 to -0.477)
- Much simpler to implement and maintain
- Lower volatility and more predictable outcomes
The added complexity of Optimum DCA (VWAP bands, volatility adjustments, dynamic multipliers) **actually hurts performance** when tested on full historical data with proper statistical methods.
---
## Project Structure
```
CryptoInvestor/
├── src/ # Core implementation
│ └── optimum_dca_analyzer.py
├── tools/ # Analysis tools
│ ├── balanced_rolling_analyzer.py (recommended)
│ ├── duration_simulator.py
│ ├── advanced_duration_analyzer.py
│ └── comprehensive_comparison.py
├── reports/ # Generated outputs
│ ├── simulations/
│ ├── comparisons/
│ └── analysis/
├── docs/ # Documentation
│ ├── guides/
│ └── methodology/
├── tests/ # Test suite (90 tests, 100% pass)
├── data/ # Bitcoin price data
└── examples/ # Usage examples
```
**See**: [PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) for complete details.
---
## Analysis Tools Comparison
| Tool | Simulations | Statistical Power | Special Features | Best For |
|------|-------------|------------------|------------------|----------|
| **Paired Comparison** | 75-114 | **Highest** | Paired tests, correlation | **Investment decisions** |
| **Enhanced Statistical** | Varies | High | Block bootstrap, fat tails | **Risk analysis** |
| **Balanced Rolling** | 378 | Moderate | Risk metrics | Standard analysis |
| **Duration Simulator** | 1,512 | Low | Maximum data | Pattern exploration |
| **Non-Overlapping** | 18 | Low | Perfect independence | Academic rigor |
**v2.2 Revolution**: Paired testing provides 2-3x more statistical power and reveals Simple DCA's dominance.
### Which Tool Should I Use?
```
Making investment decisions? (RECOMMENDED)
→ paired_strategy_comparison.py
Analyzing risk and market regimes?
→ enhanced_statistical_analyzer.py
Standard investment analysis?
→ balanced_rolling_analyzer.py
Exploring historical patterns?
→ duration_simulator.py
Publishing research paper?
→ advanced_duration_analyzer.py
Want comprehensive comparison?
→ comprehensive_comparison.py
```
**See**: [docs/guides/ANALYSIS_TOOL_GUIDE.md](docs/guides/ANALYSIS_TOOL_GUIDE.md)
---
## Example Usage
### Quick Analysis
```python
from src.optimum_dca_analyzer import FlexibleOptimumDCA
from datetime import date
# Create analyzer
analyzer = FlexibleOptimumDCA(
weekly_budget=250.0,
start_date=date(2022, 1, 10),
end_date=date(2025, 9, 22)
)
# Run both strategies
optimum = analyzer.run_optimum_dca_simulation()
simple = analyzer.run_simple_dca_simulation()
print(f"Optimum DCA: {optimum['profit_pct']:.1f}% return")
print(f"Simple DCA: {simple['profit_pct']:.1f}% return")
```
### Custom Period Analysis
```python
from tools.balanced_rolling_analyzer import AdvancedDurationAnalyzer
from datetime import date
# Analyze custom period
analyzer = AdvancedDurationAnalyzer(
weekly_budget=500.0, # Custom budget
overall_start=date(2020, 1, 1),
overall_end=date(2024, 12, 31),
risk_free_rate=0.04 # 4% risk-free rate
)
results = analyzer.run_comprehensive_analysis(
use_non_overlapping=False,
rolling_step_weeks=13 # Quarterly
)
analyzer.print_analysis_report(results)
```
---
## Testing
```bash
# Run all tests
python scripts/run_tests.py
# Run with coverage report
python scripts/run_tests.py --coverage
# Run specific test categories
python scripts/run_tests.py --validation # Core validation tests
python scripts/run_tests.py --unit # Unit tests
python scripts/run_tests.py --performance # Performance tests
```
**Test Coverage**:
- 90 total tests, 100% pass rate
- Core DCA validation tests
- All analyzer tools fully tested
- Statistical methods validated
- Integration and performance tests
---
## Documentation
| Document | Description |
|----------|-------------|
| [PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) | Complete project organization |
| [QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) | Quick commands and tips |
| [ANALYSIS_TOOL_GUIDE.md](docs/guides/ANALYSIS_TOOL_GUIDE.md) | Which tool to use when |
| [REPORTS_GUIDE.md](docs/guides/REPORTS_GUIDE.md) | Understanding report outputs |
| [STATISTICAL_METHODOLOGY_COMPARISON.md](docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md) | Statistical methods explained |
| [DURATION_SIMULATION_README.md](docs/guides/DURATION_SIMULATION_README.md) | Simulation results |
| [TEST_SUMMARY.md](docs/TEST_SUMMARY.md) | Test documentation |
---
## Recommended Workflow
### For Investment Analysis
```bash
# 1. Run balanced analysis (recommended)
python tools/balanced_rolling_analyzer.py > reports/analysis/my_analysis.txt
# 2. Review results
cat reports/analysis/my_analysis.txt
# 3. Understand the statistics
cat docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md
```
### For Research
```bash
# 1. Explore patterns
python tools/duration_simulator.py
# 2. Rigorous analysis
python tools/balanced_rolling_analyzer.py
# 3. Validate findings
python tools/advanced_duration_analyzer.py
# 4. Compare all methods
python tools/comprehensive_comparison.py
```
---
## Performance Metrics Explained
### Raw Returns
- **Mean Return**: Average return across all periods
- **Median Return**: Middle value (less affected by outliers)
- **Volatility (σ)**: Standard deviation of returns
### Risk-Adjusted Returns
- **Sharpe Ratio**: Return per unit of total risk (higher is better)
- **Sortino Ratio**: Return per unit of downside risk (higher is better)
- **Calmar Ratio**: Return per unit of maximum drawdown
### Risk Metrics
- **Max Drawdown**: Worst peak-to-trough decline
- **VaR (95%)**: Maximum expected loss at 95% confidence
- **CVaR (95%)**: Average loss in worst 5% of cases
### Statistical Tests
- **P-Value**: Probability of false positive (< 0.05 is significant)
- **Effect Size (Cohen's d)**: Magnitude of difference (0.2=small, 0.5=medium, 0.8=large)
- **Confidence Interval**: Range of likely true values
---
## Configuration
### Custom Budget and Dates
```python
analyzer = FlexibleOptimumDCA(
weekly_budget=500.0, # Your budget
start_date=date(2020, 1, 1), # Custom start
end_date=date(2024, 12, 31), # Custom end
final_btc_price=100000.0, # Custom BTC price for valuation
verbose=True # Show details
)
```
### Analysis Parameters
```python
analyzer = AdvancedDurationAnalyzer(
weekly_budget=250.0,
overall_start=date(2016, 1, 1),
overall_end=date(2025, 9, 24),
risk_free_rate=0.04, # 4% annual risk-free rate
verbose=True
)
# Quarterly rolling (recommended)
results = analyzer.run_comprehensive_analysis(
use_non_overlapping=False,
rolling_step_weeks=13
)
# Or non-overlapping (maximum rigor)
results = analyzer.run_comprehensive_analysis(
use_non_overlapping=True
)
```
---
## Dependencies
### Core Requirements
```
pandas >= 1.5.0
numpy >= 1.21.0
scipy >= 1.9.0
```
### Optional (Testing)
```
pytest >= 7.0.0
pytest-cov >= 3.0.0
```
Install all:
```bash
pip install -r requirements/base.txt # Core only
pip install -r requirements/dev.txt # Everything
```
---
## Citing This Work
If you use this analysis in research, please cite:
```
CryptoInvestor DCA Analysis Suite v2.2
Statistical Analysis of Dollar Cost Averaging Strategies for Bitcoin
October 2025
```
And reference the methodology paper:
- [STATISTICAL_METHODOLOGY_COMPARISON.md](docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md)
---
## What's New in v2.3
### Complete Test Suite Overhaul
- **100% test pass rate** (90/90 tests passing)
- **Comprehensive test coverage** for all analyzer tools
- **Fixed all test failures** from 65% to 100% pass rate
- **Production-ready** with full validation
### Previous Updates (v2.2)
- Enhanced statistical tools with paired testing and block bootstrap
- Discovery that Simple DCA outperforms Optimum DCA significantly
- Fat-tailed distribution modeling (df=1.56 for Bitcoin)
- Volatility regime detection (3 distinct market regimes)
### Previous Updates (v2.1)
- 3x more simulations using monthly rolling windows
- Higher statistical power (90% vs 35%)
- Risk-adjusted metrics (Sharpe, Sortino, Calmar, VaR, CVaR)
---
## Technical Implementation Details
### Financial Terminology
The codebase uses precise financial terminology to distinguish between returns and volatility:
| Variable | Description | Mathematical Notation | Excel Reference |
|----------|-------------|----------------------|-----------------|
| `weekly_return` | Percentage price change: (P_t - P_{t-1}) / P_{t-1} | r_t | Column D "Weekly Volatility" (misnomer) |
| `mean_weekly_return` | Average of all weekly returns (expected return) | μ (mu) | Cell T2 "AVG" |
| `return_volatility` | Standard deviation of returns (population σ) | σ (sigma) | Cell X2 "SD" |
| `ma_14w_volatility` | 14-week rolling standard deviation | σ_{14} | Used in VWAP bands |
**Key Distinction**:
- **Return** = Single period percentage change (can be positive or negative)
- **Volatility** = Standard deviation of returns (always positive, measures variation)
### Data Processing
**Weekly Volume Calculation**:
- Calculated dynamically as rolling 7-day sum of daily volumes
- Matches Excel formula: `=IF(C1531<>"",SUM(C1524:C1530),"")`
- Implementation: `daily_df['Daily Volume'].shift(1).rolling(window=7).sum()`
- The `shift(1)` excludes current day, `rolling(7)` sums previous 7 days
**Weekly Aggregation**:
- Uses Monday-based weeks (`W-MON`) with `label='right'`
- Takes last price of week (matching Excel's weekly snapshot)
- Weekly returns calculated as: `weekly_df['Price'].pct_change()`
### Statistical Calculations
**Mean Return (μ)**:
```python
mean_return = weekly_df['weekly_return'].mean() # Average of all returns
```
**Standard Deviation (σ)**:
```python
variance = (weekly_df['weekly_return'] - mean_return) ** 2
std_dev = np.sqrt(variance.mean()) # Population standard deviation
```
**Investment Multiple Formula**:
Uses Excel's formula incorporating:
- Price position relative to VWAP bands (2σ, 3σ, 4σ)
- Weekly return magnitude: `abs(weekly_return)`
- Rolling volatility: `ma_14w_volatility`
- Global return volatility: `return_volatility` (σ)
---
## Contributing
Contributions welcome! Please:
1. Follow the coding guidelines in [CLAUDE.md](CLAUDE.md)
2. Add tests for new features
3. Update documentation
4. Run test suite before submitting
---
## License
MIT License
---
## Acknowledgments
- Original Optimum DCA Excel strategy concept
- Statistical methodology based on quantitative finance best practices
- Bootstrap resampling implementation based on Efron & Tibshirani (1993)
---
## Support
**Documentation**:
- Tool Selection: [docs/guides/ANALYSIS_TOOL_GUIDE.md](docs/guides/ANALYSIS_TOOL_GUIDE.md)
- Statistics: [docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md](docs/methodology/STATISTICAL_METHODOLOGY_COMPARISON.md)
- Project Structure: [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)
**Reports**:
- Comprehensive Comparison: `reports/comparisons/COMPREHENSIVE_COMPARISON_REPORT.txt`
- Method Comparison: `reports/comparisons/method_comparison_summary.csv`
---
**Version**: 2.3.0
**Last Updated**: October 1, 2025
**Test Status**: 90/90 tests passing (100% pass rate)
**Recommended Tool**: `paired_strategy_comparison.py` (maximum statistical power)
**Key Insight**: Simple DCA significantly outperforms Optimum DCA across all horizons!