Skip to main content

download.download_data_jkp()

Download and process Global Factor Data.

Usage

Source

download.download_data_jkp(
    dataset="factors",
    region="usa",
    factors="all_factors",
    classification="gics",
    frequency="monthly",
    weighting="vw_cap",
    start_date=None,
    end_date=None
)

Downloads and processes data from Global Factor Data <https://jkpfactors.com/data>_, the public data library accompanying Jensen, Kelly, and Pedersen (2023). The data are stored as zipped CSV files (and a few plain CSV reference files) in a public AWS S3 bucket. For the factor, portfolio, and industry products the function validates the requested selection against the library’s live availability manifest, then downloads the matching archive, unzips it, aligns monthly dates to the beginning of the month, and optionally filters by a date range.

Returns are already expressed as plain numeric (decimal) values in the source data, so no rescaling is applied. The data are licensed under CC BY-NC 4.0 (non-commercial use).

Parameters

dataset: str = "factors"

The Global Factor Data product to download, one of: ‘factors’ (characteristic-managed portfolio returns), ‘portfolios’ (the underlying low/middle/high portfolios that make up each long-short factor), ‘industry’ (industry returns), ‘nyse_cutoffs’ (NYSE size breakpoints), or ‘return_cutoffs’ (return winsorization cutoffs).

region: str = "usa"

The region or country to download, using the codes from the availability manifest (e.g., ‘usa’, ‘world’, ‘developed’, ‘emerging’, or an ISO-3 country code such as ‘jpn’). Ignored for the reference datasets ‘nyse_cutoffs’ and ‘return_cutoffs’. Call ‘list_supported_jkp_factors’ to see the available regions.

factors: str = "all_factors"

The factor content for the ‘factors’ and ‘portfolios’ datasets. For ‘factors’: ‘mkt’ (the market factor), ‘all_factors’ (all factors), ‘all_themes’ (all themes), a single theme (e.g., ‘value’, ‘momentum’), or a single factor code (e.g., ‘be_me’, ‘ret_12_1’). For ‘portfolios’: a single factor code. Call ‘list_supported_jkp_factors(region, dataset)’ to see the values available for a region.

classification: str = "gics"

The industry classification for the ‘industry’ dataset, either ‘gics’ or ‘ff49’ (Fama-French 49 industries).

frequency: str = "monthly"

The data frequency, either ‘monthly’ or ‘daily’. The ‘industry’ dataset is only available at monthly frequency. For ‘return_cutoffs’, the frequency selects the monthly or daily cutoff file.

weighting: str = "vw_cap"

The portfolio weighting scheme: ‘vw_cap’ (capped value-weighted), ‘vw’ (value-weighted), or ‘ew’ (equal-weighted). Ignored for the reference datasets.

start_date: str = None

A character string or date in ‘YYYY-MM-DD’ format specifying the start date for the data. If not provided, the full dataset is returned.

end_date: str = None
A character string or date in ‘YYYY-MM-DD’ format specifying the end date for the data. If not provided, the full dataset is returned.

Returns

pl.DataFrame
A data frame with the processed data. The ‘date’ column is aligned to the beginning of the month for monthly data, and all returns are plain numeric (decimal) values. The remaining columns depend on ‘dataset’: the ‘factors’ data carry ‘location’, ‘name’, ‘freq’, ‘weighting’, ‘direction’, ‘n_stocks’, ‘n_stocks_min’, and ‘ret’; the ‘portfolios’ data add a ‘pf’ portfolio identifier; the ‘industry’ data carry the classification code alongside ‘ret’; and the reference datasets carry breakpoint or cutoff columns.

References

Jensen, T. I., Kelly, B. T., and Pedersen, L. H. (2023). Is there a replication crisis in finance? Journal of Finance, 78(5), 2465-2518. https://doi.org/10.1111/jofi.13249

Examples

from tidyfinance import download_data_jkp
download_data_jkp(
    region='usa', factors='mkt',
    start_date='2000-01-01', end_date='2020-12-31',
)
download_data_jkp(
    dataset='portfolios', region='usa', factors='be_me',
    start_date='2000-01-01', end_date='2020-12-31',
)
download_data_jkp(dataset='industry', region='usa', classification='gics')
download_data_jkp(dataset='nyse_cutoffs')