Type: Package
Language: en-GB
Title: R Interface to ILOSTAT Open Data
Version: 2.3.4
Date: 2025-10-01
Maintainer: David Bescond <bescond@ilo.org>
Description: Provides tools to access, search, and manipulate ILO's ilostat database, including bulk download of statistical data, dictionary lookups, and table of contents.
License: BSD_2_clause + file LICENSE
Depends: R (≥ 4.4.0)
Imports: dplyr (≥ 1.1.4), stringr (≥ 1.5.2), readr (≥ 2.1.5), tibble (≥ 3.3.0), plyr, haven, httr2, data.table
Suggests: shiny, plotrix, ggplot2, plotly, knitr
URL: https://ilostat.github.io/Rilostat/
BugReports: https://github.com/ilostat/Rilostat/issues
RoxygenNote: 7.3.3
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2025-10-01 15:31:49 UTC; bescond
Author: David Bescond ORCID iD [aut, cre], Mabelin Villarreal-Fuentes ORCID iD [ctb], ILO Department of Statistics [cph, fnd]
Repository: CRAN
Date/Publication: 2025-10-01 17:00: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 + LICENSE
LazyLoad: yes

Author(s)

David Bescond bescond@ilo.org

References

See citation("Rilostat")

ilostat bulk download facility user guidelines https://webapps.ilo.org/ilostat-files/Documents/ILOSTAT_BulkDownload_Guidelines.pdf

See Also

Useful links:

Examples

## Not run: 
# check which documentation have been recently added:
# help(Rilostat)

# https://ilostat.github.io/Rilostat/

## End(Not run)

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", FALSE)
)

Arguments

cache_dir

A character, path to a cache directory. The directory has to exist. The NULL (default) uses and creates 'ilostat' directory in the temporary directory from tempdir. The directory can also be set with option ilostat_cache_dir,

cache_update

a logical whether to delete only out of date cache files. Useful when cache_dir is set as keep only update datasets. Can be set also with options(ilostat_update = TRUE). Default is FALSE.

quiet

a logical, if TRUE , don't return message from processing, FALSE (default). Can be set also with options(ilostat_quiet = TRUE),

Author(s)

David Bescond bescond@ilo.org

References

See citation("Rilostat") ilostat bulk download facility user guidelines https://webapps.ilo.org/ilostat-files/Documents/ILOSTAT_BulkDownload_Guidelines.pdf

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)

Arguments

x

dataset to transform into distribution.

var

String variable name use for the distribution default "no", could be "sex", "classif1", "classif2".

.keep

if true return only new column call distribution default FALSE.

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://webapps.ilo.org/ilostat-files/Documents/ILOSTAT_BulkDownload_Guidelines.pdf

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"),
  fixed = getOption("ilostat_fixed", TRUE),
  detail = getOption("ilostat_detail", "full"),
  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 get_ilostat_toc or details for how to get code.

segment

A character, way to get datasets by: "indicator" (default) or "ref_area". Can be set also with options(ilostat_segment = 'ref_area'),

type

a character, type of variables, "code" (default), "label" or "both". Can be set also with options(ilostat_type = 'both'),

lang

a character, code for language. Available are "en" (default), "fr" and "es". Can be set also with options(ilostat_lang = 'fr'),

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 Date with a first date of the period. A "date_last" converted to a Date with a last date of the period and "num" converted to a numeric. Can be set also with options(ilostat_time_format = 'date'),

filters

a list; "none" (default) to get a whole dataset or a named list of filters to get just part of the table. Names of list objects are ilostat variable codes and values are vectors of observation codes. filters detect on variables, so could be partial, ie. list(sex = 'T') is enough but equivalent to list(sex = 'SEX_T'). Additional options: enough but equivalent to list(sex = 'SEX_T'). Additional options:

  • timefrom : starting year of the return dataset,

  • timeto : ending year of the return dataset.

fixed

a logical, if TRUE (default), filters arguments pattern is a string to be matched as is, Change to FALSE if more complex regex matching is needed.

detail

a character, 'full' (default), whether 'serieskeysonly', return only key, no data, no notes or dataonly return key and data, no notes or 'bestsourceonly' return best source only at the series key levels, see details. Can be set also with options(ilostat_detail = 'serieskeysonly'),

