Merge pull request #31 from glenem/laus

LAUS wrapper function for blsAPI

DESCRIPTION

@@ -11,7 +11,8 @@ Depends:
     R (>= 3.1.1)
 Imports:
     rjson,
-    httr
+    httr,
+    dplyr
 License: GPL (>= 2)
 LazyData: true
-RoxygenNote: 6.1.0
+RoxygenNote: 7.1.1

NAMESPACE

@@ -1,7 +1,13 @@
 # Generated by roxygen2: do not edit by hand
 
+export(apiDF)
 export(blsAPI)
 export(blsQCEW)
+export(help_laus_areacodes)
+export(laus_get_areacode)
+export(laus_get_data)
+export(laus_get_measure)
+import(dplyr)
 import(httr)
 import(rjson)
 importFrom(utils,read.csv)

R/LAUS_AreaCodes.R

@@ -0,0 +1,14 @@
+#' Area codes for Labor Area Unemployment Statistics (LAUS) data
+#'
+#' A data set containing the area code and area text associated with each code for the LAUS data set
+#'
+#' @format A data frame with 8321 rows and 2 variables
+#' \describe{
+#'     \item{area_code}{area code for LAUS}
+#'     \item{area_text}{area name for LAUS}
+#' }
+#'  
+#' @source \url{https://download.bls.gov/pub/time.series/la/la.area}
+#'
+#'
+"LAUS_AreaCodes"

R/apiDF.R

@@ -0,0 +1,29 @@
+# apiDF.R
+#
+#' @title Creates data frame after data is called using blsAPI.R
+#' @description Used in the laus_get_data function
+#' @param data The JSON used to extract the data gathered from the blsAPI function
+#' @return returns a data frame of the data requested from the bLSAPI function call
+#' @export apiDF
+#' @import rjson
+#' @examples
+#' library(blsAPI)
+#' library(rjson)
+#' response <- blsAPI('LAUCN040010000000005')
+#' json <- fromJSON(response)
+#' df <- apiDF(json$Results$series[[1]]$data)
+#' 
+apiDF <- function(data){
+  df <- data.frame(year=character(),
+                   period=character(),
+                   periodName=character(),
+                   value=character(),
+                   stringsAsFactors=FALSE)
+
+  i <- 0
+  for(d in data){
+    i <- i + 1
+    df[i,] <- c(d$year, d$period, d$periodName, d$value)
+  }
+  return(df)
+}

R/help_laus_areacodes.R

@@ -0,0 +1,16 @@
+# help_laus_areacodes
+
+#' @title Prints a list of area names associated to an area code for the LAUS data
+#' @return prints a list in the console
+#' @export help_laus_areacodes
+#'
+#' @examples
+#' library(blsAPI)
+#' library(dplyr)
+#' help_laus_areacodes() 
+#' 
+help_laus_areacodes <- function(){
+  data("LAUS_AreaCodes", envir = environment())
+  AreaName <- select(LAUS_AreaCodes, "area_text")
+  print.data.frame(AreaName)
+}

R/laus_get_areacode.R

@@ -0,0 +1,22 @@
+# laus_get_areacode
+#
+#' @title Acquire the area code used in the series id for observations in Labor Area Unemployment Statistics (LAUS) data
+#' @description Gathers the area code used in the laus_get_data function to acquire a data frame using the blsAPI function that request data through the U.S. Bureau of Labor Statistics API. The laus_get_areacode function is called by the laus_get_data function not the user.
+#' @param Location_Name A string or vector of the different cities, states or metropolitan statistical areas you want LAUS data from
+#' @details type help_laus_areacodes() to get a list of all of the area names that area associated to an area code in the LAUS data
+#' @export laus_get_areacode
+#' @return returns a string or vector representing area codes
+#' @examples
+#' library(blsAPI)
+#' laus_get_areacode(Location_Name = c("Florida", "California", 
+#'                     "Charlotte County, FL", "Fresno County, CA"))
+#' 
+laus_get_areacode <- function(Location_Name){
+  # Loading in the Area Code rda file
+  data("LAUS_AreaCodes", envir = environment())
+  #
+  laus_df <- subset(LAUS_AreaCodes, LAUS_AreaCodes$area_text %in% Location_Name, select = c("area_code", 'area_text'))
+  #
+  laus_vector <- laus_df$area_code
+  return(laus_vector)
+}

