HMD.jl
A simple interface to load mortality data from the Human Mortality Database (HMD).
Note: expects users to have already registered on mortality.org. New users can register here.
Quickstart
Get Australian mortality data in yearly intervals using the codes:
julia> df = read_HMD("AUS", "Mx", "1x1", "username", "password");
Checking inputs are valid...
Attempting initial connection...
Attempting to login...
Data successfully retrieved...
Data processing in progress...
Success!
julia> df
11100×5 DataFrame
Row │ Year Age Female Male Total
│ Int64 Int64 Float64 Float64 Float64
───────┼────────────────────────────────────────────
1 │ 1921 0 0.059987 0.076533 0.068444
2 │ 1921 1 0.012064 0.014339 0.013225
3 │ 1921 2 0.005779 0.006047 0.005916
4 │ 1921 3 0.002889 0.004197 0.003554
5 │ 1921 4 0.003254 0.003254 0.003254
6 │ 1921 5 0.002517 0.002509 0.002513
7 │ 1921 6 0.002485 0.002218 0.00235
8 │ 1921 7 0.001812 0.001924 0.001869
9 │ 1921 8 0.001384 0.001914 0.001651
10 │ 1921 9 0.001371 0.001419 0.001395
11 │ 1921 10 0.001249 0.001508 0.00138
12 │ 1921 11 0.001159 0.002104 0.001639
13 │ 1921 12 0.001128 0.001639 0.001387
14 │ 1921 13 0.001417 0.001547 0.001482
15 │ 1921 14 0.001435 0.001809 0.001625
16 │ 1921 15 0.001602 0.001463 0.001531
17 │ 1921 16 0.00181 0.002022 0.001918
18 │ 1921 17 0.002166 0.002518 0.002343
19 │ 1921 18 0.002477 0.002569 0.002523
20 │ 1921 19 0.002201 0.002415 0.002308
21 │ 1921 20 0.002976 0.002496 0.002737
22 │ 1921 21 0.002542 0.003257 0.002896
23 │ 1921 22 0.002535 0.003347 0.002934
24 │ 1921 23 0.003258 0.003237 0.003248
25 │ 1921 24 0.003139 0.003657 0.003388
⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮
11077 │ 2020 87 0.07675 0.099391 0.08613
11078 │ 2020 88 0.085788 0.113244 0.0969
11079 │ 2020 89 0.100232 0.130582 0.11221
11080 │ 2020 90 0.112916 0.150207 0.127205
11081 │ 2020 91 0.138173 0.166285 0.148653
11082 │ 2020 92 0.151967 0.191856 0.166303
11083 │ 2020 93 0.170144 0.216478 0.185781
11084 │ 2020 94 0.192143 0.23242 0.204956
11085 │ 2020 95 0.234952 0.25596 0.241327
11086 │ 2020 96 0.236959 0.298463 0.25461
11087 │ 2020 97 0.279762 0.342779 0.296528
11088 │ 2020 98 0.303953 0.360883 0.317969
11089 │ 2020 99 0.321907 0.406846 0.341437
11090 │ 2020 100 0.35555 0.436786 0.373218
11091 │ 2020 101 0.431901 0.481868 0.441727
11092 │ 2020 102 0.477836 0.534439 0.487884
11093 │ 2020 103 0.509162 0.571852 0.51938
11094 │ 2020 104 0.541729 0.571353 0.546343
11095 │ 2020 105 0.583185 0.612091 0.587314
11096 │ 2020 106 0.623046 0.675425 0.629872
11097 │ 2020 107 0.669924 0.85531 0.688934
11098 │ 2020 108 0.737114 1.85915 0.793049
11099 │ 2020 109 0.898135 0.0 0.898135
11100 │ 2020 110 1.69687 0.0 1.69687
11051 rows omitted
Alternatively, get data by writing the full name out:
julia> df = HMD.read_HMD("United Kingdom (England and Wales)", "Deaths by Lexis Triangle", "1x5", "username", "password");
Checking inputs are valid...
Attempting initial connection...
Attempting to login...
Data successfully retrieved...
Data processing in progress...
Success!
julia> df
40001×6 DataFrame
Row │ Year Age Cohort Female Male Total
│ Int64 Int64 Float64 Float64 Float64 Float64
───────┼─────────────────────────────────────────────────────
1 │ 1841 0 1841.0 22154.1 27549.9 49704.0
2 │ 1841 0 1840.0 10645.9 13975.1 24621.0
3 │ 1841 1 1840.0 7701.29 8141.42 15842.7
4 │ 1841 1 1839.0 5593.71 5872.58 11466.3
5 │ 1841 2 1839.0 3890.47 3911.58 7802.05
6 │ 1841 2 1838.0 3628.53 3619.42 7247.95
7 │ 1841 3 1838.0 2478.04 2562.2 5040.24
8 │ 1841 3 1837.0 2412.96 2475.8 4888.76
9 │ 1841 4 1837.0 1797.61 1844.6 3642.21
10 │ 1841 4 1836.0 1750.39 1782.4 3532.79
11 │ 1841 5 1836.0 1345.03 1392.61 2737.64
12 │ 1841 5 1835.0 1369.71 1375.59 2745.3
13 │ 1841 6 1835.0 1044.56 1095.8 2140.36
14 │ 1841 6 1834.0 1063.73 1082.41 2146.14
15 │ 1841 7 1834.0 807.25 857.85 1665.1
16 │ 1841 7 1833.0 822.07 847.36 1669.43
17 │ 1841 8 1833.0 633.11 678.75 1311.86
18 │ 1841 8 1832.0 644.73 670.45 1315.18
19 │ 1841 9 1832.0 522.12 558.51 1080.63
20 │ 1841 9 1831.0 531.7 551.68 1083.38
21 │ 1841 10 1831.0 452.53 479.38 931.91
22 │ 1841 10 1830.0 490.93 496.2 987.13
23 │ 1841 11 1830.0 427.6 439.79 867.39
24 │ 1841 11 1829.0 463.88 455.23 919.11
25 │ 1841 12 1829.0 424.04 420.59 844.63
⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮
39978 │ 2021 98 1922.0 1837.07 596.95 2434.02
39979 │ 2021 99 1922.0 1514.03 509.59 2023.62
39980 │ 2021 99 1921.0 1412.97 469.41 1882.38
39981 │ 2021 100 1921.0 1185.09 327.66 1512.75
39982 │ 2021 100 1920.0 1046.91 277.34 1324.25
39983 │ 2021 101 1920.0 916.5 244.25 1160.75
39984 │ 2021 101 1919.0 578.5 150.75 729.25
39985 │ 2021 102 1919.0 387.07 86.28 473.35
39986 │ 2021 102 1918.0 303.93 64.72 368.65
39987 │ 2021 103 1918.0 239.75 49.42 289.17
39988 │ 2021 103 1917.0 195.25 38.58 233.83
39989 │ 2021 104 1917.0 152.43 28.31 180.74
39990 │ 2021 104 1916.0 138.57 24.69 163.26
39991 │ 2021 105 1916.0 100.9 18.14 119.04
39992 │ 2021 105 1915.0 73.98 12.94 86.92
39993 │ 2021 106 1915.0 54.24 9.1 63.34
39994 │ 2021 106 1914.0 40.79 6.65 47.44
39995 │ 2021 107 1914.0 29.33 4.6 33.93
39996 │ 2021 107 1913.0 20.57 2.89 23.46
39997 │ 2021 108 1913.0 14.52 1.97 16.49
39998 │ 2021 108 1912.0 9.93 1.43 11.36
39999 │ 2021 109 1912.0 6.89 0.96 7.85
40000 │ 2021 109 1911.0 4.7 0.63 5.33
40001 │ 2021 110 0.0 9.13 0.68 9.81
39952 rows omitted
Package Features
- Downloads and creates a
DataFrame
object for a given country, type of table, and interval. - Provides the functionality to save output as CSVs.
- Supports full country and table names.
- Displays available countries and tables.
TODO
- Check all combinations and flag invalid ones.
- Add unit tests
Documentation
HMD.get_countries
— Methodget_countries()::Dict{String, String}
Returns a Dictionary
of valid countries and territories (i.e "Australia", "Austria", etc.)
HMD.get_groups
— Methodget_groups()::Vector{String}
Returns a Vector
of valid groupings (i.e. "1x1", "1x5", etc.)
HMD.get_tables
— Methodget_tables()::Dict{String, String}
Returns a Dictionary
of valid tables (i.e. "Births", "Deaths", etc.).
HMD.read_HMD
— Methodread_HMD(country::String, tbl::String, grp::String, username::String, password::String; save=false, verbose=false)::Union{Nothing, DataFrame}
Takes as input the country, table, interval and user credentials.
country
the country OR country code – seeget_country()
for a full listtbl
the chosen table OR table code – seeget_table()
for a full listgrp
one of "1x1", "1x5", "1x10" – depending on combination withtbl
username
email address when registeringpassword
password when registering
Optional:
save
a Boolean keyword to save to a CSVverbose
for progress logs
Returns a DataFrame
object if successful.
HMD.read_HMD
— Methodread_HMD(file_name::String; save=false, verbose=false)::Union{Nothing, DataFrame}
Takes as input the location of a .txt file downloaded from https://www.mortality.org/ and stored locally
Optional:
save
a Boolean keyword to save to a CSVverbose
for progress logs
Returns a DataFrame
object containing the data.
HMD.transform
— Methodtransform(df::DataFrame, col::Symbol)::Union{Nothing, DataFrame}
Returns a DataFrame
structured age x year for a given feature (e.g. :Total)