GetFactors: Scrape Academic Financial Data Libraries

Description Usage Arguments Details Value Note Author(s) Source Examples

View source: R/GetFactors.R


This is a convenience function to provide an easy way to download research financial data sets from several accredited sources. Specifically, it allows to import them in the R environment as xts objects. Scientific libraries here contemplated are from several researchers as, unfortunately, a wide open source collection is not available at this time. On one hand, these resources - of admirable effort - lack important features (financial) databases guarantee: importantly, there aren't APIs to leverage by systematic connections. On the other hand, these data sets satisfy important characteristics: they are open sourced, free to use for everyone, and collected/maintained by researchers of the field.

In the case of the Fama-French's online library, generally stock data is obtained from the Center for Research in Security Prices, LLC (CRSP) and the risk-free rate is from Ibbotson and Associates, Inc. or Bloomberg databases.

All credits for collecting, maintaining, and sharing data belong to the mentioned authors or copyright holders (see 'Source').


GetFactors(x, src, freq, term, country = NULL)



A character string specifying which data set to download. One of FF3, FF5, MOM, REV, or Q5. See 'Value'.


A character string, the source to download data from. FF (default) and HXZ currently available.


A character string, specifying x data frequency. One of 'annual', 'monthly' (default), 'quarterly', 'weekly', 'w2w', or 'daily'. See 'Details'.


A character to be additionally provided when x='REV'. Either 'ST' (short-term, default) or 'LT' (long term).


A character string indicating for which country Fama-French's factors are being requested. Default is U.S. factors. See 'Details' for other countries available.


Not all the data sets are available at all frequencies. Most Fama-French data sets are available on a 'annual', 'monthly' (default), 'weekly', and 'daily' frequency. However, with respect to factor data, 'weekly' data frequency is available for the three-factor model only. For what concerns the q-factor models, frequencies available also include 'quarterly' and w2w(Wednesday-to-Wednesday weekly data) frequencies.

The parameter country can specify one of those "country" (country or region) made available by Fama-French. Countries they make available are 'Asia Pacific ex Japan', 'Developed', 'Developed ex US', 'Emerging', 'Europe', 'Japan', 'North America' and 'United States' (the 'domestic' country with respect to which the standard Fama-French's factors are computed, with markets being NYSE, AMEX and NASDAQ).

Fama-French often indicate missing data by -99.99 or -999.


An xts object with columns being factors over the whole period available from source. For FF3, FF5, and Q5, the risk free rate (RF, e.g. 1-month T-Bill return for the U.S.) is included as well. RF may present small differences from data set to data set. All values are returned in decimal units. Because the actual object depends on the data set chosen, which more often than not resembles factors included in established models in the literature, below we provide a brief summary of the factors currently available relative to the model they originally belong to.

Other factors downloadable as standalone time series are MOM - the momentum factor, also referred to as Up Minus Down (UMD) - and REV, the reversal factor further distinguished in short- and long-term. Adding the former to FF3 gives the factors data set of the so called Fama-French-Carhart model, while adding it to FF5 originates the Fama-French six-factor model.


WARNING: We are not in a position to interact directly with the online library via an API and there could be possible inconsistencies in source files formatting. Given this shaking foundations and despite our efforts to guarantee an optimal result, it could happen that data obtained is not what expected. A sign that the data file downloaded may be incomplete is the lack of the header as specified above.

Also, please be considerate while using the function. In particular, do not send too frequent requests to the web source as the supported/tolerated request rate is unknown. Usage remains at your own discretion and responsibility.


Vito Lestingi


Kenneth R. French's data library,


## Not run: 
# Fama-French Three-factor model data
GetFactors('FF3', src='FF')

# Momentum factor
GetFactors('MOM', 'FF', 'monthly')

# Short-term reversal factor
GetFactors('REV', 'FF', 'annual', term='ST')

# Fama-French Five-factor model data
GetFactors('FF5', 'FF', 'weekly') # fails, no data currently available

# q^5 monthly factors
GetFactors('Q5', src='HXZ', 'monthly')

## End(Not run) #end dontrun

JustinMShea/ExpectedReturns documentation built on Sept. 27, 2020, 5:41 p.m.