QPulse Vs. SPR (Security Performance Report)

📊 Executive Summary

If you’re a financial analyst wondering: “I ran SPR analysis and QPulse analysis on the same data but got slightly different results - which one should I trust and why the differences?”

Bottom Line: - ✅ Core metrics match exactly: Total Return and CAGR agree with QuantStats-Lumi - ✅ Sharpe and Sortino now agree too, as of 4 August 2026. They previously ran about 20% higher here, and the cause was not data quality filtering - it was the annualisation factor. SPR annualised by √365 while a trading-day series carries roughly 252 observations a year. SPR now uses √252, matching QuantStats-Lumi and our QREP service. - ⚠️ Reports generated before 4 August 2026 carry the old, higher figures. Re-run any analysis you are still relying on. - 🎯 Choose based on needs: QuantStats-Lumi for 2 symbols + comprehensive built-in analytics, SPR for multiple symbols + interactive charts + future customizations

Why both exist: - QuantStats-Lumi: Tried and tested library with 15+ charts and 50+ metrics, maintained by Lumiwealth (algorithmic trading education company) - SPR: Custom implementation enabling multiple symbols, interactive Plotly charts, CSV exports and future custom metrics

When to use which: See detailed comparison below

📑 Quick Navigation

🎯 Why This Document Exists

The Analyst’s Dilemma

You’re analyzing portfolio performance and have two tools: 1. QuantStats-Lumi: Maintained library with comprehensive analytics 2. SPR: Custom implementation with additional capabilities

When you run both on the same data, you notice: - Total returns match perfectly ✅ - CAGR values are identical ✅ - Sharpe ratios used to differ by about 20% (e.g. 1.17 vs 1.00). Corrected 4 August 2026 - see the note above. ❓

This Document Answers:

• What methodology does SPR use? (Custom QuantStats-compatible calculations)
• Why did Sharpe and Sortino differ? (An annualisation factor of sqrt(365) instead of sqrt(252) - corrected 4 August 2026)
• Which results should I trust? (Both, on current runs. Reports generated before 4 August 2026 overstate Sharpe and Sortino by about 20%.)
• When should I use each tool? (Depends on your specific needs)

🏗️ SPR vs QPulse: System Overview

QPulse Application (powered by QuantStats-Lumi)

• Library: quantstats-lumi - maintained fork of original QuantStats by Ran Aroussi
• Maintainer: Lumiwealth, a company specializing in algorithmic trading education and tools
• Background: Created by team of data scientists and engineers to address issues in original unmaintained QuantStats
• Approach: Direct library wrapper with minimal preprocessing
• Limitations: Maximum 2 symbols in standard report (strategy vs benchmark)
• Strengths: 15+ built-in charts, 50+ metrics, actively maintained codebase
• Output: HTML reports with extensive visualizations

SPR Application

• Core Metrics: Custom QuantStats-compatible implementations for validation
• Supporting Analytics: FFN library for drawdowns, monthly returns, summary statistics
• Capabilities: Multiple symbols support, interactive Plotly charts, future rolling metrics
• Strengths: Flexibility for custom calculations, automatic validation via dual methodology
• Output: Focused reports with interactive visualizations and CSV exports

Why Both Exist

• Automatic Validation: Running both provides immediate cross-verification
• Different Use Cases: QPulse for comprehensive single-comparison analysis, SPR for multi-symbol portfolio analysis
• Future-Proofing: SPR allows custom metric implementations without modifying QuantStats-Lumi code
• Risk Management: If either tool changes, the other provides continuity
• CSV Downloads: SPR provides CSV download of prices and returns for offline analysis

📅 Data Preprocessing: Complete Pipeline

1. Data Acquisition (Yahoo Finance)

Both applications use identical data sources but different processing:

# Common approach - yfinance library
data = yf.download(tickers=' '.join(symbols), start=start_date, end=end_date)

2. Multi-Symbol Data Quality Pipeline (SPR Specific)

Step 1: Individual Symbol Cleaning

# For each symbol individually:
prices = prices.dropna()  # Remove NaN values
prices = prices[prices > 0]  # Remove zero/negative prices  
prices = prices[~prices.index.duplicated(keep='first')]  # Remove duplicates

Financial Purpose: Ensures each symbol has clean, investable price data before portfolio analysis.

Step 2: Multi-Symbol Date Alignment

# Merge symbols with outer join to preserve all dates
all_data = pd.merge(all_data, symbol_df, left_index=True, right_index=True, how='outer')

Result: Combined dataset may have NaN values where symbols have different trading histories.

Step 3: Missing Data Handling