R/laus_get_data.R

@@ -0,0 +1,96 @@
+# laus_get_data.R
+#
+#' @title A wrapper function for blsAPI.R function that processes gathered Labor Area Unemployment Statistics (LAUS) data into a data frame
+#' @description Allows users to request LAUS data and have it downloaded as a data frame with ease
+#' @param location.vector A string or vector of the different cities, states or metropolitan statistical areas you want LAUS data from. To get help type help_laus_areacodes() to get a list of all of the area names that area associated to an area code in the LAUS data
+#' @param measure.vector  A string of the laus measure you want to gather in your call, e.g. unemployment, unemployment rate.
+#' @param start.year The year you want as the beginning period of data collection
+#' @param end.year The year you want as the ending period of data collection
+#' @param api.version A numerical value that specifies which version of the api you're using (1 or 2). Default is version 1.
+#' @param bls.key The BLS key you're using to retrieve data using version 2
+#' @export laus_get_data
+#' @import dplyr rjson 
+#' @examples
+#' library(blsAPI)
+#' library(dplyr)
+#' library(rjson)
+#' unem_df <- laus_get_data(location.vector = c("Florida", "California", 
+#'                     "Charlotte County, FL", "Fresno County, CA"), 
+#'                      measure.vector = "unemployment rate", 
+#'                      start.year = 2019, end.year = 2021, 
+#'                      api.version = 1)
+#' 
+laus_get_data <- function(location.vector, measure.vector, start.year, end.year, api.version=1, bls.key=NULL){
+
+  # Saves the Fips codes to a vector for later use
+  SeriesID <- laus_get_areacode(location.vector)
+
+  # Saves the measure code to a vector for later use
+  Measure_Code <- laus_get_measure(measure = measure.vector)
+
+  # Initializes a blank character vector that will house the Series IDs for the LAUS data for each location and for one specified measure
+  location_vec <- character()
+  # For loop that creates a Series ID for each location based on the measure selected
+  for (i in SeriesID){
+    location_vec <- c(location_vec, paste("LAU",i, Measure_Code, sep=""))
+  }
+
+  # An if statement to ascertain which version of the API is used then creates the correct payload
+  if (api.version==1){
+  payload <- list(
+    'seriesid'=c(location_vec),
+    'startyear'=start.year,
+    'endyear'=end.year)
+  response <- blsAPI(payload, api_version = api.version)
+  json <- fromJSON(response)
+  return
+  }else if(api.version==2){
+    payload <- list(
+      'seriesid'=c(location_vec),
+      'startyear'=start.year,
+      'endyear'=end.year,
+      'registrationKey'=bls.key)
+    response <- blsAPI(payload, api_version = api.version)
+    json <- fromJSON(response)
+  }
+
+  # Creates an empty data frame with specified columns 
+  # Used later in the next for loop to house data for each area 
+  df = data.frame(
+    year = character(),
+    period = character(),
+    periodName = character(),
+    value = numeric(),
+    Location = character()
+  )
+
+  # 
+  n = 1
+  # For loop that takes the data for each area and adds its rows to the df specified above
+  for (i in location.vector){
+    temp <- apiDF(json$Results$series[[n]]$data)
+    temp$Location <- i
+    temp$value <- as.numeric(temp$value)
+    df <- rbind(df, temp)
+    n = n +1
+  }
+
+  # If else statements to rename the value column based on the measure used
+  if(Measure_Code == "03"){
+    df <- dplyr::rename(df, Unemployment_Rate = value)
+  }else if(Measure_Code == "04"){
+    df <- dplyr::rename(df, Unemployment = value)
+  }else if(Measure_Code == "05"){
+    df <- dplyr::rename(df, Employment = value)
+  }else if(Measure_Code == "06"){
+    df <- dplyr::rename(df, Labor_Force = value)
+  }else if(Measure_Code == "07"){
+    df <- dplyr::rename(df, Employment_Pop_Ratio = value)
+  }else if(Measure_Code == "08"){
+    df <- dplyr::rename(df, Labor_Force_Participation_Rate = value)
+  }else if(Measure_Code == "09"){
+    df <- dplyr::rename(df, Civilian = value)
+  }
+
+  return(df)
+}

