Reference Guide#

Retrieve Data#

Download and read data from the R-series Geostationary Operational Environmental Satellite data.

Data is downloaded from Amazon Web Services and can be returned as a file list or read as an xarray.Dataset. If the data is not available in a local directory, it is loaded directly into memory.

https://registry.opendata.aws/noaa-goes/

Functions:

`goes_latest`(*[, satellite, product, domain, ...])	Get the latest available GOES data.
`goes_nearesttime`(attime[, within, ...])	Get the GOES data nearest a specified time.
`goes_timerange`([start, end, recent, ...])	Get GOES data for a time range.

goes2go.data.goes_latest(*, satellite='noaa-goes16', product='ABI-L2-MCMIP', domain='C', return_as='xarray', download=True, overwrite=False, save_dir=PosixPath('/p/cwfs/blaylock/data'), bands=None, s3_refresh=True, verbose=True)[source]#

Get the latest available GOES data.

Parameters

satellite ({'goes16', 'goes17', 'goes18'}) –
Specify which GOES satellite. The following alias may also be used:
- 'goes16': 16, ‘G16’, or ‘EAST’
- 'goes17': 17, ‘G17’, or ‘WEST’
- 'goes18': 18, ‘G18’, or ‘WEST’
product ({'ABI', 'GLM', other GOES product}) –
Specify the product name.
- ’ABI’ is an alias for ABI-L2-MCMIP Multichannel Cloud and Moisture Imagery
- ’GLM’ is an alias for GLM-L2-LCFA Geostationary Lightning Mapper
Others may include 'ABI-L1b-Rad', 'ABI-L2-DMW', etc. For more available products, look at this README
domain ({'C', 'F', 'M'}) –
ABI scan region indicator. Only required for ABI products if the given product does not end with C, F, or M.
- C: Contiguous United States (alias ‘CONUS’)
- F: Full Disk (alias ‘FULL’)
- M: Mesoscale (alias ‘MESOSCALE’)
return_as ({'xarray', 'filelist'}) – Return the data as an xarray.Dataset or as a list of files
download (bool) –
- True: Download the data to disk to the location set by save_dir
- False: Just load the data into memory.
save_dir (pathlib.Path or str) – Path to save the data.
overwrite (bool) –
- True: Download the file even if it exists.
- False Do not download the file if it already exists
bands (None, int, or list) – ONLY FOR L1b-Rad products; specify the bands you want
s3_refresh (bool) – Refresh the s3fs.S3FileSystem object when files are listed.

goes2go.data.goes_nearesttime(attime, within=Timedelta('0 days 01:00:00'), *, satellite='noaa-goes16', product='ABI-L2-MCMIP', domain='C', return_as='xarray', download=True, overwrite=False, save_dir=PosixPath('/p/cwfs/blaylock/data'), bands=None, s3_refresh=True, verbose=True)[source]#

Get the GOES data nearest a specified time.

Parameters

attime (datetime) – Time to find the nearest observation for. May also use a pandas-interpretable datetime string.
within (timedelta or pandas-parsable timedelta str) – Timerange tht the nearest observation must be.
satellite ({'goes16', 'goes17', 'goes18'}) –
Specify which GOES satellite. The following alias may also be used:
- 'goes16': 16, ‘G16’, or ‘EAST’
- 'goes17': 17, ‘G17’, or ‘WEST’
- 'goes18': 18, ‘G18’, or ‘WEST’
product ({'ABI', 'GLM', other GOES product}) –
Specify the product name.
- ’ABI’ is an alias for ABI-L2-MCMIP Multichannel Cloud and Moisture Imagery
- ’GLM’ is an alias for GLM-L2-LCFA Geostationary Lightning Mapper
Others may include 'ABI-L1b-Rad', 'ABI-L2-DMW', etc. For more available products, look at this README
domain ({'C', 'F', 'M'}) –
ABI scan region indicator. Only required for ABI products if the given product does not end with C, F, or M.
- C: Contiguous United States (alias ‘CONUS’)
- F: Full Disk (alias ‘FULL’)
- M: Mesoscale (alias ‘MESOSCALE’)
return_as ({'xarray', 'filelist'}) – Return the data as an xarray.Dataset or as a list of files
download (bool) –
- True: Download the data to disk to the location set by save_dir
- False: Just load the data into memory.
save_dir (pathlib.Path or str) – Path to save the data.
overwrite (bool) –
- True: Download the file even if it exists.
- False: Do not download the file if it already exists
bands (None, int, or list) – ONLY FOR L1b-Rad products; specify the bands you want
s3_refresh (bool) – Refresh the s3fs.S3FileSystem object when files are listed.

