The hetu R package provides tools to work with Finnish personal identity numbers (hetu). Some functions can also be used with Finnish Business ID numbers (y-tunnus).
Where possible, we have unified the syntax with sweidnumbr.
Install the current devel version in R:
devtools::install_github("ropengov/hetu")
Test the installation by loading the library:
library(hetu)
We also recommend setting the UTF-8 encoding:
Sys.setlocale(locale="UTF-8")
Finnish personal identification numbers (Finnish: henkilötunnus, hetu in short), are used to identify citizens. Hetu PIN consists of eleven characters: DDMMYYCZZZQ, where DDMMYY is the day, month and year of birth, C is the century marker, ZZZ is the individual number and Q is the control character.
Males have odd and females have even individual number. The control character is determined by dividing DDMMYYZZZ by 31 and using the remainder (modulo 31) to pick up the corresponding character from the string “0123456789ABCDEFHJKLMNPRSTUVWXY”. For example, if the remainder is 0, the control character is 0 and if the remainder is 12, the control character is C.
A valid individual number is between 002-899. Individual numbers 900-999 are not in normal use and are used only for temporary or artificial PINs. These temporary PINs are sometimes used in different organizations, such as insurance companies or hospitals, if the individual is not a Finnish citizen, a permanent resident or if the exact identity of the individual cannot be determined at the time. Artificial or temporary PINs are not intended for continuous, long term use and they are not usually accepted by PIN validity checking algorithms.
Temporary PINs provide similar information about individual's birth date or sex as regular PINs. Temporary PINs can also be safely used for testing purposes, as such a number cannot be linked to any real person.
The basic hetu function can be used to view information included in a Finnish personal identification number. The data is outputted as a data frame.
example_pin <- "111111-111C"
hetu(example_pin)
#> hetu sex p.num checksum date day month year century valid.pin
#> 1 111111-111C Male 111 C 1911-11-11 11 11 1911 - TRUE
The output can be made prettier, for example by using knitr:
knitr::kable(hetu(example_pin))
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin |
|---|---|---|---|---|---|---|---|---|---|
| 111111-111C | Male | 111 | C | 1911-11-11 | 11 | 11 | 1911 | - | TRUE |
The hetu function also accepts vectors with several identification numbers as input:
example_pins <- c("010101-0101", "111111-111C")
knitr::kable(hetu(example_pins))
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin |
|---|---|---|---|---|---|---|---|---|---|
| 010101-0101 | Female | 010 | 1 | 1901-01-01 | 1 | 1 | 1901 | - | TRUE |
| 111111-111C | Male | 111 | C | 1911-11-11 | 11 | 11 | 1911 | - | TRUE |
The hetu function does not print warning messages to the user if input vector contains invalid PINs. Validity of specific PINs can be determined by looking at the valid.pin column.
hetu(c("010101-0102", "111311-111C", "010101-0101"))
#> hetu sex p.num checksum date day month year century valid.pin
#> 1 010101-0102 Female 010 2 1901-01-01 1 1 1901 - FALSE
#> 2 111311-111C Male 111 C <NA> 11 NA 1911 - FALSE
#> 3 010101-0101 Female 010 1 1901-01-01 1 1 1901 - TRUE
Information contained in the PIN can be extracted with a generic extract parameter. Valid values for extraction are hetu, sex, personal.number, checksum, date, day, month, year, century, valid.pin and is.temp.
is.temp can be extracted only if allow.temp is set to TRUE. If allow.temp is set to FALSE (default), temporary PINs are filtered from the output and information provided by is.temp would be meaningless.
hetu(example_pins, extract = "sex")
#> [1] "Female" "Male"
hetu(example_pins, extract = "checksum")
#> [1] "1" "C"
Some fields can be extracted with specialized functions. Extracting sex with hetu_sex function:
hetu_sex(example_pins)
#> [1] "Female" "Male"
Extracting age at current date and at a given date with hetu_age function:
hetu_age(example_pins)
#> The age in years has been calculated at 2020-10-16.
#> [1] 119 108
hetu_age(example_pins, date = "2012-01-01")
#> The age in years has been calculated at 2012-01-01.
#> [1] 111 100
hetu_age(example_pins, timespan = "months")
#> The age in months has been calculated at 2020-10-16.
#> [1] 1437 1307
Dates (birth dates) also have their own function, hetu_date.
hetu_date(example_pins)
#> [1] "1901-01-01" "1911-11-11"
The basic hetu function output includes information on the validity of each pin, which can be extracted by using hetu-function with valid.pin as extract parameter.
The validity of the PINs can also be determined by using the hetu_ctrl function, which produces a vector:
hetu_ctrl(c("010101-0101", "111111-111C")) # TRUE TRUE
#> [1] TRUE TRUE
hetu_ctrl("010101-1010") # FALSE
#> [1] FALSE
The package functions can be made to accept artificial or temporary personal identification numbers. Artificial and temporary PINs can be used normally by allowing them through allow.temp parameter.
example_temp_pin <- "010101A900R"
knitr::kable(hetu(example_temp_pin, allow.temp = TRUE))
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin | is.temp |
|---|---|---|---|---|---|---|---|---|---|---|
| 010101A900R | Female | 900 | R | 2001-01-01 | 1 | 1 | 2001 | A | TRUE | TRUE |
A vector with regular and temporary PINs mixed together prints only regular PINs, if allow.temp is not set to TRUE. Automatic omitting of temporary PINs does not produce a visible error message and therefore users need to be cautious if they want to use temporary PINs.
If temporary PINs are not explicitly allowed and the input vector consists of temporary PINs only, the function will return an error.
example_temp_pins <- c("010101A900R", "010101-0101")
hetu_ctrl("010101A900R", allow.temp = FALSE)
#> [1] NA
knitr::kable(hetu(example_temp_pins))
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin | |
|---|---|---|---|---|---|---|---|---|---|---|
| 2 | 010101-0101 | Female | 010 | 1 | 1901-01-01 | 1 | 1 | 1901 | - | TRUE |
When allow.temp is set to TRUE, all PINs are handled as if they were regular PINs.
knitr::kable(hetu(example_temp_pins, allow.temp = TRUE))
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin | is.temp |
|---|---|---|---|---|---|---|---|---|---|---|
| 010101A900R | Female | 900 | R | 2001-01-01 | 1 | 1 | 2001 | A | TRUE | TRUE |
| 010101-0101 | Female | 010 | 1 | 1901-01-01 | 1 | 1 | 1901 | - | TRUE | FALSE |
hetu_ctrl("010101A900R", allow.temp = TRUE)
#> [1] TRUE
Validation function hetu_ctrl produces a FALSE for every artificial / temporary PIN, if they are not explicitly allowed.
knitr::kable(hetu(example_temp_pins)) #FALSE TRUE
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin | |
|---|---|---|---|---|---|---|---|---|---|---|
| 2 | 010101-0101 | Female | 010 | 1 | 1901-01-01 | 1 | 1 | 1901 | - | TRUE |
knitr::kable(hetu(example_temp_pins, allow.temp = TRUE)) #TRUE TRUE
| hetu | sex | p.num | checksum | date | day | month | year | century | valid.pin | is.temp |
|---|---|---|---|---|---|---|---|---|---|---|
| 010101A900R | Female | 900 | R | 2001-01-01 | 1 | 1 | 2001 | A | TRUE | TRUE |
| 010101-0101 | Female | 010 | 1 | 1901-01-01 | 1 | 1 | 1901 | - | TRUE | FALSE |
Random PINs can be generated by using the rpin function.
rhetu(n = 4)
#> [1] "050192-2561" "070662-881S" "200408-4689" "130161-6629"
rhetu(n = 4, start_date = "1990-01-01", end_date = "2005-01-01")
#> [1] "200390-279J" "080991-091U" "070997-8208" "020701A0294"
The number of males in the generated sample can be changed with parameter p.male. Default is 0.4.
random_sample <- rhetu(n = 4, p.male = 0.8)
table(random_sample)
#> random_sample
#> 010207-306X 130320A107D 141273-833D 300313-387L
#> 1 1 1 1
The default proportion of artificial / temporary PINs is 0.0, meaning that no artificial / temporary PINs are generated by default.
temp_sample <- rhetu(n = 4, p.temp = 0.5)
table(hetu(temp_sample, allow.temp = TRUE, extract = "is.temp"))
#>
#> FALSE TRUE
#> 2 2
In addition to information mentioned in the section Extracting specific information, the user can choose to print additional columns containing information about checks done on PINs. The diagnostic checks produce a TRUE or FALSE for the following categories: valid.p.num, valid.checksum, correct.checksum, valid.date, valid.day, valid.month, valid.year, valid.length and valid.century, FALSE meaning that hetu is somehow incorrect.
diagnosis_example <- c("010101-0102", "111111-111Q",
"010101B0101", "320101-0101", "011301-0101",
"010101-01010", "010101-0011")
head(hetu(diagnosis_example, diagnostic = TRUE), 3)
#> hetu sex p.num checksum date day month year century valid.pin
#> 1 010101-0102 Female 010 2 1901-01-01 1 1 1901 - FALSE
#> 2 111111-111Q Male 111 Q 1911-11-11 11 11 1911 - FALSE
#> 3 010101B0101 Female 010 1 <NA> 1 1 NA B FALSE
#> valid.p.num valid.checksum correct.checksum valid.date valid.day valid.month
#> 1 TRUE TRUE FALSE TRUE TRUE TRUE
#> 2 TRUE FALSE FALSE TRUE TRUE TRUE
#> 3 TRUE TRUE TRUE FALSE TRUE TRUE
#> valid.year valid.length valid.century
#> 1 TRUE TRUE TRUE
#> 2 TRUE TRUE TRUE
#> 3 TRUE TRUE FALSE
Diagnostic information can be examined more closely by using subset or by using a separate hetu_diagnostics function. The user can print all diagnostic information for all PINs in the dataset:
tail(hetu_diagnostic(diagnosis_example), 3)
#> hetu is.temp valid.p.num valid.checksum correct.checksum valid.date
#> 5 011301-0101 FALSE TRUE TRUE FALSE FALSE
#> 6 010101-01010 FALSE TRUE TRUE TRUE TRUE
#> 7 010101-0011 FALSE FALSE TRUE FALSE TRUE
#> valid.day valid.month valid.year valid.length valid.century
#> 5 TRUE FALSE TRUE TRUE TRUE
#> 6 TRUE TRUE TRUE FALSE TRUE
#> 7 TRUE TRUE TRUE TRUE TRUE
By using extract, the user can limit the printed columns to only those which have FALSE values.
hetu_diagnostic(diagnosis_example, extract = c("valid.century", "correct.checksum"))
#> hetu valid.century correct.checksum
#> 1 010101-0102 TRUE FALSE
#> 2 111111-111Q TRUE FALSE
#> 3 010101B0101 FALSE TRUE
#> 4 320101-0101 TRUE TRUE
#> 5 011301-0101 TRUE FALSE
#> 6 010101-01010 TRUE TRUE
#> 7 010101-0011 TRUE FALSE
When subsetting is set to TRUE, the function prints only rows with FALSE value in the extracted test.
hetu_diagnostic(diagnosis_example, subsetting = TRUE, extract = "valid.century")
#> hetu sex p.num checksum date day month year century valid.pin
#> 1 010101B0101 Female 010 1 <NA> 1 1 NA B FALSE
#> valid.p.num valid.checksum correct.checksum valid.date valid.day valid.month
#> 1 TRUE TRUE TRUE FALSE TRUE TRUE
#> valid.year valid.length valid.century is.temp
#> 1 TRUE TRUE FALSE FALSE
Because of the way PINs are handled in inside hetu-function, the diagnostics-function can show unexpected warning messages or introduce NAs by coercion if the date-part of the PIN is too long. This may result in inability to handle the PIN at all!
# Faulty example
hetu_diagnostic(c("01011901-01010"))
The package has also the ability to generate Finnish Business ID codes (y-tunnus) and check their validity. Unlike with personal identification numbers, no additional information can be extracted from Business IDs.
Similar to hetu PINs, random Finnish Business IDs (y-tunnus) can be generated by using rbid function.
bid_sample <- rbid(3)
bid_sample
#> [1] "3363802-7" "9073195-7" "2855946-3"
The validity of Finnish Business Identity Codes can be checked with a similar function to hetu_ctrl: bid_ctrl.
bid_ctrl(c("0737546-2", "1572860-0")) # TRUE TRUE
#> [1] TRUE TRUE
bid_ctrl("0737546-1") # FALSE
#> [1] FALSE
Data frames generated by hetu function work well with tidyverse/dplyr workflows as well.
library(hetu)
library(tidyverse)
library(dplyr)
# Generate data for this example
hdat<-tibble(pin=rhetu(n = 4, start_date = "1990-01-01", end_date = "2005-01-01"))
# Extract all the hetu information to tibble format
hdat<-hdat %>%
mutate(result=map(.x=pin,.f=hetu::hetu)) %>% unnest(cols=c(result))
hdat
This work can be freely used, modified and distributed under the open license specified in the DESCRIPTION file.
Kindly cite the work as follows
citation("hetu")
#>
#> Kindly cite the hetu R package as follows:
#>
#> (C) Pyry Kantanen, Mans Magnusson, Jussi Paananen and Leo Lahti
#> (rOpenGov 2020). hetu: Finnish personal ID number data toolkit for
#> R. URL: http://github.com/rOpenGov/hetu
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Misc{,
#> title = {hetu: Finnish personal ID number data toolkit for R},
#> author = {Pyry Kantanen and Mans Magnusson and Jussi Paananen and Leo Lahti},
#> year = {2020},
#> }
#>
#> Many thanks for all contributors!
This vignette was created with
sessionInfo()
#> R version 4.0.3 (2020-10-10)
#> Platform: x86_64-apple-darwin17.0 (64-bit)
#> Running under: macOS Catalina 10.15.7
#>
#> Matrix products: default
#> BLAS: /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRblas.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRlapack.dylib
#>
#> locale:
#> [1] C/fi_FI.UTF-8/fi_FI.UTF-8/C/fi_FI.UTF-8/fi_FI.UTF-8
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] hetu_1.0.1
#>
#> loaded via a namespace (and not attached):
#> [1] Rcpp_1.0.5 lubridate_1.7.9 crayon_1.3.4 dplyr_1.0.2
#> [5] R6_2.4.1 lifecycle_0.2.0 backports_1.1.10 magrittr_1.5
#> [9] evaluate_0.14 pillar_1.4.6 highr_0.8 rlang_0.4.7
#> [13] stringi_1.5.3 ellipsis_0.3.1 checkmate_2.0.0 vctrs_0.3.4
#> [17] generics_0.0.2 tools_4.0.3 stringr_1.4.0 glue_1.4.2
#> [21] purrr_0.3.4 xfun_0.18 compiler_4.0.3 pkgconfig_2.0.3
#> [25] tidyselect_1.1.0 knitr_1.30 tibble_3.0.3