factor-factory

A domain-agnostic factor-model + analysis-pipeline framework with a Protocol-based pluggable engine pattern, first-class jellycell integration, and the only production-grade Python implementations of Synthetic Difference-in-Differences (Arkhangelsky et al. 2021, AER) and the Four-way Mediation Decomposition (VanderWeele 2014, Epidemiology).

Authored by Blaise Albis-Burdige.

The same Panel shape hosts NYC-civic data, finance event studies, clinical trials, agronomic dose-response, chemistry assays, climate anomaly studies, education-intervention evaluations, energy-meter data, marketing A/B tests, macroeconomic country panels, ecological biodiversity surveys, and social-network diffusion cascades. Add a new domain by writing extractors; add a new method by writing a ~150-LOC engine adapter that fits the Protocol.

Install

# Default install — tidy layer + diagnostics + jellycell (no engines)
pip install factor-factory

# With specific engine families
pip install factor-factory[did,survival,event-study]

# Everything currently shipping
pip install factor-factory[all]

Supports Python 3.12+. Dependency manager of choice is uv; pip works the same way.

Quick start

Scaffold a showcase, run it, render tearsheets:

python -m factor_factory scaffold my-showcase
cd my-showcase
python notebooks/01_load.py

The scaffolded notebook builds a synthetic panel, runs a TWFE DiD via factor_factory.engines.did.estimate, saves a parallel-trends figure, and regenerates all five canonical manuscripts (METHODOLOGY.md, DIAGNOSTICS_CHECKLIST.md, FINDINGS.md, MANUSCRIPT.md, AUDIT.md).

The canonical pattern inside a notebook:

from datetime import date
from factor_factory.tidy import Panel, TreatmentEvent
from factor_factory.engines.did import estimate as did_estimate

panel = Panel.from_records(
    records,
    dimension="community_district",
    freq="ME",
    treatment_events=(TreatmentEvent(
        name="rat_pilot",
        treated_units=("MN-01", "MN-02"),
        treatment_date=date(2024, 6, 1),
        dimension="community_district",
    ),),
    outcome_col="complaint_count",
)

# Multi-engine DiD in one call — TWFE + Callaway-Sant'Anna side-by-side
results = did_estimate(panel, methods=("twfe", "cs"), cluster="unit_id")
print(results.summary_table())

See the getting-started guide for cross-domain examples (finance event study, multi-arm RCT, agronomic dose-response, chemistry IC₅₀ assay, etc.).

Architecture

raw records
  ↓ tidying              factor_factory.tidy         Panel + TreatmentEvent + Provenance + RecordView
tidied panel
  ↓ diagnostics          factor_factory.diagnostics  SMD, parallel-trends, residuals, balance
diagnostic-annotated panel
  ↓ modeling             factor_factory.engines      17 engine families (see below)
modeling results
  ↓ reporting            factor_factory.jellycell    5 tearsheet renderers + scaffold CLI
                         factor_factory.reporting    Quarto (.qmd) alternative

Every engine family follows the same shape: a frozen Result dataclass + an Engine Protocol + a registry-backed estimate() dispatcher. Adapters wrap external packages (linearmodels, differences, lifelines, rdrobust, pysyncon, econml, DoubleML, ruptures, sktime, pyfixest, esda, tick, ndlib, …) or roll their own math when no canonical package exists.

See the design contracts for the data contract and the reference architecture page for the full engine-family contract.

Shipping engine families

Install the extras you need; unlisted adapters fail-fast with a crisp ImportError pointing at the right pip install factor-factory[<family>].

17 engine families / 30+ adapters. Use the /engine-status Claude Code slash-command (or inspect factor_factory.engines.<family>.registry) to see the live state.

Python-ecosystem gaps closed

Two methods the Python ecosystem was missing entirely (canonical R packages, no maintained Python equivalent). Both shipped as first-class engines with the canonical paper + reference R-package linked in the engine docstring.

engines.sdid — Synthetic Difference-in-Differences

Arkhangelsky, D., Athey, S., Hirshberg, D. A., Imbens, G. W., & Wager, S. (2021). Synthetic Difference-in-Differences. American Economic Review, 111(12), 4088–4118. doi:10.1257/aer.20190159

Reference R implementation: synthdid

SDID combines unit weights (synthetic-control style) with time weights and a weighted DiD estimator. It's a 2021 advance that addresses the parallel-trends fragility of vanilla DiD when units have heterogeneous trends. The R synthdid package is canonical; partial Python ports like pysdid are lightly maintained.

Our adapter:

• Solves the unit- and time-weights QPs via scipy.optimize.minimize (SLSQP), no cvxpy dependency
• Uses the regularization ζ = (N_tr · T_post)^(1/4) · σ̂ from AER §3.3
• Computes the closed-form weighted-DiD ATT for binary block treatment
• Supports both jackknife (AER §3.4 default) and placebo inference (preferred for single-treated-unit panels)
• Returns unit weights + time weights so analysts can interrogate the synthetic control

Validated against a known-ATT=4.0 fixture: recovers ATT=4.535 (SE=0.245).

engines.mediation.FourWayMediationEngine — VanderWeele's four-way decomposition

VanderWeele, T. J. (2014). A unification of mediation and interaction: A four-way decomposition. Epidemiology, 25(5), 749–761. doi:10.1097/EDE.0000000000000121

Reference R implementation: CMAverse

Decomposes a treatment's total effect into:

• CDE (Controlled Direct Effect)
• INTref (Reference Interaction)
• INTmed (Mediated Interaction)
• PIE (Pure Indirect Effect)

statsmodels.stats.mediation only provides the simpler Imai-Keele-Tingley two-component decomposition (NDE / NIE). The mediation package on PyPI is stale. Our adapter ports the linear-linear case from the Epidemiology paper directly with bootstrap inference (1000 resamples by default), and adds an unobserved-confounding sensitivity analysis (.sensitivity(rho_range, n_points)) ported from CMAverse's rho-test.

Validates against a fixture with known components — recovers all four within 1 SE:

Domain coverage

Cross-domain conformance fixtures exercise the Panel contract across data shapes from NYC-civic to chemistry. See the supported-domains page for the full matrix.

GWAS / biobank-scale genetics is deliberately out of scope — scale, file formats, and inference shape all mismatch. Use hail, pysnptools, PLINK 2.0, or BOLT-LMM instead. Full rationale on the supported-domains page.

Documentation

Full docs at factor-factory.readthedocs.io (Sphinx + Furo + autodoc2).

Contributing

PRs welcome — especially new engine families. Factor-factory is an adapter-first framework: before writing engine math from scratch, consult the piggyback map. See CONTRIBUTING.md for the full workflow.

Claude Code users get slash-commands for common operations:

/engine-status    # 17-family status report
/add-engine <family>   # scaffold a new engine family end-to-end
/contract-check   # audit a diff against the three contract invariants
/bump [patch|minor|major]   # bump version + roll CHANGELOG
/release-check    # preflight before a tag push

Citing

If you use factor-factory in academic work, please cite:

• The engine-specific canonical paper(s) — each adapter's docstring carries the DOI + reference R-package URL.
• This software record — via CITATION.cff (Zenodo-compatible).

License

MIT. See LICENSE. Same license as sibling random-walks packages (jellycell, nyc311, nyc-geo-toolkit).