In MazamaScience/MazamaSatelliteUtils: Utilities for Working with Model and Satellite Data as Rasters

knitr::opts_chunk$set(echo = TRUE)

This article will walk through the steps of visualizing GOES AOD scans using the high-level functions provided by the MazamaSatelliteUtils package.

Point and Raster Plots

Each GOES scan records the AOD value for millions of fixed locations across the continental US. MazamaSatelliteUtils allows you to visualize this data either with points or rasters--each having their upsides and downsides when it comes to plotting.

Point Plots

Pros:

• Points show the raw (unaggregated) AOD values at the exact location where they were sampled. Therefore, points give the most direct information at the highest possible spatial resolution.
• Render very fast in both Mercator-projected and Cartesian coordinate systems.

Cons:

• The arrangement of sample locations means points will likely overlap or have gaps between them when plotted.
• Point size is not determined by axis units. Therefore, the user will have to manually determine the best point size for each plot depending on the plot dimensions and the geographic region it covers.

Raster Plots

Pros:

• Cells aggregate multiple points in a small region and therefore help fill 'gaps' of NA AOD values.
• Cells will never overlap of have gaps between them and their size is defined using axis units. Therefore, the user does not have to adjust anything depending on the size of the plot or the region it covers.

Cons:

• Cells will not be as precise (both in raw AOD value and location) as points, unless the grid resolution is very high.
• High-resolution rasters render slowly in Mercator-projected coordinate systems.

How to Plot a Scan

1. Getting Scan Files

First things first: since each scan is saved as a netCDF file on a remote server, we need to download the files for the scans we want to see! We can do this with goesaodc_downloadScanFiles(), which downloads the scan file taken closest to the given datetime by the named satellite. If an endtime is provided as well, then all that satellite's scans taken at or after datetime and up to (but not including) endtime will be downloaded. Scan files will be stored in the directory specified by setSatelliteDataDir().

Downloading a single scan file:

library(MazamaSatelliteUtils)
setSatelliteDataDir("~/Data/Satellite")

scanFile <- goesaodc_downloadScanFiles(
  satID = "G17",
  datetime = "2020-09-08 12:30",
  timezone = "America/Los_Angeles"
)

scanFile

scanFile %>%
  goesaodc_convertFilenameToDatetime() %>%
  MazamaCoreUtils::parseDatetime(timezone = "America/Los_Angeles")

Downloading a series of scan files:

scanFiles <- goesaodc_downloadScanFiles(
  satID = "G17",
  datetime = "2020-09-08 12:00",
  endtime = "2020-09-08 13:00",
  timezone = "America/Los_Angeles"
)

scanFiles

scanFiles %>%
  goesaodc_convertFilenameToDatetime() %>%
  MazamaCoreUtils::parseDatetime(timezone = "America/Los_Angeles")

You can also see what scan files are available either locally or remotely with goesaodc_listScanFiles():

goesaodc_listScanFiles(
  satID = "G17",
  datetime = "2020-09-08 12:30",
  timezone = "America/Los_Angeles",
  useRemote = FALSE
)

2. Creating Points and Rasters

Now that we can identify and download the scan files we're interested in, the next step is to read them into R data structures. Here you have the choice of turning a scan into a SpatialPointsDataFrame (SPDF) with goesaodc_createScanSpdf() or a raster with goesaodc_createScanRaster(). These functions allow you to filter AOD readings using bbox and dqfLevel parameters so that only readings within bbox will be kept and all readings with a DQF above dqfLevel will have their AOD values set to NA.

An important point to note: A raster is created by first generating a SpatialPointsDataFrame (which includes the filtering process) and then rasterizing the resulting points. A raster cell's AOD value is determined by summarizing the values of all the points that fall in it with the fun function (defaults to mean).

One more thing! Creating points and rasters requires that each scan reading is assigned to the proper location in its GOES grid. Therefore, before running either goesaodc_createScan...() function you must first install the GOES grid files with goesaodc_installGoesGrids().

goesaodc_installGoesGrids()

Creating an SPDF:

bboxOregon <- c(-125, -116, 42, 46.5)

scanSpdf <- goesaodc_createScanSpdf(
  filename = scanFile,
  bbox = bboxOregon,
  dqfLevel = 2
)
scanSpdf

Creating a raster:

scanRaster <- goesaodc_createScanRaster(
  filename = scanFile,
  bbox = bboxOregon,
  dqfLevel = 2,
  cellSize = 0.05
)
scanRaster

If you pass in a vector of filenames to filename, then goesaodc_createScanSpdf() will return a list of SPDFs and goesaodc_createScanRaster() will return a RasterBrick.

scanSpdfList <- goesaodc_createScanSpdf(
  filename = scanFiles,
  bbox = bboxOregon
)

scanRasterBrick <- goesaodc_createScanRaster(
  filename = scanFiles,
  bbox = bboxOregon,
  cellSize = 0.05
)

An SPDF list or a RasterBrick can be used to aggregate AOD readings from multiple scans into a single SPDF or RasterLayer. For instance, goesaodc_calcAverageScan...() will find the average value for each point/cell across all the scans in the data structure:

