AnalysisContext

The AnalysisContext provides lazy, cached metric computation with export capabilities.

Basic Usage

import fincore

ctx = fincore.analyze(returns, factor_returns=benchmark)

# Metrics computed on first access, then cached
print(ctx.sharpe_ratio)
print(ctx.max_drawdown)
print(ctx.annual_return)
print(ctx.alpha)
print(ctx.beta)

Performance Stats

stats = ctx.perf_stats()  # pandas Series with all key metrics
print(stats)

Export

# JSON
json_str = ctx.to_json()

# Dictionary
d = ctx.to_dict()

# HTML report (self-contained, no extra dependencies)
ctx.to_html(path="report.html")

API Reference

fincore.core.context.AnalysisContext(returns, *, factor_returns=None, positions=None, transactions=None, period=DAILY)

Lazy, cached container for performance analytics.

All metrics are computed on first access and cached via :func:functools.cached_property. Call :meth:invalidate to clear all cached values (e.g. after replacing the underlying data).

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative simple returns with a DatetimeIndex.	必需
factor_returns	Series	Benchmark / factor returns aligned to the same dates.	None
positions	DataFrame	Daily net position values.	None
transactions	DataFrame	Executed trades.	None
period	str	Data frequency. Default DAILY.	DAILY

Initialize the analysis context.

参数：

名称	类型	描述	默认
returns	Series	Portfolio returns.	必需
factor_returns	Series	Benchmark or factor returns.	None
positions	DataFrame	Portfolio positions.	None
transactions	DataFrame	Executed trades.	None
period	str	Data frequency.	DAILY

annual_return cached property

Annualized return.

cumulative_returns cached property

Total cumulative return.

annual_volatility cached property

Annualized volatility.

sharpe_ratio cached property

Sharpe ratio (annualized).

calmar_ratio cached property

Calmar ratio (annual return / max drawdown).

stability cached property

R-squared of linear fit to cumulative returns.

max_drawdown cached property

Maximum drawdown.

omega_ratio cached property

Omega ratio.

sortino_ratio cached property

Sortino ratio (annualized).

skew cached property

Return skewness.

kurtosis cached property

Return kurtosis.

tail_ratio cached property

Tail ratio (95th percentile / 5th percentile).

daily_value_at_risk cached property

Daily Value at Risk.

alpha cached property

Alpha (excess return over factor returns).

beta cached property

Beta (sensitivity to factor returns).

perf_stats()

Return a :class:pd.Series of key performance metrics.

This method assembles the cached sub-metrics so that repeated calls are essentially free after the first computation.

to_dict()

Return metrics as a plain dict (JSON-friendly values).

to_json(**kwargs)

Serialize metrics to a JSON string.

plot(backend='matplotlib', **kwargs)

Plot key performance charts using the specified backend.

参数：

名称	类型	描述	默认
backend	str	Visualization backend name ('matplotlib' or 'html').	'matplotlib'

返回：

类型	描述
Depends on the backend (e.g. matplotlib Figure or HTML string).

to_html(path=None)

Generate a self-contained HTML performance report.

参数：

名称	类型	描述	默认
path	str	If given, write the HTML to this file path.	None

返回：

类型	描述
str	The HTML report as a string.

invalidate()

Clear all cached metric values.