lehdr (pronounced: lee dur like a metric litre) is an R package that allows users to interface with the Longitudinal Employer-Household Dynamics (LEHD) Origin-Destination Employment Statistics (LODES) dataset, returned as tidy data frames. The package is designed to download LODES flat files (origin-destination, workplace area characteristics, and residential area characteristics), aggregate them to common Census geographies, and now includes built-in analytical functions for commute flow statistics, longitudinal job change, and earnings tier shares.
Full documentation and the Getting Started vignette are available at the lehdr pkgdown site. For a detailed walkthrough of all analytical functions and maps, see the Getting Started vignette.
You can install the released version of lehdr from CRAN with:
install.packages("lehdr")And the development version from GitHub with:
# install.packages("pak")
pak::pak("jamgreen/lehdr")Load the library and optionally set the lehdr_use_cache
option to save downloaded files for reuse across sessions:
library(lehdr)
options(lehdr_use_cache = TRUE)The grab_lodes() function downloads data for a specific
state, year, and LODES version. The table type is set with
lodes_type: origin-destination ("od"),
residential area characteristics ("rac"), or workplace area
characteristics ("wac").
For example, Oregon (state = "or") for 2020
(year = 2020) from LODES version 8
(version = "LODES8", the default), origin-destination
(lodes_type = "od"), primary jobs
(job_type = "JT01", the default), all worker segments
(segment = "S000", the default), aggregated to the Census
tract level (agg_geo = "tract"):
or_od <- grab_lodes(
state = "or",
year = 2020,
version = "LODES8",
lodes_type = "od",
job_type = "JT01",
segment = "S000",
state_part = "main",
agg_geo = "tract"
)
head(or_od)Pass character vectors to state and numeric vectors to
year to retrieve multiple states and years in a single
call:
or_ri_od <- grab_lodes(
state = c("or", "ri"),
year = c(2013, 2014),
lodes_type = "od",
job_type = "JT01",
segment = "S000",
state_part = "main",
agg_geo = "tract"
)
head(or_ri_od)Not all years are available for each state. For the full availability matrix, see the LEHD Technical Document at https://lehd.ces.census.gov/data/lodes/LODES8/.
Set geometry = TRUE to join Census geometries via the
tigris package. When lodes_type = "rac" or
"wac", grab_lodes() returns an sf
data frame directly:
ri_rac_geo <- grab_lodes(
state = "ri",
year = 2020,
lodes_type = "rac",
agg_geo = "county",
geometry = TRUE
)
plot(ri_rac_geo["C000"])For lodes_type = "od", separate h_geometry
and w_geometry columns are returned. These can be combined
into flow lines:
or_od_geo <- grab_lodes(
state = "or",
year = 2020,
lodes_type = "od",
agg_geo = "county",
geometry = TRUE,
state_part = "main"
)
h_to_w_geometry <- lapply(
seq(nrow(or_od_geo)),
function(i) {
sf::st_linestring(
c(
sf::st_centroid(or_od_geo[["h_geometry"]][[i]]),
sf::st_centroid(or_od_geo[["w_geometry"]][[i]])
)
)
}
)
h_to_w_lines <- sf::st_as_sfc(h_to_w_geometry, crs = 4269)
or_od_lines <- sf::st_set_geometry(
or_od_geo[, c("w_county", "h_county", "h_geometry", "S000")],
h_to_w_lines
)
multnomah_od_lines <- dplyr::filter(or_od_lines, w_county == "41051")
plot(multnomah_od_lines["S000"], reset = FALSE)
plot(or_od_geo["h_geometry"], lwd = 0.25, add = TRUE)The optional version parameter selects the LODES
vintage. LODES8 (default) uses 2020 Census blocks. LODES7 uses 2010
Census blocks and ends in 2019. LODES5 uses 2000 Census blocks and ends
in 2009.
lehdr includes three functions for common LODES analyses.
compute_commute_stats() takes an OD data frame and
returns per-geography inflow, outflow, internal flow, net flow, and
self-containment ratio. Self-containment is the share of employed
residents who also work within the same geographic unit.
od_md <- grab_lodes(
state = "md",
year = 2019,
lodes_type = "od",
job_type = "JT00",
segment = "S000",
state_part = "main",
agg_geo = "county"
)
commute_md <- compute_commute_stats(od_md, agg_geo = "county")
commute_md |>
dplyr::arrange(dplyr::desc(self_containment)) |>
dplyr::select(county, workers_in, workers_out, net_flow, self_containment) |>
head(10)The map below shows self-containment at the Census tract level for Baltimore City, Maryland (FIPS 24510):
compute_lodes_change() computes absolute and percentage
change in any LODES variable between two years. Output can be wide (one
row per geography) or long (suitable for ggplot2).
wac_md_panel <- grab_lodes(
state = "md",
year = c(2010, 2019),
lodes_type = "wac",
job_type = "JT00",
segment = "S000",
agg_geo = "county"
)
change_md <- compute_lodes_change(
wac_md_panel,
geo_col = "w_county",
base_year = 2010,
compare_year = 2019,
variables = c("C000", "CE01", "CE02", "CE03")
)
change_md |>
dplyr::arrange(dplyr::desc(C000_change)) |>
dplyr::select(w_county, C000_base, C000_compare, C000_change, C000_pct_change) |>
head(10)The map below shows percent change in total jobs across Maryland counties from 2010 to 2019:
compute_earnings_share() computes the distribution of
jobs across LODES earnings tiers: low (up to $1,250/month), mid
($1,251-$3,333/month), and high (above $3,333/month). Use
output = "long" for a ggplot2-ready
format.
wac_md <- grab_lodes(
state = "md",
year = 2019,
lodes_type = "wac",
job_type = "JT00",
segment = "S000",
agg_geo = "county"
)
earn_shares <- compute_earnings_share(wac_md, type = "wac", geo_col = "w_county")
earn_shares |>
dplyr::arrange(dplyr::desc(share_low)) |>
dplyr::select(w_county, share_low, share_mid, share_high) |>
head(10)
The figures above were produced with ggplot2 and
tigris. The general pattern is: download with
grab_lodes(), compute a derived variable, fetch geometries
with tigris::tracts() or tigris::counties(),
join on GEOID, and plot with geom_sf(). See
vignette("getting_started") for full figure code.
The map below shows a flow-weighted job accessibility index for Baltimore City tracts, computed directly from LODES OD data:
All figures can be reproduced by running
source("data-raw/render_vignette_figures.R") locally. The
map below shows self-containment at the Census tract level for Baltimore
City, Maryland — a simple but powerful use of LODES OD data to
understand which neighborhoods have strong local job access versus heavy
out-commuting:
See vignette("getting_started") for the full figure code
and additional maps of Maryland county job change, earnings tier
composition, and tract-level job accessibility.
Downloaded files are deleted after reading by default. Set
use_cache = TRUE in grab_lodes() or
options(lehdr_use_cache = TRUE) globally to retain files in
the user cache directory
(tools::R_user_dir("lehdr", "cache")). Cache filenames
include the LODES version (e.g.,
lodes8_md_wac_S000_JT00_2019.csv.gz), so switching between
versions will not serve stale data from a different vintage.
Upgrading from lehdr < 1.2.0? Earlier versions
cached files without a version prefix (e.g.,
md_wac_S000_JT00_2019.csv.gz). Those files will never be
matched by the new naming scheme and can be safely deleted. To clear the
entire cache:
cache_dir <- tools::R_user_dir("lehdr", "cache")
list.files(cache_dir) # inspect before deleting
unlink(cache_dir, recursive = TRUE)The LODES dataset is frequently used by transportation and economic development planners, regional economists, disaster managers, and other public servants who need fine-grained understanding of the spatial distribution of employment. Such data underpins regional travel demand models, workforce and industrial policy analysis, and, as a Census product, can be joined to Decennial or American Community Survey data to illuminate the relationship between population and employment geography.
LODES is the only source of detailed geographic information on employment for the entire country, and lehdr is designed to make it more accessible for researchers and analysts working on regional development issues.
If you use lehdr in published work, please cite it:
citation("lehdr")Green, Jamaal, Liming Wang, and Dillon Mahmoudi. 2025. “lehdr: Grab Longitudinal Employer-Household Dynamics (LEHD) Flat Files.” R package version 1.2.0. https://github.com/jamgreen/lehdr/
This package was developed by Jamaal Green, University of Pennsylvania; Dillon Mahmoudi, University of Maryland Baltimore County; and Liming Wang, Portland State University.
This package would not exist in its current format without the inspiration of Bob Rudis’s lodes package.