| Type: | Package |
| Language: | en-GB |
| Title: | Access and Manipulation of ILOSTAT Labour Statistics |
| Version: | 2.5.1 |
| Date: | 2026-10-16 |
| Maintainer: | David Bescond <bescond@ilo.org> |
| Description: | Provides functions to access and manipulate data from the ILOSTAT database https://ilostat.ilo.org, the International Labour Organization's repository of labour statistics. Supports bulk download of datasets, metadata retrieval, and tools for filtering, reshaping, and analysing data. |
| License: | BSD_2_clause + file LICENSE |
| Depends: | R (≥ 4.2.0) |
| Imports: | data.table (≥ 1.15.0), dplyr (≥ 1.1.4), httr2 (≥ 1.0.0), haven (≥ 2.5.0), jsonlite (≥ 1.8.0), rlang (≥ 1.1.0), readr (≥ 2.1.5), stringr (≥ 1.5.2), tibble (≥ 3.3.0), tidyselect (≥ 1.2.0), xml2 (≥ 1.3.0) |
| Suggests: | ggplot2, knitr, plotly, plotrix, rmarkdown, shiny, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| URL: | https://ilostat.github.io/Rilostat/, https://github.com/ilostat/Rilostat |
| BugReports: | https://github.com/ilostat/Rilostat/issues |
| Encoding: | UTF-8 |
| Config/testthat/edition: | 3 |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-11-04 14:52:09 UTC; bescond |
| Author: | David Bescond |
| Repository: | CRAN |
| Date/Publication: | 2026-11-04 15:30:02 UTC |
R Tools for ilostat Open Data
Description
This package provides a user-friendly interface to access, download, and manage ILOSTAT open data.
Details
On a regular basis new tutorials and examples are built and available through this function.
| Package: | Rilostat |
| Type: | Package |
| Version: | See sessionInfo() or DESCRIPTION file |
| Date: | 2020-2025 |
| License: | BSD_2_clause + file LICENSE |
| LazyLoad: | yes |
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat")
ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
See Also
Useful links:
Report bugs at https://github.com/ilostat/Rilostat/issues
Examples
## Not run:
# check which documentation have been recently added:
# help(Rilostat)
# https://ilostat.github.io/Rilostat/
## End(Not run)
Check Rilostat version against CRAN
Description
Compare installed version with CRAN and warn if outdated.
Usage
check_ilostat_version(pkg = "Rilostat", quiet = FALSE)
Arguments
pkg |
Package name (default "Rilostat") |
quiet |
Logical, suppress message if up-to-date |
Value
Invisible logical (TRUE = up-to-date, FALSE = outdated or unknown)
Clean ilostat Cache
Description
Deletes all cache files from the your ilostat cache directory.
See get_ilostat for more on cache.
Usage
clean_ilostat_cache(
cache_dir = getOption("ilostat_cache_dir", file.path(tempdir(), "ilostat")),
cache_update = getOption("ilostat_cache_update", FALSE),
quiet = getOption("ilostat_quiet", TRUE)
)
Arguments
cache_dir |
A character, path to a cache directory. The directory has to exist.
The |
cache_update |
a logical whether to delete only out of date cache files. Useful when |
quiet |
a logical, if |
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
Examples
## Not run:
clean_ilostat_cache()
## End(Not run)
Switch ilostat to distribution
Description
Get distribution for ilostat number of persons only.
Usage
distribution_ilostat(
x,
var,
.keep = FALSE,
quiet = getOption("ilostat_quiet", TRUE)
)
Arguments
x |
dataset to transform into distribution. |
var |
String variable name use for the distribution default |
.keep |
if true return only new column call distribution default |
quiet |
a logical, if |
Details
this function use the max of the corresponding grouping so it is important to not filter any subset of the corresponding variable selected for the distribution at this level, ie. if you remove SEX_T, the distribution by sex will only have SEX_F or SEX_M / max(SEX_M, SEX_F) * 100, which is no longer a distribution.
In addition, distribution is only applicable for indicators with Number of persons (usually in thousands), So please do not distribute ratios, earnings, hours of works, CPI, GDP etc ... no warning will prevent for that if doubts use distribution from get_ilostat() instead of, warnings will help you.
Value
a data_frame. obs_status will no longer be a number of persons but a percentage.
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
Examples
## Not run:
dat <- get_ilostat("EMP_TEMP_SEX_STE_GEO_NB_A", cache = FALSE)
dat_dist <- distribution_ilostat(dat, "classif1")
dat_plus_dist <- mutate(dat, dist = distribution_ilostat(dat,"classif1", .keep=TRUE))
head(dat_dist)
clean_ilostat_cache()
## End(Not run)
Read ilostat Data
Description
Download datasets from ilostat https://ilostat.ilo.org via bulk download facility https://ilostat.ilo.org/data/bulk/.
Usage
get_ilostat(
id,
segment = getOption("ilostat_segment", "indicator"),
type = getOption("ilostat_type", "code"),
lang = getOption("ilostat_lang", "en"),
time_format = getOption("ilostat_time_format", "raw"),
filters = getOption("ilostat_filter", "none"),
best_source = getOption("ilostat_best_source", "yes"),
fixed = getOption("ilostat_fixed", TRUE),
cache = getOption("ilostat_cache", TRUE),
cache_update = getOption("ilostat_cache_update", TRUE),
cache_dir = getOption("ilostat_cache_dir", NULL),
cache_format = getOption("ilostat_cache_format", "rds"),
back = getOption("ilostat_back", TRUE),
cmd = getOption("ilostat_cmd", "none"),
quiet = getOption("ilostat_quiet", TRUE)
)
Arguments
id |
A code name for the dataset of interest.
See |
segment |
A character, way to get datasets by: |
type |
a character, type of variables, |
lang |
a character, code for language. Available are |
time_format |
a string giving a type of the conversion of the time
column from the ilostat format. "raw" (default)
does not do conversion and return time as character (ie. "2017", "2017Q1", "2017M01"). A "date" converted to
a |
filters |
a list;
|
best_source |
a character; |
fixed |
a logical, if |
cache |
a logical whether to do caching. Default is |
cache_update |
a logical whether to update cache. Check cache update with last.update attribute store on the cache file name
and the one from the table of contents. Can be set also with
options(ilostat_cache_update = FALSE). Default is |
cache_dir |
a path to a cache directory. The directory has to exist.
The |
cache_format |
a character, format to store on the cache |
back |
a logical; if TRUE (default) return a data frame, otherwise only write to cache, |
cmd |
a character, R expression use for manipulate internal data frame |
quiet |
a logical, if |
Value
a tibble. One column for each dimension in the data and the values column for numerical values, as well as the metadata columns. The time column for a time dimension.
others
Data sets are downloaded from the
ilostat bulk download facility.
If only the table id is given, the whole table is downloaded from the
bulk download facility.
The bulk download facility is the fastest method to download whole datasets.
By default datasets from the bulk download facility are cached as they are often rather large.
Cache files are stored in a temporary directory by default or in
a named directory if cache_dir or option ilostat_cache_dir is defined.
The cache can be emptied with clean_ilostat_cache.
The id, a code, for the dataset can be searched with
the get_ilostat_toc or from the [bulk download facility](https://ilostat.ilo.org/data/bulk/).
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
See Also
get_ilostat_toc, label_ilostat
Examples
## Not run:
############# get simple dataset
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A")
head(dat)
dat <- get_ilostat("NZL_Q", segment = "ref_area")
head(dat)
dir.create(file.path(tempdir(), "r_cache"))
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A",
cache_dir = file.path(tempdir(), "r_cache"))
head(dat)
clean_ilostat_cache(cache_dir = file.path(tempdir(), "r_cache"))
options(ilostat_update = TRUE)
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A")
head(dat)
options(ilostat_update = FALSE)
options(ilostat_cache_dir = file.path(tempdir(), "r_cache"))
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A")
clean_ilostat_cache()
############# get multiple datasets
dat <- get_ilostat(c("CPI_ACPI_COI_RT_M", "CPI_ACPI_COI_RT_Q"), cache = FALSE)
head(dat)
toc <- get_ilostat_toc(search = "CPI_")
head(toc)
dat <- get_ilostat(toc, cache = FALSE) #id as a tibble
############# get datasets with filters
dat <- get_ilostat(id = c("UNE_TUNE_SEX_AGE_NB_A", "EMP_TEMP_SEX_AGE_NB_A"),
filters = list( ref_area = "FRA",
classif1 = "_YGE15",
time = "2016",
sex = c("T", "SEX_F")), quiet = TRUE)
head(dat)
clean_ilostat_cache()
############# store in other format
dir.create(file.path(tempdir(), "ilostat"))
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A",
cache_dir = file.path(tempdir(), "r_cache"), cache_format = "csv")
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A",
cache_dir = file.path(tempdir(), "r_cache"), cache_format = "dta")
############# advanced manipulation
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A", cmd = "dat %>% count(ref_area)", quiet = TRUE)
label_ilostat(dat, code = "ref_area")
clean_ilostat_cache()
## End(Not run)
Read ilostat Dictionary
Description
Downloads one ilostat dictionary from ilostat https://ilostat.ilo.org via bulk download facility https://ilostat.ilo.org/data/bulk/.
Usage
get_ilostat_dic(
dic,
lang = getOption("ilostat_lang", "en"),
cache_dir = getOption("ilostat_cache_dir", NULL),
quiet = getOption("ilostat_quiet", TRUE)
)
Arguments
dic |
A character, dictionary for the variable to be downloaded, |
lang |
a character, code for language. Available are |
cache_dir |
a path to a cache directory. The directory has to exist.
The |
quiet |
a logical, if |
Details
For a given coded variable from ilostat https://ilostat.ilo.org/.
The dictionaries link codes with human-readable labels.
To translate codes to labels, use label_ilostat.
Value
tibble with two columns: code names and full names.
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
See Also
Examples
## Not run:
tmp <- get_ilostat_dic("indicator")
head(tmp)
tmp <- get_ilostat_dic("classif1", lang = "fr")
head(tmp)
## End(Not run)
Retrieve ILOSTAT data using an SDMX-oriented interface
Description
'get_ilostat_sdmx()' provides an SDMX-oriented interface to ILOSTAT datasets while reusing the native Rilostat download, disk-cache and filtering infrastructure.
Usage
get_ilostat_sdmx(
id = NULL,
resource = "data",
component = NULL,
segment = "indicator",
type = "code",
format = "dataframe",
lang = "en",
filters = NULL,
best_source = "yes",
fixed = TRUE,
cache_dir = NULL,
refresh = FALSE
)
Arguments
id |
Character. ILOSTAT dataset identifier, for example '"UNE_TUNE_SEX_AGE_NB_A"'. Required for '"data"', '"structure"' and '"codelist"'. For 'resource = "dataflow"', 'id = NULL' returns the complete ILOSTAT dataflow catalogue. |
resource |
Character. SDMX resource to return. One of: '"data"', '"structure"', '"codelist"' or '"dataflow"'. |
component |
Character. SDMX component identifier used with 'resource = "codelist"', for example '"AGE"', '"SEX"', '"OBS_STATUS"' or '"UNIT_MEASURE"'. |
segment |
Character. Native ILOSTAT segment passed to [get_ilostat()] or [get_ilostat_toc()]. |
type |
Character. Representation of coded values. One of: '"code"', '"label"', '"label_short"' or '"both"'. '"code"' returns SDMX codes. '"label"' replaces coded values with their labels. '"label_short"' uses short/display labels when available. '"both"' returns codes together with companion '*_LABEL' columns. |
format |
Character. Output format. One of: '"dataframe"', '"sdmx-ml"' or '"sdmx-json"'. '"sdmx-ml"' and '"sdmx-json"' are available for the structural resources '"structure"', '"codelist"' and '"dataflow"'. Observation data are currently returned as a data frame. |
lang |
Character. Language used for labels. One of '"en"', '"fr"' or '"es"'. |
filters |
Named list of filters using SDMX component identifiers, for example 'REF_AREA', 'SEX', 'AGE', 'FREQ', 'MEASURE' and 'TIME_PERIOD'. Ordinary component filters reuse native Rilostat matching semantics. For example, 'SEX = "SEX_F"' filters female observations. 'FREQ' and 'MEASURE' are dataset-level SDMX constants. A filter that does not match the dataset returns an empty SDMX data frame. 'TIME_PERIOD' supports the existing Rilostat time filtering semantics. Equality can be expressed directly, for example 'TIME_PERIOD = "2020"', while comparison operators can be supplied as a named list, for example 'TIME_PERIOD = list(ge = "2020", le = "2023")'. Ordinary coded components also support 'eq' and 'ne', for example 'SEX = list(ne = "SEX_T")'. |
best_source |
Character. Source-selection behavior passed to [get_ilostat()]. '"yes"' (default) returns best-source observations and does not expose 'BEST_SOURCE'; '"no"' and '"all"' retain the 'BEST_SOURCE' component. |
fixed |
Logical. Native matching behavior passed to [get_ilostat()]. |
cache_dir |
Character or 'NULL'. Directory used for the SDMX metadata disk cache and native Rilostat cache. If 'NULL', the standard Rilostat cache location is used. |
refresh |
Logical. If 'TRUE', refresh cached dataset metadata and request a refresh of the native ILOSTAT data cache. |
Details
The existing [get_ilostat()] function remains the native ILOSTAT interface. 'get_ilostat_sdmx()' adds an SDMX semantic layer whose components are derived dynamically from dataset metadata.
For 'resource = "data"', native ILOSTAT column names are mapped to SDMX component identifiers. Dynamic classifications are obtained from the dataset metadata rather than hard-coded. For example, a native 'classif1' column can become 'AGE' when the dataset metadata identifies that dimension as age.
The data resource includes the SDMX message envelope components 'STRUCTURE', 'STRUCTURE_ID' and 'ACTION'. 'STRUCTURE_NAME' is also returned when labels are requested.
Dataset-level components such as 'FREQ', 'MEASURE', 'UNIT_MEASURE' and 'UNIT_MULT' are derived from the dataset SDMX metadata.
'resource = "codelist"' returns the canonical ILOSTAT codelist associated with the requested SDMX component.
Value
The return value depends on 'resource' and 'format'.
With 'format = "dataframe"', a data frame is returned.
With 'format = "sdmx-ml"', a character string containing SDMX-ML 3.1 is returned.
With 'format = "sdmx-json"', a character string containing SDMX-JSON 2.1 is returned.
Examples
## Not run:
# Observation data using SDMX component names
x <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
filters = list(
REF_AREA = "FRA",
SEX = "SEX_F",
AGE = "AGE_YTHADULT_YGE15"
)
)
# Codes and labels
x <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
type = "both",
filters = list(
REF_AREA = "FRA",
SEX = "SEX_F"
)
)
# Time range
x <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
filters = list(
REF_AREA = "FRA",
TIME_PERIOD = list(
ge = "2020",
le = "2023"
)
)
)
# Dataset structure
structure <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
resource = "structure"
)
# Canonical AGE codelist
age <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
resource = "codelist",
component = "AGE"
)
# One Dataflow
flow <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
resource = "dataflow"
)
# Complete ILOSTAT Dataflow catalogue
flows <- get_ilostat_sdmx(
resource = "dataflow"
)
# SDMX-ML 3.1 structure message
xml <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
resource = "structure",
format = "sdmx-ml"
)
# SDMX-JSON 2.1 structure message
json <- get_ilostat_sdmx(
"UNE_TUNE_SEX_AGE_NB_A",
resource = "structure",
format = "sdmx-json"
)
## End(Not run)
Read ilostat Table of Contents / workflow
Description
Download one table of contents from ilostat https://ilostat.ilo.org via bulk download facility https://ilostat.ilo.org/data/bulk/.
Usage
get_ilostat_toc(
segment = getOption("ilostat_segment", "indicator"),
lang = getOption("ilostat_lang", "en"),
search = getOption("ilostat_search", "none"),
filters = getOption("ilostat_filter", "none"),
fixed = getOption("ilostat_fixed", TRUE),
cache_dir = getOption("ilostat_cache_dir", NULL),
cache_update = getOption("ilostat_cache_update", TRUE),
quiet = getOption("ilostat_quiet", TRUE)
)
Arguments
segment |
A character, way to get datasets by: |
lang |
a character, code for language. Available are |
search |
a character vector, "none" (default), datasets with this pattern in the description will be returned, characters vector will be use as AND, Character with "|" as OR, see example, options(ilostat_time_format = "date"), |
filters |
a list; |
fixed |
a logical, if |
cache_dir |
a path to a cache directory. The directory has to exist.
The |
cache_update |
a logical whether to update cache. Check cache update with last.update attribute store on the cache file name
and the one from the table of contents. Can be set also with
options(ilostat_cache_update = FALSE). Default is |
quiet |
a logical, if |
Details
The toc in English by indicator is downloaded from ilostat API https://rplumber.ilo.org/__docs__/#get-/metadata/toc/indicator/. The values in column "id" should be used to download a selected dataset.
The toc in English by ref_area is downloaded from ilostat API https://rplumber.ilo.org/__docs__/#get-/metadata/toc/ref_area/. The values in column "id" should be used to download a selected dataset.
Value
A tibble with ten columns depending of the segment: indicator or ref_area
id: The codename of dataset of theme, will be used by the get_ilostat and get_ilostat_raw functions,indicator or ref_area: The indicator or ref_area code of dataset,indicator.label or ref_area.label: The indicator or ref_area name of dataset,freq: The frequency code of dataset,freq.label: Is freq name of dataset,size: Size of the csv.gz files,data.start: First time period of the dataset,data.end: Last time period of the dataset,last.update: Last update of the dataset,...: Others relevant information
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
See Also
Examples
## Not run:
## default segment by indicator, default lang English
toc <- get_ilostat_toc()
head(toc)
toc <- get_ilostat_toc(segment = "ref_area", lang = "fr")
head(toc)
##
## search on toc
toc <- get_ilostat_toc(search = "education")
head(toc)
toc <- get_ilostat_toc(lang = "fr", search = "age")
head(toc)
toc <- get_ilostat_toc(segment = "ref_area", lang = "fr", search = "Albanie")
toc
toc <- get_ilostat_toc(segment = "ref_area", lang = "es", search = "Trimestral")
head(toc)
##
## search multi on toc
toc <- get_ilostat_toc(segment = "ref_area", lang = "fr",
search = "Albanie|France", fixed = FALSE)
head(toc)
toc <- get_ilostat_toc(search = "youth|adult", fixed = FALSE)
head(toc)
##
## End(Not run)
Switch ilostat codes and labels
Description
Gets definitions/labels for ilostat codes from ilostat dictionaries.
Usage
label_ilostat(
x,
dic = NULL,
code = NULL,
lang = getOption("ilostat_lang", "en")
)
Arguments
x |
A character or a factor vector or a data_frame to labelled. |
dic |
A string (vector) naming ilostat dictionary or dictionaries.
If |
code |
a vector of names of the column for which code columns
should be retained. Set to |
lang |
a character, code for language. Available are |
Details
A character or a factor vector of codes returns a corresponding vector of definitions.
label_ilostat labels also data_frames from get_ilostat. For vectors a dictionary
"time" and "values" columns are returned as they were, so you can supply data_frame from get_ilostat
and get data_frame with definitions instead of codes.
Value
a vector or a data_frame. The suffix ".label" is added to code column names.
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat") ilostat bulk download facility user guidelines https://ilostat.ilo.org/data/bulk/
Examples
## Not run:
dat <- get_ilostat("UNE_2UNE_SEX_AGE_NB_A", cache = FALSE)
dat_lab <- label_ilostat(dat)
head(dat_lab)
# add just ref_area label
require(tidyverse)
dat <- get_ilostat("UNE_TUNE_SEX_AGE_NB_A") %>%
mutate(ref_area.label = ref_area %>%
label_ilostat( "ref_area", code = "all"), .after = ref_area)
clean_ilostat_cache()
## End(Not run)
Play with ILOSTAT data apps
Description
Open various data exploration and analysis applications hosted by the ILO.
Usage
runapp_ilostat(name = "dataexplorer")
Arguments
name |
'chr' The name of the application to open. Available applications:
|
Author(s)
David Bescond bescond@ilo.org
References
See citation("Rilostat")
See Also
Additional documentation for microdata:
Examples
## Not run:
runapp_ilostat(name = "dataexplorer")
# You can also run other apps like:
runapp_ilostat(name = "microquery")
runapp_ilostat(name = "regionalaggregate")
## End(Not run)