-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
132 lines (81 loc) · 3.87 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
---
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%"
)
```
# emberr
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental) [](https://github.com/andypicke/emberr/actions/workflows/R-CMD-check.yaml)
[](https://www.repostatus.org/#wip)
<!-- badges: end -->
The goal of {emberr} is to provide functions to query and retrieve data from the [Ember](https://ember-energy.org/) [API](https://ember-energy.org/data/api/).
You can view the [API documentation](https://api.ember-energy.org/docs) for details. Please note the license information provided by Ember:
*Our data is published using the CC-BY-4.0 license. Anyone is able to use our data for any purpose (personal, commercial, etc.). The only requirements by this license are that:
1) Ember is cited as the data source. E.g. 'Monthly electricity generation data, Ember'
2) You may not add any additional legal/technological restrictions to the data.*
See this [blog post](https://andypicke.quarto.pub/portfolio/posts/emberr/emberr.html) for a description and examples of the package.
## Installation
You can install the development version of [emberr](https://github.com/andypicke/emberr) from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("andypicke/emberr")
```
You will need to sign up for a free API key from Ember.
The package assumes you have stored your API key in your .Renviron file as *EMBER_API_KEY*. You can also pass in an API key explicitly to each function.
## Using the package
The main function to retrieve a dataset from the api is *get_ember_data()*.
There are 4 main datasets available from the API (these correspond to the *dataset* option in *get_ember_data()*:
- electricity-generation
- power-sector-emissions
- electricity-demand
- carbon-intensity
Each dataset is available in yearly or monthly resolution (the *temporal_resolution* option in *get_ember_data()*).
Countries/regions are contained in the *entity* variable.
## Example
Get monthly electricity generation data for 2021-2023. By Default this returns data for all countries/regions ("entities").
```{r example}
library(emberr)
gen <- emberr::get_ember_data(dataset = "electricity-generation",
temporal_resolution = "monthly",
min_date = 2021,
max_date = 2023)
head(gen)
```
The *series* variable specifies the fuel type:
```{r}
unique(gen$series)
```
You can specify a single year instead of a min and max date:
```{r}
gen_2023 <- emberr::get_ember_data(dataset = "electricity-generation",
temporal_resolution = "monthly",
year = 2023)
head(gen_2023)
```
The *get_ember_options()* function can be used to return all options for a varialbe. For example, get options for the *entity* parameter:
```{r}
options <- emberr::get_ember_options(dataset = "electricity-generation", filter_name = "entity")
str(options)
```
or the *series* parameter:
```{r}
options_series <- emberr::get_ember_options(dataset = "electricity-generation", filter_name = "series")
options_series
```
Retrieve data for just one country/region by specifying an entity:
```{r}
df_usa <- emberr::get_ember_data(entity = "United States")
str(df_usa)
```
You can also retrieve data for multiple countries/regions (entities):
```{r}
df <- get_ember_data(min_date = 2020, entity = "United States,United Kingdom")
str(df)
```