farms

Financial Analysis & Risk Management (farms) is a Python toolkit for teaching and research. It provides a simple interface for downloading Fama-French factors and portfolio returns from the Kenneth French Data Library.

Installation

farms requires Python 3.11 or newer.

python -m pip install farms

To work on a local checkout, install it in editable mode:

python -m pip install -e .

The data-loading functions require an internet connection when called.

Alpha Vantage monthly adjusted prices

format_alpha_vantage formats a response from Alpha Vantage's TIME_SERIES_MONTHLY_ADJUSTED endpoint. Obtain an API key from Alpha Vantage before making a request.

Inputs

Invalid, reversed, rate-limited, or malformed API responses raise clear exceptions.

Output

Returns a DataFrame with a monthly PeriodIndex named date, sorted chronologically.

All output columns are numeric.

Examples

import os

import farms
import requests

response = requests.get(
    "https://www.alphavantage.co/query",
    params={
        "function": "TIME_SERIES_MONTHLY_ADJUSTED",
        "symbol": "MSFT",
        "apikey": os.environ["ALPHAVANTAGE_API_KEY"],
    },
    timeout=30,
)

monthly = farms.format_alpha_vantage(
    response,
    start_date="2020-01",
    end_date="2020-12",
)
print(monthly.head())

CRSP monthly stock data (WRDS)

get_crsp_msf_by_ids loads CRSP Monthly Stock File observations through a caller-provided WRDS connection. You need a WRDS account with access to the CRSP data set. wrds is intentionally not installed as a required farms dependency, so install it separately:

python -m pip install wrds

Inputs

The date range refers to complete calendar months. For example, start_date="2020-01" and end_date="2020-03" returns observations from January through March 2020.

Output

Returns a DataFrame with a monthly PeriodIndex named date, sorted chronologically. Columns include PERMNO, PERMCO, ticker, company/name-history fields, and CRSP price, return, volume, and shares-outstanding fields. ret and retx are decimal returns (0.01 means 1%). prc follows the CRSP price sign convention, vol is trading volume, and shrout is reported by CRSP in thousands of shares.

Examples

Query by PERMNO:

import farms
import wrds

db = wrds.Connection()
monthly = farms.get_crsp_msf_by_ids(
    db,
    identifiers=[14593, 12079],
    start_date="2020-01",
    end_date="2020-12",
    identifier_type="permno",
)

Or query by ticker:

monthly = farms.get_crsp_msf_by_ids(
    db,
    identifiers=["AAPL", "MSFT"],
    start_date="2020-01",
    end_date="2020-12",
    identifier_type="ticker",
)
db.close()

Unified Kenneth French loader

load_ken_french_data is the central loader for normalized Kenneth French factor and portfolio data. The existing get_ff3, get_ff5, get_ff3d, get_ff5d, and get_ken_french_deciles functions remain available as convenience and compatibility wrappers.

import farms

# Monthly or daily factors
ff3 = farms.load_ken_french_data("ff3")
ff5_daily = farms.load_ken_french_data("ff5", frequency="daily")

# All momentum deciles
momentum = farms.load_ken_french_data(
    "deciles",
    strategy="momentum",
)

# Selected portfolios plus Fama-French three-factor data
momentum_extremes = farms.load_ken_french_data(
    "deciles",
    strategy="momentum",
    portfolio=[1, 10],
    include_factors="ff3",
)

The first argument can be "ff3", "ff5", "deciles", or "quintiles". Factor data currently supports monthly and daily frequencies. Portfolio data currently supports the registered monthly decile views for all available univariate strategies and quintile views where the source dataset provides true quintile columns. Some ten-portfolio prior-return datasets are decile-only.

For portfolio data, portfolio=None or "all" returns every portfolio; portfolio="low", portfolio="high", an integer, or a sequence of integers selects specific portfolios. include_factors=None leaves portfolio data unchanged, while "market", "ff3", or "ff5" adds factor columns.

Fama-French factors

Inputs

For Fama-French factor loaders and Kenneth French decile portfolios, start_date and end_date are optional.

• When start_date=None, the loader requests the full available history, beginning from 1900-01-01.
• When end_date=None, the loader requests observations through the latest date available from the Kenneth French Data Library.
• You may provide either bound independently.

Use month-formatted dates (YYYY-MM) for get_ff3, get_ff5, and decile data. For daily factor data (get_ff3d and get_ff5d), use day-formatted dates (YYYY-MM-DD).

Outputs

All factor loaders return decimal returns (0.01 means 1%) and an index named date. This differs from the Kenneth French source files, which report returns in percent.

Examples

# Full available history through the latest available observation
ff3 = farms.get_ff3()

# January 2000 through the latest available observation
ff5 = farms.get_ff5(start_date="2000-01")

# Earliest available history through December 2020
momentum = farms.get_ken_french_deciles(
    "momentum",
    end_date="2020-12",
)

Monthly three-factor data:

import farms

ff3 = farms.get_ff3("2000-01", "2025-12")
print(ff3.head())

Monthly five-factor data:

ff5 = farms.get_ff5("2000-01", "2025-12")
print(ff5.head())

Daily three-factor data:

ff3_daily = farms.get_ff3d("2025-01-01", "2025-12-31")
print(ff3_daily.head())

Daily five-factor data:

ff5_daily = farms.get_ff5d("2025-01-01", "2025-12-31")
print(ff5_daily.head())

The daily five-factor result contains Mkt-RF, SMB, HML, RMW, CMA, and RF. Dates are optional; supplying only start_date retrieves observations from that date through the latest available observation:

ff5_daily = farms.get_ff5d(start_date="2025-01-01")

Monthly factor data use a pandas PeriodIndex. Daily factor data use a pandas DatetimeIndex.

Kenneth French monthly decile portfolios

Inputs

Output

For a strategy, returns a DataFrame with a monthly PeriodIndex named date. It contains Dec 1 through Dec 10, plus mkt-rf and rf by default. factors="FF3" adds smb and hml; factors="FF5" additionally adds rmw and cma. With stype="list", the function prints the supported strategies and returns None.

All portfolio-return and factor columns are decimal returns (0.01 means 1%).

With details=True, the function also prints the strategy title, portfolio-construction details, and the available date range. It still returns the same DataFrame.

Examples

Display the available strategies:

farms.get_ken_french_deciles("list")

Supported strategies are:

• accruals
• beta
• booktomarket
• dividendyield
• earningsprice
• idiosyncraticvariance
• investment
• momentum
• netissuances
• profitability
• shorttermreversal
• size
• variance

Load monthly value-weighted momentum deciles:

momentum = farms.get_ken_french_deciles(
    "momentum",
    start_date="2000-01",
    end_date="2025-12",
)
print(momentum.head())

Add all three-factor columns:

momentum_ff3 = farms.get_ken_french_deciles(
    "momentum",
    start_date="2000-01",
    end_date="2025-12",
    factors="FF3",
)

Add all five-factor columns:

momentum_ff5 = farms.get_ken_french_deciles(
    "momentum",
    start_date="2000-01",
    end_date="2025-12",
    factors="FF5",
)

Print teaching details while retaining the returned DataFrame:

momentum = farms.get_ken_french_deciles(
    "momentum",
    start_date="2000-01",
    end_date="2025-12",
    details=True,
)

Running tests

Install pytest and run the suite from the repository root:

python -m pip install pytest
python -m pytest