Skip to content

Shadow Factor

shadow-factor is the factor engine in the Shadow stack.

It turns financial and market data into factor-ready outputs, and provides a factor DSL for generating new factors from existing fields and operators.

What It Is For

Use shadow-factor when you want to:

  • query factor panels as final dataframes
  • treat source data as factor inputs instead of manually preprocessing wide tables
  • define new factors through a compact DSL rather than custom imperative code
  • register reusable factors for repeated research or production use
  • keep factor logic readable, reviewable, and composable

Stable Public API

The current stable public API is intentionally small:

  • panel(...) — evaluate one or more factors into a dataframe panel
  • register_factor(...) — register a named factor formula for reuse
  • list_factors(...) — inspect registered factors and metadata

Core Ideas

Data as a factor

In shadow-factor, base fields are not just raw columns to export and manually transform later.

They are the starting point of factor construction.

That means you can treat financial fields such as net_profit, operating_revenue, or total_assets as building blocks for higher-level factors.

Factor DSL as a generator

Instead of writing one-off calculation scripts, you can define factor logic as formula strings.

Examples:

"TTM(net_profit)"
"YoY(TTM(net_profit))"
"SafeDiv(TTM(net_profit), total_assets)"

This makes factors easier to register, compare, version, and reuse.