Display BLS Dataset Overview

Description

Fetches and displays the overview text file for a BLS dataset. This provides a convenient reference within the R environment without needing to manually find and review the text file on the BLS website.

Usage

bls_overview(
  series_id,
  display_method = "viewer",
  base_url = "https://download.bls.gov/pub/time.series"
)

Arguments

Value

Invisibly returns the text content. Function is called to use the viewer, console, or as a popup, depending on the 'display_method' argument.

Examples

# Display labor force statistics overview
bls_overview("ln")

# Display consumer price index overview  
bls_overview("cu")

# Display in console instead of viewer
bls_overview("ln", display_method = "console")

Create a BLS data object with diagnostics

Description

This is a helper function to create a list with the additional class 'bls_data_collection' containing data downloaded form the U.S. Bureau of Labor Statistics as well as diagnostic details about the download. It is used invisibly in the package to bundle information about file downloads.

Usage

create_bls_object(
  data,
  downloads,
  data_type = "BLS",
  processing_steps = character(0)
)

Arguments

Value

A bls_data_collection object

Display text content in console.

Description

Helper function used to display content from 'bls_overview' in the console..

Usage

display_in_console(content, series_id)

Arguments

Value

No object returned, called to render content in console only..

Display text content in popup window.

Description

Helper function used to display content from 'bls_overview' in a popup window.

Usage

display_in_popup(content, series_id)

Arguments

Value

No object returned, called to render content in popup.

Display text content in Viewer window.

Description

Helper function used to display content from 'bls_overview' in the HTML viewer.

Usage

display_in_viewer(content, series_id)

Arguments

Value

No object returned, called to render content in HTML viewer.

Helper function for downloading and tracking BLS files

Description

This function is used to pass multiple URLs at the Bureau of Labor Statistics into 'fread_bls()'

Usage

download_bls_files(urls, suppress_warnings = TRUE)

Arguments

Value

Named list of bls_data objects

Download BLS Time Series Data

Description

This function downloads a tab-delimited BLS flat file, incorporating diagnostic information about the file and returning an object with the bls_data class that can be used in the BLSloadR package.

Usage

fread_bls(url, verbose = FALSE)

Arguments

Value

A named list with two elements:

data

A data.table with the results of passing the url contents to 'data.table::fread()' as a tab-delimited text file.

diagnostics

A named list of diagnostics run when reading the file including column names, empty columns, cleaning applied to the file, the url, the column names and original and final dimensions of the data.

Examples

data <- fread_bls("https://download.bls.gov/pub/time.series/ec/ec.series")

Extract data from BLS data object

Description

This is a helper function to extract the data element of a 'bls_data_collection' object.

Usage

get_bls_data(bls_obj)

Arguments

Value

The data component of a 'bls_data_collection' object as a data frame.

Get download diagnostics from BLS data object

Description

This is a helper function to extract the download diagnostics element of a 'bls_data_collection' object.

Usage

get_bls_diagnostics(bls_obj)

Arguments

Value

List of download diagnostics from a bls_data_collection object.

Get summary information from BLS data object

Description

This is a helper function to extract the summary element of a 'bls_data_collection' object. This containes the number of files downloaded, the number of files with potential warnings, and the total number of warnings.

Usage

get_bls_summary(bls_obj)

Arguments

Value

List of summary information

Download Current Employment Statistics (CES) Data

Description

This function downloads Current Employment Statistics data from the Bureau of Labor Statistics. The data includes national, regional, state, and substate employment statistics. By default, all available areas, data types, and periods are included.

Usage

get_ces(
  transform = TRUE,
  monthly_only = TRUE,
  simplify_table = TRUE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE
)

Arguments

Value

By default, returns a data.table with CES data. If return_diagnostics = TRUE, returns a bls_data_collection object containing data and comprehensive diagnostics.

Examples

# Download CES data (streamlined approach)
ces_data <- get_ces()

