tessl/pypi-quantstats
Portfolio analytics for quants - comprehensive statistical analysis, risk assessment, and performance visualization for quantitative finance
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
statistical-analysis.mddocs/
Statistical Analysis
Core statistical functions for portfolio performance analysis including return calculations, risk metrics, performance ratios, drawdown analysis, benchmarking, and advanced statistical measures. These functions form the foundation of quantitative portfolio analysis.
Capabilities
Performance Ratios
Essential risk-adjusted return metrics for evaluating portfolio performance.
def sharpe(returns, rf=0.0, periods=252, annualize=True, smart=False):
"""
Calculate Sharpe ratio - risk-adjusted return metric.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate (default 0.0)
- periods: int, number of periods per year (default 252 for daily)
- annualize: bool, whether to annualize the result
- smart: bool, whether to use smart Sharpe with autocorrelation penalty
Returns:
float: Sharpe ratio
"""
def sortino(returns, rf=0, periods=252, annualize=True, smart=False):
"""
Calculate Sortino ratio - downside deviation-adjusted return metric.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate (default 0.0)
- periods: int, number of periods per year
- annualize: bool, whether to annualize the result
- smart: bool, whether to use smart Sortino
Returns:
float: Sortino ratio
"""
def calmar(returns, prepare_returns=True, periods=252):
"""
Calculate Calmar ratio - CAGR to max drawdown ratio.
Parameters:
- returns: pandas Series of returns
- prepare_returns: bool, whether to prepare returns data
- periods: int, number of periods per year
Returns:
float: Calmar ratio
"""
def treynor_ratio(returns, benchmark, periods=252.0, rf=0.0):
"""
Calculate Treynor ratio - beta-adjusted return metric.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- periods: float, number of periods per year
- rf: float, risk-free rate
Returns:
float: Treynor ratio
"""
def omega(returns, rf=0.0, required_return=0.0, periods=252):
"""
Calculate Omega ratio - probability-weighted ratio of gains vs losses.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- required_return: float, required return threshold
- periods: int, number of periods per year
Returns:
float: Omega ratio
"""Rolling Performance Metrics
Time-varying performance metrics calculated over rolling windows.
def rolling_sharpe(returns, rf=0, periods=252, window=126, annualize=True, prepare_returns=True):
"""
Calculate rolling Sharpe ratio over a specified window.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- periods: int, number of periods per year
- window: int, rolling window size
- annualize: bool, whether to annualize the result
- prepare_returns: bool, whether to prepare returns data
Returns:
pandas Series: Rolling Sharpe ratios
"""
def rolling_sortino(returns, rf=0, periods=252, window=126, annualize=True, prepare_returns=True):
"""
Calculate rolling Sortino ratio over a specified window.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- periods: int, number of periods per year
- window: int, rolling window size
- annualize: bool, whether to annualize the result
- prepare_returns: bool, whether to prepare returns data
Returns:
pandas Series: Rolling Sortino ratios
"""
def rolling_volatility(returns, periods=252, window=126, min_periods=None, annualize=True, prepare_returns=True):
"""
Calculate rolling volatility over a specified window.
Parameters:
- returns: pandas Series of returns
- periods: int, number of periods per year
- window: int, rolling window size
- min_periods: int, minimum periods required for calculation
- annualize: bool, whether to annualize the result
- prepare_returns: bool, whether to prepare returns data
Returns:
pandas Series: Rolling volatilities
"""Return Analysis
Functions for analyzing return characteristics and patterns.
def cagr(returns, rf=0.0, compounded=True, periods=252):
"""
Calculate Compound Annual Growth Rate.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- compounded: bool, whether returns are compounded
- periods: int, number of periods per year
Returns:
float: CAGR
"""
def volatility(returns, periods=252, annualize=True, prepare_returns=True):
"""
Calculate volatility (standard deviation of returns).
Parameters:
- returns: pandas Series of returns
- periods: int, number of periods per year
- annualize: bool, whether to annualize the result
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Volatility
"""
def expected_return(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate expected return of the asset.
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method (None, 'M', 'Q', 'Y')
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Expected return
"""
def skew(returns, prepare_returns=True):
"""
Calculate skewness of returns distribution.
Parameters:
- returns: pandas Series of returns
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Skewness
"""
def kurtosis(returns, prepare_returns=True):
"""
Calculate kurtosis of returns distribution.
Parameters:
- returns: pandas Series of returns
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Kurtosis
"""Win/Loss Analysis
Analysis of winning and losing periods and their characteristics.
def win_rate(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate win rate (percentage of positive returns).
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Win rate as percentage
"""
def avg_win(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate average winning return.
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Average winning return
"""
def avg_loss(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate average losing return.
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Average losing return
"""
def consecutive_wins(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate maximum consecutive winning periods.
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
int: Maximum consecutive wins
"""
def consecutive_losses(returns, aggregate=None, compounded=True, prepare_returns=True):
"""
Calculate maximum consecutive losing periods.
Parameters:
- returns: pandas Series of returns
- aggregate: str, aggregation method
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
int: Maximum consecutive losses
"""Drawdown Analysis
Analysis of portfolio drawdowns and recovery patterns.
def max_drawdown(prices):
"""
Calculate maximum drawdown from peak to trough.
Parameters:
- prices: pandas Series of prices or cumulative returns
Returns:
float: Maximum drawdown as negative percentage
"""
def to_drawdown_series(returns):
"""
Convert returns to drawdown series.
Parameters:
- returns: pandas Series of returns
Returns:
pandas Series: Drawdown series
"""
def drawdown_details(drawdown):
"""
Analyze drawdown periods in detail.
Parameters:
- drawdown: pandas Series of drawdown values
Returns:
pandas DataFrame: Detailed drawdown analysis with start, end, duration, and magnitude
"""Benchmarking Functions
Functions for comparing portfolio performance against benchmarks.
def r_squared(returns, benchmark, prepare_returns=True):
"""
Calculate R-squared coefficient against benchmark.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- prepare_returns: bool, whether to prepare returns data
Returns:
float: R-squared value (0-1)
"""
def information_ratio(returns, benchmark, prepare_returns=True):
"""
Calculate Information Ratio against benchmark.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Information ratio
"""
def greeks(returns, benchmark, periods=252.0, prepare_returns=True):
"""
Calculate alpha and beta coefficients against benchmark.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- periods: float, number of periods per year
- prepare_returns: bool, whether to prepare returns data
Returns:
dict: Dictionary with 'alpha' and 'beta' keys
"""
def rolling_greeks(returns, benchmark, periods=252, prepare_returns=True):
"""
Calculate rolling alpha and beta coefficients.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- periods: int, number of periods per year
- prepare_returns: bool, whether to prepare returns data
Returns:
pandas DataFrame: Rolling alpha and beta values
"""Advanced Statistical Measures
Sophisticated statistical metrics for in-depth analysis.
def kelly_criterion(returns, prepare_returns=True):
"""
Calculate Kelly Criterion for optimal position sizing.
Parameters:
- returns: pandas Series of returns
- prepare_returns: bool, whether to prepare returns data
Returns:
float: Kelly Criterion percentage
"""
def gain_to_pain_ratio(returns, rf=0, resolution="D"):
"""
Calculate gain-to-pain ratio.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- resolution: str, return resolution ('D', 'M', 'Q', 'Y')
Returns:
float: Gain-to-pain ratio
"""
def probabilistic_sharpe_ratio(returns, benchmark, periods=252.0, rf=0.0):
"""
Calculate probabilistic Sharpe ratio.
Parameters:
- returns: pandas Series of portfolio returns
- benchmark: pandas Series of benchmark returns
- periods: float, number of periods per year
- rf: float, risk-free rate
Returns:
float: Probabilistic Sharpe ratio
"""
def monthly_returns(returns, eoy=True, compounded=True, prepare_returns=True):
"""
Generate monthly returns table.
Parameters:
- returns: pandas Series of returns
- eoy: bool, whether to include end-of-year totals
- compounded: bool, whether returns are compounded
- prepare_returns: bool, whether to prepare returns data
Returns:
pandas DataFrame: Monthly returns table
"""Install with Tessl CLI
npx tessl i tessl/pypi-quantstats