-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
172 lines (88 loc) · 6.42 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# BARIS <a><img src='man/figures/hex.png' align="right" height="200" /></a>
<!-- badges: start -->
[](https://cran.r-project.org/package=BARIS)
[](https://cran.r-project.org/package=BARIS)
[](https://cran.r-project.org/package=BARIS)
[](https://cran.r-project.org/package=BARIS)
[](https://cran.r-project.org/package=BARIS)
[](https://choosealicense.com/licenses/mit/)
[](https://github.com/feddelegrand7/BARIS)
[](https://github.com/feddelegrand7/BARIS/actions)
<!-- badges: end -->
With **BARIS** you can interact with the [French Official Open Data Portal](https://www.data.gouv.fr/fr/) API directly from R. The package offers several capabilities, from listing the available data sets to extracting the needed resources. Nevertheless, there are many features offered by the API (e.g. uploading a data set, removing a resource ... among others) that are not covered within the **BARIS** package which instead focus on the data extraction aspect of the API. The good news is that the user doesn't need an API key or any credential to run the available functions provided by **BARIS**. Finally, in order to fully apprehend the package, a distinction has to be made. The data.gouv API provides several **data sets which contain one or many data frames.** The unique identifier (ID) of a data set has this form : **53699934a3a729239d2051a1** while the ID of an individual data frame or resource has this form: **59ea7bba-f38a-4d75-b85f-2d1955050e53**.
## Installation
You can install the BARIS package from
[CRAN](https://cran.r-project.org/) with:
```{r eval=FALSE, message=FALSE, warning=FALSE}
install.packages("BARIS")
```
You can also install the development version from [GitHub](https://github.com/) with:
```{r eval=FALSE, message=FALSE, warning=FALSE}
devtools::install_github("feddelegrand7/BARIS")
```
## BARIS_home()
Using the function `BARIS_home()` you can list the displayed datasets within the [home page of the data.gouv website](https://www.data.gouv.fr/fr/). The function doesn't take any argument. It will return a data frame with many useful information about the data set.
```{r message=FALSE, warning=FALSE}
library(BARIS)
BARIS_home()
```
The data is quite condensed so you should use the `View()` or `DT::datatable()` functions.
## BARIS_search()
The `BARIS_search()` function allows you to search for a specific data set. Suppose we're curious about the city of Marseille.
```{r message=FALSE, warning=FALSE}
Marseille_data <- BARIS_search(query = "Marseille", page_number = 1, page_size = 20)
Marseille_data[, c("id", "title")]
```
Suppose we're interested in the dataset entitled **Marseille - Monuments historiques** with its corresponding ID:
**5cebfa8306e3e77ffdb31ef5** and we want to know more about this data. In this case, the `BARIS_explain()` function can be useful.
## BARIS_explain()
`BARIS_explain()` returns a description of a dataset. It has one argument which is the ID of the dataset of interest.
```{r message=FALSE, warning=FALSE}
BARIS_explain("5cebfa8306e3e77ffdb31ef5")
```
The description is in French but even non-French speakers can use this function in conjunction with a translation tool, for the example the [googleLanguageR package]( https://CRAN.R-project.org/package=googleLanguageR).
## BARIS_resources()
As mentioned previously, each data set contains one or several data frames or as the API call them **resources**. The `BARIS_resources()` function allows you to list all the available resources within a determined data set.
```{r message=FALSE, warning=FALSE}
BARIS_resources("5cebfa8306e3e77ffdb31ef5") # The "Marseille - Monuments historiques" ID
```
Many useful information related to the resource are provided: The id, the title, the format, the date of publication, the url of the resource, and a description.
## BARIS_extract()
The `BARIS_extract()` function allows you to extract the needed resource into your R session. You have to specify the id of the resource and its format. Currently, "only" theses formats are supported: json, csv, xls, xlsx, xml, geojson and shp, nevertheless you can always rely on the url of the resource to download whatever you need.
As an example, let us extract the above listed csv file: *MARSEILLE_MONUMENTS_HISTORIQUES_2018.csv*:
```{r message=FALSE, warning=FALSE}
BARIS_extract(resourceId = "59ea7bba-f38a-4d75-b85f-2d1955050e53", format = "csv")
```
# BARIS Addin
BARIS comes with an integrated Addin that generates a Shiny widget allowing the user to interact with the package in an interactive manner. You can trigger the addin from the `Addins` menu in `RStudio` or you can run:
```{r,eval=FALSE}
BARIS:::BARIS_ui()
```
# Citation
If you use the BARIS package for your work, research or teaching, I'd appreciate if you could cite it as follows:
Mohamed El Fodil Ihaddaden (2020). BARIS: Access and
Import Data from the French Open Data Portal. R package
version 1.1.1. https://CRAN.R-project.org/package=BARIS
A BibTeX entry for LaTeX users is
@Manual{,
title = {BARIS: Access and Import Data from the French Open Data Portal},
author = {Mohamed El Fodil Ihaddaden},
year = {2020},
note = {R package version 1.1.1},
url = {https://CRAN.R-project.org/package=BARIS},
}
## Code of Conduct
Please note that the BARIS project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. Finally, I appreciate any feedback, feel free to reach out at [moh_fodil](https://twitter.com/moh_fodil) or open an issue on [Github](https://github.com/feddelegrand7/BARIS/issues).