eia

An R package wrapping the US Energy Information Administration open data API.

https://github.com/ropensci/eia

Science Score: 26.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (22.8%) to scientific vocabulary

Keywords

cran eia eia-api energy-data energy-information-administration open-data r-package

Keywords from Contributors

color-palette

Last synced: 4 months ago · JSON representation

Repository

An R package wrapping the US Energy Information Administration open data API.

Basic Info

Host: GitHub
Owner: ropensci
License: other
Language: R
Default Branch: master
Homepage: https://docs.ropensci.org/eia
Size: 1.37 MB

Statistics

Stars: 48
Watchers: 4
Forks: 11
Open Issues: 0
Releases: 8

Topics

cran eia eia-api energy-data energy-information-administration open-data r-package

Created over 6 years ago · Last pushed 7 months ago

Metadata Files

Readme Changelog License Code of conduct Codemeta

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", out.width = "100%",
  fig.path = "man/figures/README-", fig.width = 7, fig.height = 4, dpi = 150,
  message = FALSE, warning = FALSE, error = FALSE
)
library(eia)
library(ggplot2)
```

# eia 


[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)
[![R-CMD-check](https://github.com/ropensci/eia/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/eia/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/ropensci/eia/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/eia?branch=master)
[![](https://badges.ropensci.org/342_status.svg)](https://github.com/ropensci/software-review/issues/342)
[![CRAN status](https://www.r-pkg.org/badges/version/eia)](https://cran.r-project.org/package=eia)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/eia)](https://cran.r-project.org/package=eia)
[![Github Stars](https://img.shields.io/github/stars/ropensci/eia.svg?style=social&label=Github)](https://github.com/ropensci/eia)


The `eia` package provides API access to data from the US [Energy Information Administration](https://www.eia.gov/) (EIA).

Pulling data from the US Energy Information Administration (EIA) API requires a registered API key.
A key can be obtained at no cost [here](https://www.eia.gov/opendata/register.php).
A valid email and agreement to the API Terms of Service is required to obtain a key.

`eia` includes functions for searching the EIA API data directory and importing various datasets.
Datasets returned by these functions are provided in a tidy format or alternatively in more raw form.
It also offers helper functions for working with EIA API date strings and time formats and for
inspecting different summaries of data metadata. The package also provides control over API key
storage and caching of API request results.

## Installation

Install the CRAN release of `eia` with

```{r instl1, eval=FALSE}
install.packages("eia")
```

or install the development version from GitHub with

```{r instl2, eval=FALSE}
# install.packages("remotes")
remotes::install_github("ropensci/eia")
```

## Example

After obtaining the API key, store it somewhere such as `.Renviron` and never have
to do anything with the key when using the package. Alternatively, set it manually
with `eia_set_key()` in the current R session. Further, it can always be passed
explicitly to the `key` argument of a given `eia` function.

### Load package and set key

```{r xmpl1, eval=FALSE}
library(eia)

# not run
eia_set_key("yourkey") # set API key if not already set globally
```

### Explore the API directory

Get a list of the EIA's data directory (and sub-directories) with `eia_dir()`.

```{r xmpl2}
# Top-level directory
eia_dir()

# Electricity sub-directory
eia_dir("electricity")
```

### Get data

Get annual retail electric sales for the Ohio residential sector since 2010

```{r xmpl3}
(d <- eia_data(
  dir = "electricity/retail-sales",
  data = "sales",
  facets = list(stateid = "OH", sectorid = "RES"),
  freq = "annual",
  start = "2010",
  sort = list(cols = "period", order = "asc"),
))
```

and make a nice plot.

```{r plt}
library(ggplot2)
ggplot(d, aes(x = period, y = sales / 1e3)) +
  geom_bar(col = "steelblue", fill = "steelblue", stat = "identity") +
  theme_bw() +
  labs(
    title = "Annual Retail Sales of Electricity (GWh)",
    subtitle = "State: Ohio; Sector: Residential",
    x = "Year", y = "Sales (GWh)"
  )
