pyhmfd

A Python package for reading data from the Human Mortality Database (HMD), Human Fertility Database (HFD), Human Fertility Collection (HFC), Japanese Mortality Database (JMD), and Canadian Historical Mortality Database (CHMD).

Returns tidy pandas.DataFrame objects ready for analysis.

Credits

This package is a Python port of the R package HMDHFDplus by Tim Riffe, Jose Manuel Aburto, and contributors:

Riffe T, Aburto JM, et al. (2023). HMDHFDplus: Read Human Mortality Database and Human Fertility Database Data from the Web. R package. https://github.com/timriffe/HMDHFDplus

The authentication flow, URL patterns, parsing logic, and data-cleaning conventions are derived directly from that work. Licensed under GPL-2.0.

Supported databases

Installation

pip install pyhmfd

Or from source:

git clone https://github.com/filipeclduarte/pyhmfd.git
cd pyhmfd
pip install -e ".[dev]"

Credentials

For HMD and HFD you need a free account at their respective websites. Supply credentials via environment variables (recommended for scripts/CI):

export HMD_USER="your@email.com"
export HMD_PASSWORD="yourpassword"
export HFD_USER="your@email.com"
export HFD_PASSWORD="yourpassword"

Or pass them directly to the function, or let the package prompt interactively. Credentials entered interactively are offered to the system keyring for storage.

Quick start

import pyhmfd

# Human Mortality Database — needs credentials
df = pyhmfd.read_hmd_web("USA", "Mx_1x1")
df = pyhmfd.read_hmd_web("FRATNP", "Deaths_1x1", username="u@example.com", password="pw")

# Human Fertility Database — needs credentials
df = pyhmfd.read_hfd_web("USA", "asfrRR")

# Japanese Mortality Database — no auth
df = pyhmfd.read_jmd_web("01", "Deaths_1x1")   # 01 = Hokkaido

# Canadian Historical Mortality Database — no auth
df = pyhmfd.read_chmd_web("que", "Mx_1x1")     # que = Quebec

# Human Fertility Collection — no auth
df = pyhmfd.read_hfc_web("RUS", "ASFRstand")

# Read a locally downloaded file
df = pyhmfd.read_hmd("/path/to/Mx_1x1.txt")
df = pyhmfd.read_hfd("/path/to/asfrRR.txt", item="asfrRR")

Utility functions

# List available countries
pyhmfd.get_hmd_countries()         # ['AUS', 'AUT', ..., 'USA']
pyhmfd.get_hfd_countries()         # DataFrame with country names and codes
pyhmfd.get_hfc_countries()         # list of codes
pyhmfd.get_jmd_prefectures()       # dict: name → 2-digit code
pyhmfd.get_chmd_provinces()        # ['alb', 'bco', 'can', ...]

# List available data items per country
pyhmfd.get_hmd_items("USA")        # DataFrame: item, description, url
pyhmfd.get_hfd_items("USA")        # DataFrame: item, description, url

# Last-update date for an HFD country
pyhmfd.get_hfd_date("USA")         # '20260323' (date of last update)

Output format

All functions return a pandas.DataFrame. When fixup=True (default):

• Age column is Int64 (nullable integer).
• OpenInterval boolean column marks the terminal open age group (e.g. 110+).
• Year and Cohort are Int64.
• Rate and count columns are float64.
• Missing values coded as '.' in source files become NaN.

Running tests

pytest

License

GPL-2.0, following the original R package.