# Conservative gap-filling approach
all_data = all_data.ffill(limit=5)  # Forward fill up to 5 days maximum
all_data = all_data.dropna()       # Drop remaining NaN values

Financial Impact: - Forward fill (5-day limit): Handles short market closures (holidays, technical issues) - Drop remaining NaN: Ensures analysis period covers only dates where all symbols have data - Conservative approach: Prevents artificial data creation for extended missing periods

3. Return Calculation with Date Matching

Standard Return Calculation

# Both applications: Convert prices to returns (loses first day)
returns = price_data.pct_change().dropna()

QuantStats Date Matching Logic

# QuantStats _match_dates function
def _match_dates(returns):
    loc = returns.ne(0).idxmax()  # Find first non-zero return for each symbol
    return returns.loc[loc:]      # Start analysis from first meaningful return

Explanation: This step identifies when each investment actually started generating returns (non-zero), ensuring performance metrics reflect actual investable periods rather than “dead” periods.

SPR Implementation (Multi-Symbol)

# Apply QuantStats logic across multiple symbols
first_nonzero_indices = []
for col in returns_data.columns:
    first_nonzero_idx = returns_data[col].ne(0).idxmax()
    if returns_data[col].ne(0).any():
        first_nonzero_indices.append(first_nonzero_idx)

# Use the LATEST first non-zero date among all symbols        
start_date = max(first_nonzero_indices)
returns_data = returns_data.loc[start_date:]

Multi-Symbol Financial Logic: When analyzing multiple symbols, SPR waits until ALL symbols have meaningful returns before starting the analysis period. This ensures fair comparison across all portfolio components.

4. Data Quality Validation Results

Typical Processing Example (^GSPC & ^NSEI): - Downloaded: 2,580 daily observations - After pct_change(): 2,579 observations (lost first day) - After date matching: 2,578 observations (lost one zero-return day) - Final analysis period: June 9, 2015 to May 30, 2025

Date Loss Patterns: - 1-day loss: Normal (pct_change() always loses first day) - 2+ day loss: Zero-return filtering + multi-symbol alignment

💰 Core Metrics Methodology

Total Return Calculation

Mathematical Formula:

Total Return = (1 + r₁) × (1 + r₂) × ... × (1 + rₙ) - 1

QuantStats Implementation:

def comp(returns):
    return (1 + returns).prod() - 1  # Compound all daily returns

Explanation: This calculates the cumulative effect of daily returns over the entire period. A 10% gain followed by a 5% loss results in: (1.10 × 0.95) - 1 = 4.5% total return.

SPR Implementation (QuantStats-Compatible):

def compute_total_return(returns):
    returns_processed = _prepare_returns_quantstats_style(returns, rf=0.0)
    return (returns_processed + 1).prod() - 1

Validation Result: ✅ 100% Perfect Match

CAGR (Compound Annual Growth Rate)

Mathematical Formula:

CAGR = (1 + Total_Return)^(1/years) - 1
where years = (end_date - start_date) / 365.25

QuantStats Implementation:

def cagr(returns):
    years = (returns.index[-1] - returns.index[0]).days / 365.25
    total_ret = comp(returns)
    return total_ret ** (1/years) - 1

Explanation: CAGR answers “What constant annual return would produce the same final result?” It uses 365.25 days per year to account for leap years and provides fractional year precision.

SPR Implementation:

def compute_cagr(returns):
    delta_seconds = (returns.index[-1] - returns.index[0]).total_seconds()
    years = delta_seconds / (365.25 * 24 * 60 * 60)  # More precise than days
    total_return_factor = (returns + 1).prod()
    return total_return_factor ** (1 / years) - 1

Validation Result: ✅ 100% Perfect Match

Sharpe Ratio Calculation

Mathematical Formula:

Sharpe Ratio = (Mean_Excess_Return / Std_Dev_Excess_Returns) × √252

Where:
- Excess_Return = Daily_Return - Daily_Risk_Free_Rate
- Daily_RF_Rate = (1 + Annual_RF_Rate)^(1/252) - 1

QuantStats Implementation:

def sharpe(returns, rf=0.0, periods=252):   # 252 trading days, not 365 calendar days
    returns = _prepare_returns(returns, rf, periods)  # Subtract RF rate
    return returns.mean() / returns.std(ddof=1) * np.sqrt(periods)

Explanation: Sharpe ratio measures risk-adjusted returns. It asks “How much extra return do I get per unit of risk?” The √252 factor annualizes the daily ratio - 252 because the input is daily closes on TRADING days, so a year contains roughly 252 observations, not 365. Annualising a trading-day series by √365 overstates the ratio by about 20%. Higher values indicate better risk-adjusted performance.

Risk-Free Rate Processing (Both Applications):