```

## References

See the collection of vignette tutorials and examples as well as complete package
documentation available at the `eia` package [website](https://docs.ropensci.org/eia/).

---

Please note that the `eia` project is released with
a [Contributor Code of Conduct](https://github.com/ropensci/eia/blob/master/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.

[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)

Owner

Name: rOpenSci
Login: ropensci
Kind: organization
Email: info@ropensci.org
Location: Berkeley, CA

Website: https://ropensci.org/
Twitter: rOpenSci
Repositories: 307
Profile: https://github.com/ropensci

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "eia",
  "description": "Provides API access to data from the U.S. Energy Information Administration ('EIA') <https://www.eia.gov/>. Use of the EIA's API and this package requires a free API key obtainable at <https://www.eia.gov/opendata/register.php>. This package includes functions for searching the EIA data directory and returning time series and geoset time series datasets. Datasets returned by these functions are provided by default in a tidy format, or alternatively, in more raw formats. It also offers helper functions for working with EIA date strings and time formats and for inspecting different summaries of series metadata. The package also provides control over API key storage and caching of API request results.",
  "name": "eia: API Wrapper for U.S. Energy Information Administration ('EIA') Open Data",
  "relatedLink": "https://docs.ropensci.org/eia/",
  "codeRepository": "https://github.com/ropensci/eia",
  "issueTracker": "https://github.com/ropensci/eia/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.4.2",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.3.1 (2023-06-16)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Matthew",
      "familyName": "Leonawicz",
      "@id": "https://orcid.org/0000-0001-9452-2771"
    },
    {
      "@type": "Person",
      "givenName": "Matthew",
      "familyName": "Hoff",
      "email": "matthew.g.hoff@gmail.com"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Matthew",
      "familyName": "Hoff",
      "email": "matthew.g.hoff@gmail.com"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "tidyr",
      "name": "tidyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tidyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "spelling",
      "name": "spelling",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spelling"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "tibble",
      "name": "tibble",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tibble"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "httr",
      "name": "httr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httr"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "jsonlite",
      "name": "jsonlite",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=jsonlite"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "memoise",
      "name": "memoise",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=memoise"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "lubridate",
      "name": "lubridate",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=lubridate"
    },
    "SystemRequirements": null
  },
  "fileSize": "202.885KB"
}

GitHub Events

Total

Issues event: 4
Watch event: 5
Issue comment event: 6
Push event: 1
Fork event: 5

Last Year

Issues event: 4
Watch event: 5
Issue comment event: 6
Push event: 1
Fork event: 5

Committers

Last synced: 5 months ago

All Time

Total Commits: 296
Total Committers: 6
Avg Commits per committer: 49.333
Development Distribution Score (DDS): 0.453

Past Year

Commits: 191
Committers: 3
Avg Commits per committer: 63.667
Development Distribution Score (DDS): 0.152

Top Committers

Name	Email	Commits
Matthew Hoff	m**f@g**m	162
leonawicz	m**z@e**m	102
leonawicz	m**z@g**m	28
Maëlle Salmon	m**n@y**e	2
David Ranzolin	d**n@g**m	1
James Lamb	j**0@g**m	1

Committer Domains (Top 20 + Academic)

esource.com: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 15
Total pull requests: 11
Average time to close issues: 7 months
Average time to close pull requests: 6 days
Total issue authors: 10
Total pull request authors: 5
Average comments per issue: 3.53
Average comments per pull request: 0.27
Merged pull requests: 11
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 2
Pull requests: 0
Average time to close issues: 6 days
Average time to close pull requests: N/A
Issue authors: 1
Pull request authors: 0
Average comments per issue: 5.0
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

leonawicz (4)
jameelalsalam (2)
BeckerJoe (2)
msgoussi (1)
mtkerbeR (1)
rdavis120 (1)
leungi (1)
tanga94 (1)
bobweeks (1)
morrisseyj (1)

Pull Request Authors

mghoff (7)
maelle (3)
leonawicz (3)
daranzolin (1)
jameslamb (1)

Top Labels

Issue Labels

help wanted (2) documentation (1)

Pull Request Labels

Packages

Total packages: 2
Total downloads:
- cran 517 last-month

Total dependent packages: 0
(may contain duplicates)
Total dependent repositories: 1
(may contain duplicates)
Total versions: 16
Total maintainers: 1

proxy.golang.org: github.com/ropensci/eia

Documentation: https://pkg.go.dev/github.com/ropensci/eia#section-documentation
License: other
Latest release: v0.4.2
published over 1 year ago

Versions: 8
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 5.4%

Average: 5.6%

Dependent repos count: 5.8%

Last synced: 4 months ago

cran.r-project.org: eia

API Wrapper for U.S. Energy Information Administration ('EIA') Open Data

Homepage: https://docs.ropensci.org/eia/
Documentation: http://cran.r-project.org/web/packages/eia/eia.pdf
License: MIT + file LICENSE
Latest release: 0.4.2
published over 1 year ago

Versions: 8
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 517 Last month

Rankings

Dependent repos count: 24.0%

Downloads: 24.3%

Average: 25.7%

Dependent packages count: 28.8%

Maintainers (1)

matthew.g.hoff@gmail.com

Last synced: 4 months ago

Dependencies

DESCRIPTION cran

dplyr * imports
httr * imports
jsonlite * imports
lubridate * imports
magrittr * imports
memoise * imports
purrr * imports
readxl * imports
tibble * imports
covr * suggests
ggplot2 * suggests
knitr * suggests
rmarkdown * suggests
testthat * suggests
tidyr * suggests

.github/workflows/R-CMD-check.yaml actions

actions/checkout v3 composite
r-lib/actions/check-r-package v2 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/test-coverage.yaml actions

actions/checkout v3 composite
actions/upload-artifact v3 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite