Help for package Rilostat

Type:

Package

Title:

ILO Open Data via Ilostat Bulk Download Facility

Date:

2025-03-10

Version:

2.3.1

Encoding:

UTF-8

Maintainer:

David Bescond <bescond@ilo.org>

Description:

Tools to download data from the [ilostat](https://ilostat.ilo.org) database together with search and manipulation utilities.

License:

BSD_2_clause + file LICENSE

Depends:

R (≥ 4.1.0)

Imports:

plyr, dplyr (≥ 1.1.2), stringr (≥ 1.5.0), readr (≥ 2.1.4), tibble (≥ 3.2.1), haven, data.table

Suggests:

shiny

URL:

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

BugReports:

https://github.com/ilostat/Rilostat/issues

Repository:

CRAN

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-03-10 14:23:05 UTC; bescond

Author:

David Bescond

[aut, cre], Mabelin Villarreal-Fuentes

[ctb], ILO Department of Statistics [cph, fnd]

Date/Publication:

2025-03-10 14:40:06 UTC

Get more Support

Description

On regular basis new tutorial and examples are building and available through this function.

Details

brief description of the package

Package:	Rilostat
Type:	Package
Version:	See sessionInfo() or DESCRIPTION file
Date:	2020-2025
License:	BSD_2_clause + LICENSE
LazyLoad:	yes

R Tools for ilostat Open Data

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: 

# 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)

Play with ilostat data explorer

Description

open ilostat data explorer app on your computer.

Usage

dataexplorer()

Author(s)

David Bescond bescond@ilo.org

References

See citation("Rilostat")

Examples

## Not run: 

require(shiny)

 dataexplorer()


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

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:

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. It is also often the only way as the sdmx API has limitation of maximum 300 000 records at the same time and whole datasets usually exceeds that.

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/

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

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'),

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://webapps.ilo.org/ilostat-files/WEB_bulk_download/ILOSTAT_BulkDownload_Guidelines.pdf ilostat bulk download facility main page https://ilostat.ilo.org/data/bulk/

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)
)

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.

Details

The TOC in English by indicator is downloaded from https://webapps.ilo.org/ilostat-files/WEB_bulk_download/indicator/table_of_contents_en.csv. The values in column 'id' should be used to download a selected dataset.

The TOC in English by ref_area is downloaded from https://webapps.ilo.org/ilostat-files/WEB_bulk_download/ref_area/table_of_contents_en.csv. 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://webapps.ilo.org/ilostat-files/WEB_bulk_download/ILOSTAT_BulkDownload_Guidelines.pdf

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)
 toc <- get_ilostat_toc(search = c('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)

Get more Support

Description

Details

Author(s)

References

Examples

Clean Ilostat Cache

Description

Usage

Arguments

Author(s)

References

Examples

Play with ilostat data explorer

Description

Usage

Author(s)

References

Examples

Switch ilostat to distribution

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Read Ilostat Data

Description

Usage

Arguments

Value

others

Author(s)

References

See Also

Examples

Read Ilostat Dictionary

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Read Ilostat Table of Contents

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Switch Ilostat codes and labels

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples