Get EJScreen results near each site, compiled as a table, with map and plot

This is the main high-level function that does all the work involved in using the EJScreen API outside of the web app to get results for multiple locations compiled in one table.

Usage

ejscreenit(
  x,
  y = NULL,
  radius = 3,
  maxradiusmiles = 10,
  fips = NULL,
  shapefile = NULL,
  namestr = "",
  nosave = TRUE,
  nosee = TRUE,
  save_map = TRUE,
  see_map = TRUE,
  save_plot = TRUE,
  see_plot = TRUE,
  save_table = TRUE,
  see_table = FALSE,
  interactiveprompt = FALSE,
  calculate_ratios = TRUE,
  nicenames = TRUE,
  folder = ".",
  getstatefromplacename = TRUE,
  ...
)

Arguments

x

Point locations may be specified in several ways:

x can be a vector of longitudes (decimal degrees), in which case y also must be provided as latitudes; or
x can be the path/filename to a file in .xlsx or .csv format with lat, lon header names
x can be a data.frame, data.table, or matrix (or list) with lat,lon as column names (or names of list elements)
x can be omitted if one is using RStudio interactively, in which case the user is prompted to select a file from a local drive.

y

latitudes, or ignored if x was a file or table with lat,lon info.

radius

in miles - gets data on all residents within that distance from each point

maxradiusmiles

optional in case you want to use a radius of more than default cap

fips

if used instead of x,y it can specify fips codes of counties, tracts, or blockgroups

shapefile

not implemented

namestr

optional text

nosave

logical, if TRUE, sets as FALSE and overrides save_map, save_plot, save_table. Ignored if FALSE.

nosee

logical, if TRUE, sets as FALSE and overrides see_map, see_plot, see_table. Ignored if FALSE.

save_map

logical, whether to save png image file locally

see_map

logical, whether to display interactive map

save_plot

logical, whether to save png image file locally

see_plot

logical, whether to display plot (boxplots)

save_table

logical, whether to save table of data in a file locally

see_table

logical, whether to display interactive table

interactiveprompt

logical, whether to prompt for upload of file and ask to hit key to continue after map shown, etc. If interactive() is TRUE, this actually defaults to TRUE.

calculate_ratios

whether to add columns with ratio of raw score to the US or State average

nicenames

whether to use long plain english headers in table or R variable names, e.g., "Particulate Matter (PM 2.5 in ug/m3)" not "pm"

folder

full path of directory in which to save files like map, plot, table Default is working directory.

getstatefromplacename

set to FALSE if you need the exact output of API and TRUE if you want to try to extract ST abbrev and statename from the placename field, which is more likely to be correct than the stateAbbr and stateName fields in the API output.

...

passed to ejscreenapi_plus()

Value

Returns a list with map, boxplot, table

map of sites with popups of EJ stats, as returned plot, viewed interactive map and .png
graphic boxplot of some residential population percentages as ratios to average, as returned plot, viewed noninteractive plot and .png
table of results as a returned data.frame, viewed interactive datatable, and .xlsx and .csv Which includes us.ratios and state.ratios via one row per site and one column per indicator as ratios to US and to State average.

It also now drops redundant columns where the same numbers had been returned from API using the normal name and a synonym name.

Details

This function provides EJScreen indicator results near each of a list of sites, all in one function, for those who want to do so in RStudio (for interactive analysis) or via their own software/apps (programmatically) rather than through the web app interface. It is an alternative to EJAM, as explained below.

Based on a set of places, ejscreenit() requests an EJScreen standard report for each place and assembles all those results as a single spreadsheet. The indicators include residential population and environmental indicators as well as Summary Indexes that combine them, and some geospatial information about each site.

ejscreenit() is the basic, high-level tool that enables easy access to the EJScreen API for a list of sites, outside the context of a web app. It accepts lat/lon values flexibly and interactively in the R console, and then uses the helper functions below to return a list of 3 objects:

a table
an interactive map (html widget with popups in R console or saved as html file)
plot of some indicators over the range of sites

The table it provides uses plain-English column headers, such as "Traffic Proximity and Volume (daily traffic count/distance to road)"

EJAM vs EJScreen

To obtain overall summary statistics (and faster results) use ejamit() from the EJAM package instead of ejscreenit(). The two tools, ejamit() and ejscreenit(), are different, and have pros and cons:

The key advantages of EJAM are

ejscreenit / EJScreen API is much, much slower than EJAM
ejscreenit cannot provide an overall summary across sites, while EJAM can

