fincore.core

AnalysisContext

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

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
normalize_tz	(None, 'UTC')	Explicit timezone normalization for datetime-indexed inputs. Mixed timezones are rejected unless UTC normalization is requested.	None

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).

gross_leverage cached property

Gross leverage series for the stored positions snapshot.

turnover cached property

Turnover series for the stored portfolio and transaction snapshots.

compute(name, *args, **kwargs)

Compute an extension-registered metric by name on the stored returns.

Resolves metrics registered through :func:fincore.plugin.register_metric (default family). The metric receives the stored returns as its first argument, followed by any positional/keyword arguments given here.

引发：

类型	描述
ValueError	If no extension metric with this name is registered.

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(path=None, **kwargs)

Serialize metrics and optionally write the exact payload to path.

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

Plot key performance charts using the specified backend.

参数：

名称	类型	描述	默认
backend	str	Visualization backend name ('matplotlib' or 'html', or a backend registered through :func:fincore.plugin.register_viz_backend).	'matplotlib'

返回：

类型	描述
Depends on the backend (e.g. matplotlib Figure or HTML string).
Custom backends that define ``render(model, **kwargs)`` receive a
class:`~fincore.viz.base.RenderModel` and control the returned
artifacts.

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.

replace_data(*, returns=_UNSET, factor_returns=_UNSET, positions=_UNSET, transactions=_UNSET, period=_UNSET, normalize_tz=_UNSET)

Atomically replace snapshot inputs and invalidate every cached metric.

RollingEngine

fincore.core.engine.RollingEngine(returns, *, factor_returns=None, window=252, period=DAILY)

Batch rolling metric computation engine.

参数：

名称	类型	描述	默认
returns	Series	Non-cumulative simple returns with a DatetimeIndex.	必需
factor_returns	Series	Benchmark returns (required for beta).	None
window	int	Rolling window size. Default 252 (approx. 1 year of daily data).	252
period	str	Data frequency. Default DAILY.	DAILY

available_metrics property

Return the set of metric names supported by this engine.

Sourced from the "rolling" family of the single extension registry — the same store that user extensions register into.

compute(metrics='all')

Compute the requested rolling metrics.

参数：

名称	类型	描述	默认
metrics	list of str or ``'all'``	Which metrics to compute. Pass 'all' to compute every available metric.	'all'

返回：

类型	描述
dict[str, Series]	Mapping from metric name to rolling values.