README.md 4.79 KB
Newer Older
Pauline Maury Laribière's avatar
done    
Pauline Maury Laribière committed
1
# FSO Metadata Auto R Package
2
3
4

## Introduction

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
5
6
7
This repository aims to simplify the access to the [Swiss Federal Statistical Office](https://www.bfs.admin.ch/bfs/en/home.html) metadata. 
Following the implementation in the [interoperability platform](https://www.i14y.admin.ch) and the [SIS portal](https://sharepoint.admin.ch/edi/bfs/fr-ch/News/Pages/go-life-neues-sis-portals.aspx), the APIs are made available here in R.
This public library is made available for the internal FSO staff, the federal administration and for external actors.
8

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
9
## Installation
10

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
11
12
You can install the library with
```
13
14
install.packages("remotes")
remotes::install_gitlab("DSCC/fso-metadata-r")
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
15
```
16

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
17
then at the beginning of your R script, you will need to 
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
18
```
Pauline Maury Laribière's avatar
done    
Pauline Maury Laribière committed
19
library("fso.metadata")
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
20
```
21

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
22

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
23
24
## Functionnalities
Based on the metadata that you want, you will call certain functions and parameters. 
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
25

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
26
27
### Codelists
1. Export a codelist based on an identifier
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
28
```
29
codelist <- get_codelist(identifier, environment, language, export_format, version_format, annotations)
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
30
31
32
```

    Parameters:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
33
        - identifier ("character"): the codelist's identifier
34
35
36
37
        - environment ("character", default="PRD" for production)
            Available are 'PRD', 'ABN', 'TEST', 'QA' and 'DEV'.
        - language ("character", default="all" for all languages, no filtering)
            Available are 'all', 'fr', 'de', 'it', 'en'.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
38
39
40
41
42
        - export_format ("character", default="SDMX-ML"): the export's format. 
            Available are CSV, XLSX, SDMX-ML or SDMX-JSON.
        - version_format ("numeric", default=2.1): the export format's version 
            (2.0 or 2.1 when format is SDMX-ML).
        - annotations (bool, default=FALSE): flag to include annotations
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
43
    Returns:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
44
45
46
        - codelist (data.frame) based on the export format
            - a data.frame if export_format was CSV or XLSX
            - a json if export_format was SDMX-ML or SDMX-JSON.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
47
48


Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
49
### Nomenclatures
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
50
   
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
51
1. Export one level of a nomenclature
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
52
```
53
one_level_df <- get_nomenclature_one_level(identifier, environment, level_number, filters, language, annotations)
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
54
55
56
```

    Parameters:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
57
        - identifier ("character"): nomenclature's identifier
58
59
        - environment ("character", default="PRD" for production)
            Available are 'PRD', 'ABN', 'TEST', 'QA' and 'DEV'.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
60
        - level_number ("numeric"): level to export
61
        - filter (list): additionnal filters in form of named list
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
62
        - language ("character", default='fr'): response data's language 
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
63
            Available are 'fr', 'de', 'it', 'en'.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
64
        - annotations (bool, default=FALSE): flag to include annotations
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
65
    Returns:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
66
        - response (data.frame): dataframe with 3 columns 
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
67
68
69
            (Code, Parent and Name in the selected language)


Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
70
2. Export multiple levels of a nomenclature (from `level_from` to `level_to`)
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
71
```
72
multiple_levels_df = get_nomenclature_multiple_levels(identifier, environment, level_from, level_to, filters, language, annotations)
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
73
74
75
```

    Parameters:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
76
        - identifier ("character"): nomenclature's identifier
77
78
        - environment ("character", default="PRD" for production)
            Available are 'PRD', 'ABN', 'TEST', 'QA' and 'DEV'.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
79
80
        - level_from ("numeric"): the 1st level to include
        - level_to ("numeric"): the last level to include
81
        - filter (list): additionnal filters in form of named list
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
82
        - language ("character", default='fr'): response data's language 
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
83
            Available are 'fr', 'de', 'it', 'en'.
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
84
        - annotations (bool, default=FALSE): flag to include annotations
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
85
    Returns:
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
86
        - multiple_levels_df (data.frame): dataframe columns from `level_from` to `level_to` codes
Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
87
88
89
90


As the APIs continue to be implemented, further functionnalities will be added.

Pauline Maury Laribière's avatar
done    
Pauline Maury Laribière committed
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

### Upcoming function: Data Structures
1. Get the data structure (not available yet)
```
data_structure <- get_data_structure(identifier, language)
```

    Parameters:
        - identifier ("character"): the nomenclature's identifier
        - language ("character", default='fr'): the language of the response data. 
            Available are 'fr', 'de', 'it', 'en'.
    Returns:
        - data_structure: data structure
        

Pauline Maury Laribière's avatar
Pauline Maury Laribière committed
106
107
108
109
110
111
112
## Background
All the APIs made available in this library are also documented in Swagger UI should you want to do more experiments through a UI.
- [Here](https://www.i14y.admin.ch/api/index.html) for APIs of the interoperability platform (public).
- [Here](https://dcat.app.cfap02.atlantica.admin.ch/api/index.html) for dcat APIs (internal to configuration).

## Example

Pauline Maury Laribière's avatar
done    
Pauline Maury Laribière committed
113
Examples for each API are provided in the [R Markdown](https://renkulab.io/gitlab/dscc/metadata-auto-r-library/-/blob/master/example.Rmd).
114

115
116
117
Practical [demo](https://renkulab.io/gitlab/dscc/metadata-auto-r-library/-/blob/master/demo.R).

A documentation page is also available [here](https://DSCC.gitlab.io/fso-metadata-r/).