R/laus_get_measure.R

@@ -0,0 +1,22 @@
+# laus_get_measure.R
+#
+#' @title Acquire the measure code used in the series id for observations in Labor Area Unemployment Statistics (LAUS) data
+#' @description Gathers the measure code used in the laus_get_data function to acquire a data frame using the blsAPI function that request data through the U.S. Bureau of Labor Statistics API. The laus_get_areacode function is called by the laus_get_data function not the user.
+#' @param measure a string containing the desired measure. Exs: unemployment rate, labor force, employment, etc.
+#' @details See <\url{https://download.bls.gov/pub/time.series/la/la.measure}> to see the format of the strings used in the measure param found in the measure_text column
+#' @return returns a string representing a measure code
+#' @export laus_get_measure
+#' @
+#' @examples
+#' library(blsAPI)
+#' laus_get_measure("unemployment rate")
+laus_get_measure <- function(measure){
+  #
+  data("laus_measure", envir = environment())
+  #
+  laus_df <- subset(laus_measure, laus_measure$measure_text %in% measure, select = c("measure_code", 'measure_text'))
+  #
+  laus_vector <- laus_df$measure_code
+  return(laus_vector)
+}
+

R/laus_measure.R

@@ -0,0 +1,14 @@
+#' Measure codes for Labor Area Unemployment Statistics (LAUS) data
+#'
+#' A data set containing the measure code and measure text associated with each code for the LAUS data set
+#'
+#' @format A data frame with 7 rows and 2 variables
+#' \describe{
+#'     \item{measure_code}{measure code for LAUS}
+#'     \item{measure_text}{measure name for LAUS}
+#' }
+#'  
+#' @source \url{https://download.bls.gov/pub/time.series/la/la.measure}
+#'
+#'
+"laus_measure"

README.md

@@ -148,6 +148,30 @@ MichiganData <- blsQCEW('Area', year='2017', quarter='1', area='26000')
 
 Please see the help file for more options and example code.
 
+## Labor Area Unemployment Statistics Function
+The laus_get_data() function is a wrapper of the blsAPI() function that makes it easier to get the labor area unemployment data without knowing the Series ID for the specific area and measure you want. A few examples of a measure would be the unemployment rate, or the labor force. 
+
+#### Example
+This example pulls the unemployment rate for California, Florida, Texas, and Nevada from 2019 to 2021.
+
+```r
+library(rjson)
+library(blsAPI)
+library(dplyr)
+
+unemployment_rate <- laus_get_data(c("California", "Florida", "Texas", "Nevada"), "unemployment rate", 2019, 2021)
+```
+
+The resulting data frame will look like this for the first four rows
+|  year  |  period  |  periodName  |  Unemployment_Rate  | Location   |
+|:------:|:--------:|:------------:|:-------------------:|:----------:|
+|  2021  |   M07    | July         |   2.2               | California |
+|  2021  |   M06    | June         |   2.0               | California |
+|  2021  |   M05    | May          |   1.8               | California |
+|  2021  |   M04    | April        |   2.0               | California |
+
+For more examples of this function and to learn more about it type ?laus_get_data in your R console. 
+
 ## Learning More
 With the basics described above you can get started with the BLS API right away. To learn more see: