French: Download Datasets from Kenneth French's Data Library

In NMOF: Numerical Methods and Optimization in Finance

Download Datasets from Kenneth French's Data Library

Description

Download datasets from Kenneth French's Data Library.

Usage

French(dest.dir,
       dataset = "F-F_Research_Data_Factors_CSV.zip",
       weighting = "value", frequency = "monthly",
       price.series = FALSE, na.rm = FALSE,
       adjust.frequency = TRUE,
       return.class = "data.frame")

Arguments

dest.dir	string: a path to a directory
dataset	a character string: the CSV file name. Also supported are the keywords ‘market’ and ‘rf’.
weighting	a character string: "equal" or "value"
frequency	a character string: daily, monthly or annual. Whether it is used or ignored depends on the particular dataset.
price.series	logical: convert the returns series into prices series?
na.rm	logical: remove missing values in the calculation of price series?
adjust.frequency	logical: if TRUE, frequency is switched to ‘"daily"’ when the word ‘"daily"’ appears in the dataset's name
return.class	a string: ‘data.frame’ (the default) or ‘zoo’

Details

The function downloads data provided by Kenneth French at https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html. The download file gets a date prefix (current date in format YYYYMMDD) and is stored in directory dest.dir. Before any download is attempted, the function checks whether a file with today's prefix exist in dest.dir; if yes, the file is used.

In the original data files, missing values are coded as -99 or similar. These numeric values are replaced by NA.

Calling the function without any arguments will print the names of the supported datasets (and return them insivibly).

For dataset ‘market’, the function downloads the three-factor dataset, and adds excess return and risk-free rate. For dataset ‘rf’, only the risk-free rate is returned.

Value

A data.frame, with contents depending on the particular dataset, or an object as specified by return.class.

If the download fails, the function evaluates to NULL, typically with warnings.

Author(s)

Enrico Schumann

References

Fama, Eugene F. and French, Kenneth R. (2023) Production of U.S. Rm-Rf, SMB, and HML in the Fama-French Data Library, Chicago Booth Research Paper No. 23-22. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2139/ssrn.4629613")}

Gilli, M., Maringer, D. and Schumann, E. (2019) Numerical Methods and Optimization in Finance. 2nd edition. Elsevier. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/C2017-0-01621-X")}

Schumann, E. (2023) Financial Optimisation with R (NMOF Manual). https://enricoschumann.net/NMOF.htm#NMOFmanual

See Also

Shiller

Examples

## list all supported files
French()


  ## fetch names of files from Kenneth French's website
  try({
      txt <- readLines(paste0("https://mba.tuck.dartmouth.edu/pages/",
                              "faculty/ken.french/data_library.html"))
      csv <- txt[grep("ftp/.*CSV.zip", txt, ignore.case = TRUE)]
      gsub(".*ftp/(.*?CSV.zip).*", "\1", csv, ignore.case = TRUE)
    })


## Not run: 
archive.dir <- "~/Downloads/French"
if (!dir.exists(archive.dir))
    dir.create(archive.dir)
French(archive.dir, "F-F_Research_Data_Factors_CSV.zip")

## End(Not run)

NMOF documentation built on Nov. 5, 2025, 6:38 p.m.