Opioid Environment Toolkit for R-Spatial

Preface

This toolkit provides an introduction to GIS and spatial analysis for health applications that will allow researchers, analysts, and practitioners to support their communities with better data analytics and visualization services.

We introduce basic spatial analytic functionalities using open source tools, mainly in R, using applied examples for visualizing, mapping, and understanding the community environment. As a project of the Justice Community Overdose Innovation network, applications covered consider the opioid and overdose risk environment.

The original toolkit version was published in 2020. This version was updated in 2025 and will continue to be expanded through the end of 2029.

What You’ll Need

In addition to this workbook, you’ll need a working instance of R and the data. You can also clone the Github repository that hosts this workbook to get direct access to all the working code, data, and additional items.

Software Basics

We assume a basic knowledge of R and coding languages for most sections. For most of the tutorials in this toolkit, you’ll need to have R and RStudio downloaded and installed on your system. You should be able to install packages, know how to find the address to a folder on your computer system, and have very basic familiarity with R. If you are new to R, we recommend the following intro-level tutorials provided through installation guides. You can also refer to this R for Social Scientists tutorial developed by Data Carpentry for a refresher.

We will work with following libraries, so please be sure to install:

• tidyverse or dplyr
• sf
• tmap
• tidygeocoder
• tidycensus

To install a package in R, input install.packages("dplyr") in your console. You generally only need to install a library once, but you’ll call it every time you work with a new R session.

Setting up your environment

We recommend setting up your working directory as soon as you can! Create a new folder called “data” to put all the data you’ve downloaded for the workshop.

There are differing spatial ecosystems in R. We use the sf ecosystem that is compatible with the tidyverse. If you need to work between these two R spatial ecosystems, see this guide for a translation of sp to sf commands.

Author Team

This toolkit was developed for the JCOIN Network by Marynia Kolak, Moksha Menghaney, Qinyun Lin, and Angela Li at the Healthy Regions & Policies Lab as part of the Methodology and Advanced Analytics Resource Center (MAARC). Susan Paykin and Yilin Liu have contributed substantially as workshop facilitators. The Healthy Regions Lab is based out the University of Illinois at Urbana-Champaign, and serves as the Geospatial Core home of the MAARC, which is situated at the University of Chicago.

JCOIN is part of the of the NIH HEAL Initiative. The Helping to End Addiction Long-term Initiative, or NIH HEAL Initiative, supports a wide range of programs to develop new or improved prevention and treatment strategies for opioid addiction.

Acknowledgements

This research was supported by the National Institutes of Health through the NIH HEAL Initiative under award number 1U2CDA050098-01 and 5UM1DA050098-03. The contents of this publication are solely the responsibility of the authors and do not necessarily represent the official views of the NIH, the NIH HEAL Initiative, or the participating sites.