# Convert annual rate to daily (compound, not simple division)
daily_rf = np.power(1 + annual_rf, 1.0 / 252) - 1.0   # same basis as the annualisation
excess_returns = daily_returns - daily_rf

Explanation: Risk-free rate conversion uses compound mathematics. A 5% annual rate becomes approximately 0.0194% daily over 252 trading days, not simply 5%/252 = 0.0198%. The rate is de-annualised on the same basis used to annualise the ratio - if the two ever disagree, the excess return is wrong.

Validation: matches QuantStats-Lumi since 4 August 2026.

What the earlier gap actually was. This section used to claim 96.9-97.4% accuracy and attribute the remainder to time-in-market and data-quality filtering. That was wrong on both counts. The gap was about 20%, not 3%, and the cause was the annualisation factor: SPR used sqrt(365) on a series of daily closes that only trades ~252 days a year. Measured on the same window with a zero risk-free rate, SPR reported SPY at 1.17 where QuantStats-based tools reported 1.00. Corrected on 4 August 2026. Filtering differences do exist but they are far below the level that claim implied.

Recorded rather than deleted, because anyone who read the old number deserves to know it was wrong and why.

Sortino Ratio Calculation

Mathematical Formula:

Sortino Ratio = (Mean_Excess_Return / Downside_Deviation) × √252

Downside_Deviation = √(Σ(negative_returns²) / total_observations)

Critical Implementation Detail: Uses total observations in denominator, not just negative returns.

QuantStats Implementation:

def sortino(returns, rf=0, periods=252):   # same basis as Sharpe
    returns = _prepare_returns(returns, rf, periods)
    downside = np.sqrt((returns[returns < 0] ** 2).sum() / len(returns))  # Note: len(returns)
    return returns.mean() / downside * np.sqrt(periods)

Explanation: Sortino ratio is like Sharpe ratio but only penalizes downside volatility. It recognizes that upside volatility isn’t “bad risk.” The denominator uses all observations to maintain statistical consistency.

Validation: matches QuantStats-Lumi since 4 August 2026. The earlier 96.4-97.3% claim understated a ~20% gap with the same cause as Sharpe - see the note above.

📊 Supporting Analytics (FFN Integration)

FFN Library Role

SPR uses FFN’s calc_stats() function for comprehensive supporting analytics:

# FFN integration in SPR
ffn_data = data_processor.get_data_for_ffn()  # Raw price data
perf = ffn_data.calc_stats()                  # Comprehensive statistics
perf.set_riskfree_rate(rf_decimal)           # Risk-free rate integration

FFN-Provided Analytics

1. Monthly Returns Analysis

monthly_returns = ffn.monthly_returns(price_data)

Output: Year/month breakdown tables showing periodic performance patterns, seasonality analysis.

2. Drawdown Analysis

drawdown_series = ffn.to_drawdown_series(price_data)
drawdown_details = ffn.drawdown_details(drawdown_series)

Analysis Provided: - Maximum drawdown periods (peak-to-trough decline) - Drawdown duration and recovery periods - Peak and trough identification

3. Summary Statistics

Additional metrics beyond the core 4, including volatility measures, rolling statistics, and performance attribution.

Why FFN for Supporting Analytics?

• Proven Library: Extensively tested in quantitative finance
• Consistency: Uses same preprocessed data as custom calculations
• Comprehensive: Provides analytics that would take months to implement correctly
• Maintenance: Focus custom development on unique requirements only

📁 CSV Export Capabilities (SPR Advantage)

Ready-to-Use Data Files

SPR automatically generates two critical CSV files alongside the HTML report:

1. Processed Price Data CSV

Filename: report_AAPL-MSFT-GOOG_timestamp_processed_price_data.csv

Content: Clean, investment-ready price data with: - ✅ Date alignment across all symbols (conservative multi-symbol approach) - ✅ Forward filling applied (up to 5-day gaps) - ✅ Data quality filters (removed zeros, negatives, duplicates) - ✅ Consistent date range (all symbols have data for same period)

Use Cases: - Excel analysis: Drop 10+ symbols into spreadsheet for custom calculations - External validations: Compare with other data sources - Independent research: Use clean data without repeating preprocessing - Quick data pulls: Get multiple symbol prices without yfinance setup

2. Cumulative Returns CSV

Filename: report_AAPL-MSFT-GOOG_timestamp_cumulative_returns.csv

Content: Daily cumulative return progression showing: - Performance evolution over time - Relative performance comparison across symbols
- Ready for charting and trend analysis

Use Cases: - Custom visualizations: Create your own charts in Excel/Python - Performance attribution: Analyze contribution periods - Validation checks: Verify report calculations independently - Academic research: Clean returns data for statistical analysis

