GitHub

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 — Method

get_countries()::Dict{String, String}

Returns a Dictionary of valid countries and territories (i.e "Australia", "Austria", etc.)

source
HMD.get_groups — Method

get_groups()::Vector{String}

Returns a Vector of valid groupings (i.e. "1x1", "1x5", etc.)

source
HMD.get_tables — Method

get_tables()::Dict{String, String}

Returns a Dictionary of valid tables (i.e. "Births", "Deaths", etc.).

source
HMD.read_HMD — Method

read_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 – see get_country() for a full list
  • tbl the chosen table OR table code – see get_table() for a full list
  • grp one of "1x1", "1x5", "1x10" – depending on combination with tbl
  • username email address when registering
  • password password when registering

Optional:

  • save a Boolean keyword to save to a CSV
  • verbose for progress logs

Returns a DataFrame object if successful.

source
HMD.read_HMD — Method

read_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 CSV
  • verbose for progress logs

Returns a DataFrame object containing the data.

source
HMD.transform — Method

transform(df::DataFrame, col::Symbol)::Union{Nothing, DataFrame}

Returns a DataFrame structured age x year for a given feature (e.g. :Total)

source