An "overall summary" here means, for example, the overall percent low income among all unique residents near any one or more of the sites. This inability to provide an overall summary aggregating across sites is due to limitations of the EJScreen API – it does not provide all data needed to correctly aggregate across sites (see detailed explanation in the ejscreenapi About document).

Inputs and Outputs

The ejscreenit() function accepts a set of points (locations) and a radius, and then accesses EJScreen (the server via API) to assemble a list of results similar to the EJScreen standard report but for each of many sites.

Points can be specified in several ways:

as a table (columns lat, lon that are the geographic coordinates)
in a spreadsheet file with that info (named, or pointed to interactively in RStudio)

The function returns a list of items: table, map, plot

a table of scores that are like the EJScreen standard buffer report, but with one row per site (input point)
- and as a set of columns in that table, a set of ratios, which are the indicator value nearby a site divided by the indicator value in the US overall (which puts all indicators in common units, facilitating comparisons, offering a summary statistic that is complementary to the percentile but may be more useful in some cases)
a map with interactivity and popups of results at each point
a plot/graphic visualization of the range of sites

Details of helper functions used

This function works by requesting each site report from EPA servers via the EJScreen API using various helper functions. It uses functions including the following:

ejscreenit() is the basic, high-level tool that enables access to the EJScreen API for a list of sites, outside the context of a web app. It accepts lat/lon values flexibly and interactively in the R console, and then uses the helper functions below to return a list of 3 objects: a table, interactive map, and plot. The table it provides uses plain-English column headers, such as "Traffic Proximity and Volume (daily traffic count/distance to road)"
- ejscreenapi_plus() can accept a file of point data, uses ejscreenapi() to get EJScreen stats, and then prepends input table and renames columns as R variables like "traffic.score"
  - ejscreenapi() gets EJ stats for many points as a data.table of many rows.
  - ejscreenapi1() gets EJ stats for 1 point via API, as data.frame of 1 row.
  - ejscreenRESTbroker() gets EJ stats for one point as JSON.

Also used are ejscreenapi_plus(), ejscreenapi(), urls_clusters_and_sort_cols(), fixcolnames(), url_linkify(), popup_from_ejscreen(), calc_ratios_to_avg(), boxplots_ratios()

Examples

if (FALSE) { # \dontrun{
 pts <- testpoints_50[1:3, ] # sample data from package
 mapfast(pts)
 #pts <- system.file("testdata/latlon/testpoints_10.xlsx", package="EJAM") 
 if (interactive)
 
 x <- ejscreenit(pts, 
   save_map = F, save_plot = F, save_table = F, folder = "~", see_table = T)
 
 myradius <- 1 # in miles
 # myradius <- 5000 / meters_per_mile # 5 kilometer radius, approx 3.1 miles
 # Get results from server by using API 
 x <- ejscreenit(
   pts=pts, radius = myradius,
   save_table = FALSE, save_map = FALSE, save_plot = FALSE)
  
 # see format of output results
 names(x) # [1] "table" "map"   "plot"
 
 y = ejscreenapi_plus(pts, radius = myradius)
 all.equal(x$table, y)
 
 # For this table view, remove map and pdf URL columns 
 y <- x$table[ , !grepl("EJScreen", names(x$table))] 
 t(y[1, ])  # see one column of results
 DT::datatable(y)  # see interactive data table view in viewer of RStudio
 
 # View links in RStudio Viewer window rather than shiny app or Excel 
 html_print(HTML(paste(paste(x$table[,"EJScreen Report"], collapse="<br>"),
    "<p></p>", paste(x$table[,"EJScreenMAP"], collapse="<br>") )  ))
 
 # View the boxplots of results
 x$plot
 
 # Save the plot as a file:
 
 # You can save it while running ejscreenit()
 # by including the parameters save_map = T, nosave = F, folder = "."
 # or afterwords like this:
 
 png(filename = file.path(folder,"Boxplot of EJ stats.png"), 
   width = 1200, height = 600)
 x$plot
 dev.off()
 
 # Save the map as a file:
 
 # You can save the map while running ejscreenit()
 # by including the parameters save_plot = T, nosave = F, folder = "."
 # or afterwords save as an interactive HTML webpage, like this:
 
 # htmltools::save_html(x$map, "mapfile.html")
 
 # or make it printable as a static file like this:
 x$map %>% leaflet.extras2::easyprintMap(
   filename = file.path(folder, "map.png"), exportOnly = TRUE)
} # }