# Download with full diagnostics if needed
ces_result <- get_ces(return_diagnostics = TRUE)
ces_data <- get_bls_data(ces_result)

# Check for download issues
if (has_bls_issues(ces_result)) {
  print_bls_warnings(ces_result)
}

Download Job Openings and Labor Turnover Survey (JOLTS) Data

Description

This function downloads Job Openings and Labor Turnover data from the U.S. Bureau of Labor Statistics. JOLTS data provides insights into job market dynamics including job openings, hires, separations, quits, and layoffs. Data is available at national, regional, and state levels with various industry and size class breakdowns.

Usage

get_jolts(
  monthly_only = TRUE,
  remove_regions = TRUE,
  remove_national = TRUE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE
)

Arguments

Details

The function performs several data transformations:

• Converts rate values to proportions (divides by 100) except for Unemployed to Job Opening ratio.

• Converts level values to actual counts (multiplies by 1000)

• Creates a proper date column from year and period

• Adds readable month names

Value

By default, returns a data.table with JOLTS data. If return_diagnostics = TRUE, returns a bls_data_collection object containing JOLTS data with the following key columns:

series_id

BLS series identifier

year

Year of observation

period

Time period (M01-M12 for months)

value

JOLTS statistic value (transformed based on data type)

date

Date of observation

state_text

State name

dataelement_text

Type of JOLTS measure (job openings, hires, separations, etc.)

area_text

Geographic area description

sizeclass_text

Establishment size class

industry_text

Industry classification

ratelevel_code

Whether the value is a "Level" (count) or "Rate" (percentage)

periodname

Month name

Examples

# Download state-level JOLTS data (default - returns data directly)
jolts_data <- get_jolts()

# Include national data with industry breakdowns
jolts_national <- get_jolts(remove_national = FALSE)

# Get full diagnostic object if needed
jolts_with_diagnostics <- get_jolts(return_diagnostics = TRUE)
print_bls_warnings(jolts_with_diagnostics)

# View job openings by state for latest period
job_openings <- jolts_data[dataelement_text == "Job openings" & 
                          date == max(date)]

Download Local Area Unemployment Statistics (LAUS) Data

Description

This function downloads Local Area Unemployment Statistics data from the U.S. Bureau of Labor Statistics. Due to the large size of some LAUS datasets (county and city files are >300MB), users must specify which geographic level to download. The function provides access to both seasonally adjusted and unadjusted data at various geographic levels. Additional datasets provide comprehensive non-seasonally-adjusted data for all areas broken out in 5-year increments

Usage

get_laus(
  geography = "state_adjusted",
  monthly_only = TRUE,
  transform = TRUE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE
)

Arguments

Details

The function joins data from multiple BLS files:

• Main data file (varies by geography selection)

• Series definitions (la.series)

• Area codes and names (la.area)

• Measure definitions (la.measure)

Value

By default, returns a data.table with LAUS data. If return_diagnostics = TRUE, returns a bls_data_collection object containing LAUS data with the following key columns:

series_id

BLS series identifier

year

Year of observation

period

Time period (M01-M12 for months, M13 for annual)

value

Employment statistic value (transformed if transform = TRUE)

date

Date of observation (if monthly_only = TRUE)

area_text

Geographic area name

area_type_code

Code indicating area type

measure_text

Type of measure (unemployment rate, labor force, employment, etc.)

seasonal

Seasonal adjustment status

Examples

# Download state-level seasonally adjusted data (default operation)
laus_states <- get_laus()

# View unemployment rates by state for latest period
unemployment <- laus_states[grepl("unemployment rate", measure_text) & date == max(date)]

# Download unadjusted state data
laus_states_unadjusted <- get_laus("state_unadjusted")

# Download metro area data with rates as whole number percentages (64.3 instead of 0.643)
laus_metro <- get_laus("metro", transform = FALSE)

