Merge pull request #1 from RamiKrispin/data-refresh-04/22

Data refresh 04/22

Author: RamiKrispin

.Rbuildignore

@@ -6,3 +6,4 @@
 ^data_raw$
 ^LICENSE\.md$
 ^CRAN-RELEASE$
+^CRAN-SUBMISSION$

CRAN-SUBMISSION

@@ -0,0 +1,3 @@
+Version: 0.1.2
+Date: 2023-04-16 06:30:52 UTC
+SHA: efb45230dddbd71b96c33b71c990eb6976f18b7f

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: USgas
 Type: Package
 Title: The Demand for Natural Gas in the US
-Version: 0.1.1
+Version: 0.1.2
 Authors@R: person(given = "Rami", 
                     family ="Krispin", 
                     email = "rami.krispin@gmail.com",
@@ -13,10 +13,11 @@ Encoding: UTF-8
 LazyData: true
 Depends: 
     R (>= 2.10)
-RoxygenNote: 7.1.1
+RoxygenNote: 7.2.1
 URL: https://github.com/RamiKrispin/USgas
 BugReports: https://github.com/RamiKrispin/USgas/issues
 Suggests: 
     knitr,
-    rmarkdown
+    rmarkdown,
+    plotly
 VignetteBuilder: knitr

NEWS.md

@@ -1,3 +1,8 @@
+# USgas 0.1.2
+
+* Add new dataset `usgas`, describing the US monthly natural gas consumption by end-use on the state and US aggregate level
+* Deprecating the previous package datasets - `us_residential`, `us_total`, and `us_total`, as they can be generated by the `usgas` dataset
+
 # USgas 0.1.1
 
 * Fixing CRAN errors - removing the `digits` argument from the `format` function

R/usgas.R

@@ -0,0 +1,72 @@
+#' US Monthly Consumption of Natural Gas by End Use
+#' @description The US monthly consumption of natural gas by end-use and state between 1973 (US aggregate, state level since 1989) and 2022.
+#'
+#' Units: Million Cubic Feet
+#'
+#'
+#' @format A data.frame with 6 variables.
+#' \describe{
+#'   \item{date}{A Date, the month and year of the observation (the day set by default to 1st of the month)}
+#'   \item{process}{The process type description}
+#'   \item{state}{The US state name}
+#'   \item{state_abb}{the US state abbreviation}
+#'   \item{y}{A numeric, the monthly natural gas residential consumption in a million cubic feet}
+#'   }
+#' @source US Energy Information Administration (EIA) \href{https://www.eia.gov/}{website}.
+#' @keywords datasets timeseries natural gas us state
+#' @details The dataset contains monthly summary of the consumption of natural gas
+#' by end-use in the US by state and total aggregate level. The data is available
+#' for the state level between January 1989 and December 2022, and for the US level
+#' between January 1973 and Dec 2022. It includes the following end-use categories:
+#'
+#' - Commercial Consumption
+#' - Delivered to Consumers
+#' - Electric Power Consumption
+#' - Industrial Consumption
+#' - Lease and Plant Fuel Consumption
+#' - Pipeline Fuel Consumption
+#' - Residential Consumption
+#' - Vehicle Fuel Consumption
+#'
+#' @examples
+#'
+#' library(plotly)
+#'
+#' data("usgas")
+#'
+#' head(usgas)
+#'
+#' # Plot the US consumption
+#'
+#' us_df <- usgas[which(usgas$state == "U.S."), ]
+#'
+#' plot_ly(data = us_df,
+#'         x = ~ date,
+#'         y = ~ y,
+#'         color = ~ process,
+#'         type = "scatter",
+#'         mode = "line") |>
+#'   layout(title = "US Monthly Consumption by End Use",
+#'          yaxis = list(title = "MMCF"),
+#'          xaxis = list(title = "Source: EIA Website"),
+#'          legend = list(x = 0, y = 1.05),
+#'          margin = list(l = 50, r = 50, b = 70, t = 60))
+#'
+#'
+#' # Plot the California consumption
+#'
+#' ca_df <- usgas[which(usgas$state == "California"), ]
+#'
+#' plot_ly(data = ca_df,
+#'         x = ~ date,
+#'         y = ~ y,
+#'         color = ~ process,
+#'         type = "scatter",
+#'         mode = "line") |>
+#'   layout(title = "California Monthly Consumption by End Use",
+#'          yaxis = list(title = "MMCF"),
+#'          xaxis = list(title = "Source: EIA Website"),
+#'          legend = list(x = 0, y = 1.05),
+#'          margin = list(l = 50, r = 50, b = 70, t = 60))
+#'
+"usgas"

README.Rmd

@@ -17,16 +17,31 @@ knitr::opts_chunk$set(
 # USgas <a href='https://ramikrispin.github.io/USgas/'><img src='man/figures/USgas.png' align="right" width="150" height="150" /></a>
 
 <!-- badges: start -->
-[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/USgas)](https://cran.r-project.org/package=USgas) [![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![GitHub commit](https://img.shields.io/github/last-commit/RamiKrispin/USgas)](https://github.com/RamiKrispin/USgas/commit/main)
+[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/USgas)](https://cran.r-project.org/package=USgas) [![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/mit/) [![GitHub commit](https://img.shields.io/github/last-commit/RamiKrispin/USgas)](https://github.com/RamiKrispin/USgas/commit/main)
 
 <!-- badges: end -->
 
-The **USgas** package provides an overview of demand for natural gas in the US in a time-series format. That includes the following datasets:
+The **USgas** package provides an overview of demand for natural gas in the US in a time-series format. That includes the following dataset:
+
+* `usgas` - The monthly consumption of natural gas in the US/state level by end-use since 1973 for US level and 1989 for state level. It includes the following end-use categories:
+
+   - Commercial Consumption
+   - Delivered to Consumers
+   - Electric Power Consumption
+   - Industrial Consumption
+   - Lease and Plant Fuel Consumption
+   - Pipeline Fuel Consumption
+   - Residential Consumption
+   - Vehicle Fuel Consumption
+
+The package also includes the following datasets, from previous release:
 
 * `us_total` - The US annual natural gas consumption by state-level between 1997 and 2019, and aggregate level between 1949 and 2019
 * `us_monthly` - The monthly demand for natural gas in the US between 2001 and 2020
 * `us_residential` - The US monthly natural gas residential consumption by state and aggregate level between 1989 and 2020
 
+The `us_total`, `us_monthly`, and `us_residential` can be derived out of the `usgas` dataset. Therefore, those datasets in the process of deprication and will be removed in the next release to CRAN.
+
 Data source: The US Energy Information Administration [API](https://www.eia.gov/)
 
 More information about the package datasets available on this [vignette](https://ramikrispin.github.io/USgas/articles/introduction.html).
@@ -47,106 +62,87 @@ devtools::install_github("RamiKrispin/USgas")
 ```
 ## Example
 
-Plotting the consumption of natural gas in New England states:
+Let's load the data:
 
 ```{r}
-data(us_total)
+data("usgas")
 
-str(us_total)
+head(usgas)
 
-head(us_total)
+str(usgas)
 ```
 
 
-Subsetting the New England states:
+Plotting the residential consumption of natural gas in the US:
+``` r
+library(plotly)
+
+us_res <- usgas[which(usgas$state == "U.S." & usgas$process == "Residential Consumption"), ]
+
+plot_ly(data = us_res,
+        x = ~ date,
+        y = ~ y,
+        type = "scatter",
+        mode = "line") |>
+  layout(title = "US Monthly Residential Consumption",
+         yaxis = list(title = "MMCF"),
+         xaxis = list(title = "Source: EIA API"))
+```
 
-```{r}
-ne <- c("Connecticut", "Maine", "Massachusetts",
-        "New Hampshire", "Rhode Island", "Vermont")
-ne_gas <-  us_total[which(us_total$state %in% ne),]
+```{r, include = FALSE}
+library(plotly)
+
+us_res <- usgas[which(usgas$state == "U.S." & usgas$process == "Residential Consumption"), ]
+
+p1 <- plot_ly(data = us_res,
+        x = ~ date,
+        y = ~ y,
+        type = "scatter",
+        mode = "line") |>
+  layout(title = "US Monthly Natural Gas Consumption by Residential Consumers",
+         yaxis = list(title = "MMCF"),
+         xaxis = list(title = "Source: EIA API"))
+orca(p1, "man/figures/us_res.svg")
+```
 
-ne_wide <- reshape(ne_gas, v.names = "y", idvar = "year",
-                   timevar = "state", direction = "wide")
-ne_wide <- ne_wide[order(ne_wide$year), ]
+<img src="man/figures/us_res.svg" width="100%" />
 
-names(ne_wide) <- c("year",ne)
 
-head(ne_wide)
-```
 
-Plotting the states series:
+Plotting the total monthly natural gas delivered in the New England states:
 
-```{r}
-# Set the y and x axis ticks
-at_x <- seq(from = 2000, to = 2020, by = 5)
-
-at_y <- pretty(ne_gas$y)[c(2, 4, 6)]
-
-# plot the first series
-plot(ne_wide$year, ne_wide$Connecticut,
-     type = "l",
-     col = "#073b4c",
-     frame.plot = FALSE,
-     axes = FALSE,
-     panel.first = abline(h = c(at_y), col = "grey80"),
-     main = "New England Annual Natural Gas Consumption by State",
-     cex.main = 1.2, font.main = 1, col.main = "black",
-     xlab = "Source: https://www.eia.gov/",
-     font.axis = 1, cex.lab= 1,
-     ylab = "Million Cubic Feet",
-     ylim = c(min(ne_gas$y, na.rm = TRUE), max(ne_gas$y, na.rm = TRUE)),
-     xlim = c(min(ne_gas$year), max(ne_gas$year) + 3))
-
-# Add the 5 other series
-lines(ne_wide$year, ne_wide$Maine, col = "#1f77b4")
-lines(ne_wide$year, ne_wide$Massachusetts, col = "#118ab2")
-lines(ne_wide$year, ne_wide$`New Hampshire`, col = "#06d6a0")
-lines(ne_wide$year, ne_wide$`Rhode Island`, col = "#ffd166")
-lines(ne_wide$year, ne_wide$Vermont, col = "#ef476f")
-
-# Add the y and x axis ticks
-
-mtext(side =1, text = format(at_x, nsmall=0), at = at_x,
-      col = "grey20", line = 1, cex = 0.8)
-
-mtext(side =2, text = format(at_y, scientific = FALSE), at = at_y,
-      col = "grey20", line = 1, cex = 0.8)
-
-# Add text 
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$Connecticut,1),
-     "Connecticut",
-     col = "#073b4c",
-     cex = 0.7)
-
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$Maine,1) * 0.95,
-     "Maine",
-     col = "#1f77b4",
-     cex = 0.7)
-
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$Massachusetts,1),
-     "Massachusetts",
-     col = "#118ab2",
-     cex = 0.7)
-
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$`New Hampshire`,1) * 1.1,
-     "New Hampshire",
-     col = "#06d6a0",
-     cex = 0.7)
-
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$`Rhode Island`,1) * 1.05,
-     "Rhode Island",
-     col = "#ffd166",
-     cex = 0.7)
-
-text(max(ne_wide$year) + 2,
-     tail(ne_wide$Vermont,1),
-     "Vermont",
-     col = "#ef476f",
-     cex = 0.7)
+```r
+ne <- c("Connecticut", "Maine", "Massachusetts",
+        "New Hampshire", "Rhode Island", "Vermont")
+ne_gas <-  usgas[which(usgas$state %in% ne & usgas$process == "Delivered to Consumers"),]
+
+plot_ly(data = ne_gas,
+        x = ~ date,
+        y = ~ y,
+        color = ~ state,
+        type = "scatter",
+        mode = "line") |>
+  layout(title = "Total Natrual Gas Delivered to Consumers in New England States",
+         yaxis = list(title = "MMCF"),
+         xaxis = list(title = "Source: EIA API"))
+```
+
+```{r , include = FALSE}
+ne <- c("Connecticut", "Maine", "Massachusetts",
+        "New Hampshire", "Rhode Island", "Vermont")
+ne_gas <-  usgas[which(usgas$state %in% ne & usgas$process == "Delivered to Consumers"),]
+
+p2 <- plot_ly(data = ne_gas,
+        x = ~ date,
+        y = ~ y,
+        color = ~ state,
+        type = "scatter",
+        mode = "line") |>
+  layout(title = "Total Natrual Gas Delivered to Consumers in New England States",
+         yaxis = list(title = "MMCF"),
+         xaxis = list(title = "Source: EIA API"))
+
+orca(p2, "man/figures/new_england.svg")
 ```
 
+<img src="man/figures/new_england.svg" width="100%" />