factrix.MetricOutput dataclass

MetricOutput(name: str, value: float, n_obs: int | None = None, stat: float | None = None, significance: str | None = None, metadata: dict[str, object] = dict())

Return type for factrix.metrics.* primitives.

Parameters:

Name	Type	Description	Default
name	str	Metric identifier (e.g. "ic_ir", "oos_decay").	required
value	float	Raw metric value.	required
n_obs	int | None	Sample size the metric primitive's estimator actually saw. Same family name as FactorProfile.n_obs but a different scope: per-metric single-stage count, vs. the final-stage test denominator at the dispatched-cell level. None for metrics where a single integer count is not meaningful (e.g. multi-window CAAR series).	None
stat	float | None	Test statistic (t, z, W, chi2, ...), when applicable.	None
significance	str | None	*** / ** / * / "" derived from metadata["p_value"] when available.	None
metadata	dict[str, object]	Tool-specific context (p_value, stat_type, h0, method are the standard keys).	dict()

The unified return type produced by every metric in factrix.metrics. A single dataclass carrying the canonical scalar (value), the sample size the estimator saw (n_obs), the test statistic (stat), the significance marker, and a metadata dict for everything else (p-value, method label, short-circuit reason, secondary diagnostics). All metrics — primary or auxiliary — return this shape so downstream code can treat every metric uniformly. n_obs shares its name with FactorProfile.n_obs but a different scope: per-metric single-stage count vs. the final-stage test denominator at the dispatched-cell level.

Resolving MetricOutput.name to a docs page

Downstream consumers holding a MetricOutput can map output.name back to the metric's API page two ways:

• Programmatic — list_metrics(..., format="json") rows carry an emitted_name field (the literal MetricOutput.name value) and a docs_anchor field following the DOCS_ANCHOR_FMT convention defined in factrix._metric_index (docs-root-relative path + mkdocstrings symbol fragment), resolvable without scraping.
• Static — the auto-generated table below maps every emitted MetricOutput.name value to the function that produced it and the API page anchor. Regenerated from the same Matrix-row: SSOT on every docs build.

For most metrics MetricOutput.name equals the function name; a small set of historical exceptions (e.g. fama_macbeth emits fm_beta, corrado_rank_test emits corrado_rank) emit a different label. The first column is what you receive at runtime; the second column is the import-path callable.

MetricOutput.name	Function	Source module	API page
beta_sign_consistency	beta_sign_consistency	factrix.metrics.fama_macbeth	beta_sign_consistency
bmp_test	bmp_test	factrix.metrics.caar	bmp_test
breakeven_cost	breakeven_cost	factrix.metrics.tradability	breakeven_cost
caar	caar	factrix.metrics.caar	caar
clustering_hhi	clustering_diagnostic	factrix.metrics.clustering	clustering_diagnostic
compute_rolling_mean_beta	compute_rolling_mean_beta	factrix.metrics.ts_beta	compute_rolling_mean_beta
corrado_rank	corrado_rank_test	factrix.metrics.corrado	corrado_rank_test
event_around_return	event_around_return	factrix.metrics.event_horizon	event_around_return
event_hit_rate	event_hit_rate	factrix.metrics.event_quality	event_hit_rate
event_ic	event_ic	factrix.metrics.event_quality	event_ic
event_skewness	event_skewness	factrix.metrics.event_quality	event_skewness
fm_beta	fama_macbeth	factrix.metrics.fama_macbeth	fama_macbeth
greedy_forward_selection	greedy_forward_selection	factrix.metrics.spanning	greedy_forward_selection
hit_rate	hit_rate	factrix.metrics.hit_rate	hit_rate
ic	ic	factrix.metrics.ic	ic
ic_ir	ic_ir	factrix.metrics.ic	ic_ir
ic_newey_west	ic_newey_west	factrix.metrics.ic	ic_newey_west
ic_trend	ic_trend	factrix.metrics.trend	ic_trend
mean_r_squared	mean_r_squared	factrix.metrics.ts_beta	mean_r_squared
mfe_mae_summary	mfe_mae_summary	factrix.metrics.mfe_mae	mfe_mae_summary
monotonicity	monotonicity	factrix.metrics.monotonicity	monotonicity
net_spread	net_spread	factrix.metrics.tradability	net_spread
notional_turnover	notional_turnover	factrix.metrics.tradability	notional_turnover
oos_decay	multi_split_oos_decay	factrix.metrics.oos	multi_split_oos_decay
pooled_beta	pooled_ols	factrix.metrics.fama_macbeth	pooled_ols
profit_factor	profit_factor	factrix.metrics.event_quality	profit_factor
quantile_spread	quantile_spread	factrix.metrics.quantile	quantile_spread
quantile_spread_vw	quantile_spread_vw	factrix.metrics.quantile	quantile_spread_vw
signal_density	signal_density	factrix.metrics.event_quality	signal_density
spanning_alpha	spanning_alpha	factrix.metrics.spanning	spanning_alpha
top_concentration	top_concentration	factrix.metrics.concentration	top_concentration
ts_asymmetry	ts_asymmetry	factrix.metrics.ts_asymmetry	ts_asymmetry
ts_beta	ts_beta	factrix.metrics.ts_beta	ts_beta
ts_beta_sign_consistency	ts_beta_sign_consistency	factrix.metrics.ts_beta	ts_beta_sign_consistency
ts_quantile_spread	ts_quantile_spread	factrix.metrics.ts_quantile	ts_quantile_spread
turnover	turnover	factrix.metrics.tradability	turnover