# Get full diagnostic object if needed
laus_with_diagnostics <- get_laus(return_diagnostics = TRUE)
print_bls_warnings(laus_with_diagnostics)

Get National Current Employment Statistics (CES) Data from BLS

Description

This function downloads and processes national Current Employment Statistics (CES) data from the Bureau of Labor Statistics (BLS). It retrieves multiple related datasets and joins them together to create a comprehensive employment statistics dataset with industry classifications, data types, and time period information.

Usage

get_national_ces(
  monthly_only = TRUE,
  simplify_table = TRUE,
  show_warnings = FALSE,
  return_diagnostics = FALSE
)

Arguments

Details

The function downloads the following BLS CES datasets:

• ce.data.0.AllCESSeries - Main employment data

• ce.series - Series metadata

• ce.industry - Industry classifications

• ce.datatype - Data type definitions

• ce.period - Time period definitions

• ce.supersector - Supersector classifications

These datasets are joined together to provide context and labels for the employment statistics. The function uses the 'fread_bls()' helper function to download and read the BLS data files with robust error handling and diagnostic reporting.

Value

By default, returns a data.table with CES data. If return_diagnostics = TRUE, returns a bls_data_collection object containing data and comprehensive diagnostics.

Note

This function requires the following packages: dplyr, data.table, httr, and lubridate (for date formatting when simplify_table=TRUE). The 'fread_bls()' and 'create_bls_object()' helper functions must be available in your environment.

See Also

Please visit the Bureau of Labor Statistics at https://www.bls.gov/ces/ for more information about CES data

Examples

# Get monthly CES data with simplified table structure
ces_monthly <- get_national_ces()

# Get all data including annual averages with full metadata
ces_full <- get_national_ces(monthly_only = FALSE, simplify_table = FALSE)

# Get monthly data but keep all metadata columns
ces_detailed <- get_national_ces(monthly_only = TRUE, simplify_table = FALSE)

# Access the data component
ces_data <- get_bls_data(ces_monthly)

# Get full diagnostic object if needed
data_with_diagnostics <- get_national_ces(return_diagnostics = TRUE)
print_bls_warnings(data_with_diagnostics)

Download Occupational Employment and Wage Statistics (OEWS) Data

Description

This function downloads and joins together occupational employment and wage data from the Bureau of Labor Statistics OEWS program. The data includes employment and wage estimates by occupation and geographic area. Note that OEWS is a large data set (over 6 million rows), so it will require longer to download.

Usage

get_oews(
  simplify_table = TRUE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE
)

Arguments

Value

By default, returns a data.table with OEWS data. If return_diagnostics = TRUE, returns a bls_data_collection object containing data and comprehensive diagnostics. The columns in the returned data frame when 'simplify_table = TRUE' are listed below. Unless otherwise specified, all data is returned as a character string to preserve the value of leading and trailing zeroes.

• series_id - The unique OEWS series identifier.

• year - The year to which the estimate refers. Because OEWS is not time series data, this is always the most recent year.

• value - Numeric. The value of the given data type, for the given area, in the given industry and occupation.

• seasonal - Whether or not the data is seasonally adjusted.

• areatype_code - Code representing the type of area (National ("N"), Statewide ("S"), or Local ("M")).

• industry_code - NAICS code of the industry.

• occupation_code - SOC code of the occupation. Description given by occupation_name.

• datatype_code - Lookup code for the data type of a given row. Description given by datatype_name.

• state_code - Two-digit FIPS code for the state.

• area_code - The unique OEWS code for a substate area. Description given by area_name.

• series_title - Descriptive title of the full series ID.

• occupation_name - The text description of the occupation.

• occupation_description - More detailed description of the tasks associated with the occupation.

• area_name - The text description of the area.

• datatype_name - The text description of the type of data represented by 'value'.

Examples

# Download current OEWS data
oews_data <- get_oews()

# View available occupations
unique(oews_data$occupation_name)

# Filter for specific occupation
software_devs <- oews_data[grepl("Software", occupation_name)]

# Get full diagnostic object if needed
oews_with_diagnostics <- get_oews(return_diagnostics = TRUE)
print_bls_warnings(oews_with_diagnostics)

Download State Alternative Labor Market Measures (SALT) Data

Description

This function downloads detailed alternative unemployment measures data from BLS, including U-1 through U-6 measures. The data provides a more comprehensive view of labor market conditions beyond the standard unemployment rate (U-3).

Usage

get_salt(
  only_states = TRUE,
  geometry = FALSE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE
)

Arguments

Value

By default, returns a data.table with Alternative Measures of Labor Underutilization data. If return_diagnostics = TRUE, returns a bls_data_collection object containing data and comprehensive diagnostics. The function also adds derived measures and quartile comparisons across states.

Examples

# Download state-level SALT data
salt_data <- get_salt()

# View top 10 highest U-6 rates by state in current data
latest <- salt_data |> 
  dplyr::filter(date == max(date)) |> 
  dplyr::select(state, u6) |> 
  dplyr::arrange(-u6)
head(latest)

# Include sub-state areas
salt_all <- get_salt(only_states = FALSE)
 
# Download SALT with geometry included
get_salt(geometry = TRUE)

# Get full diagnostic object if needed
data_with_diagnostics <- get_salt(return_diagnostics = TRUE)
print_bls_warnings(data_with_diagnostics)

Check if BLS data object has potential issues with import.

Description

Check if BLS data object has potential issues with import.

Usage

has_bls_issues(bls_obj)

Arguments

Value

Logical indicating if there were any import issues detected.

Generic BLS Dataset Download

Description

This function generalizes a method to download all BLS data for a given time series database. These files are accessed from https://download.bls.gov/pub/time.series/ and several datasets are available. A summary of an identified database can be generated using the 'bls_overiew()' function. When multiple potential data files exist (common in large data sets), the function will prompt for an input of which file to use.

Usage

load_bls_dataset(
  database_code,
  return_full = FALSE,
  simplify_table = TRUE,
  suppress_warnings = FALSE
)

Arguments

Value

This function will return either a bls_data_collection object (if return_full is FALSE or not provided) or a named list of the returned data including the bls_data_collection object.

Examples

## Not run: 
# Download Employer Cost Index Data
cost_index <- load_bls_dataset("ci")

# Download separated data, series, and mapping columns
benefits <- load_bls_dataset("eb", return_full = TRUE)

# Download data without removing excess columns and value conversions
productivity <- load_bls_dataset("mp", simplify_table = FALSE)

# Check for download issues
if (has_bls_issues(cost_index)) {
  print_bls_warnings(cost_index, detailed = TRUE)
}

## End(Not run)

Print warnings for BLS data object

Description

Print warnings for BLS data object

Usage

print_bls_warnings(bls_obj, detailed = FALSE, silent = FALSE)

Arguments

Value

Character vector of warnings (invisibly)

Read Plain Text Files from BLS Website

Description

Downloads and reads plain text files from the Bureau of Labor Statistics (BLS) website. This is a companion function to fread_bls() that handles text files rather than structured data tables. The function uses custom headers to ensure reliable access to BLS resources.

Usage

read_bls_text(url)

Arguments

Details

This function is designed to read descriptive text files from BLS, such as README files or database overview documents. It sends an HTTP GET request with browser-like headers to ensure compatibility with BLS server requirements.

The function will stop with an error if the HTTP request fails (e.g., if the URL is invalid or the server is unavailable).

Value

A character vector where each element is one line from the text file. Lines are split on newline characters (\n).

See Also

bls_overview for formatted database overviews, load_bls_dataset for loading complete datasets

Examples

# Read the overview file for Current Employment Statistics
ces_overview <- read_bls_text(
  "https://download.bls.gov/pub/time.series/ce/ce.txt"
)

# Display the first few lines
head(ces_overview)