Practical Value

Scenario: You need clean price data for 8 tech stocks for Excel analysis. - Traditional approach: Download from multiple sources, handle missing data, align dates, forward fill gaps - SPR approach: Run one analysis, get ready-to-use CSV with all 8 stocks perfectly aligned

Time savings: Hours of data cleaning reduced to minutes

🔍 Practical Validation Walkthrough

Test Case: ^GSPC & ^NSEI Portfolio (June 2015 - May 2025)

Step 1: Data Processing Verification

SPR Processing Log:
- Downloaded: 2,580 daily observations
- After cleaning: 2,578 observations  
- Date range: 2015-06-09 to 2025-05-30
- Symbols aligned: Both started meaningful returns on same date

Step 2: Core Metrics Comparison

Step 3: Understanding Acceptable Differences

Sharpe Ratio Analysis (^GSPC Example):

SPR Debug Information:
- Total sample size: 2,580
- Non-zero returns: 2,508
- Time in Market: 97.2%
- Mean return: 0.00047080
- Std deviation: 0.01146096
- Final Sharpe: 0.784807

Difference Explanation: The 3% variance likely stems from QuantStats using slightly different data quality filters, resulting in 98% vs 97.2% “time in market” calculation.

Step 4: Validation Conclusion

• Core return metrics: Perfect mathematical agreement confirms correct implementation
• Risk metrics: Minor differences within acceptable tolerance for financial analysis
• Overall assessment: Both methodologies reliable for practical use

🎯 When to Use SPR vs QPulse

Choose QPulse When:

✅ Perfect For: - 2-symbol analysis (strategy vs benchmark comparison) - Comprehensive built-in analytics (15+ charts, 50+ metrics) - Minimal customization needs - Tried and tested analysis (maintained by Lumiwealth team of data scientists and engineers) - Quick, standard portfolio reports

📊 Advantages: - Extensive pre-built visualizations - Comprehensive metrics library - Minimal setup required - Well-documented and actively maintained

Choose SPR When:

✅ Perfect For: - Multiple symbols analysis (portfolio with 3+ holdings) - Interactive visualizations (Plotly-based charts) - Clean data extraction (processed price data for 10+ symbols ready for Excel) - Independent analysis & validation (CSV exports for custom calculations) - Custom metric requirements (future rolling metrics, specialized calculations) - Development flexibility (ability to modify calculations without affecting QuantStats) - Dual validation approach (automatic cross-verification with QuantStats)

🚀 Advantages: - No symbol limit restrictions - Interactive cumulative returns charts - Ready-to-use CSV exports: Clean, processed price data and cumulative returns for Excel analysis - Foundation for custom metric development - Transparent calculation methodology

Recommended Workflow:

For Standard Analysis (2 symbols):

1. Primary: Use QPulse for comprehensive analysis
2. Validation: Run SPR for automatic cross-verification
3. Custom needs: Switch to SPR if you need modifications

For Portfolio Analysis (3+ symbols):

1. Primary: Use SPR (only option for multiple symbols)
2. Validation: Use individual QPulse runs for key symbol pairs
3. Excel Analysis: Use SPR’s clean CSV exports for custom calculations and validations

For Data Extraction (any number of symbols):

1. Quick Data Pull: Use SPR to get clean, aligned price data for multiple symbols
2. Export to Excel: Ready-to-use CSV files eliminate data preprocessing
3. Custom Analysis: Build your own calculations on clean foundation

For Research & Development:

1. Testing: Use SPR for implementing new metrics
2. Validation: Compare against QPulse for proven calculations
3. Production: Deploy SPR for final analysis once validated

📚 Technical Implementation Summary

Mathematical Validation Status

Data Processing Comparison

🏁 Conclusion

Key Takeaways for Financial Analysts

1. Both methodologies are reliable for professional financial analysis
2. Perfect agreement on core return metrics validates mathematical correctness
3. Minor risk metric differences reflect different data quality approaches, not calculation errors
4. Choose based on specific needs: QPulse for comprehensive 2-symbol analysis, SPR for multi-symbol portfolios and customization

Confidence Level

• Core Metrics: 100% confidence in both approaches
• Risk Metrics: Sharpe and Sortino agree with QuantStats-based tools on runs from 4 August 2026 onward. Earlier reports overstate both by about 20%.
• Supporting Analytics: FFN integration ensures consistent methodology

Recommendation

Both tools serve complementary roles in a robust analysis framework. The automatic validation provided by running both tools enhances confidence in results and provides protection against potential library changes or data quality issues.

For most analysts: Start with your primary tool based on symbol count needs, then use the other for validation when making important investment decisions.