averageScanSpdf <- goesaodc_calcAverageScanSpdf(
  spdfList = scanSpdfList,
  na.rm = TRUE
)

averageScanRaster <- goesaodc_calcAverageScanRaster(
  rasterBrick = scanRasterBrick,
  na.rm = TRUE
)

The goesaodc_calcTrendScan...() functions calculate the "trend" for each point/cell across all the given scans. A trend value for a point/cell is calculated by subtracting it's average value in the second half of the scan series by it's average value in the first half.

trendScanSpdf <- goesaodc_calcTrendScanSpdf(
  spdfList = scanSpdfList,
  na.rm = TRUE
)

trendScanRaster <- goesaodc_calcTrendScanRaster(
  rasterBrick = scanRasterBrick,
  na.rm = TRUE
)

Note: Rasters calculate their averages and trends using their cell values--not the raw AOD values of the points they were rasterized from.

3. Plotting

At last, we can draw SPDFs/rasters with goesaodc_plotScanSpdf() or goesaodc_plotScanRaster(). These require you to pass in a single SPDF or RasterLayer respectively. Point and cell colors have a gradient color scale by default, but you can set a discrete palette by passing in an RColorBrewer paletteName and a vector of paletteBreaks values. NA AOD values are drawn in gray.

Plotting scan points:

# Load state polygons
library(MazamaSpatialUtils)
setSpatialDataDir("~/Data/Spatial")
loadSpatialData("NaturalEarthAdm1")

goesaodc_plotScanSpdf(
  spdf = scanSpdf,
  bbox = bboxOregon,
  pointAlpha = 0.5,
  includeMap = TRUE,
  zoom = 7,
  stateCodes = "OR"
)

Plotting a scan raster:

goesaodc_plotScanRaster(
  raster = scanRaster,
  bbox = bboxOregon,
  paletteName = "Blues",
  paletteBreaks = c(-Inf, 0, 1, 2, 3, 4, 5, Inf),
  stateCodes = "OR"
)

Since we have already seen how to aggregate multiple scans into a single SPDF or RasterLayer, we can also draw average or trend scans:

goesaodc_plotScanSpdf(
  spdf = averageScanSpdf,
  bbox = bboxOregon,
  stateCodes = "OR"
)

goesaodc_plotScanSpdf(
  spdf = trendScanSpdf,
  bbox = bboxOregon,
  stateCodes = "OR",
)

Animations

goesaodc_plotScanSpdf() and goesaodc_plotScanRaster() allow you to plot static images of GOES AOD data. You can create animated videos of AOD as well using the goesaodc_animateScanSpdfs_exec.R and goesaodc_animateScanRasters_exec.R executable scripts. These scripts take in the same parameters as their plot counterparts (except datetime is now starttime), but they require several additional arguments:

• satelliteDataDir: Directory where satellite data is downloaded to and read from.
• spatialDataDir: Directory where spatial data is downloaded to and read from.
• outputDir: Directory where the video file should be saved to.
• logDir: Directory where the output log files should be saved to.
• frameRate: Framerate of the video in fps.
• verbose: Logical flag determining whether to print out progress messages in the console.
• version: Logical flag determining whether to print out the current version of the executable script.

Another thing to note: Since animations are made up of individual plots, it's essential that they all share a consistent color legend both so that the color scale bounds don't change between frames and that the legend should be drawn even if all the AOD values for a frame are NA. This is achieved by requiring the user to set the legendLimits parameter.

Here's an example of animating points:

./goesaodc_animateScanSpdfs_exec.R \
  --satID="G17" \
  --starttime="2020-09-08 09:00" \
  --endtime="2020-09-08 10:00" \
  --timezone="America/Los_Angeles" \
  --bbox="-125, -116, 42, 47" \
  --dqfLevel=3 \
  --pointSize=0.3 \
  --pointShape=15 \
  --pointAlpha=0.6 \
  --paletteName="YlOrRd" \
  --legendLimits="-0.5, 5.5" \
  --includeMap=TRUE \
  --zoom=7 \
  --stateCodes="OR" \
  --satelliteDataDir="~/Data/Satellite" \
  --spatialDataDir="~/Data/Spatial" \
  --frameRate=6 \
  --outputDir="~/Downloads" \
  --logDir="~/Downloads" \
  --verbose=TRUE

And another for animating rasters (only difference is passing in cellSize):

./goesaodc_animateScanRasters_exec.R \
  --satID="G17" \
  --starttime="2020-09-08 09:00" \
  --endtime="2020-09-08 10:00" \
  --timezone="America/Los_Angeles" \
  --bbox="-125, -116, 42, 47" \
  --dqfLevel=3 \
  --cellSize=0.05 \
  --rasterAlpha=0.6 \
  --paletteName="YlOrRd" \
  --legendLimits="-0.5, 5.5" \
  --includeMap=TRUE \
  --zoom=7 \
  --stateCodes="OR" \
  --satelliteDataDir="~/Data/Satellite" \
  --spatialDataDir="~/Data/Spatial" \
  --frameRate=6 \
  --outputDir="~/Downloads" \
  --logDir="~/Downloads" \
  --verbose=TRUE

MazamaScience/MazamaSatelliteUtils documentation built on Dec. 17, 2021, 3:20 a.m.