cache

a logical whether to do caching. Default is TRUE. Affects only queries from the ilostat bulk download facility. Can be set also with options(ilostat_cache = FALSE),

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 TRUE,

cache_dir

a path to a cache directory. The directory has to exist. The NULL (default) uses and creates 'ilostat' directory in the temporary directory from tempdir. The directory can also be set with option ilostat_cache_dir,

cache_format

a character, format to store on the cache "rds" (default), but also "csv", "dta", "sav", "sas7bdat". useful for getting ilostat dataset directly on the cache_dir without R. Can be set also with options(ilostat_cache_format = 'dta'),

back

a logical, TRUE return dataframe on R or not FALSE, useful for just saving file in specific cache_format,

cmd

a character, R expression use for manipulate internal data frame dat object applied to each datasets retrieved If use, cache is set to FALSE. see examples.

quiet

a logical, if TRUE , don't return message from processing, FALSE (default). Can be set also with options(ilostat_quiet = TRUE),

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_2UNE_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_2UNE_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_2UNE_SEX_AGE_NB_A")
 head(dat)
 options(ilostat_update = FALSE)
 options(ilostat_cache_dir = file.path(tempdir(), "r_cache"))
 dat <- get_ilostat("UNE_2UNE_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_2UNE_SEX_AGE_NB_A", 'EMP_2EMP_SEX_AGE_NB_A'), 
 		filters = list(	ref_area = "FRA", 
 		classif1 = "AGE_YTHADULT_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_2UNE_SEX_AGE_NB_A", 
                  cache_dir = file.path(tempdir(), "r_cache"), cache_format = 'csv')
 dat <- get_ilostat("UNE_2UNE_SEX_AGE_NB_A", 
                  cache_dir = file.path(tempdir(), "r_cache"), cache_format = 'dta')

############# advanced manipulation

 dat <- get_ilostat("UNE_2UNE_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"),
  quiet = getOption("ilostat_quiet", FALSE)
)

Arguments

dic

A character, dictionary for the variable to be downloaded,

lang

a character, code for language. Available are "en" (default), "fr" and "es". Can be set also with options(ilostat_lang = 'fr'),

quiet

a logical, if FALSE , return message from processing, TRUE (default). Can be set also with options(ilostat_quiet = TRUE),

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

label_ilostat, get_ilostat.

Examples

## Not run: 
 tmp <- get_ilostat_dic("indicator")
 head(tmp)
 tmp <- get_ilostat_dic("classif1", lang = "fr")
 head(tmp)

## End(Not run)

Read ilostat Table of Contents

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),
  quiet = getOption("ilostat_quiet", FALSE)
)

Arguments

segment

A character, way to get datasets by: "indicator" (default) or "ref_area", Can be set also with options(ilostat_segment = 'ref_area'),

lang

a character, code for language. Available are "en" (default), "fr" and "es". Can be set also with options(ilostat_lang = 'fr'),

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; "none" (default) to get a whole toc or a named list of filters to get just part of the table. Names of list objects are ilostat toc variable codes and values are vectors of observation codes. filters detect on variables.

fixed

a logical, if TRUE (default), pattern is a string to be matched as is, Change to FALSE if more complex regex matching is needed.

quiet

a logical, if FALSE , return message from processing, TRUE (default). Can be set also with options(ilostat_quiet = TRUE),

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

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.

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 = 'éducation')
 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 NULL (default) dictionary names are taken from column names of the data_frame. A character or a factor vector or a data_frame to labelled,

code

a vector of names of the column for which code columns should be retained. Set to "all", keep all the code.

lang

a character, code for language. Available are "en" (default), "fr" and "es". Can be set also with options(ilostat_lang = 'fr'),

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://webapps.ilo.org/ilostat-files/Documents/ILOSTAT_BulkDownload_Guidelines.pdf

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:

  • "dataexplorer": Quickly find, filter, pivot, and download ILOSTAT data.

  • "microquery": Explore data availability and create custom queries from the ILO Harmonized Microdata Collection. Users can select variables, filters, and indicators to generate tailored datasets.

  • "regionalaggregate": Generate custom regional estimates by defining or selecting country groupings. The app automatically aggregates country-level modelled data for selected indicators.

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)