goes2go.data.goes_timerange(start=None, end=None, recent=None, *, satellite='noaa-goes16', product='ABI-L2-MCMIP', domain='C', return_as='filelist', download=True, overwrite=False, save_dir=PosixPath('/p/cwfs/blaylock/data'), max_cpus=1, bands=None, s3_refresh=False, verbose=True)[source]#

Get GOES data for a time range.

Parameters

start (datetime) – Required if recent is None.
end (datetime) – Required if recent is None.
recent (timedelta or pandas-parsable timedelta str) – Required if start and end are None. If timedelta(hours=1), will get the most recent files for the past hour.
satellite ({'goes16', 'goes17', 'goes18'}) –
Specify which GOES satellite. The following alias may also be used:
- 'goes16': 16, ‘G16’, or ‘EAST’
- 'goes17': 17, ‘G17’, or ‘WEST’
- 'goes18': 18, ‘G18’, or ‘WEST’
product ({'ABI', 'GLM', other GOES product}) –
Specify the product name.
- ’ABI’ is an alias for ABI-L2-MCMIP Multichannel Cloud and Moisture Imagery
- ’GLM’ is an alias for GLM-L2-LCFA Geostationary Lightning Mapper
Others may include 'ABI-L1b-Rad', 'ABI-L2-DMW', etc. For more available products, look at this README
domain ({'C', 'F', 'M'}) –
ABI scan region indicator. Only required for ABI products if the given product does not end with C, F, or M.
- C: Contiguous United States (alias ‘CONUS’)
- F: Full Disk (alias ‘FULL’)
- M: Mesoscale (alias ‘MESOSCALE’)
return_as ({'xarray', 'filelist'}) – Return the data as an xarray.Dataset or as a list of files
download (bool) –
- True: Download the data to disk to the location set by save_dir
- False: Just load the data into memory.
save_dir (pathlib.Path or str) – Path to save the data.
overwrite (bool) –
- True: Download the file even if it exists.
- False Do not download the file if it already exists
max_cpus (int) –
bands (None, int, or list) – ONLY FOR L1b-Rad products; specify the bands you want
s3_refresh (bool) – Refresh the s3fs.S3FileSystem object when files are listed.

GOES Class#

Custom Accessors#

Field of View#

Create polygon objects of the GOES field of view for the ABI and GLM instrument. Access with the FOV accessor.

# G is an xarray.Dataset of GOES data.
G.FOV.domain  # only ABI datasets
G.FOV.full_disk  # ABI or GLM datasets

G.FOV.crs  # Cartopy coordinate reference system for the satellite.

class goes2go.accessors.fieldOfViewAccessor(xarray_obj)[source]#

Create a field-of-view polygon for the GOES data.

Based on information from the GOES-R Series Data Book.

GLM lense field of view is 16 degree, or +/- 8 degrees (see page 225) ABI full-disk field of view if 17.4 degrees (see page 48)

Methods:

`__init__`(xarray_obj)
`get_latlon`()	Get lat/lon of all points

Attributes:

`crs`	Cartopy coordinate reference system for the Satellite.
`domain`	Field of view for the ABI domain (CONUS or MesoScale).
`full_disk`	Full-disk field of view for the ABI or GLM instruments.
`imshow_kwargs`	Key word arguments for plt.imshow for generating images.
`x`	x sweep in crs units (m); x * sat_height
`y`	y sweep in crs units (m); x * sat_height

