API Reference
HMD
pyhmfd.hmd.read_hmd(filepath, fixup=True)
Read a locally saved HMD text file into a DataFrame.
Parameters
filepath:
Path to the HMD .txt file (e.g. Mx_1x1.txt).
fixup:
If True, run :func:~pyhmfd.parsers.hmd_parse to coerce column
types and add the OpenInterval indicator column.
Returns
pandas.DataFrame
pyhmfd.hmd.read_hmd_web(country, item, username=None, password=None, fixup=True)
Download one data item for one country from the HMD.
Parameters
country:
HMD country short code (e.g. "USA", "FRATNP").
Use :func:get_hmd_countries to list valid codes.
item:
Data item name (e.g. "Mx_1x1", "Deaths_1x1").
Use :func:get_hmd_items to list available items per country.
username:
HMD account e-mail. Resolved from HMD_USER env var if omitted.
password:
HMD account password. Resolved from HMD_PASSWORD env var or
keyring if omitted.
fixup:
If True, coerce column types and add OpenInterval column.
Returns
pandas.DataFrame
Examples
import pyhmfd df = pyhmfd.read_hmd_web("USA", "Mx_1x1")
pyhmfd.multi.read_hmd_web_multi(countries, item, username=None, password=None, fixup=True, workers=4, on_error='warn')
Download one HMD data item for multiple countries in parallel.
Parameters
countries:
List of HMD country short codes, or "all" to download every
available country. Use :func:~pyhmfd.get_hmd_countries to list
valid codes.
item:
Data item name (e.g. "Mx_1x1", "Deaths_1x1").
username:
HMD account e-mail. Resolved from HMD_USER env var if omitted.
password:
HMD account password. Resolved from HMD_PASSWORD env var or
keyring if omitted.
fixup:
If True, coerce column types and add OpenInterval column.
workers:
Number of parallel download threads.
on_error:
"warn" (default) — skip failing countries and emit a warning.
"raise" — raise the first error encountered.
Returns
pandas.DataFrame
Concatenated data with a leading country column.
Examples
import pyhmfd df = pyhmfd.read_hmd_web_multi(["AUS", "USA", "SWE"], "Mx_1x1") df = pyhmfd.read_hmd_web_multi("all", "Deaths_1x1", workers=8)
pyhmfd.hmd.get_hmd_countries()
Return all HMD country and sub-population short codes.
Returns
list[str]
e.g. ['AUS', 'AUT', ..., 'USA']
pyhmfd.hmd.get_hmd_items(country)
List all data items available for a given HMD country.
Parameters
country: HMD country short code.
Returns
pandas.DataFrame
Columns: item, description, url.
HFD
pyhmfd.hfd.read_hfd(filepath, fixup=True, item=None)
Read a locally saved HFD text file into a DataFrame.
Parameters
filepath:
Path to the HFD .txt file.
fixup:
If True, run :func:~pyhmfd.parsers.hfd_parse to coerce column
types and add the OpenInterval indicator column.
item:
Data product code (e.g. "mabRR"). Used by the parser to
determine column types when fixup=True.
Returns
pandas.DataFrame
pyhmfd.hfd.read_hfd_web(country, item, username=None, password=None, fixup=True)
Download one data item for one country from the HFD.
Parameters
country:
HFD country short code (e.g. "USA", "FRATNP").
Use :func:get_hfd_countries to list valid codes.
item:
Data product code (e.g. "asfrRR", "mabRR").
Use :func:get_hfd_items to list available items per country.
username:
HFD account e-mail. Resolved from HFD_USER env var if omitted.
password:
HFD account password. Resolved from HFD_PASSWORD env var or
keyring if omitted.
fixup:
If True, coerce column types and add OpenInterval column.
Returns
pandas.DataFrame
Examples
import pyhmfd df = pyhmfd.read_hfd_web("USA", "asfrRR")
pyhmfd.multi.read_hfd_web_multi(countries, item, username=None, password=None, fixup=True, workers=4, on_error='warn')
Download one HFD data item for multiple countries in parallel.
Parameters
countries:
List of HFD country short codes, or "all" to download every
available country. Use :func:~pyhmfd.get_hfd_countries to list
valid codes.
item:
Data product code (e.g. "asfrRR", "mabRR").
username:
HFD account e-mail. Resolved from HFD_USER env var if omitted.
password:
HFD account password. Resolved from HFD_PASSWORD env var or
keyring if omitted.
fixup:
If True, coerce column types and add OpenInterval column.
workers:
Number of parallel download threads.
on_error:
"warn" (default) — skip failing countries and emit a warning.
"raise" — raise the first error encountered.
Returns
pandas.DataFrame
Concatenated data with a leading country column.
Examples
import pyhmfd df = pyhmfd.read_hfd_web_multi(["USA", "SWE", "JPN"], "asfrRR") df = pyhmfd.read_hfd_web_multi("all", "asfrRR", workers=6)
pyhmfd.hfd.get_hfd_countries()
Return a DataFrame of all HFD countries.
Returns
pandas.DataFrame
Columns: country (full name), code (short code).
pyhmfd.hfd.get_hfd_items(country)
List all data items available for a given HFD country.
Parameters
country: HFD country short code.
Returns
pandas.DataFrame
Columns: item, description, url.
pyhmfd.hfd.get_hfd_date(country)
Return the last-update date for a given HFD country.
Parameters
country: HFD country short code.
Returns
str
Eight-digit date string in 'YYYYMMDD' format.
JMD
pyhmfd.jmd.read_jmd_web(pref_id='00', item='Deaths_5x5', fixup=True)
Download data for a Japanese prefecture from the JMD.
No authentication is required.
Parameters
pref_id:
Two-digit prefecture code ('00' = all Japan, '01' = Hokkaido,
…, '47' = Okinawa).
Use :func:~pyhmfd.hmd.get_jmd_prefectures to list all codes.
item:
Data item name (e.g. 'Deaths_5x5', 'Mx_1x1').
fixup:
If True, coerce column types and add OpenInterval column.
Returns
pandas.DataFrame
Examples
import pyhmfd df = pyhmfd.read_jmd_web("01", "Deaths_1x1")
pyhmfd.hmd.get_jmd_prefectures()
Return a mapping of Japanese prefecture name → 2-digit code.
Codes run from '00' (all Japan) to '47' (Okinawa).
Returns
dict[str, str]
CHMD
pyhmfd.chmd.read_chmd_web(prov_id='can', item='Deaths_1x1', fixup=True)
Download data for a Canadian province from the CHMD.
No authentication is required.
Parameters
prov_id:
Province short code ('can' = all Canada, 'qc' = Quebec, …).
Use :func:~pyhmfd.hmd.get_chmd_provinces to list all codes.
item:
Data item name (e.g. 'Deaths_1x1', 'Mx_1x1').
fixup:
If True, coerce column types and add OpenInterval column.
Returns
pandas.DataFrame
Examples
import pyhmfd df = pyhmfd.read_chmd_web("que", "Mx_1x1")
pyhmfd.hmd.get_chmd_provinces()
Return Canadian province/territory codes for the CHMD.
Returns
list[str]
e.g. ['alb', 'bco', 'can', ...]
Notes
CHMD uses its own 3-letter codes, distinct from standard ISO abbreviations:
can (Canada), que (Quebec), ont (Ontario), bco (British Columbia),
alb (Alberta), man (Manitoba), nbr (New Brunswick),
nsc (Nova Scotia), nfl (Newfoundland), pei (PEI),
sas (Saskatchewan), nwt (Northwest Territories), yuk (Yukon).
HFC
pyhmfd.hfc.read_hfc_web(country, item, fixup=True)
Download a data item for a country from the HFC.
No authentication is required.
Parameters
country:
HFC population short code. Use :func:get_hfc_countries to list
available codes.
item:
Data item identifier (e.g. 'ASFRstand').
fixup:
If True, coerce column types and add OpenInterval column.
Returns
pandas.DataFrame
Examples
import pyhmfd df = pyhmfd.read_hfc_web("RUS", "ASFRstand")
pyhmfd.hfc.get_hfc_countries(names=False)
Return HFC population codes (and optionally full names).
Parameters
names:
If False (default), return a sorted list of short codes.
If True, return a DataFrame with columns country and code.
Returns
list[str] or pandas.DataFrame