Skip to content

Commit d2c8194

Browse files
e-kotove-kotov
committed
update README
1 parent 7832025 commit d2c8194

File tree

5 files changed

+606
-38
lines changed

5 files changed

+606
-38
lines changed

‎README.md‎

Lines changed: 299 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,43 +12,327 @@ and dashboard (product of the [Mapineq](https://mapineq.eu/) proejct)
1212

1313
[![Lifecycle:
1414
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
15+
[![R-CMD-check](https://github.com/e-kotov/mapineqr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/e-kotov/mapineqr/actions/workflows/R-CMD-check.yaml)
1516
[![CRAN
1617
status](https://www.r-pkg.org/badges/version/mapineqr.png)](https://CRAN.R-project.org/package=mapineqr)
17-
[![R-CMD-check](https://github.com/e-kotov/mapineqr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/e-kotov/mapineqr/actions/workflows/R-CMD-check.yaml)
1818
<!-- badges: end -->
1919

20-
The goal of mapineqr is to …
20+
The goal of `{mapineqr}` is to access the data from the [Mapineq.org
21+
API](https://www.mapineq.org/data-users/) and
22+
[dashboard](https://dashboard.mapineq.org/datacatalogue) (product of the
23+
[Mapineq](https://mapineq.eu/) proejct).
2124

2225
## Installation
2326

24-
You can install the development version of mapineqr from
27+
You can install the development version of `{mapineqr}` from
2528
[GitHub](https://github.com/) with:
2629

2730
``` r
28-
# install.packages("pak")
31+
if (!require("pak")) install.packages("pak")
2932
pak::pak("e-kotov/mapineqr")
3033
```
3134

32-
## Example
35+
``` r
36+
# load packages used in the examples on this page
37+
library(mapineqr)
38+
library(dplyr)
39+
library(ggplot2)
40+
library(eurostat)
41+
library(sf)
42+
library(biscale)
43+
```
44+
45+
## Basic Example - univariate data and maps
3346

34-
This is a basic example which shows you how to solve a common problem:
47+
1. Get the full list of available data at NUTS 3 level:
3548

3649
``` r
3750
library(mapineqr)
38-
## basic example code
51+
52+
available_data <- mi_sources(level = "3")
53+
head(available_data)
54+
```
55+
56+
# A tibble: 52 × 3
57+
source_name short_description description
58+
<chr> <chr> <chr>
59+
1 DEMO_R_D3AREA "Area by NUTS 3 regio" Area by NUTS 3 region (ESTAT)
60+
2 PROJ_19RAASFR3 "Assumptions for fert" Assumptions for fertility rates by age, type of projection and NUTS…
61+
3 PROJ_19RAASMR3 "Assumptions for prob" Assumptions for probability of dying by age, sex, type of projectio…
62+
4 BD_HGNACE2_R3 "Business demography " Business demography and high growth enterprise by NACE Rev. 2 and N…
63+
5 BD_SIZE_R3 "Business demography " Business demography by size class and NUTS 3 regions (ESTAT)
64+
6 CENS_11DWOB_R3 "Conventional dwellin" Conventional dwellings by occupancy status, type of building and NU…
65+
7 CRIM_GEN_REG "Crimes recorded by t" Crimes recorded by the police by NUTS 3 regions (ESTAT)
66+
8 DEMO_R_MAGEC3 "Deaths by age group," Deaths by age group, sex and NUTS 3 region (ESTAT)
67+
9 DEMO_R_MWK3_T "Deaths by week and N" Deaths by week and NUTS 3 region (ESTAT)
68+
10 DEMO_R_MWK3_TS "Deaths by week, sex " Deaths by week, sex and NUTS 3 region (ESTAT)
69+
# ℹ 42 more rows
70+
# ℹ Use `print(n = ...)` to see more rows
71+
72+
2. Select data source by `source_name` column and check it’s year and
73+
NUTS level coverage:
74+
75+
``` r
76+
mi_source_coverage("CRIM_GEN_REG")
77+
```
78+
79+
# A tibble: 10 × 5
80+
nuts_level year source_name short_description description
81+
<chr> <chr> <chr> <chr> <chr>
82+
1 0 2008 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
83+
2 0 2009 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
84+
3 0 2010 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
85+
4 1 2008 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
86+
5 1 2009 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
87+
6 1 2010 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
88+
7 2 2008 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
89+
8 2 2009 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
90+
9 2 2010 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
91+
10 3 2008 CRIM_GEN_REG Crimes recorded by t Crimes recorded by the police by NUTS 3 regions (ESTAT)
92+
93+
3. Check the available filters for the data source:
94+
95+
``` r
96+
mi_source_filters("CRIM_GEN_REG", year = 2010, level = "2")
97+
```
98+
99+
# A tibble: 6 × 4
100+
field field_label label value
101+
<chr> <chr> <chr> <chr>
102+
1 unit Unit of measure Number NR
103+
2 freq Time frequency Annual A
104+
3 iccs International classification of crime for statistical purposes (ICCS) Intentional homicide ICCS0101
105+
4 iccs International classification of crime for statistical purposes (ICCS) Robbery ICCS0401
106+
5 iccs International classification of crime for statistical purposes (ICCS) Burglary of private residential premises ICCS05012
107+
6 iccs International classification of crime for statistical purposes (ICCS) Theft of a motorized land vehicle ICCS050211
108+
109+
4. Choose the indicator to filter (let it be burglaries) to and get the
110+
data:
111+
112+
``` r
113+
x <- mi_data(x_source = "CRIM_GEN_REG", year = 2010, level = "2", x_filters = list(iccs = "ICCS05012"))
114+
head(x)
39115
```
40116

41-
What is special about using `README.Rmd` instead of just `README.md`?
42-
You can include R chunks like so:
117+
# A tibble: 6 × 4
118+
best_year geo geo_name x
119+
<chr> <chr> <chr> <int>
120+
1 2008 AT11 Burgenland (A) 223
121+
2 2008 AT12 Niederösterreich 2557
122+
3 2008 AT13 Wien 9319
123+
4 2008 AT21 Kärnten 507
124+
5 2008 AT22 Steiermark 1163
125+
6 2008 AT31 Oberösterreich 988
126+
127+
5. Map the indicator using NUTS2 polygons:
43128

44129
``` r
45-
summary(cars)
130+
library(eurostat)
131+
library(ggplot2)
132+
133+
# load NUTS2 level polygons
134+
nuts2 <- eurostat::get_eurostat_geospatial(nuts_level = 2, year = "2010", crs = "4326")
135+
136+
# join data to NUTS2 polygons
137+
nuts2_crime <- nuts2 |>
138+
left_join(x, by = "geo")
139+
140+
# plot a map of burglaries
141+
map_burglaries <- ggplot(nuts2_crime) +
142+
geom_sf(aes(fill = x)) +
143+
scale_fill_viridis_c() +
144+
labs(title = "Number of burglaries of private residential premises in 2010") +
145+
theme_minimal()
146+
147+
ggsave("man/figures/map_burglaries.png", map_burglaries, width = 8, height = 6, dpi = 200, create.dir = TRUE)
46148
```
47149

48-
You’ll still need to render `README.Rmd` regularly, to keep `README.md`
49-
up-to-date. `devtools::build_readme()` is handy for this.
150+
![Number of burglaries of private residential premises in
151+
2010](man/figures/map_burglaries.png)
152+
153+
## Advanced Example - bivariate data and maps
154+
155+
1. Select two indicators.
156+
157+
Let those be (1) unemployment rate:
158+
159+
``` r
160+
mi_source_coverage("TGS00010") |> dplyr::arrange(desc(year))
161+
```
162+
163+
# A tibble: 12 × 5
164+
nuts_level year source_name short_description description
165+
<chr> <chr> <chr> <chr> <chr>
166+
1 2 2022 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
167+
2 2 2021 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
168+
3 2 2020 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
169+
4 2 2019 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
170+
5 2 2018 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
171+
6 2 2017 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
172+
7 2 2016 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
173+
8 2 2015 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
174+
9 2 2014 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
175+
10 2 2013 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
176+
11 2 2012 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
177+
12 2 2011 TGS00010 Unemployment rate by Unemployment rate by NUTS 2 regions (ESTAT)
178+
179+
And (2) life expectancy:
180+
181+
``` r
182+
mi_source_coverage("DEMO_R_MLIFEXP") |> dplyr::arrange(desc(year))
183+
```
184+
185+
# A tibble: 96 × 5
186+
nuts_level year source_name short_description description
187+
<chr> <chr> <chr> <chr> <chr>
188+
1 0 2021 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
189+
2 1 2021 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
190+
3 2 2021 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
191+
4 0 2020 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
192+
5 1 2020 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
193+
6 2 2020 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
194+
7 0 2019 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
195+
8 1 2019 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
196+
9 2 2019 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
197+
10 0 2018 DEMO_R_MLIFEXP Life expectancy by a Life expectancy by age, sex and NUTS 2 region (ESTAT)
198+
# ℹ 86 more rows
199+
# ℹ Use `print(n = ...)` to see more rows
200+
201+
2. Check for available filters:
202+
203+
``` r
204+
mi_source_filters("TGS00010", year = 2018, level = "2")
205+
```
206+
207+
# A tibble: 12 × 4
208+
field field_label label value
209+
<chr> <chr> <chr> <chr>
210+
1 unit Unit of measure Percentage PC
211+
2 isced11 International Standard Classification of Education (ISCED 2011) All ISCED 2011 levels TOTAL
212+
3 isced11 International Standard Classification of Education (ISCED 2011) Less than primary, primary and lower secondary education (levels 0-2) ED0-2
213+
4 isced11 International Standard Classification of Education (ISCED 2011) Upper secondary and post-secondary non-tertiary education (levels 3 and 4) ED3_4
214+
5 isced11 International Standard Classification of Education (ISCED 2011) Tertiary education (levels 5-8) ED5-8
215+
6 isced11 International Standard Classification of Education (ISCED 2011) Unknown UNK
216+
7 isced11 International Standard Classification of Education (ISCED 2011) No response NRP
217+
8 sex Sex Total T
218+
9 sex Sex Males M
219+
10 sex Sex Females F
220+
11 freq Time frequency Annual A
221+
12 age Age class 15 years or over Y_GE15
222+
223+
``` r
224+
mi_source_filters("DEMO_R_MLIFEXP", year = 2018, level = "2") |> print(n=90)
225+
```
226+
227+
# A tibble: 91 × 4
228+
field field_label label value
229+
<chr> <chr> <chr> <chr>
230+
1 unit Unit of measure Year YR
231+
2 sex Sex Total T
232+
3 sex Sex Males M
233+
4 sex Sex Females F
234+
5 freq Time frequency Annual A
235+
6 age Age class Less than 1 year Y_LT1
236+
7 age Age class 1 year Y1
237+
8 age Age class 2 years Y2
238+
9 age Age class 3 years Y3
239+
10 age Age class 4 years Y4
240+
11 age Age class 5 years Y5
241+
12 age Age class 6 years Y6
242+
13 age Age class 7 years Y7
243+
14 age Age class 8 years Y8
244+
15 age Age class 9 years Y9
245+
16 age Age class 10 years Y10
246+
17 age Age class 11 years Y11
247+
...
248+
249+
3. Get the data for the two indicators:
250+
251+
``` r
252+
xy_data <- mi_data(
253+
year = 2018,
254+
level = "2",
255+
x_source = "TGS00010", x_filters = list(isced11 = "TOTAL", unit = "PC", age = "Y_GE15", sex = "T", freq = "A"),
256+
y_source = "DEMO_R_MLIFEXP", y_filters = list(unit = "YR", age = "Y_LT1", sex = "T", freq = "A")
257+
)
258+
```
259+
260+
4. Plot the scratterplot:
261+
262+
``` r
263+
edu_v_life_exp_plot <- ggplot(xy_data, aes(x = x, y = y)) +
264+
geom_point() +
265+
labs(x = "Percentage of all adults aged 15 years or over with a degree", y = "Life expectancy at birth") +
266+
theme_minimal()
267+
# ggsave("man/figures/edu_v_life_exp_plot.png", edu_v_life_exp_plot, width = 8, height = 6, units = "in", dpi = 300)
268+
```
269+
270+
![Education vs Life Expectancy](figures/edu_v_life_exp_plot.png)
271+
272+
4. Add the bivariate data to the NUTS2 polygons and create a plot:
273+
274+
``` r
275+
nuts2 <- eurostat::get_eurostat_geospatial(nuts_level = 2, year = "2016", crs = "4326")
276+
nuts2_edu_v_life_exp <- nuts2 |>
277+
left_join(xy_data, by = "geo")
278+
```
279+
280+
``` r
281+
library(biscale)
282+
bidata <- bi_class(nuts2_edu_v_life_exp, x = x, y = y, style = "quantile", dim = 3)
283+
284+
legend <- bi_legend(pal = "GrPink",
285+
dim = 3,
286+
xlab = " Higher % with a degree",
287+
ylab = " Higher life expectancy",
288+
size = 8)
289+
```
290+
291+
``` r
292+
map <- ggplot() +
293+
geom_sf(data = bidata, mapping = aes(fill = bi_class), color = "white", size = 0.1, show.legend = FALSE) +
294+
bi_scale_fill(pal = "GrPink", dim = 3) +
295+
labs(
296+
title = "Education vs Life Expectancy"
297+
) +
298+
bi_theme()
299+
300+
png("man/figures/edu_v_life_exp_map.png", width = 8, height = 6, units = "in", res = 300)
301+
print(map)
302+
print(legend, vp = grid::viewport(x = 0.4, y = .75, width = 0.2, height = 0.2, angle = -45))
303+
dev.off()
304+
```
305+
306+
![Education vs Life Expectancy](man/figures/edu_v_life_exp_map.png)
307+
308+
## Citation
309+
310+
To cite the R package and data in publications use:
311+
312+
Kotov E (2024). *mapineqr. Access Mapineq inequality indicators via
313+
API*. doi:10.32614/CRAN.package.mapineqr
314+
<https://doi.org/10.32614/CRAN.package.mapineqr>,
315+
<https://github.com/e-kotov/mapineqr>.
316+
317+
Mills M, Leasure D (2024). “Mapineq Link: Geospatial Dashboard and
318+
Database.” doi:10.5281/zenodo.13864000
319+
<https://doi.org/10.5281/zenodo.13864000>.
320+
321+
BibTeX:
50322

51-
You can also embed plots, for example:
323+
@Manual{mapineqr,
324+
title = {mapineqr. Access Mapineq inequality indicators via API},
325+
author = {Egor Kotov},
326+
year = {2024},
327+
url = {https://github.com/e-kotov/mapineqr},
328+
doi = {10.32614/CRAN.package.mapineqr},
329+
}
52330

53-
In that case, don’t forget to commit and push the resulting figure
54-
files, so they display on GitHub and CRAN.
331+
@Misc{mapineq_link,
332+
title = {Mapineq Link: Geospatial Dashboard and Database},
333+
author = {Melinda C Mills and Douglas Leasure},
334+
year = {2024},
335+
month = {October},
336+
publisher = {Mapineq deliverables. Turku: INVEST Research Flagship Centre / University of Turku},
337+
doi = {10.5281/zenodo.13864000},
338+
}

0 commit comments

Comments
 (0)