__init__(xarray_obj)[source]#

property crs#: Cartopy coordinate reference system for the Satellite.

property domain#

Field of view for the ABI domain (CONUS or MesoScale).

Return type: shapely.Polygon

property full_disk#

Full-disk field of view for the ABI or GLM instruments.

Return type: shapely.Polygon

get_latlon()[source]#: Get lat/lon of all points

property imshow_kwargs#

Key word arguments for plt.imshow for generating images.

Projection axis must be the coordinate reference system.

property x#: x sweep in crs units (m); x * sat_height

property y#: y sweep in crs units (m); x * sat_height

RGB Recipes#

RGB recipes for ABI multichannel cloud moisture imagery files. Access with the rgb accessor. The RGB method will return a DataArray of the RGB values and also attaches the RGB DataArray to the existing GOES Dataset.

# G is an xarray.Dataset of GOES data.
G.rgb.TrueColor()
G.rgb.NaturalColor()
... etc.

# Also can get the Cartopy coordinate reference system
G.rgb.crs

To make a simple RGB plot on a Cartopy axes, do the following:

from goes2go.data import goes_latest
import matplotlib.pyplot as plt
import cartopy.crs as ccrs

# Download a GOES ABI dataset
G = goes_latest(product='ABI')

# Make figure on Cartopy axes
ax = plt.subplot(projection=G.rgb.crs )
ax.imshow(G.rgb.TrueColor(), **G.rgb.imshow_kwargs)
ax.coastlines()

class goes2go.accessors.rgbAccessor(xarray_obj)[source]#

Methods:

`AirMass`()	Air Mass RGB: (See Quick Guide for reference)
`Ash`()	Ash RGB: (See Quick Guide for reference)
`DayCloudConvection`()	Day Cloud Convection RGB: (See Quick Guide for reference)
`DayCloudPhase`()	Day Cloud Phase Distinction RGB: (See Quick Guide for reference)
`DayConvection`()	Day Convection RGB: (See Quick Guide for reference)
`DayLandCloud`()	Day Land Cloud Fire RGB: (See Quick Guide for reference)
`DayLandCloudFire`()	Day Land Cloud Fire RGB: (See Quick Guide for reference)
`DaySnowFog`()	Day Snow-Fog RGB: (See Quick Guide for reference)
`DifferentialWaterVapor`()	Differential Water Vapor RGB: (See Quick Guide for reference)
`Dust`()	SulfurDioxide RGB: (See Quick Guide for reference)
`FireTemperature`()	Fire Temperature RGB: (See Quick Guide for reference)
`NaturalColor`([gamma, pseudoGreen, night_IR])	Natural Color RGB based on CIMSS method.
`NightFogDifference`()	Night Fog Difference RGB (greyscale): (See Quick Guide for reference)
`NighttimeMicrophysics`()	Nighttime Microphysics RGB: (See Quick Guide for reference)
`NormalizedBurnRatio`()	Normalized Burn Ratio
`RocketPlume`([night])	Rocket Plume RGB
`SplitWindowDifference`()	Split Window Difference RGB (greyscale): (See Quick Guide for reference)
`SulfurDioxide`()	SulfurDioxide RGB: (See Quick Guide for reference)
`TrueColor`([gamma, pseudoGreen, night_IR])	True Color RGB: (See Quick Guide for reference)
`WaterVapor`()	Simple Water Vapor RGB: (See Quick Guide for reference)
`__init__`(xarray_obj)
`get_latlon`()	Get lat/lon of all points

Attributes:

`crs`	Cartopy coordinate reference system
`imshow_kwargs`	Key word arguments for plt.imshow for generating images.
`x`	x sweep in crs units (m); x * sat_height
`y`	y sweep in crs units (m); x * sat_height

AirMass()[source]#: Air Mass RGB: (See Quick Guide for reference)

Ash()[source]#: Ash RGB: (See Quick Guide for reference)

