Skip to content

Shadow Docs

Shadow Factor Quick Start

Shadow Factor Quick Start¶

This is the fastest path to understanding how shadow-factor is meant to be used.

Install¶

uv sync

1. Query one factor¶

import shadow_factor as sf

price_like_df = sf.panel(
    "net_profit_mrq_0",
    start_date="2024-01-01",
    end_date="2024-12-31",
)

print(price_like_df.head())

2. Evaluate an ad hoc factor formula¶

import shadow_factor as sf

margin_df = sf.panel(
    "SafeDiv(TTM(net_profit), TTM(operating_revenue))",
    start_date="2024-01-01",
)

print(margin_df.head())

3. Query multiple factors together¶

import shadow_factor as sf

multi_df = sf.panel(
    [
        "TTM(net_profit)",
        "YoY(TTM(net_profit))",
        "SafeDiv(TTM(net_profit), total_assets)",
    ],
    stocks=["000001.SZ", "600000.SH"],
    start_date="2024-01-01",
    end_date="2024-12-31",
)

print(multi_df.columns)

4. Register a reusable factor¶

import shadow_factor as sf

sf.register_factor(
    name="roa_ttm",
    formula="SafeDiv(TTM(net_profit), total_assets)",
    description="Return on assets based on trailing-twelve-month net profit",
)

roa_df = sf.panel("roa_ttm", start_date="2024-01-01")

Mental Model¶

A simple way to think about the project is:

panel(...) gives you factor-shaped data
raw fields can already act as factor inputs
the DSL lets you compose new factors from existing fields
register_factor(...) turns useful formulas into reusable named assets

Read Next¶