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
data-utilities.mddocs/
Data Utilities
Data preparation and utility functions for converting between prices and returns, data validation, aggregation, benchmarking preparation, and integration with external data sources for quantitative analysis workflows.
Capabilities
Data Conversion Functions
Convert between different data formats commonly used in quantitative finance.
def to_returns(prices, rf=0.0):
"""
Convert price series to return series.
Parameters:
- prices: pandas Series of prices
- rf: float, risk-free rate to subtract from returns
Returns:
pandas Series: Returns calculated as pct_change()
"""
def to_prices(returns, base=1e5):
"""
Convert return series to price index.
Parameters:
- returns: pandas Series of returns
- base: float, starting value for price index
Returns:
pandas Series: Cumulative price index
"""
def log_returns(returns, rf=0.0, nperiods=None):
"""
Convert returns to log returns.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- nperiods: int, number of periods for annualization
Returns:
pandas Series: Log returns
"""
def to_log_returns(returns, rf=0.0, nperiods=None):
"""
Alias for log_returns function.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- nperiods: int, number of periods
Returns:
pandas Series: Log returns
"""
def to_excess_returns(returns, rf, nperiods=None):
"""
Calculate excess returns above risk-free rate.
Parameters:
- returns: pandas Series of returns
- rf: float, risk-free rate
- nperiods: int, number of periods for rate conversion
Returns:
pandas Series: Excess returns
"""
def rebase(prices, base=100.0):
"""
Rebase price series to start at specified value.
Parameters:
- prices: pandas Series of prices
- base: float, new base value
Returns:
pandas Series: Rebased price series
"""Data Validation and Preparation
Ensure data quality and prepare data for analysis.
def validate_input(data, allow_empty=False):
"""
Validate input data for QuantStats functions.
Parameters:
- data: pandas Series or DataFrame to validate
- allow_empty: bool, whether to allow empty data
Returns:
pandas Series or DataFrame: Validated data
Raises:
DataValidationError: If data validation fails
"""
def _prepare_returns(data, rf=0.0, nperiods=None):
"""
Internal function to prepare returns data for analysis.
Parameters:
- data: pandas Series of returns or prices
- rf: float, risk-free rate
- nperiods: int, number of periods
Returns:
pandas Series: Prepared returns data
"""
def _prepare_prices(data, base=1.0):
"""
Internal function to prepare price data.
Parameters:
- data: pandas Series of prices
- base: float, base value for rebasing
Returns:
pandas Series: Prepared price data
"""
def _prepare_benchmark(benchmark=None, period="max", rf=0.0, prepare_returns=True):
"""
Prepare benchmark data for analysis.
Parameters:
- benchmark: str or pandas Series, benchmark identifier or data
- period: str, time period for data retrieval
- rf: float, risk-free rate
- prepare_returns: bool, whether to prepare returns
Returns:
pandas Series: Prepared benchmark data
"""Data Aggregation and Resampling
Functions for aggregating returns across different time periods.
def aggregate_returns(returns, period=None, compounded=True):
"""
Aggregate returns to specified frequency.
Parameters:
- returns: pandas Series of returns
- period: str, aggregation period ('M', 'Q', 'Y', etc.)
- compounded: bool, whether to compound returns
Returns:
pandas Series: Aggregated returns
"""
def group_returns(returns, groupby, compounded=False):
"""
Group returns by specified criteria.
Parameters:
- returns: pandas Series of returns
- groupby: str or function, grouping criteria
- compounded: bool, whether to compound grouped returns
Returns:
pandas Series: Grouped returns
"""
def multi_shift(df, shift=3):
"""
Create DataFrame with multiple shifted versions.
Parameters:
- df: pandas DataFrame to shift
- shift: int, number of periods to shift
Returns:
pandas DataFrame: DataFrame with original and shifted columns
"""Statistical Utilities
Helper functions for statistical calculations and data manipulation.
def exponential_stdev(returns, window=30, is_halflife=False):
"""
Calculate exponentially weighted standard deviation.
Parameters:
- returns: pandas Series of returns
- window: int, window size or halflife
- is_halflife: bool, whether window represents halflife
Returns:
pandas Series: Exponentially weighted standard deviation
"""
def _count_consecutive(data):
"""
Count consecutive occurrences in data.
Parameters:
- data: pandas Series of boolean or numeric data
Returns:
int: Maximum consecutive count
"""
def _round_to_closest(val, res, decimals=None):
"""
Round value to closest resolution.
Parameters:
- val: float, value to round
- res: float, resolution to round to
- decimals: int, number of decimal places
Returns:
float: Rounded value
"""Portfolio Construction
Functions for creating portfolios and indices from return data.
def make_portfolio(returns, start_balance=1e5, mode="comp", round_to=None):
"""
Create portfolio value series from returns.
Parameters:
- returns: pandas Series of returns
- start_balance: float, starting portfolio value
- mode: str, calculation mode ('comp' for compounded)
- round_to: int, decimal places to round to
Returns:
pandas Series: Portfolio value over time
"""
def make_index(ticker, **kwargs):
"""
Create market index from ticker symbol.
Parameters:
- ticker: str, ticker symbol
- **kwargs: additional parameters for data retrieval
Returns:
pandas Series: Index price or return data
"""Data Download and External Sources
Retrieve financial data from external sources.
def download_returns(ticker, period="max", proxy=None):
"""
Download return data for specified ticker.
Parameters:
- ticker: str, ticker symbol (e.g., 'SPY', 'AAPL')
- period: str, time period ('1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max')
- proxy: str, proxy server URL (optional)
Returns:
pandas Series: Return series for the ticker
"""Date and Time Utilities
Functions for working with time-based data filtering and analysis.
def _mtd(df):
"""
Filter DataFrame to month-to-date data.
Parameters:
- df: pandas DataFrame or Series with datetime index
Returns:
pandas DataFrame or Series: Month-to-date filtered data
"""
def _qtd(df):
"""
Filter DataFrame to quarter-to-date data.
Parameters:
- df: pandas DataFrame or Series with datetime index
Returns:
pandas DataFrame or Series: Quarter-to-date filtered data
"""
def _ytd(df):
"""
Filter DataFrame to year-to-date data.
Parameters:
- df: pandas DataFrame or Series with datetime index
Returns:
pandas DataFrame or Series: Year-to-date filtered data
"""
def _pandas_date(df, dates):
"""
Filter DataFrame by specific dates.
Parameters:
- df: pandas DataFrame or Series
- dates: list or pandas DatetimeIndex of dates to filter
Returns:
pandas DataFrame or Series: Filtered data
"""
def _pandas_current_month(df):
"""
Filter DataFrame to current month data.
Parameters:
- df: pandas DataFrame or Series with datetime index
Returns:
pandas DataFrame or Series: Current month data
"""Environment and Context Detection
Utility functions for detecting execution environment and setting up context.
def _in_notebook(matplotlib_inline=False):
"""
Detect if running in Jupyter notebook environment.
Parameters:
- matplotlib_inline: bool, whether to enable matplotlib inline mode
Returns:
bool: True if running in notebook, False otherwise
"""
def _file_stream():
"""
Create file stream context for data operations.
Returns:
file-like object: Stream for file operations
"""Cache Management
Functions for managing internal data caches to improve performance.
def _generate_cache_key(data, rf, nperiods):
"""
Generate cache key for prepared returns data.
Parameters:
- data: pandas Series, input data
- rf: float, risk-free rate
- nperiods: int, number of periods
Returns:
str: Cache key
"""
def _clear_cache_if_full():
"""
Clear cache if it exceeds maximum size limit.
Returns:
None
"""Data Formatting and Display
Functions for formatting data for display and analysis.
def _score_str(val):
"""
Format score value as string with appropriate precision.
Parameters:
- val: float, score value to format
Returns:
str: Formatted score string
"""
def _flatten_dataframe(df, set_index=None):
"""
Flatten hierarchical DataFrame structure.
Parameters:
- df: pandas DataFrame with hierarchical structure
- set_index: str, column name to set as index
Returns:
pandas DataFrame: Flattened DataFrame
"""Exception Classes
class QuantStatsError(Exception):
"""Base exception class for QuantStats."""
class DataValidationError(QuantStatsError):
"""Raised when input data validation fails."""
class CalculationError(QuantStatsError):
"""Raised when a calculation fails."""
class PlottingError(QuantStatsError):
"""Raised when plotting operations fail."""
class BenchmarkError(QuantStatsError):
"""Raised when benchmark-related operations fail."""Usage Examples
Basic Data Conversion
import quantstats as qs
import pandas as pd
# Convert prices to returns
prices = pd.Series([100, 102, 101, 105, 103])
returns = qs.utils.to_returns(prices)
# Convert returns back to prices
reconstructed_prices = qs.utils.to_prices(returns, base=100)
# Calculate log returns
log_rets = qs.utils.log_returns(returns)Data Validation and Preparation
# Validate input data
try:
validated_returns = qs.utils.validate_input(returns)
except qs.utils.DataValidationError as e:
print(f"Data validation failed: {e}")
# Aggregate to monthly returns
monthly_returns = qs.utils.aggregate_returns(returns, period='M')External Data Integration
# Download benchmark data
spy_returns = qs.utils.download_returns('SPY', period='5y')
# Create excess returns
excess_returns = qs.utils.to_excess_returns(returns, rf=0.02)Constants
_PREPARE_RETURNS_CACHE: dict
"""Internal cache for prepared returns data"""
_CACHE_MAX_SIZE: int
"""Maximum size for internal caches (default: 100)"""Install with Tessl CLI
npx tessl i tessl/pypi-quantstats