alpholio 0.4.0__tar.gz

alpholio-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 myang682
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alpholio-0.4.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# src/alpholio/data/ 下的 S&P 500 序列受数据使用权限制，不得对外分发。
+#
+# pyproject.toml 的 include-package-data=false 只挡住 wheel；sdist 的文件清单由本文件
+# 决定，默认会把包目录内的全部文件一并打包，因此必须在此显式排除。
+# 两处缺一，构建产物就会重新带上该数据。
+prune src/alpholio/data

alpholio-0.4.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: alpholio
+Version: 0.4.0
+Summary: Config-driven cross-sectional portfolio backtesting toolkit
+Author: myang682
+License: MIT
+Project-URL: Homepage, https://github.com/mzyang-code/alpholio
+Project-URL: Documentation, https://mzyang-code.github.io/alpholio/
+Project-URL: Source, https://github.com/mzyang-code/alpholio
+Project-URL: Issues, https://github.com/mzyang-code/alpholio/issues
+Keywords: quant,portfolio,backtest,cross-section,finance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyarrow>=10.0
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: jieba>=0.42; extra == "docs"
+Dynamic: license-file
+
+# alpholio
+
+Cross-sectional portfolio backtesting. The toolkit consumes alpha and handles bucketing,
+weighting, metrics and charts.
+
+**📖 [Documentation](https://mzyang-code.github.io/alpholio/)** (Chinese) ｜ [简体中文 README](https://github.com/mzyang-code/alpholio/blob/main/README.zh-CN.md)
+
+Four modules, one direction of data flow. Each module owns a single public entry point,
+so any stage can be swapped without touching the others.
+
+```
+InputProcessor ──InputBundle──▶ PortfolioEngine ──EngineResult──▶ Analyzer ──AnalysisResult──▶ Visualizer ──▶ PNG / CSV
+```
+
+The toolkit consumes alpha only — it never generates signals. Price-based factors such as
+MOM / STR / WSTR are ordinary inputs; see the
+[daily MOM example](https://mzyang-code.github.io/alpholio/examples/daily-mom/) for one
+worked end to end.
+
+## Install
+
+```bash
+pip install alpholio
+```
+
+Working from a clone instead:
+
+```bash
+pip install -e .                      # compatible ranges
+pip install -e ".[docs]"              # adds the documentation site toolchain
+```
+
+To reproduce the exact verified combination (Python 3.12.2):
+
+```bash
+conda env create -f environment.yml
+conda activate alpholio
+pip install -e .
+```
+
+## Quick start
+
+Factor and price tables go in as DataFrames — no need to write them to disk first:
+
+```python
+import alpholio as alp
+
+bt = alp.backtest(signals=alpha_df, prices=price_df, horizon=5)
+
+bt.summary()                   # metrics per (signal_model, bucket, weight)
+bt.plot("long_short")          # long-short equity curve, returns a matplotlib Figure
+bt.plot("deciles")             # per-quantile gradient chart
+bt.save("outputs/")            # PNG charts and CSV metrics to disk
+
+bt.returns                     # per-period portfolio returns, long format
+bt.curves                      # equity and cumulative log-return curves
+```
+
+`horizon` is the measurement window of each period's realised return and is required.
+Column mapping is inferred when the source names already match the contract
+(`date` / `id` / `alpha`); the rebalance interval defaults to `horizon`; and value
+weighting is added automatically when the price table carries a `cap` column.
+
+Monthly panels only need a `frequency`: `horizon` and the rebalance interval then count
+calendar months, and metrics annualise at 12 periods per year.
+
+```python
+bt = alp.backtest(signals=alpha_df, prices=panel_df, horizon=1, frequency="monthly")
+```
+
+File paths work interchangeably with in-memory tables:
+
+```python
+bt = alp.backtest(signals="alpha.feather", prices="prices.feather", horizon=5)
+bt = alp.backtest(signals={"MOM": mom_df, "REV": rev_df}, prices=price_df, horizon=5)
+```
+
+### Batch runs and reproducible archives
+
+The JSON config directory remains a first-class entry point, suited to batch execution
+on a server and to shipping alongside a paper:
+
+```bash
+alpholio run --config-dir configs/
+```
+
+```python
+result = alp.run_pipeline("configs/")
+```
+
+Both paths share the same validation and computation and agree value for value.
+Parameters settled in a notebook export back out into a config directory:
+
+```python
+bt.to_config("paper/configs/", data_dir="paper/data/")
+```
+
+## Documentation
+
+The full documentation is written in Chinese. Direct links:
+
+| Page | Contents |
+|---|---|
+| [Quick start](https://mzyang-code.github.io/alpholio/guide/quickstart/) | Install through the first equity curve |
+| [Concepts](https://mzyang-code.github.io/alpholio/guide/concepts/) | Four modules, three data contracts, extension points |
+| [Preparing input](https://mzyang-code.github.io/alpholio/guide/prepare-data/) | Signal table format, column mapping, forward-return sources |
+| [Data frequency](https://mzyang-code.github.io/alpholio/guide/frequency/) | Daily vs monthly: units, alignment rules, annualisation base |
+| [Multiple signals](https://mzyang-code.github.io/alpholio/guide/multi-signal/) | Running several alphas at once, and how charts split |
+| [Outputs](https://mzyang-code.github.io/alpholio/guide/outputs/) | File listing, naming rules, long-table structure |
+| [Math contract](https://mzyang-code.github.io/alpholio/guide/math/) | The exact formula behind every metric |
+| [Daily example](https://mzyang-code.github.io/alpholio/examples/daily-mom/) | MOM 12-2 end to end: input shape, call, measured results |
+| [Monthly example](https://mzyang-code.github.io/alpholio/examples/monthly-panel/) | Three alphas off one monthly panel, `frequency="monthly"` |
+| [Python API](https://mzyang-code.github.io/alpholio/reference/api/) | `backtest()` parameters and the result object |
+| [Config reference](https://mzyang-code.github.io/alpholio/reference/config-input/) | Per-field types, defaults and constraints |
+
+## Benchmarks
+
+No market index data is bundled. Benchmark series are supplied by the user through
+`input.references`, enter the result table under bucket `REF`, and appear on charts once
+`"REF"` is listed in a chart's `buckets`.
+
+Equal-weighted portfolios should be paired with an equal-weighted index and cap-weighted
+with a cap-weighted index — only like-for-like comparisons mean anything. A single
+`references` entry is replicated across every weighting scheme, so pairing one index per
+scheme takes two entries plus two chart configs constraining `weights` and `signals`. See
+[Multiple signals](https://mzyang-code.github.io/alpholio/guide/multi-signal/).
+
+## Building the docs locally
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## License
+
+MIT

alpholio-0.4.0/README.md

@@ -0,0 +1,137 @@
+# alpholio
+
+Cross-sectional portfolio backtesting. The toolkit consumes alpha and handles bucketing,
+weighting, metrics and charts.
+
+**📖 [Documentation](https://mzyang-code.github.io/alpholio/)** (Chinese) ｜ [简体中文 README](https://github.com/mzyang-code/alpholio/blob/main/README.zh-CN.md)
+
+Four modules, one direction of data flow. Each module owns a single public entry point,
+so any stage can be swapped without touching the others.
+
+```
+InputProcessor ──InputBundle──▶ PortfolioEngine ──EngineResult──▶ Analyzer ──AnalysisResult──▶ Visualizer ──▶ PNG / CSV
+```
+
+The toolkit consumes alpha only — it never generates signals. Price-based factors such as
+MOM / STR / WSTR are ordinary inputs; see the
+[daily MOM example](https://mzyang-code.github.io/alpholio/examples/daily-mom/) for one
+worked end to end.
+
+## Install
+
+```bash
+pip install alpholio
+```
+
+Working from a clone instead:
+
+```bash
+pip install -e .                      # compatible ranges
+pip install -e ".[docs]"              # adds the documentation site toolchain
+```
+
+To reproduce the exact verified combination (Python 3.12.2):
+
+```bash
+conda env create -f environment.yml
+conda activate alpholio
+pip install -e .
+```
+
+## Quick start
+
+Factor and price tables go in as DataFrames — no need to write them to disk first:
+
+```python
+import alpholio as alp
+
+bt = alp.backtest(signals=alpha_df, prices=price_df, horizon=5)
+
+bt.summary()                   # metrics per (signal_model, bucket, weight)
+bt.plot("long_short")          # long-short equity curve, returns a matplotlib Figure
+bt.plot("deciles")             # per-quantile gradient chart
+bt.save("outputs/")            # PNG charts and CSV metrics to disk
+
+bt.returns                     # per-period portfolio returns, long format
+bt.curves                      # equity and cumulative log-return curves
+```
+
+`horizon` is the measurement window of each period's realised return and is required.
+Column mapping is inferred when the source names already match the contract
+(`date` / `id` / `alpha`); the rebalance interval defaults to `horizon`; and value
+weighting is added automatically when the price table carries a `cap` column.
+
+Monthly panels only need a `frequency`: `horizon` and the rebalance interval then count
+calendar months, and metrics annualise at 12 periods per year.
+
+```python
+bt = alp.backtest(signals=alpha_df, prices=panel_df, horizon=1, frequency="monthly")
+```
+
+File paths work interchangeably with in-memory tables:
+
+```python
+bt = alp.backtest(signals="alpha.feather", prices="prices.feather", horizon=5)
+bt = alp.backtest(signals={"MOM": mom_df, "REV": rev_df}, prices=price_df, horizon=5)
+```
+
+### Batch runs and reproducible archives
+
+The JSON config directory remains a first-class entry point, suited to batch execution
+on a server and to shipping alongside a paper:
+
+```bash
+alpholio run --config-dir configs/
+```
+
+```python
+result = alp.run_pipeline("configs/")
+```
+
+Both paths share the same validation and computation and agree value for value.
+Parameters settled in a notebook export back out into a config directory:
+
+```python
+bt.to_config("paper/configs/", data_dir="paper/data/")
+```
+
+## Documentation
+
+The full documentation is written in Chinese. Direct links:
+
+| Page | Contents |
+|---|---|
+| [Quick start](https://mzyang-code.github.io/alpholio/guide/quickstart/) | Install through the first equity curve |
+| [Concepts](https://mzyang-code.github.io/alpholio/guide/concepts/) | Four modules, three data contracts, extension points |
+| [Preparing input](https://mzyang-code.github.io/alpholio/guide/prepare-data/) | Signal table format, column mapping, forward-return sources |
+| [Data frequency](https://mzyang-code.github.io/alpholio/guide/frequency/) | Daily vs monthly: units, alignment rules, annualisation base |
+| [Multiple signals](https://mzyang-code.github.io/alpholio/guide/multi-signal/) | Running several alphas at once, and how charts split |
+| [Outputs](https://mzyang-code.github.io/alpholio/guide/outputs/) | File listing, naming rules, long-table structure |
+| [Math contract](https://mzyang-code.github.io/alpholio/guide/math/) | The exact formula behind every metric |
+| [Daily example](https://mzyang-code.github.io/alpholio/examples/daily-mom/) | MOM 12-2 end to end: input shape, call, measured results |
+| [Monthly example](https://mzyang-code.github.io/alpholio/examples/monthly-panel/) | Three alphas off one monthly panel, `frequency="monthly"` |
+| [Python API](https://mzyang-code.github.io/alpholio/reference/api/) | `backtest()` parameters and the result object |
+| [Config reference](https://mzyang-code.github.io/alpholio/reference/config-input/) | Per-field types, defaults and constraints |
+
+## Benchmarks
+
+No market index data is bundled. Benchmark series are supplied by the user through
+`input.references`, enter the result table under bucket `REF`, and appear on charts once
+`"REF"` is listed in a chart's `buckets`.
+
+Equal-weighted portfolios should be paired with an equal-weighted index and cap-weighted
+with a cap-weighted index — only like-for-like comparisons mean anything. A single
+`references` entry is replicated across every weighting scheme, so pairing one index per
+scheme takes two entries plus two chart configs constraining `weights` and `signals`. See
+[Multiple signals](https://mzyang-code.github.io/alpholio/guide/multi-signal/).
+
+## Building the docs locally
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## License
+
+MIT

alpholio-0.4.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alpholio"
+# 版本号的唯一真源是 src/alpholio/__init__.py 的 __version__，见 tool.setuptools.dynamic
+dynamic = ["version"]
+description = "Config-driven cross-sectional portfolio backtesting toolkit"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "myang682" }]
+keywords = ["quant", "portfolio", "backtest", "cross-section", "finance"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+# 兼容区间。确切的已验证版本组合见 environment.yml
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "pyarrow>=10.0",
+    "matplotlib>=3.6",   # 需要 mpl.colormaps 注册表
+]
+
+[project.optional-dependencies]
+# 构建 docs/ 下的文档站用。jieba 非可选：缺失时中文正文不分词，
+# 搜索索引退化为整句匹配，站内检索基本失效
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "jieba>=0.42"]
+
+[project.urls]
+Homepage = "https://github.com/mzyang-code/alpholio"
+Documentation = "https://mzyang-code.github.io/alpholio/"
+Source = "https://github.com/mzyang-code/alpholio"
+Issues = "https://github.com/mzyang-code/alpholio/issues"
+
+[project.scripts]
+alpholio = "alpholio.cli:main"
+
+[tool.setuptools]
+# data/ 下的 S&P 500 序列受数据使用权限制，不得随 sdist 与 wheel 分发。
+# 该项在 pyproject.toml 下默认为 true，会把包目录内的非 .py 文件一并收进构建产物，
+# 因此必须显式关闭；同时不声明任何 package-data。
+# 基准数据由使用者自行准备，见 input.references。
+include-package-data = false
+
+[tool.setuptools.dynamic]
+version = { attr = "alpholio.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

alpholio-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alpholio-0.4.0/src/alpholio/__init__.py

@@ -0,0 +1,44 @@
+# 跨截面组合回测工具包：Input → Engine → Analyzer → Visualizer 单向数据流
+from .analyzer import Analyzer
+from .api import BacktestResult, backtest
+from .config_schema import AnalyzerConfig, EngineConfig, InputConfig, PipelineConfig, VisualizerConfig
+from .contracts import AnalysisResult, EngineResult, InputBundle, to_legacy_wide
+from .engine import PortfolioEngine
+from .input import InputProcessor
+from .pipeline import PipelineResult, run_pipeline
+from .settings import settings
+from .visualizer import Visualizer
+
+__version__ = "0.4.0"
+__all__ = [
+    # 一行跑通的门面入口
+    "backtest",
+    "BacktestResult",
+    "settings",
+
+    # 核心类
+    "InputProcessor",
+    "PortfolioEngine",
+    "Analyzer",
+    "Visualizer",
+
+    # 辅助函数和数据类
+    "run_pipeline",
+    "PipelineResult",
+    "InputConfig",
+    "EngineConfig",
+    "AnalyzerConfig",
+    "VisualizerConfig",
+    "PipelineConfig",
+
+    # 用于流转的中间产物
+    "InputBundle",
+    "EngineResult",
+    "AnalysisResult",
+
+    # 格式转换函数
+    "to_legacy_wide",
+
+    # 版本号
+    "__version__",
+]

alpholio-0.4.0/src/alpholio/analyzer/__init__.py

@@ -0,0 +1,18 @@
+# ③ Analyzer：组合收益 → 指标 / 曲线 / 诊断
+from .analyzer import Analyzer
+from .curves import build_curves, shared_origin, vol_rescale_to_reference
+from .diagnostics import compute_ic, compute_turnover
+from .metrics import METRICS, Metric, MetricContext, build_metric
+
+__all__ = [
+    "Analyzer",
+    "Metric",
+    "METRICS",
+    "MetricContext",
+    "build_metric",
+    "compute_turnover",
+    "compute_ic",
+    "build_curves",
+    "shared_origin",
+    "vol_rescale_to_reference",
+]

alpholio-0.4.0/src/alpholio/analyzer/analyzer.py

@@ -0,0 +1,135 @@
+# ③ Analyzer：组合收益 → 指标汇总 + 曲线 + 诊断
+from __future__ import annotations
+
+from typing import Dict, List
+
+import numpy as np
+import pandas as pd
+
+from ..config_schema import AnalyzerConfig
+from ..contracts import (
+    BUCKET,
+    DATE,
+    IC,
+    N_NAMES,
+    RET,
+    SIGNAL,
+    TURNOVER,
+    WEIGHT,
+    AnalysisResult,
+    ContractError,
+    EngineResult,
+    sort_by_bucket,
+)
+from ..frequency import DAILY, resolve
+from .curves import build_curves, shared_origin, vol_rescale_to_reference
+from .diagnostics import compute_ic, compute_turnover
+from .metrics import MetricContext, build_metric
+
+
+class Analyzer:
+    def __init__(self, cfg: AnalyzerConfig) -> None:
+        self.cfg = cfg
+        self.metrics = [build_metric(name) for name in cfg.metrics]
+
+    # 唯一出口
+    def run(self, result: EngineResult) -> AnalysisResult:
+        cfg = self.cfg
+        ppy = self._periods_per_year(result.meta)
+        ctx = MetricContext(periods_per_year=ppy, risk_free_rate=cfg.risk_free_rate)
+
+        turnover = (
+            compute_turnover(
+                result.members,
+                long_short_label=result.meta.get("long_short_label"),
+                long_bucket=result.meta.get("long_bucket"),
+                short_bucket=result.meta.get("short_bucket"),
+            )
+            if cfg.diagnostics.turnover
+            else _empty(SIGNAL, BUCKET, DATE, TURNOVER)
+        )
+        ic = (
+            compute_ic(result.aligned, cfg.diagnostics.ic_min_names)
+            if cfg.diagnostics.ic
+            else _empty(SIGNAL, DATE, IC, N_NAMES)
+        )
+
+        returns = self._rescale(result.returns)
+        origin = shared_origin(returns) if cfg.curves.shared_origin else None
+
+        return AnalysisResult(
+            summary=self._summarize(returns, ctx, turnover, ic),
+            curves=build_curves(returns, cfg.curves.clip_lower, origin),
+            turnover=turnover,
+            ic=ic,
+            meta={
+                "periods_per_year": ppy,
+                "metrics": [m.name for m in self.metrics],
+                "vol_rescaled": bool(cfg.vol_rescale.enabled),
+                "vol_rescale_reference": cfg.vol_rescale.reference if cfg.vol_rescale.enabled else None,
+                **{
+                    k: result.meta[k]
+                    for k in ("frequency", "holding_days", "n_buckets")
+                    if k in result.meta
+                },
+            },
+        )
+
+    # 开关打开时整体替换为缩放后的收益，不再并列输出两套口径
+    def _rescale(self, returns: pd.DataFrame) -> pd.DataFrame:
+        spec = self.cfg.vol_rescale
+        if not spec.enabled:
+            return returns
+        if not spec.reference:
+            raise ContractError(
+                "analyzer.vol_rescale.enabled=true 时必须指定 reference（缩放到哪个基准）"
+            )
+        return vol_rescale_to_reference(returns, spec.reference, spec.min_periods)
+
+    # 年化因子：显式配置优先，否则由「年化基数 / 持有期」推导。
+    # 基数随面板频率：日频取 analyzer.trading_days_per_year（默认 252），月频取 12。
+    # 频率沿 InputBundle → EngineResult.meta 传来，缺省按日频处理。
+    def _periods_per_year(self, engine_meta: Dict) -> float:
+        if self.cfg.periods_per_year:
+            return float(self.cfg.periods_per_year)
+        frequency = resolve(engine_meta.get("frequency", DAILY))
+        base = (
+            frequency.bars_per_year
+            if frequency.is_monthly
+            else float(self.cfg.trading_days_per_year)
+        )
+        holding = int(engine_meta.get("holding_days", 1))
+        return base / max(holding, 1)
+
+    def _summarize(
+        self, returns: pd.DataFrame, ctx: MetricContext, turnover: pd.DataFrame, ic: pd.DataFrame
+    ) -> pd.DataFrame:
+        turnover_mean = _mean_by(turnover, [SIGNAL, BUCKET], TURNOVER)
+        ic_mean = _mean_by(ic, [SIGNAL], IC)
+        rows: List[Dict] = []
+        for (signal, bucket, weight), grp in returns.groupby(
+            [SIGNAL, BUCKET, WEIGHT], sort=True
+        ):
+            series = grp[RET].dropna().to_numpy(dtype=np.float64)
+            if len(series) == 0:
+                continue
+            row = {
+                SIGNAL: signal, BUCKET: bucket, WEIGHT: weight,
+                "n_periods": int(len(series)),
+            }
+            row.update({m.name: m.compute(series, ctx) for m in self.metrics})
+            row[TURNOVER] = turnover_mean.get((signal, bucket), np.nan)
+            row["ic_mean"] = ic_mean.get(signal, np.nan)
+            rows.append(row)
+        return sort_by_bucket(pd.DataFrame(rows), [SIGNAL, WEIGHT])
+
+
+def _empty(*columns: str) -> pd.DataFrame:
+    return pd.DataFrame(columns=list(columns))
+
+
+def _mean_by(frame: pd.DataFrame, keys: List[str], column: str) -> Dict:
+    if frame.empty or column not in frame.columns:
+        return {}
+    grouped = frame.groupby(keys[0] if len(keys) == 1 else keys, sort=False)[column].mean()
+    return grouped.to_dict()