fincore.metrics

Returns

fincore.metrics.returns

Return calculation utilities.

This module provides core functions for return analytics, including: - simple returns from prices - cumulative return series and final cumulative return - return aggregation (e.g. weekly/monthly/yearly) - normalization of a value series to a starting value

annual_return(*args, **kwargs)

Backwards-compatible wrapper for computing annual return (CAGR).

The implementation lives in :func:fincore.metrics.yearly.annual_return.

参数：

名称	类型	描述	默认
*args	tuple	Positional arguments forwarded to yearly.annual_return.	()
**kwargs	dict	Keyword arguments forwarded to yearly.annual_return.	{}

返回：

类型	描述
float	Annual return.

See Also

fincore.metrics.yearly.annual_return : Implementation.

simple_returns(prices)

Compute simple returns from a time series of prices.

参数：

名称	类型	描述	默认
prices	array - like or Series or DataFrame	Time series of prices.	必需

返回：

类型	描述
array - like or Series or DataFrame	Simple returns computed as (price[t] - price[t-1]) divided by price[t-1]. The first observation is dropped. For pandas inputs, the index is preserved (excluding the first element).

cum_returns(returns, starting_value=0, out=None)

Compute cumulative returns from simple returns.

This compounds the input returns and optionally scales by an initial starting_value.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
starting_value	float	Initial portfolio value. If 0 (default), the result is returned as a pure cumulative return. Otherwise, the result is scaled so that starting_value * cumprod(1 + returns) is returned.	0
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
array - like or Series or DataFrame	Cumulative returns. The type mirrors the input type.

cum_returns_final(returns, starting_value=0)

Compute total cumulative return from a series of simple returns.

This computes the cumulative return by compounding simple period returns and optionally scaling by an initial starting_value.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns. For a DataFrame, the computation is performed column-wise.	必需
starting_value	float	Initial portfolio value. If 0 (default), the result is returned as a pure return (ending_value - 1). Otherwise, the result is scaled so that starting_value * cumprod(1 + returns) is returned.	0

返回：

类型	描述
float or ndarray or Series or DataFrame	Final cumulative return (or value, depending on starting_value). The type mirrors the input type.

aggregate_returns(returns, convert_to='monthly')

Aggregate returns at a weekly/monthly/quarterly/yearly frequency.

The function groups the input return series by calendar period and compounds the returns within each group using :func:cum_returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns with a DatetimeIndex.	必需
convert_to	('weekly', 'monthly', 'quarterly', 'yearly')	Target aggregation frequency. Case-insensitive. Default is "monthly".	"weekly"

返回：

类型	描述
Series	Aggregated returns at the requested frequency, indexed by (year, period) where period is week number, month, quarter, or year depending on convert_to.

normalize(returns, starting_value=1)

Normalize a value series to start at starting_value.

This scales the input series by its first value so that the resulting series starts at starting_value. This is commonly used to align equity curves from different strategies for comparison.

参数：

名称	类型	描述	默认
returns	Series	Value series (typically cumulative returns or prices).	必需
starting_value	float	Starting value after normalization. Default is 1.	1

返回：

类型	描述
Series	Normalized series whose first value equals starting_value.

示例：

>>> import pandas as pd
>>> returns = pd.Series([100, 110, 105, 115])
>>> normalize(returns, starting_value=1)
0    1.00
1    1.10
2    1.05
3    1.15
dtype: float64

Drawdown

fincore.metrics.drawdown

Drawdown-related metrics.

max_drawdown(returns, out=None)

Determine the maximum drawdown of a return series.

Maximum drawdown is defined as the minimum (most negative) percentage drop from a running maximum of cumulative returns.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
out	ndarray	pre-allocated output array. If provided, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray or Series	Maximum drawdown. For 1D input a scalar is returned; for 2D input one value is returned per column.

get_all_drawdowns(returns)

Extract all distinct drawdown values from a return series.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
list of float	List of drawdown magnitudes (negative values) for each distinct drawdown period.

get_all_drawdowns_detailed(returns)

Extract detailed information about all drawdown periods.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
list of dict	List of dictionaries with keys 'value', 'duration', 'recovery_duration' for each distinct drawdown period.

get_max_drawdown(returns)

Determine the maximum drawdown of a strategy.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需

返回：

名称	类型	描述
peak	datetime	The date of the peak before the maximum drawdown.
valley	datetime	The date of the trough (maximum drawdown).
recovery	datetime	The date of recovery or NaT if not recovered.

get_max_drawdown_underwater(underwater)

Determines peak, valley, and recovery dates given an underwater returns.

参数：

名称	类型	描述	默认
underwater	Series	Underwater returns (cumulative returns minus rolling max).	必需

返回：

名称	类型	描述
peak	datetime	The date of the peak before the maximum drawdown.
valley	datetime	The date of the trough (maximum drawdown).
recovery	datetime	The date of recovery or NaT if not recovered.

get_top_drawdowns(returns, top=10)

Find top drawdowns, sorted by severity.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
top	int	The amount of top drawdowns to find (default 10).	10

返回：

名称	类型	描述
drawdowns	list	List of (peak, valley, recovery) tuples.

gen_drawdown_table(returns, top=10)

Place top drawdowns in a table.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
top	int	The amount of top drawdowns to find (default 10).	10

返回：

名称	类型	描述
df_drawdowns	DataFrame	Information about top drawdowns.

get_max_drawdown_period(returns)

Get the start and end dates of the maximum drawdown period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
(Timestamp, Timestamp)	Tuple (start_date, end_date) of the maximum drawdown period, or (None, None) if it cannot be determined.

max_drawdown_days(returns)

Calculate the duration of the maximum drawdown in days.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days (or periods) between the peak and trough of the maximum drawdown, or NaN if it cannot be determined.

max_drawdown_weeks(returns)

Calculate the duration of the maximum drawdown in weeks.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
float	Number of weeks between the peak and trough of the maximum drawdown, or NaN if it cannot be determined.

max_drawdown_months(returns)

Calculate the duration of the maximum drawdown in months.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
float	Number of months between the peak and trough of the maximum drawdown, or NaN if it cannot be determined.

max_drawdown_recovery_days(returns)

Calculate the recovery time from maximum drawdown in days.

This computes the number of days (or periods) from the trough of the maximum drawdown until the portfolio value recovers to the previous peak.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days (or periods) from the trough to recovery, or NaN if recovery does not occur or cannot be determined.

max_drawdown_recovery_weeks(returns)

Calculate the recovery time from maximum drawdown in weeks.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
float	Number of weeks from the trough to recovery, or NaN if recovery does not occur or cannot be determined.

max_drawdown_recovery_months(returns)

Calculate the recovery time from maximum drawdown in months.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
float	Number of months from the trough to recovery, or NaN if recovery does not occur or cannot be determined.

second_max_drawdown(returns)

Determine the second-largest drawdown of a strategy.

