API reference#

The public surface: tidyfinance-backed sources loaders, the self-built FRED-MD builder, and the complete raw/clean/lock step lifecycle for locally pulled WRDS panels.

Sources#

`load_ff_factors`	Fama-French 3-factor tidy frame (`date, mkt_excess, smb, hml, risk_free`), in decimals.
`load_ff_momentum`	Ken French U.S.
`load_ff_portfolios`	A public Ken French portfolio frame in decimal returns.
`load_ff_portfolio_view`	Ken French multi-asset view plus a non-secret `data_vintage` provenance stamp.
`load_hxz_q4_factors`	Official Hou--Xue--Zhang q4 factors as month-end decimal returns.
`load_hxz_q_factor_legs`	Official HXZ 2x3x3 size/investment/profitability portfolios in decimal returns.
`load_pastor_stambaugh_liquidity`	Official Pastor--Stambaugh aggregate-liquidity snapshot, with explicit units.
`load_pastor_stambaugh_historical_beta_portfolios`	Official historical-liquidity-beta decile returns and traded 10-minus-1 factor.
`load_aqr_bab_original`	Load a caller-supplied AQR BAB Original workbook as decimal monthly returns.
`load_daniel_moskowitz_momentum`	Load caller-supplied Daniel--Moskowitz daily/monthly momentum deciles.
`load_hkm_paper_data`	Load the fixed He--Kelly--Manela paper factors and 124 test assets.
`load_goyal_welch`	Goyal-Welch equity-premium frame: `date, rp_div` (excess market) + macro predictors.
`load_gw_view`	Goyal-Welch view (excess `rp_div` + predictors) + `data_vintage`, ready for VoC/1-A.
`to_multiasset_view`	A tidy wide `(date, asset returns...)` frame -> returns-only `TimeSeriesView`.
`to_timeseries_view`	A tidy `(date, ret, features…)` frame → single-asset numeraire `TimeSeriesView`.
`data_vintage`	Provenance stamp for a live tidyfinance pull (`tidyfinance:<dataset>@<version>`).
`frame_data_vintage`	Return the non-secret `data_vintage` attached by a public frame loader.
`frame_provenance`	Return a copy of source provenance attached by a public frame loader.
`HXZ_Q4_FACTOR_COLUMNS`	Built-in immutable sequence.
`KEN_FRENCH_DAILY_MOMENTUM_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`PASTOR_STAMBAUGH_LIQUIDITY_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`PASTOR_STAMBAUGH_HISTORICAL_BETA_PORTFOLIOS_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`AQR_BAB_ORIGINAL_PAGE`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`AQR_TERMS_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DanielMoskowitzMemberContract`	Explicit parser and release envelope for one documented archive member.
`DanielMoskowitzArchiveContract`	Paired daily/monthly contract for the total-return, all-firm portfolios.
`DanielMoskowitzMomentumData`	Canonical paired momentum-decile frames returned by the path-only loader.
`HKMPaperData`	Fixed paper-sample factors and the unbalanced 124-test-asset panel.
`HKMAssetClassData`	One asset class aligned on its joint complete-case paper sample.
`HKMFrequency`
`HKMAssetClass`
`HKM_ARCHIVE_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`HKM_ARCHIVE_SHA256`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`HKM_ARCHIVE_MEMBERS`	Built-in immutable sequence.
`HKM_ASSET_CLASSES`	Built-in immutable sequence.
`HKM_DATA_PAGE`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DANIEL_MOSKOWITZ_ARCHIVE_FILENAME`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DANIEL_MOSKOWITZ_ARCHIVE_MEMBERS`	Built-in immutable sequence.
`DANIEL_MOSKOWITZ_DAILY_TOTAL_MEMBER`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DANIEL_MOSKOWITZ_MONTHLY_TOTAL_MEMBER`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DANIEL_MOSKOWITZ_DATA_PAGE`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`DANIEL_MOSKOWITZ_DOCUMENTATION_URL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Builders — FRED-MD#

`download`	Download recent FRED-MD single vintages (`YYYY-MM`) into `dest`; return local paths.
`download_archive`	Download a full-history zip (`which` in `HIST_ARCHIVES`, or a URL) into `dest`.
`read_vintage`	Read one FRED-MD vintage file → `(levels, tcodes)`.
`apply_tcode`	Apply a FRED-MD stationarity transform (codes 1-7) to a level series (NaN-padded at start).
`build_table`	Stack FRED-MD vintage files into a wide point-in-time table `[ref_date, vintage, series]`.
`build_from_dir`	Build from every vintage CSV under `directory` (recurses; non-vintage files skipped).

WRDS clean steps#

These functions transform caller-supplied frames and do not connect to WRDS themselves.

`crsp_monthly_clean`	Tidy monthly CRSP: common-stock filter, delisting-adjusted returns, month-end mktcap.
`crsp_daily_equity_clean`	Validate one CRSP daily-equity bucket without imputing an observation.
`daily_market_rf_clean`	Strictly align the CRSP value-weighted market and daily Fama--French risk-free rate.
`daily_stock_excess_clean`	Subtract the same-date daily RF from one clean stock bucket.
`monthly_risk_free_clean`	Normalize WRDS Fama--French monthly RF from source-month labels to month-end.
`monthly_stock_excess_clean`	Attach same-month RF and an excess return to one clean monthly stock bucket.
`compustat_annual_clean`	Tidy annual Compustat: book equity, operating profitability, and asset-growth investment.
`compustat_annual_formation_clean`	Prepare raw annual accounting fields for calendar-year portfolio formation.
`compustat_quarterly_clean`	Tidy quarterly Compustat: fresh-earnings ROE with an announcement-dated availability month.
`ccm_links_clean`	Tidy CRSP-Compustat links: primary, reliable gvkey<->permno links with valid date windows.

Data-zone provenance and step registry#

`Built`	A built frame plus the step identity and explicit inputs committed by its recipe hash.
`DataLock`	An in-memory `data.lock.json` with typed add/read helpers.
`RawMeta`	The `_meta.json` sidecar for one raw pull.
`Step`	A registered transform: a pure function plus its identity and input/output artifact names.
`available_steps`	Return the names of all registered steps, sorted.
`content_digest`	Digest a frame's values and semantic schema, preserving row/column order.
`data_vintage_of`	The numeraire `data_vintage` for a clean artifact: `<name>@<recipe-hash-prefix>`.
`get_step`	Return the step registered under `name`.
`raw_dir`	Return and create the cache directory for a `(source, vintage)` pull.
`read_meta`	Read the `_meta.json` for a `(source, vintage)` pull.
`recipe_hash`	Hash a recipe whose canonical input mapping preserves each input's semantic role.
`register_step`	Register `step_obj` under its `name`.
`run_step`	Run a registered step on named input frames, returning the output + its provenance hashes.
`write_meta`	Create a new `_meta.json` sidecar without overwriting any cache artifact.

numeraire_dataset.zones.steps.step(*, name: str, version: int, inputs: list[str], output: str, overwrite: bool = False) → Callable[[Callable[[...], DataFrame]], Callable[[...], DataFrame]][source]#: Decorator: register fn as a step and return it unchanged (still directly callable).

WRDS connector and cache#

These functions require the optional wrds dependency only when opening a live connection. Cached reads and deterministic clean builds remain usable without live credentials.

`connect`	Open a WRDS connection using credentials from the environment (or explicit arguments).
`default_vintage`	The default raw-vintage stamp for a WRDS pull, resolved at call time.
`load_clean`	Pull the standard raw tables, run the clean builders, and record the provenance lock.
`pull_raw`	Pull `sql` into a frame and cache it as parquet + `_meta.json` under the raw zone.
`pull_standard`	Pull (and cache) the standard raw tables; returns `{source: frame}`.
`raw_cached`	Whether a complete parquet + metadata cache exists for `(source, vintage)`.
`read_raw`	Read a cached raw frame after validating its metadata, schema, and values.
`wrds_available`	Whether WRDS credentials are reachable in the environment (no connection is attempted).

Partitioned WRDS equity collections#

Daily and monthly CRSP histories are intentionally exposed as iterator-backed collections rather than one materialized frame. The default is 64 stable permno buckets. Daily SIZ and CIZ have different SQL, cache labels, manifests, and data_vintage values. Licensed rows stay in the data home; the collection manifest contains only query/content identities, row/date bounds, and unit contracts. It also binds the registered clean pipeline’s step names, versions, and explicit parameters into data_vintage. Monthly targets are SIZ-only and keep stock, name-history, and delist pulls independent; sensitivity transforms must use the raw iterator plus run_step so they receive their own recipe identity.

`DailyEquityCollection`	Handle for a complete partitioned daily-equity input collection.
`DailyEquityManifestEntry`	Non-secret identity of one independently cached raw input.
`MonthlyEquityTargetCollection`	SIZ monthly target returns, streamed as independent `permno` buckets.
`MonthlyEquityManifestEntry`	Path-free identity of one monthly SIZ target input.
`MonthlyEquityRawPartition`	Three independently pulled raw frames for one monthly `permno` bucket.
`CRSP_RELEASE_MARKER_SQL`	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`crsp_daily_stock_sql`	Return deterministic SQL for one complete-history `permno` bucket.
`crsp_daily_market_sql`	CRSP value-weighted U.S.
`ff_daily_risk_free_sql`	Daily U.S.
`crsp_monthly_stock_sql`	One SIZ monthly-stock bucket, independent of names and delisting events.
`crsp_monthly_names_sql`	Name histories overlapping the target range for one SIZ `permno` bucket.
`crsp_monthly_delist_sql`	Monthly delisting events pulled independently so terminal-only rows cannot disappear.
`ff_monthly_risk_free_sql`	Monthly FF RF in decimal units; WRDS source dates label months at their first day.
`siz_monthly_target_queries`	Legacy monthly inputs for `zones.clean.crsp_monthly_clean()`.
`prepare_crsp_daily_equity`	Pull/cache one bucket at a time and publish its complete collection manifest.
`load_crsp_daily_equity`	Load a completed collection manifest without opening a WRDS connection.
`prepare_crsp_monthly_equity_targets`	Pull a complete SIZ monthly target collection, bounded by one bucket in memory.
`load_crsp_monthly_equity_targets`	Load a complete monthly SIZ target manifest without opening a WRDS connection.

Numeraire view bridge#

to_cross_section_view

Build a numeraire CrossSectionView from a tidy clean panel (lazy numeraire import).