quantlab.dataset.crsp.reference.CrspReference

class quantlab.dataset.crsp.reference.CrspReference(reference_dir)

Bases: object

Read-only access to one CRSP reference directory.

It holds no database connection and needs no login: the tables are parquet files on disk. Each table is read on first request and cached on the instance, so repeated requests cost one file read.

Parameters:

reference_dirstr or Path

The directory holding the reference parquet files and manifest.json.

Attributes:

reference_dirPath

The reference directory.

Examples

>>> from quantlab.dataset.crsp.reference import CrspReference
>>> ref = CrspReference("data/downloads/us_equity/1d/wrds_crsp/_reference")
>>> ref.table("dsp500list_v2").columns
['permno', 'indno', 'mbrstartdt', 'mbrenddt', 'mbrflg', 'indfam']
>>> ref.product_end
datetime.date(2025, 12, 31)

property manifest

Return manifest.json as a dict, read at most once.

Raises:

FileNotFoundError

If the directory has no manifest. Without one, the CRSP data version is unknown, and a panel built from an unknown version cannot be checked against a later download.

Examples

>>> ref.manifest["product_end"]
'2025-12-31'

path_for(name)

Return the parquet path where the table name is stored.

Parameters:

namestr

Table name, e.g. "stkdelists".

Returns:

Path

<reference_dir>/<name>.parquet.

Examples

>>> ref.path_for("stkdelists").name
'stkdelists.parquet'

property product_end

Return the CRSP product end date, the last date of the downloaded data version.

Examples

>>> ref.product_end
datetime.date(2025, 12, 31)

table(name)

Return one reference table, read from parquet and cached.

Parameters:

namestr

A key of REFERENCE_TABLES_BY_NAME.

Returns:

pl.DataFrame

The table as stored (already typed by its spec when written).

Raises:

KeyError

If name is not a CRSP reference table.

FileNotFoundError

If the parquet file is missing. The message names the directory and the command that fills it, because this is the error a user sees after converting before downloading the reference tables.

Examples

>>> ref.table("stksecurityinfohist").select("permno", "ticker").head(2)
shape: (2, 2)
┌────────┬────────┐
│ permno ┆ ticker │
│ ---    ┆ ---    │
│ i64    ┆ str    │
╞════════╪════════╡
│ 14593  ┆ AAPL   │
│ 14593  ┆ AAPL   │
└────────┴────────┘