This identifies all distinct drawdown periods and returns the second-most severe (second-most negative) drawdown.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Second-largest drawdown, or NaN if there are fewer than two drawdown periods.

third_max_drawdown(returns)

Determine the third-largest drawdown of a strategy.

This identifies all distinct drawdown periods and returns the third-most severe (third-most negative) drawdown.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Third-largest drawdown, or NaN if there are fewer than three drawdown periods.

second_max_drawdown_days(returns)

Calculate the duration of the second maximum drawdown in days.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days (or periods) between the peak and trough of the second-largest drawdown, or NaN if there are fewer than two drawdown periods.

second_max_drawdown_recovery_days(returns)

Calculate the recovery time from the second maximum drawdown in days.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days from the trough to recovery for the second-largest drawdown, or NaN if recovery does not occur or there are fewer than two drawdown periods.

third_max_drawdown_days(returns)

Calculate the duration of the third maximum drawdown in days.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days (or periods) between the peak and trough of the third-largest drawdown, or NaN if there are fewer than three drawdown periods.

third_max_drawdown_recovery_days(returns)

Calculate the recovery time from the third maximum drawdown in days.

参数：

名称	类型	描述	默认
returns	Series or array - like	Non-cumulative returns indexed by date or position.	必需

返回：

类型	描述
int or float	Number of days from the trough to recovery for the third-largest drawdown, or NaN if recovery does not occur or there are fewer than three drawdown periods.

Risk

fincore.metrics.risk

Risk metrics.

annual_volatility(returns, period=DAILY, volatility_power=2.0, annualization=None, out=None, *, alpha_=None)

Determine the annualized volatility of a return series.

Volatility is computed as the standard deviation of returns scaled by an annualization factor based on period or annualization.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
volatility_power	float	Power used when scaling volatility (for example 2.0 for variance, 1.0 for standard deviation). Defaults to 2.0 to match the original empyrical implementation. Named to avoid confusion with alpha (excess return) in finance.	2.0
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array. If provided, the result is written in-place into this array.	None
alpha_	float	Deprecated. Use volatility_power instead. If provided, takes precedence over volatility_power for backward compatibility.	None

返回：

类型	描述
float or ndarray or Series	Annualized volatility. For 1D input a scalar is returned; for 2D input one value is returned per column.

downside_risk(returns, required_return=0, period=DAILY, annualization=None, out=None)

Determine the annualized downside deviation below a threshold.

Downside risk is computed as the annualized standard deviation of returns that fall below required_return.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
required_return	float	Minimum acceptable return threshold. Only returns below this value contribute to the downside risk. Default is 0.	0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	Optional pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray or Series	Annualized downside risk. For 1D input a scalar is returned; for 2D input one value is returned per column. Returns 0 when all returns are above required_return (no downside component).

value_at_risk(returns, cutoff=0.05)

Calculate the (historical) value at risk (VaR) of returns.

VaR is estimated as the cutoff-percentile of the return distribution.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
cutoff	float	Left-tail probability level in [0, 1]. For example 0.05 selects the 5th percentile. Values outside [0, 1] return NaN. Default is 0.05.	0.05

返回：

类型	描述
float	Historical VaR at the given confidence level, or NaN if there are no observations or cutoff is invalid.

conditional_value_at_risk(returns, cutoff=0.05)

Calculate the conditional value at risk (CVaR) of returns.

CVaR (also known as Expected Shortfall) is the expected return conditional on the return being at or below the VaR threshold.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
cutoff	float	Left-tail probability level in [0, 1]. Values outside [0, 1] return NaN. Default is 0.05.	0.05

返回：

类型	描述
float	Conditional VaR (expected shortfall) at the given confidence level, or NaN if there are no observations or cutoff is invalid.

tail_ratio(returns)

Determine the ratio of right- to left-tail percentiles of returns.

The tail ratio is defined as the absolute value of the 95th percentile divided by the absolute value of the 5th percentile.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Tail ratio, or NaN if there are no valid observations.

tracking_error(returns, factor_returns, period=DAILY, annualization=None, out=None)

Determine the annualized tracking error versus a benchmark.

Tracking error is defined as the annualized standard deviation of the active returns (strategy minus benchmark).

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series or DataFrame	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	Optional pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray	Annualized tracking error. For 1D input a scalar is returned; for 2D input one value is returned per column.