DayCloudConvection()[source]#: Day Cloud Convection RGB: (See Quick Guide for reference)

DayCloudPhase()[source]#: Day Cloud Phase Distinction RGB: (See Quick Guide for reference)

DayConvection()[source]#: Day Convection RGB: (See Quick Guide for reference)

DayLandCloud()[source]#: Day Land Cloud Fire RGB: (See Quick Guide for reference)

DayLandCloudFire()[source]#: Day Land Cloud Fire RGB: (See Quick Guide for reference)

DaySnowFog()[source]#: Day Snow-Fog RGB: (See Quick Guide for reference)

DifferentialWaterVapor()[source]#: Differential Water Vapor RGB: (See Quick Guide for reference)

Dust()[source]#: SulfurDioxide RGB: (See Quick Guide for reference)

FireTemperature()[source]#: Fire Temperature RGB: (See Quick Guide for reference)

NaturalColor(gamma=0.8, pseudoGreen=True, night_IR=False)[source]#

Natural Color RGB based on CIMSS method. Thanks Rick Kohrs! (See Quick Guide for reference)

Check out Rick Kohrs merged GOES images.

This NaturalColor RGB is very similar to the TrueColor RGB but uses slightly different contrast stretches and ranges.

For more details on combing RGB and making the psedo green channel, refer to Bah et al. 2018.

../_images/gamma_demo_NaturalColor-PsuedoGreen.png

../_images/gamma_demo_NaturalColor-VeggieGreen.png

Parameters

gamma (float) – Darken or lighten an image with gamma correction. Values > 1 will lighten an image. Values < 1 will darken an image.
night_IR (bool) – If True, use Clean IR (channel 13) as maximum RGB value overlay so that cold clouds show up at night. (Be aware that some daytime clouds might appear brighter).

NightFogDifference()[source]#: Night Fog Difference RGB (greyscale): (See Quick Guide for reference)

NighttimeMicrophysics()[source]#: Nighttime Microphysics RGB: (See Quick Guide for reference)

NormalizedBurnRatio()[source]#

Normalized Burn Ratio

THIS FUNCTION IS NOT FULLY DEVELOPED. Need more info.

NBR= (0.86 µm – 2.2 µm)/(0.86 um + 2.2 um)

https://ntrs.nasa.gov/citations/20190030825

RocketPlume(night=False)[source]#

Rocket Plume RGB

For identifying rocket launches.

See this blog and the Quick Guide for reference

Parameters: night (bool) – If the area is in night, turn this on to use a different channel than the daytime application.

SplitWindowDifference()[source]#: Split Window Difference RGB (greyscale): (See Quick Guide for reference)

SulfurDioxide()[source]#: SulfurDioxide RGB: (See Quick Guide for reference)

TrueColor(gamma=2.2, pseudoGreen=True, night_IR=True)[source]#

True Color RGB: (See Quick Guide for reference)

This is similar to the NaturalColor RGB, but uses a different gamma correction and does not apply contrast stretching. I think these images look a little “washed out” when compared to the NaturalColor RGB. So, I would recommend using the NaturalColor RGB.

For more details on combing RGB and making the psedo green channel, refer to Bah et al. 2018.

Parameters

gamma (float) –
Darken or lighten an image with gamma correction. Values > 1 will lighten an image. Values < 1 will darken an image.
pseudoGreen (bool) – True: returns the calculated “True” green color False: returns the “veggie” channel
night_IR (bool) – If True, use Clean IR (channel 13) as maximum RGB value overlay so that cold clouds show up at night. (Be aware that some daytime clouds might appear brighter).

WaterVapor()[source]#: Simple Water Vapor RGB: (See Quick Guide for reference)

__init__(xarray_obj)[source]#

property crs#: Cartopy coordinate reference system

get_latlon()[source]#: Get lat/lon of all points

property imshow_kwargs#

Key word arguments for plt.imshow for generating images.

Projection axis must be the coordinate reference system.

property x#: x sweep in crs units (m); x * sat_height

property y#: y sweep in crs units (m); x * sat_height