analyze

Files (24)

• SKILL.md
• __init__.py
• attribution_core.py
• attribution_counterfactual.py
• attribution_decision.py
• attribution_factor.py
• attribution_ledger.py
• attribution_ranking.py
• attribution_robustness.py
• attribution_shapley.py
• attribution_stat_tests.py
• causality.py
• content_fingerprint.py
• contracts.py
• facade.py
• factor_analysis.py
• factor_evaluation.py
• factor_incremental.py
• factor_information.py
• factor_robustness.py
• spec_checks.py
• tearsheet.py
• ts_analysis.py
• validation.py

SKILL.md (first lines)

# Analyze

Analyze is the research diagnostics boundary. Use it to understand factors,
returns, attribution, robustness, and time-series behavior after data and
signals have been produced. Strategy execution and portfolio construction live
in `skills.backtest`.

`AnalyzeFacade` is the deterministic entrypoint for factor-mining preflight,
evaluation, and explicit pool comparison. The facade is read-only (no implicit
I/O), fails fast on hard preflight/alignment/causality failures before return
evaluation, and returns analyze-native structured results. Formal portfolio
returns and costs call `skills.backtest.VectorBacktester` by default;
`AnalyzeFacade(backtester_factory=...)` can substitute the engine for `evaluate`,
while the formal pool pair always uses `VectorBacktester`.

`skills.analyze` must not import `skills.factor_mining`, `strategies`, report
rendering, controller/role/workflow code, or LLM SDKs; only `tearsheet.py` reads
the store workspace paths (for its default output directory).

Install plotting and parallel-analysis dependencies with
`uv sync --extra analyze`.

## Public API

```python
from skills.analyze import AnalyzeFacade, ProtocolSnapshot, SpecSnapshot
from skills.analyze.factor_analysis import IC_stat, group_stat, full_stat
from skills.analyze.factor_information import (
    ICInformationResult,
    compute_horizon_ic,
    compute_ic_information_surface,
    compute_lagged_ic,
    rolling_factor_rank_correlation,
)
from skills.analyze.ts_analysis import TimeSeriesAnalyzer, analyze_time_series
from skills.analyze.attribution_counterfactual import performance_metrics
```

## Components

| Module family | Purpose |
|---------------|---------|
| `facade` / `contracts` | Deterministic entrypoint and analyze-native snapshots |
| `validation` / `spec_checks` / `causality` | Panel, formula structure, parameter, and prefix-causality checks |
| `factor_evaluation` / `factor_robustness` / `factor_incremental` | IC/quantiles/turnover, robustness, pool incremental |
| `factor_analysis` | IC statistics, grouped returns, winsorization helpers |
| `factor_information` | Horizon/Lag IC surfaces, HAC summaries, rank correlation, rolling correlation, and Top-N overlap |
| `ts_analysis` | KDE/QQ plots, Hurst, ADF, KPSS, trend scoring |
| `attribution_*` | Symbol/category PnL, Brinson, decision edges, ranking buckets, Shapley, robustness, stat tests |
| `tearsheet` | Single-factor four-panel PNG tearsheet |

## Recipes

**Deterministic factor-mining evaluation (via the factor_mining adapter)**

```python
from skills.analyze import AnalyzeFacade
from skills.factor_mining.adapters.analyze import (
    AnalyzeAdapter,
    build_prefix_recompute_capability,
)

# Official issuer signature: FactorSpec + optional verified FactorExecutionResult.
# Preflight (no execution): build_prefix_recompute_capability(factor=spec)
# Evaluate: build_prefix_recompute_capability(factor=spec, execution=execution)
# AnalyzeAdapter.preflight / evaluate wire this automatically.
# The snippet below is illustrative (loaders/request omitted); production code
# injects real resolvers and must not treat ellipsis as runnable.

adapter = AnalyzeAdapter(
    facade=AnalyzeFacade(),
    resolve_brief=resolve_brief,
    resolve_factor=resolve_factor,
    resolve_protocol=resolve_protocol,
    resolve_execution=resolve_execution,
    load_series=load_series,
    load_panel=load_panel,
)
preflight_report = adapter.preflight(evaluation_request)
assert preflight_report.failure is None
# After FactorExecutionAdapter.execute(...):
eval_report = adapter.evaluate(evaluation_request_with_execution_ref)
assert eval_report.engine_version
```

**Trust boundary (prefix recompute).** `BoundPrefixRecompute` cannot be
constructed publicly. The only production issuer is
`build_prefix_recompute_capability(*, factor: FactorSpec, execution=None)` —
it compiles the exact FactorSpec and optionally checks
`execution.callable_fingerprint`. Analyze does **not** expose a public API that
seals arbitrary callables with hash strings. Process trust boundary: private
helpers remain importable in-process; orchestration policy must only use the
`build_prefix_recompute_capability` adapter builder. Evaluate additionally requires an issued recompute to
reproduce evaluated values (`CAUSALITY_RECOMPUTE_VALUE_MISMATCH`).

`FunctionRef` has no module allowlist. It may point to generated strategy code,
`skills.compute`, or another importable local dependency. Analyze checks the
research contract—fields, parameter/window/lag consistency, output alignment,
and time causality—rather than treating the local Python module as untrusted.

**Trust boundary (formal pool pair).** Portfolio deltas require an officially
issued `FormalBacktestPair` from `run_official_formal_backtest_pair`, which
constructs module `VectorBacktester` twice on explicit before/after target
weights (no caller factory). Issuance is a canonical digest over before/after
`result_df`/`executed_weights` plus panel/candidate/pool/protocol/shared-sample/
target-weight hashes and engine name/version. The pair rejects ordinary
`setattr` after freeze; `is_issued()` recomputes the digest so
`object.__setattr__` tampering invalidates compare. There is no helper that
accepts caller-supplied `BacktestResult` objects as verified.

**Protocol vs Brief authority.** Brief owns horizon/rebalance/cost/universe/
`execution_delay_bars` (mapped to `signal_lag`). `trade_at` and `return_mode`
are Analyze/`ProtocolSnapshot` fields with no Brief counterpart — they are not
silently inferred from Brief; callers must set them on the protocol.

**Execution-aligned labels.** Predictive IC, group returns, and pool residual /
R² use one canonical label: forward `P[t+L+H]/P[t+L]-1` or backward
`P[t+L]/P[t+L-H]-1` on `protocol.trade_at` prices, with `signal_lag=L` and
holding window `horizon_bars=H`. Formal trading asserts the same semantics and

From quantskills/agent-quantspace, GPL-3.0.

More from quantskills/agent-quantspace