residual_risk(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate annualized residual risk (idiosyncratic risk).

Residual risk is the standard deviation of regression residuals from a single-factor regression of excess returns on benchmark excess returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	Annualized residual risk, or NaN if there are fewer than two aligned observations.

var_excess_return(returns, cutoff=0.05, risk_free=0.0, period=DAILY, annualization=None)

Calculate the excess-return-on-VaR ratio.

Defined as (annualized_return - risk_free) / abs(VaR), where VaR is the historical Value at Risk at the given cutoff level.

Reference: ER-VaR = (r_annual - rf) / |VaR|

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
cutoff	float	Left-tail probability level in (0, 1). Default is 0.05.	0.05
risk_free	float	Annual risk-free rate. Default is 0.0.	0.0
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float	Excess-return-on-VaR ratio, or NaN if there are fewer than two observations or VaR is zero.

var_cov_var_normal(p, c, mu=0, sigma=1)

Calculate parametric Value at Risk using the normal distribution.

参数：

名称	类型	描述	默认
p	float	Portfolio value.	必需
c	float	Confidence level (e.g., 0.99 for 99% VaR).	必需
mu	float	Expected return. Default is 0.	0
sigma	float	Standard deviation of returns. Default is 1.	1

返回：

类型	描述
float	Parametric VaR at the given confidence level.

trading_value_at_risk(returns, period=None, sigma=2.0)

Calculate trading Value at Risk.

This computes a simplified VaR as mean - sigma * std.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
period	str	Frequency of the input data. Currently unused.	None
sigma	float	Number of standard deviations to subtract from the mean. Default is 2.0.	2.0

返回：

类型	描述
float	Trading VaR, or NaN if there are fewer than two observations.

gpd_risk_estimates(returns, var_p=0.01)

Estimate VaR and ES using the Generalized Pareto Distribution (GPD).

This fits a GPD to the tail of the loss distribution and estimates VaR and Expected Shortfall (ES).

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
var_p	float	Probability level for VaR/ES estimation. Default is 0.01.	0.01

返回：

类型	描述
ndarray or Series	Array of length 5 containing: [threshold, scale_param, shape_param, var_estimate, es_estimate]. Returns zeros if the estimation fails.

gpd_risk_estimates_aligned(returns, var_p=0.01)

Calculate GPD risk estimates (aligned version for compatibility).

This is a wrapper around :func:gpd_risk_estimates for API compatibility.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
var_p	float	Probability level for VaR/ES estimation. Default is 0.01.	0.01

返回：

类型	描述
ndarray or Series	Array of length 5 containing GPD risk estimates.

beta_fragility_heuristic(returns, factor_returns)

Estimate fragility to a drop in beta.

This heuristic measures how fragile a strategy's returns are to changes in market conditions by comparing returns at different points in the factor return distribution.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需

返回：

类型	描述
float	Beta fragility heuristic, or NaN if there is insufficient data.

beta_fragility_heuristic_aligned(returns, factor_returns)

Calculate the beta fragility heuristic with aligned series.

This is a wrapper around :func:beta_fragility_heuristic for API compatibility.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需

返回：

类型	描述
float	Beta fragility heuristic, or NaN if there is insufficient data.

Ratios

fincore.metrics.ratios

Ratio metrics (risk-adjusted returns, drawdown ratios, capture ratios, etc.).

Function groups: (1) Basic ratios, (2) Drawdown ratios, (3) Downside-risk ratios, (4) Benchmark-relative ratios, (5) Preference/stability metrics, (6) Capture metrics.

sharpe_ratio(returns, risk_free=0, period=DAILY, annualization=None, out=None)

Determine the annualized Sharpe ratio of a strategy.

The Sharpe ratio is defined as the annualized mean excess return divided by the annualized standard deviation of returns.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.	0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array. If provided, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray or Series	Annualized Sharpe ratio. For 1D input a scalar is returned; for 2D input one value is returned per column.

sortino_ratio(returns, required_return=0, period=DAILY, annualization=None, out=None, _downside_risk=None)

Determine the Sortino ratio of a strategy.

The Sortino ratio is defined as the annualized excess return divided by the annualized downside risk. Only returns falling below required_return contribute to the downside risk term.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
required_return	float	Minimum acceptable return used as the threshold when computing downside risk. Default is 0.	0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	Optional pre-allocated output array. If given, the result is written in-place into this array.	None
_downside_risk	float or ndarray	Optional pre-computed annualized downside risk. If provided, this value is reused instead of recomputing downside risk.	None

返回：

类型	描述
float or ndarray or Series	Sortino ratio of the strategy. For 1D input a scalar is returned; for 2D input one value is returned per column.

excess_sharpe(returns, factor_returns, out=None)

Determine the excess Sharpe ratio of a strategy.

The excess Sharpe ratio is defined as the mean active return divided by the tracking error, where active return is the difference between the strategy returns and the benchmark (factor) returns.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series or DataFrame	Non-cumulative benchmark or factor returns, aligned to returns.	必需
out	ndarray	Optional pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray or Series	Excess Sharpe ratio. For 1D input a scalar is returned; for 2D input one value is returned per column.

adjusted_sharpe_ratio(returns, risk_free=0.0)

Calculate the adjusted Sharpe ratio.

This version of the Sharpe ratio applies a correction for skewness and kurtosis of the return distribution, following the standard approximation with additional dampening for small sample sizes.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0

返回：

类型	描述
float	Adjusted Sharpe ratio that accounts for non-normality. Returns NaN when there is insufficient data.

conditional_sharpe_ratio(returns, cutoff=0.05, risk_free=0, period=DAILY, annualization=None)

Calculate the Sharpe ratio conditional on the left tail.

The conditional Sharpe ratio is computed on the subset of returns that fall below a given quantile of the full return distribution.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
cutoff	float	Left-tail probability level in (0, 1). For example 0.05 selects the worst 5% of returns. Default is 0.05.	0.05
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.	0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	Sharpe ratio computed on the conditional (left-tail) subsample, annualized. Returns NaN if there are fewer than two observations.

calmar_ratio(returns, risk_free=0, period=DAILY, annualization=None)

Determine the Calmar ratio (return-to-drawdown ratio).

The Calmar ratio is defined as the annualized excess return divided by the absolute value of the maximum drawdown.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.	0
period	str	Frequency of the input data (for example DAILY). Used to annualize returns when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	Calmar ratio of the return series. Returns NaN if maximum drawdown is non-negative or infinite.

mar_ratio(returns, period=DAILY, annualization=None)

Calculate the MAR ratio.

The MAR ratio is defined as the arithmetic mean annualized return divided by the absolute value of the maximum drawdown.

Unlike the Calmar ratio (which uses CAGR), the MAR ratio uses mean(returns) × annualization_factor as the numerator.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float	MAR ratio, or NaN if the maximum drawdown is non-negative.

omega_ratio(returns, risk_free=0.0, required_return=0.0, annualization=APPROX_BDAYS_PER_YEAR)

Determine the Omega ratio of a strategy.

The Omega ratio is the probability-weighted ratio of gains over losses relative to a threshold :math:\tau. In discrete form:

.. math::

\Omega(\tau) = \frac{\sum \max(R_t - \tau,\; 0)}
                    {\sum \max(\tau - R_t,\; 0)}

The effective per-period threshold is computed as :math:\tau = \text{risk\_free} + (1 + \text{required\_return})^{1/q} - 1, where q is the annualization factor.

Reference

https://breakingdownfinance.com/finance-topics/performance-measurement/omega-ratio/

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative simple returns.	必需
risk_free	float	Per-period risk-free rate added to the threshold. Default is 0.0.	0.0
required_return	float	Annualized minimum acceptable return (MAR). It is converted to a per-period rate via compound de-annualization before being added to risk_free to form the effective threshold :math:\tau. Default is 0.0.	0.0
annualization	float	Number of periods per year used when de-annualizing required_return (for example trading days per year). Default is APPROX_BDAYS_PER_YEAR.	APPROX_BDAYS_PER_YEAR

返回：

类型	描述
float	Omega ratio of the strategy. Returns NaN if there are fewer than two observations, if the downside component is zero, or if required_return <= -1 (mathematically invalid for compound de-annualization).

information_ratio(returns, factor_returns, period=DAILY, annualization=None)

Determine the information ratio versus a benchmark.

The information ratio is defined as the annualized mean active return divided by the annualized tracking error of the active returns.

参数：

名称	类型	描述	默认
returns	Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	Series or DataFrame	Non-cumulative benchmark or factor returns, aligned to returns.	必需
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float or Series	Information ratio of the strategy versus the benchmark.

cal_treynor_ratio(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate the Treynor ratio of a strategy.

The Treynor ratio is defined as the strategy's annualized excess return divided by its beta with respect to a benchmark:

.. math::

T = \frac{R_p - R_f}{\beta_p}

where :math:R_p is the annualized portfolio return, :math:R_f is the risk-free rate, and :math:\beta_p is the portfolio beta.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative strategy returns.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark or factor returns used to estimate beta.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to annualize returns when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float or ndarray or Series	Treynor ratio. For 1D input a scalar is returned; for 2D input one value is returned per column. Returns NaN when beta is zero, negative, or NaN.

treynor_ratio(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Compute the Treynor ratio.

This is a thin wrapper around :func:cal_treynor_ratio.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative strategy returns.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate. Default is 0.0.	0.0
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float or ndarray or Series	Treynor ratio.

m_squared(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate the Modigliani (M²) measure.

The M² measure scales the portfolio's risk-adjusted performance to the benchmark's volatility. It is defined as:

.. math::

M^2 = (R_p - R_f) \frac{\sigma_b}{\sigma_p} + R_f

where :math:R_p and :math:R_f are the annualized portfolio and risk-free returns, and :math:\sigma_p and :math:\sigma_b are the annualized volatilities of the portfolio and benchmark, respectively.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative strategy returns.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to annualize returns and volatilities when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	M² value of the strategy relative to the benchmark. Returns NaN if the portfolio volatility is zero, negative, or NaN.

sterling_ratio(returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate the Sterling ratio of a strategy.

The Sterling ratio is defined as the annualized excess return divided by the average drawdown. When no explicit drawdowns are detected, this implementation falls back to using downside returns as a proxy for risk.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to annualize returns when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	Sterling ratio of the strategy. Returns np.inf when there is no drawdown risk and excess return is positive; returns NaN when there is no drawdown risk and excess return is non-positive. Downstream consumers should handle np.inf explicitly.

burke_ratio(returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate the Burke ratio of a strategy.

The Burke ratio is defined as the annualized excess return divided by the square root of the sum of squared drawdowns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to annualize returns when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float	Burke ratio of the strategy. Returns np.inf when there is no drawdown risk and excess return is positive; returns NaN when there is no drawdown risk and excess return is non-positive. Downstream consumers should handle np.inf explicitly.

kappa_three_ratio(returns, risk_free=0.0, period=DAILY, annualization=None, mar=0.0)

Calculate the Kappa 3 ratio based on third-order lower partial moment.

The Kappa ratio uses the n-th order Lower Partial Moment (LPM) as the risk measure. For Kappa 3 the formula is:

.. math::

K_3(\tau) = \frac{\mu - \tau}{\sqrt[3]{LPM_3(\tau)}}

where :math:\mu is the arithmetic mean of returns, :math:\tau is the threshold (MAR), and

.. math::

LPM_3(\tau) = \frac{1}{T}\sum_{t=1}^{T}\max(\tau - R_t, 0)^3

Reference

https://breakingdownfinance.com/finance-topics/performance-measurement/kappa-ratio/

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
risk_free	float	Kept for API compatibility. Not used in the current formula. Default is 0.0.	0.0
period	str	Kept for API compatibility. Not used in the current formula.	DAILY
annualization	float	Kept for API compatibility. Not used in the current formula.	None
mar	float	Minimum acceptable return (MAR), used as the threshold :math:\tau in both the numerator and the LPM. Default is 0.0.	0.0

返回：

类型	描述
float	Kappa 3 ratio of the strategy. Returns NaN when there is insufficient data or downside risk is effectively zero.

deflated_sharpe_ratio(returns, risk_free=0, num_trials=1, period=DAILY, annualization=None)

Calculate the Deflated Sharpe Ratio (DSR).

The DSR tests whether the observed Sharpe ratio is statistically significant after correcting for:

1. Non-normality of returns (skewness and kurtosis).
2. Finite sample length.
3. Multiple testing (number of strategies tried).

It is computed in two steps:

Step 1 — Expected maximum Sharpe ratio under the null hypothesis:

.. math::

\widehat{SR}_0 \approx \sqrt{2 \ln N}
- \frac{\ln(\pi) + \ln(\ln N)}{2\sqrt{2 \ln N}}

where N is the number of independent trials (strategies tested).

Step 2 — Probabilistic Sharpe Ratio (PSR) evaluated at :math:SR^* = \widehat{SR}_0:

.. math::

DSR = PSR(SR^*) = \Phi\!\left(
    \frac{(\widehat{SR} - SR^*)\,\sqrt{T-1}}
         {\sqrt{1 - \hat{\gamma}_3\,\widehat{SR}
                + \frac{\hat{\gamma}_4 - 1}{4}\,\widehat{SR}^2}}
\right)

where :math:\widehat{SR} is the observed (non-annualized) Sharpe ratio, T is the sample size, :math:\hat{\gamma}_3 is the sample skewness, :math:\hat{\gamma}_4 is the sample excess kurtosis, and :math:\Phi is the standard-normal CDF.

A DSR close to 1 indicates the observed Sharpe ratio is unlikely to be the result of luck; a DSR close to 0 suggests the opposite.

Reference

• Bailey, D. and M. López de Prado (2014). "The Deflated Sharpe Ratio: Correcting for Selection Bias, Backtest Over-fitting, and Non-Normality." Journal of Portfolio Management, 40(5), 94–107.
• https://en.wikipedia.org/wiki/Deflated_Sharpe_ratio

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
risk_free	float	Per-period risk-free rate. Default is 0.	0
num_trials	int	Number of independent strategy trials (backtests) that were conducted. Used to estimate the expected maximum Sharpe ratio under the null. Default is 1 (no multiple-testing correction).	1
period	str	Kept for API consistency. Not used in the current formula since the DSR operates on per-period (non-annualized) Sharpe ratios.	DAILY
annualization	float	Kept for API consistency. Not used in the current formula.	None

返回：

类型	描述
float	The Deflated Sharpe Ratio, a probability in [0, 1]. Returns NaN if there are fewer than 3 observations.

common_sense_ratio(returns)

Calculate the common sense ratio.

The common sense ratio combines the tail ratio with the win rate to provide a measure of the risk-reward profile of a strategy.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Common sense ratio. Returns NaN if there are insufficient observations or if win rate is zero.

stability_of_timeseries(returns)

Determine the R-squared of a linear fit to cumulative log returns.

This computes the coefficient of determination (R^2) from a linear regression of the cumulative log returns against time. Higher values indicate a more stable (less noisy) growth profile.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
float	R-squared of the linear fit to cumulative log returns. Returns NaN if there are fewer than two valid observations.

capture(returns, factor_returns, period=DAILY)

Calculate the capture ratio versus a benchmark.

The capture ratio is defined as the strategy's annualized return divided by the benchmark's annualized return over the same period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data (for example DAILY). Used to annualize both strategy and benchmark returns.	DAILY

返回：

类型	描述
float	Capture ratio (strategy annualized return divided by benchmark annualized return). Returns NaN if there are insufficient observations or the benchmark annualized return is zero.

up_capture(returns, factor_returns, period=DAILY)

Calculate the capture ratio for up-market periods.

The up-capture ratio is defined as the capture ratio computed using only those periods where the benchmark (factor) return is positive.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data (for example DAILY).	DAILY

返回：

类型	描述
float	Up-capture ratio of the strategy relative to the benchmark. Returns NaN if there are no positive benchmark periods.

down_capture(returns, factor_returns, period=DAILY)

Calculate the capture ratio for down-market periods.

The down-capture ratio is defined as the capture ratio computed using only those periods where the benchmark (factor) return is negative.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data (for example DAILY).	DAILY

返回：

类型	描述
float	Down-capture ratio of the strategy relative to the benchmark. Returns NaN if there are no negative benchmark periods.

up_down_capture(returns, factor_returns, period=DAILY)

Calculate the ratio of up-capture to down-capture.

This computes up_capture / down_capture using :func:up_capture and :func:down_capture.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data (for example DAILY).	DAILY

返回：

类型	描述
float	Ratio of up-capture to down-capture. Returns NaN if either capture is NaN or if the down-capture is zero.

up_capture_return(returns, factor_returns, period=DAILY, annualization=None)

Calculate the annualized return during up-market periods.

This computes the annualized return of the strategy using only those periods where the benchmark return is positive.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float	Annualized strategy return during up-market periods, or NaN if there are no positive benchmark periods.

down_capture_return(returns, factor_returns, period=DAILY, annualization=None)

Calculate the annualized return during down-market periods.

This computes the annualized return of the strategy using only those periods where the benchmark return is negative.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float	Annualized strategy return during down-market periods, or NaN if there are no negative benchmark periods.

Alpha & Beta

fincore.metrics.alpha_beta

Alpha/beta related metrics.

beta_aligned(returns, factor_returns, risk_free=0.0, out=None)

Calculate beta for already-aligned data.

This function assumes that returns and factor_returns are already aligned NumPy arrays (or array-like) with matching shapes along the time dimension. Beta is estimated using the covariance of excess returns divided by the variance of excess factor returns.

参数：

名称	类型	描述	默认
returns	ndarray	Array of non-cumulative strategy returns. The first dimension is interpreted as time; any remaining dimensions correspond to different assets/strategies.	必需
factor_returns	ndarray	Array of non-cumulative benchmark or factor returns, aligned with returns along the time dimension.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray	Beta of the strategy versus the benchmark. For 1D input a scalar is returned; for 2D input one value is returned per column.

alpha_aligned(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None, _beta=None)

Calculate annualized alpha for already-aligned series.

This function assumes that returns and factor_returns are already aligned NumPy arrays (or array-like) with matching shapes along the time dimension.

参数：

名称	类型	描述	默认
returns	ndarray	Array of non-cumulative strategy returns. The first dimension is interpreted as time; any remaining dimensions correspond to different assets/strategies.	必需
factor_returns	ndarray	Array of non-cumulative benchmark or factor returns, aligned with returns along the time dimension.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None
_beta	float or ndarray	pre-computed beta used to avoid recomputing beta internally.	None

返回：

类型	描述
float or ndarray or Series	Annualized alpha of the strategy versus the benchmark. For 1D input a scalar is returned; for higher-dimensional input one value is returned per series.

alpha_beta_aligned(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None)

Calculate annualized alpha and beta for already-aligned series.

This function assumes that returns and factor_returns are already aligned NumPy arrays (or array-like) with matching shapes along the time dimension.

参数：

名称	类型	描述	默认
returns	ndarray	Array of non-cumulative strategy returns. The first dimension is interpreted as time; any remaining dimensions correspond to different assets/strategies.	必需
factor_returns	ndarray	Array of non-cumulative benchmark or factor returns, aligned with returns along the time dimension.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array of shape returns.shape[1:] + (2),. If given, the result is written in-place into this array.	None

返回：

类型	描述
ndarray	Array of shape returns.shape[1:] + (2), whose last dimension contains [alpha, beta].

beta(returns, factor_returns, risk_free=0.0, _period=DAILY, _annualization=None, out=None)

Calculate beta versus a benchmark.

This mirrors empyrical.stats.beta: non-ndarray inputs are first aligned, then :func:beta_aligned is called to compute the beta.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series or DataFrame	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
_period	str	Deprecated. Kept for API compatibility and ignored.	DAILY
_annualization	float	Deprecated. Kept for API compatibility and ignored.	None
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
float or ndarray or Series	Beta of the strategy versus the benchmark. For 1D input a scalar is returned; for 2D input one value is returned per column.

alpha(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None, _beta=None)

Calculate annualized alpha versus a benchmark.

This mirrors empyrical.stats.alpha: non-ndarray inputs are first aligned, then :func:alpha_aligned is called to compute the annualized alpha.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series or DataFrame	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None
_beta	float or ndarray	pre-computed beta used to avoid recomputing beta internally. Primarily intended for internal reuse.	None

返回：

类型	描述
float or ndarray or Series	Annualized alpha of the strategy versus the benchmark. For 1D input a scalar is returned; for 2D input one value is returned per column.

alpha_beta(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None)

Calculate annualized alpha and beta versus a benchmark.

This is a convenience wrapper that aligns returns and factor_returns (if they are not already NumPy arrays) and then delegates to :func:alpha_beta_aligned.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series or DataFrame	Non-cumulative benchmark or factor returns, aligned to returns after preprocessing.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated output array. If given, the result is written in-place into this array.	None

返回：

类型	描述
ndarray	Array of shape (..., 2) containing annualized alpha and beta in the last dimension. For 1D inputs this is length-2; for 2D inputs it has one row per column of returns.

up_alpha_beta(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None)

Calculate alpha and beta for up-market periods only.

This helper restricts the sample to periods where the benchmark (factor) return is positive and then estimates alpha and beta using a single-factor model on excess returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY).	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated array of length 2, where index 0 receives alpha and index 1 receives beta.	None

返回：

类型	描述
ndarray	Array [alpha, beta] for up-market periods. Elements are NaN if there is insufficient data.

down_alpha_beta(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None, out=None)

Calculate alpha and beta for down-market periods only.

This helper restricts the sample to periods where the benchmark (factor) return is non-positive and then estimates alpha and beta using a single-factor model on excess returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY).	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None
out	ndarray	pre-allocated array of length 2, where index 0 receives alpha and index 1 receives beta.	None

返回：

类型	描述
ndarray	Array [alpha, beta] for down-market periods. Elements are NaN if there is insufficient data.

annual_alpha(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Determine the annual alpha for each calendar year.

This groups aligned strategy and benchmark returns by calendar year and computes :func:alpha for each year.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns indexed by date.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns indexed by date.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY).	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
Series	Annual alpha by calendar year.

annual_beta(returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Determine the annual beta for each calendar year.

This groups aligned strategy and benchmark returns by calendar year and computes :func:beta for each year.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns indexed by date.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns indexed by date.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0
period	str	Frequency of the input data (for example DAILY).	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
Series	Annual beta by calendar year.

alpha_percentile_rank(strategy_returns, all_strategies_returns, factor_returns, risk_free=0.0, period=DAILY, annualization=None)

Calculate the percentile rank of alpha versus a peer universe.

This computes the strategy's alpha and compares it to the alphas of all peer strategies, returning the percentile rank.

参数：

名称	类型	描述	默认
strategy_returns	Series	Non-cumulative returns of the strategy being evaluated.	必需
all_strategies_returns	list of pd.Series	Non-cumulative returns of all peer strategies.	必需
factor_returns	Series	Non-cumulative benchmark or factor returns.	必需
risk_free	float	Risk-free rate (default 0.0).	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
float	Percentile rank of the strategy's alpha in [0, 1], or NaN if insufficient data.

Rolling

fincore.metrics.rolling

Rolling-window metrics.

roll_alpha(returns, factor_returns, window=252, risk_free=0.0, period=DAILY, annualization=None)

Calculate rolling alpha over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns to calculate alpha against.	必需
window	int	Length of the rolling window (default 252).	252
risk_free	float	Risk-free rate (default 0.0).	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Rolling alpha values.

roll_beta(returns, factor_returns, window=252, risk_free=0.0, period=DAILY, annualization=None)

Calculate rolling beta over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns to calculate beta against.	必需
window	int	Length of the rolling window (default 252).	252
risk_free	float	Risk-free rate (default 0.0).	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Rolling beta values.

roll_alpha_beta(returns, factor_returns, window=252, risk_free=0.0, period=DAILY, annualization=None)

Calculate rolling alpha and beta over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns to calculate alpha and beta against.	必需
window	int	Length of the rolling window (default 252).	252
risk_free	float	Risk-free rate (default 0.0).	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
DataFrame or ndarray	Rolling alpha and beta values with columns ['alpha', 'beta'].

roll_sharpe_ratio(returns, window=252, risk_free=0.0, period=DAILY, annualization=None)

Calculate rolling Sharpe ratio over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
window	int	Length of the rolling window (default 252).	252
risk_free	float	Risk-free rate (default 0.0).	0.0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Rolling Sharpe ratio values.

roll_max_drawdown(returns, window=252)

Calculate rolling maximum drawdown over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
window	int	Length of the rolling window (default 252).	252

返回：

类型	描述
Series or ndarray	Rolling maximum drawdown values.

roll_up_capture(returns, factor_returns, window=252)

Calculate rolling up capture over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns.	必需
window	int	Length of the rolling window (default 252).	252

返回：

类型	描述
Series or ndarray	Rolling up capture values.

roll_down_capture(returns, factor_returns, window=252)

Calculate rolling down capture over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns.	必需
window	int	Length of the rolling window (default 252).	252

返回：

类型	描述
Series or ndarray	Rolling down capture values.

roll_up_down_capture(returns, factor_returns, window=252)

Calculate rolling up/down capture ratio over a specified window.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns of the strategy.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns.	必需
window	int	Length of the rolling window (default 252).	252

返回：

类型	描述
Series or ndarray	Rolling up/down capture ratio values.

rolling_volatility(returns, rolling_vol_window, period=DAILY, annualization=None)

Determine the rolling volatility of a strategy.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns of the strategy.	必需
rolling_vol_window	int	Length of the rolling window.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
Series	Rolling volatility, annualized.

rolling_sharpe(returns, rolling_sharpe_window, period=DAILY, annualization=None)

Determine the rolling Sharpe ratio of a strategy.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns of the strategy.	必需
rolling_sharpe_window	int	Length of the rolling window.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
Series	Rolling Sharpe ratio, annualized.

rolling_beta(returns, factor_returns, rolling_window=126)

Calculate rolling beta.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
factor_returns	Series or DataFrame	Daily noncumulative returns of the benchmark factor.	必需
rolling_window	int	The size of the rolling window, in days (default 126).	126

返回：

类型	描述
Series	Rolling beta.

rolling_regression(returns, factor_returns, rolling_window=126)

Calculate rolling regression alpha and beta.

Note: The alpha returned here is the non-annualized (daily-frequency) regression intercept, unlike roll_alpha which returns annualized alpha. To annualize, multiply by the appropriate annualization factor (e.g. 252 for daily data).

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
factor_returns	Series	Daily returns of the benchmark factor.	必需
rolling_window	int	Length of the rolling window (default 126).	126

返回：

类型	描述
DataFrame	Rolling alpha (non-annualized) and beta values with columns ['alpha', 'beta'].

Statistics

fincore.metrics.stats

Statistical metrics.

skewness(returns)

Calculate the skewness of a return series.

This is a thin wrapper around :func:scipy.stats.skew with nan_policy="omit".

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
float	Sample skewness of the return distribution, or NaN if there are fewer than three observations.

kurtosis(returns)

Calculate the kurtosis of a return series.

This is a thin wrapper around :func:scipy.stats.kurtosis with nan_policy="omit".

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
float	Sample excess kurtosis of the return distribution, or NaN if there are fewer than four observations.

hurst_exponent(returns)

Estimate the Hurst exponent of a return series.

The Hurst exponent is estimated via a rescaled range (R/S) analysis with safeguards for short and noisy series. Values near 0.5 indicate a random walk; values above 0.5 suggest persistence; values below 0.5 suggest mean reversion.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative returns.	必需

返回：

类型	描述
float	Estimated Hurst exponent in the interval [0, 1], or NaN when there is insufficient data.

stutzer_index(returns, target_return=0.0)

Calculate the Stutzer index.

The Stutzer index is a downside-risk-adjusted performance measure based on an exponential tilting of the return distribution.

Formula

I_P = max_θ { -log(mean(exp(θ × r_t))) } Stutzer = (|r̄| / r̄) × sqrt(2 × I_P)

where r_t are the excess returns and r̄ is their mean.

Reference: Stutzer, M. (2000). "A Portfolio Performance Index." Financial Analysts Journal, 56(3), 52-61.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
target_return	float	Target or benchmark return used to compute excess returns.	0.0

返回：

类型	描述
float	Stutzer index estimate, or NaN if the optimization fails or there is insufficient data.

serial_correlation(returns, lag=1)

Determine the serial correlation of returns.

This computes the correlation between r[t] and r[t-lag].

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
lag	int	Number of periods to lag. Default is 1.	1

返回：

类型	描述
float	Pearson correlation coefficient between returns and lagged returns, or NaN if there are fewer than lag + 1 valid observations.

stock_market_correlation(returns, market_returns)

Determine the correlation between strategy and stock market returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
market_returns	array - like or Series	Non-cumulative stock market (benchmark) returns.	必需

返回：

类型	描述
float	Pearson correlation coefficient in [-1, 1] between strategy and market returns, or NaN if there are fewer than two valid observations.

bond_market_correlation(returns, bond_returns)

Determine the correlation between strategy and bond market returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
bond_returns	array - like or Series	Non-cumulative bond market benchmark returns.	必需

返回：

类型	描述
float	Pearson correlation coefficient in [-1, 1] between strategy and bond market returns, or NaN if there are fewer than two valid observations.

futures_market_correlation(returns, futures_returns)

Determine the correlation between strategy and futures market returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
futures_returns	array - like or Series	Non-cumulative futures market benchmark returns.	必需

返回：

类型	描述
float	Pearson correlation coefficient in [-1, 1] between strategy and futures market returns, or NaN if there are fewer than two valid observations.

win_rate(returns)

Calculate the percentage of positive return observations.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Fraction of observations with strictly positive returns in [0, 1], or NaN if there are no valid observations.

loss_rate(returns)

Calculate the percentage of negative return observations.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Fraction of observations with strictly negative returns in [0, 1], or NaN if there are no valid observations.

relative_win_rate(returns, factor_returns)

Calculate the win rate of strategy returns relative to a benchmark.

The relative win rate is the fraction of periods where the strategy return exceeds the benchmark return.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark returns.	必需

返回：

类型	描述
float	Fraction of observations where returns > factor_returns in [0, 1], or NaN if there are no valid observations.

r_cubed(returns, factor_returns)

Calculate the R-cubed (R³) measure.

R³ is defined as the cube of the correlation between strategy returns and benchmark returns.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需

返回：

类型	描述
float	Cube of the Pearson correlation coefficient, or NaN if there is insufficient data.

r_cubed_turtle(returns, period=DAILY, annualization=None)

Calculate the R-cubed measure from the Turtle Trading system.

R³ (turtle) is defined as the Regression Annual Return (RAR) divided by the average maximum annual drawdown.

RAR is the slope of a linear regression of cumulative NAV against time, annualized.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
period	str	Frequency of the input data. Default is DAILY.	DAILY
annualization	float	Custom annualization factor.	None

返回：

类型	描述
float	R³ turtle measure, or NaN if insufficient data.

capm_r_squared(returns, factor_returns)

Calculate the CAPM R-squared.

R² = (β × σ_B / σ_P)², measuring the proportion of strategy return variance explained by market (systematic) risk.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需

返回：

类型	描述
float	CAPM R-squared in [0, 1], or NaN if insufficient data.

tracking_difference(returns, factor_returns)

Calculate tracking difference in cumulative returns.

Tracking difference is defined as the cumulative strategy return minus the cumulative benchmark return over the full sample.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or factor returns.	必需

返回：

类型	描述
float	Difference between cumulative strategy and benchmark returns.

common_sense_ratio(returns)

Calculate the common sense ratio.

Delegates to :func:fincore.metrics.ratios.common_sense_ratio.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需

返回：

类型	描述
float	Common sense ratio, or NaN if there is insufficient data.

var_cov_var_normal(p, c, mu=0, sigma=1)

Calculate variance-covariance of daily Value-at-Risk in a portfolio.

Delegates to :func:fincore.metrics.risk.var_cov_var_normal.

参数：

名称	类型	描述	默认
p	float	Portfolio value.	必需
c	float	Confidence level.	必需
mu	float	Mean. Default is 0.	0
sigma	float	Standard deviation. Default is 1.	1

返回：

类型	描述
float	Value-at-Risk.

normalize(returns, starting_value=1)

Normalize a returns series to start at a given value.

Delegates to :func:fincore.metrics.returns.normalize.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
starting_value	float	Starting value for the normalized series. Default is 1.	1

返回：

类型	描述
Series or ndarray	Normalized cumulative returns starting at starting_value.

Performance Stats

fincore.metrics.perf_stats

Performance statistics (summary tables, bootstrap stats, etc.).

perf_stats(returns, factor_returns=None, positions=None, transactions=None, turnover_denom='AGB', period=DAILY)

Calculate various performance metrics of a strategy.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
factor_returns	Series	Daily noncumulative returns of the benchmark factor to which betas are computed. Usually a benchmark such as market returns.	None
positions	DataFrame	Daily net position values.	None
transactions	DataFrame	Prices and amounts of executed trades. One row per trade.	None
turnover_denom	str	Either 'AGB' or 'portfolio_value', default 'AGB'.	'AGB'
period	str	Frequency of the input data (for example DAILY).	DAILY

返回：

类型	描述
Series	Performance metrics.

perf_stats_bootstrap(returns, factor_returns=None, return_stats=True, **_kwargs)

Calculate various bootstrapped performance metrics of a strategy.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需
factor_returns	Series	Daily noncumulative returns of the benchmark factor to which betas are computed. Usually a benchmark such as market returns.	None
return_stats	bool	If True, returns a DataFrame of mean, median, 5 and 95 percentiles for each perf metric. If False, return a DataFrame with the bootstrap samples for each perf metric.	True

返回：

类型	描述
DataFrame	if return_stats is True: - Distributional statistics of bootstrapped sampling distribution of performance metrics. If return_stats is False: - Bootstrap samples for each performance metric.

calc_bootstrap(func, returns, *args, **kwargs)

Perform a bootstrap analysis on a user-defined function returning a summary statistic.

参数：

名称	类型	描述	默认
func	callable	Function that either takes a single array (commonly returns) or two arrays (for example returns and factor_returns) and returns a single summary value.	必需
returns	Series	Daily returns of the strategy, noncumulative.	必需
n_samples	int	Number of bootstrap samples to draw. Default is 1000.	必需
random_seed	int	Seed for the pseudorandom number generator to make results reproducible. Default is None (non-deterministic).	必需
kwargs	dict	Additional keyword arguments forwarded to func. For factor-based statistics this often includes factor_returns.	{}

返回：

类型	描述
ndarray	Bootstrapped sampling distribution of passed in func.

calc_distribution_stats(x)

Calculate various summary statistics of data.

参数：

名称	类型	描述	默认
x	ndarray or Series	Array to compute summary statistics for.	必需

返回：

类型	描述
Series	Series containing mean, median, std, as well as 5, 25, 75 and 95 percentiles of passed in values.

Yearly

fincore.metrics.yearly

Yearly aggregation metrics.

annual_return(returns, period=DAILY, annualization=None)

Determine the mean annual growth rate of returns (CAGR).

This is effectively the compound annual growth rate assuming reinvestment of returns.

参数：

名称	类型	描述	默认
returns	array - like or Series or DataFrame	Non-cumulative simple returns.	必需
period	str	Frequency of the input data (for example DAILY). Used to infer the annualization factor when annualization is None.	DAILY
annualization	float	Custom annualization factor. If provided, this value is used directly instead of inferring it from period.	None

返回：

类型	描述
float or ndarray or Series	Annualized return. For 1D input a scalar is returned; for 2D input one value is returned per column.

annual_return_by_year(returns, period=DAILY, annualization=None)

Determine the annual return for each calendar year.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns indexed by date.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Annual return for each calendar year.

sharpe_ratio_by_year(returns, risk_free=0, period=DAILY, annualization=None)

Determine the Sharpe ratio for each calendar year.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns indexed by date.	必需
risk_free	float	Risk-free rate (default 0).	0
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Sharpe ratio for each calendar year.

max_drawdown_by_year(returns)

Determine the maximum drawdown for each calendar year.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Series or ndarray	Maximum drawdown for each calendar year.

annual_volatility_by_year(returns, period=DAILY, annualization=None)

Determine the annual volatility for each calendar year.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative returns indexed by date.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Annualized volatility for each calendar year.

annual_active_return(returns, factor_returns, period=DAILY, annualization=None)

Calculate annual active return (strategy minus benchmark).

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative strategy returns.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
float	Annual active return, or NaN if insufficient data.

annual_active_return_by_year(returns, factor_returns, period=DAILY, annualization=None)

Determine the annual active return for each calendar year.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative strategy returns indexed by date.	必需
factor_returns	Series	Non-cumulative benchmark returns indexed by date.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series	Annual active return for each calendar year.

information_ratio_by_year(returns, factor_returns, period=DAILY, annualization=None)

Determine the information ratio for each calendar year.

参数：

名称	类型	描述	默认
returns	Series or ndarray	Non-cumulative strategy returns indexed by date.	必需
factor_returns	Series or ndarray	Non-cumulative benchmark returns indexed by date.	必需
period	str	Frequency of the returns (default 'daily').	DAILY
annualization	int	Factor to convert period returns to yearly returns.	None

返回：

类型	描述
Series or ndarray	Information ratio for each calendar year.

Timing

fincore.metrics.timing

Market timing metrics.

treynor_mazuy_timing(returns, factor_returns, risk_free=0.0)

Calculate the Treynor–Mazuy market timing coefficient (gamma).

This fits a quadratic regression of excess strategy returns on excess factor returns and uses the coefficient on the squared factor term as a measure of market timing ability.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or market returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0

返回：

类型	描述
float	Treynor–Mazuy timing coefficient (gamma), or NaN if there is insufficient data.

henriksson_merton_timing(returns, factor_returns, risk_free=0.0)

Calculate the Henriksson–Merton market timing coefficient.

This fits a regression of excess strategy returns on excess factor returns and a down-market dummy, using the coefficient on the dummy as a measure of market timing.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or market returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0

返回：

类型	描述
float	Henriksson–Merton timing coefficient, or NaN if there is insufficient data.

market_timing_return(returns, factor_returns, risk_free=0.0)

Calculate the market timing return component.

Given the Treynor–Mazuy timing coefficient, this computes the portion of returns attributable to market timing as gamma * E[(R_m - R_f)^2].

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or market returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0

返回：

类型	描述
float	Estimated contribution of market timing to returns, or NaN if the timing coefficient cannot be estimated.

cornell_timing(returns, factor_returns, risk_free=0.0)

Calculate the Cornell timing model coefficient.

The Cornell timing model decomposes market returns into positive and negative components and estimates different betas in up and down markets. The timing coefficient is the difference between these two betas.

参数：

名称	类型	描述	默认
returns	array - like or Series	Non-cumulative strategy returns.	必需
factor_returns	array - like or Series	Non-cumulative benchmark or market returns.	必需
risk_free	float	Risk-free rate used when computing excess returns. Default is 0.0.	0.0

返回：

类型	描述
float	Cornell timing coefficient (beta_up - beta_down), or NaN if there is insufficient data.

extract_interesting_date_ranges(returns)

Extract returns based on interesting events.

参数：

名称	类型	描述	默认
returns	Series	Daily returns of the strategy, noncumulative.	必需

返回：

名称	类型	描述
ranges	OrderedDict	Date ranges, with returns, of all valid events.

Consecutive

fincore.metrics.consecutive

Consecutive up/down metrics.

consecutive_stats(returns)

Compute all consecutive up/down metrics in one pass.

This avoids redundant resample operations when computing multiple consecutive indicators for the same return series.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative daily returns.	必需

返回：

类型	描述
dict	Dictionary with keys for all consecutive metrics.

max_consecutive_up_days(returns)

Determine the maximum number of consecutive days with positive returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative daily returns with a pandas index.	必需

返回：

类型	描述
int or float	Length (in days) of the longest run of strictly positive daily returns, or NaN if the input is empty.

max_consecutive_down_days(returns)

Determine the maximum number of consecutive days with negative returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative daily returns with a pandas index.	必需

返回：

类型	描述
int or float	Length (in days) of the longest run of strictly negative daily returns, or NaN if the input is empty.

max_consecutive_gain(returns)

Determine the maximum cumulative gain over consecutive positive days.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative daily returns with a pandas index.	必需

返回：

类型	描述
float	Maximum sum of returns over any contiguous block of strictly positive-return days, or NaN if there are no positive days.

max_consecutive_loss(returns)

Determine the maximum cumulative loss over consecutive negative days.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative daily returns with a pandas index.	必需

返回：

类型	描述
float	Minimum (most negative) sum of returns over any contiguous block of strictly negative-return days, or NaN if there are no negative days.

max_consecutive_up_weeks(returns)

Determine the maximum number of consecutive weeks with positive returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
int or float	Length (in weeks) of the longest run of strictly positive weekly returns, or NaN if the input is empty.

max_consecutive_down_weeks(returns)

Determine the maximum number of consecutive weeks with negative returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
int or float	Length (in weeks) of the longest run of strictly negative weekly returns, or NaN if the input is empty.

max_consecutive_up_months(returns)

Determine the maximum number of consecutive months with positive returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
int or float	Length (in months) of the longest run of strictly positive monthly returns, or NaN if the input is empty.

max_consecutive_down_months(returns)

Determine the maximum number of consecutive months with negative returns.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
int or float	Length (in months) of the longest run of strictly negative monthly returns, or NaN if the input is empty.

max_single_day_gain(returns)

Determine the maximum single-day gain.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
float	Maximum single-day return, or NaN if the input is empty.

max_single_day_loss(returns)

Determine the maximum single-day loss.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
float	Minimum (most negative) single-day return, or NaN if the input is empty.

max_single_day_gain_date(returns)

Determine the date of the maximum single-day gain.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	Date of the maximum single-day gain, or None if the input is empty.

max_single_day_loss_date(returns)

Determine the date of the maximum single-day loss.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	Date of the maximum single-day loss, or None if the input is empty.

max_consecutive_up_start_date(returns)

Determine the start date of the longest consecutive up period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	Start date of the longest run of strictly positive returns, or None if there are no positive returns.

max_consecutive_up_end_date(returns)

Determine the end date of the longest consecutive up period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	End date of the longest run of strictly positive returns, or None if there are no positive returns.

max_consecutive_down_start_date(returns)

Determine the start date of the longest consecutive down period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	Start date of the longest run of strictly negative returns, or None if there are no negative returns.

max_consecutive_down_end_date(returns)

Determine the end date of the longest consecutive down period.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative returns indexed by date.	必需

返回：

类型	描述
Timestamp or None	End date of the longest run of strictly negative returns, or None if there are no negative returns.