download_data_jkp: Download and Process Global Factor Data

In tidyfinance: Tidy Finance Helper Functions

Download and Process Global Factor Data

Description

Downloads and processes data from Global Factor 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.

Usage

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

Arguments

dataset	The Global Factor Data product to download, one of: "factors" (characteristic-managed portfolio returns, the default), "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	A character string with 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"). Defaults to "usa". Ignored for the reference datasets "nyse_cutoffs" and "return_cutoffs". Call list_supported_jkp_factors() to see the available regions.
factors	A character string selecting the factor content for the "factors" and "portfolios" datasets. For "factors": "mkt" (the market factor), "all_factors" (all 153 factors), "all_themes" (all 13 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. Defaults to "all_factors". Call list_supported_jkp_factors(region, dataset) to see the values available for a region.
classification	The industry classification for the "industry" dataset, either "gics" (default) or "ff49" (Fama-French 49 industries).
frequency	The data frequency, either "monthly" (default) or "daily". The "industry" dataset is only available at monthly frequency. For "return_cutoffs", the frequency selects the monthly or daily cutoff file.
weighting	The portfolio weighting scheme: "vw_cap" (capped value-weighted, the default), "vw" (value-weighted), or "ew" (equal-weighted). Ignored for the reference datasets.
start_date	Optional. A character string or Date object in "YYYY-MM-DD" format specifying the start date for the data. If not provided, the full dataset is returned.
end_date	Optional. A character string or Date object in "YYYY-MM-DD" format specifying the end date for the data. If not provided, the full dataset is returned.

Details

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).

Value

A tibble 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., & Pedersen, L. H. (2023). Is there a replication crisis in finance? Journal of Finance, 78(5), 2465-2518. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/jofi.13249")}

See Also

Other download functions: download_data(), download_data_constituents(), download_data_factors_ff(), download_data_factors_q(), download_data_fred(), download_data_huggingface(), download_data_macro_predictors(), download_data_osap(), download_data_pastor_stambaugh(), download_data_risk_free(), download_data_stambaugh_yuan(), download_data_stock_prices(), download_factor_library_grid(), download_factor_library_ids()

Examples

  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")

tidyfinance documentation built on July 3, 2026, 1:09 a.m.