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('/home/docs/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('/home/docs/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('/home/docs/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#

Classes:

GOES([satellite, product, domain, bands, ...])

The GOES satellite class.
class goes2go.NEW.GOES(satellite='noaa-goes16', product='ABI-L2-MCMIP', domain='C', bands=None, channel=None)[source]#

The GOES satellite class.

Methods:

__init__([satellite, product, domain, ...])

Initialize a GOES object for a desired satellite and product.

df(start, end[, refresh])

Get list of requested GOES files as pandas.DataFrame.

latest(**kwargs)

Get the latest available GOES data.

nearesttime(attime[, within])

Get the GOES data nearest a specified time.

timerange([start, end, recent])

Get GOES data for a time range.
__init__(satellite='noaa-goes16', product='ABI-L2-MCMIP', domain='C', bands=None, channel=None)[source]#

Initialize a GOES object for a desired satellite and product.

Parameters:

  • satellite ({16, 17, 18}) – The satellite number. May also use the following aliases {‘G16’, “G17”, “EAST”, “WEST”}

  • product (str) – The product to acquire. A full list of products is here blaylockbk/goes2go - GLM = alias for geostationary lighting mapper - ABI = alias for ABI multi-channel cloud moisture imagery

  • domain ({None, 'F', 'C', "M", "M1", "M2"}) – Only needed for ABI products. - F = Full Disk - C = CONUS - M = Mesoscale sector (both) - M1 = Mesoscale sector 1 - M2 = Mesoscale sector 2

  • bands (None, int, or list) – Specify the ABI channels to retrieve. Only used if the product requested has unique bands. For example, bands=2 for channel 2 or bands=[1,2,3] for channels 1, 2 and 3.

  • channel (None, int, or list) –

    Alias for “bands” argument. If channel is not None, then “bands” is not use.

    Note: I don’t like the name of “bands”, but the NetCDF file uses the term “band” instead of “channel” in reference to the ABI products, so I’ll stick with “band” for now.

df(start, end, refresh=True)[source]#

Get list of requested GOES files as pandas.DataFrame.

Parameters:

  • start (datetime) –

  • end (datetime) –

  • refresh (bool) – Refresh the s3fs.S3FileSystem object when files are listed. Default True will refresh and not use a cached list.

latest(**kwargs)[source]#

Get the latest available GOES data.

nearesttime(attime, within=Timedelta('0 days 01:00:00'), **kwargs)[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.

timerange(start=None, end=None, recent=None, **kwargs)[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.

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.

# Get latest multi-channel cloud moisture imagery product.
# "G" is an xarray.Dataset of GOES data.
G = GOES(satellite=16, product="ABI-L2-MCMIPC").latest()

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

The x sweep in crs units (m); x * sat_height.

y

The 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).

../_images/ABI_field-of-view_16dom.png ../_images/ABI_field-of-view_16M1M2.png ../_images/ABI_field-of-view_17dom.png
Return type:

shapely.Polygon

property full_disk#

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

../_images/ABI_field-of-view.png ../_images/GLM_field-of-view.png
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#

The x sweep in crs units (m); x * sat_height.

property y#

The 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.

from goes2go import GOES
import matplotlib.pyplot as plt

# Get latest multi-channel cloud moisture imagery product.
# "G" is an xarray.Dataset of multi-channel GOES data (e.g., product="ABI-L2-MCMIPC").
G = GOES(satellite=16, product="ABI-L2-MCMIPC").latest()

# Create RGB an plot
tc = G.rgb.TrueColor()
plt.imshow(tc)

nc = G.rgb.NaturalColor()
plt.imshow(nc)

# etc.

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

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

from goes2go import GOES
import matplotlib.pyplot as plt
import cartopy.crs as ccrs

# Download and read a GOES ABI MCMIPC dataset
G = GOES(satellite=16, product="ABI-L2-MCMIPC").latest()

# Make figure on Cartopy axes
ax = plt.subplot(projection=G.rgb.crs )
ax.imshow(G.rgb.TrueColor(), **G.rgb.imshow_kwargs)
ax.coastlines()
../_images/demo_rgb_accessor.png
class goes2go.accessors.rgbAccessor(xarray_obj)[source]#

An accessor to create RGB composites.

Methods:

AirMass()

Create the Air Mass RGB.

AirMassTropical()

Create the Air Mass Tropical RGB.

AirMassTropicalPac()

Create the Air Mass Tropical Pac RGB.

Ash()

Create the Ash RGB.

DayCloudConvection()

Create the Day Cloud Convection RGB.

DayCloudPhase()

Create the Day Cloud Phase Distinction RGB.

DayConvection()

Create the Day Convection RGB.

DayLandCloud()

Create the Day Land Cloud Fire RGB.

DayLandCloudFire()

Create the Day Land Cloud Fire RGB.

DaySnowFog()

Day Snow-Fog RGB.

DifferentialWaterVapor()

Differential Water Vapor RGB.

Dust()

Create the SulfurDioxide RGB.

FireTemperature()

Create the Fire Temperature RGB.

NaturalColor([gamma, pseudoGreen, night_IR])

Create a Natural Color RGB based on CIMSS method.

NightFogDifference()

Night Fog Difference RGB (greyscale).

NighttimeMicrophysics()

Create the Nighttime Microphysics RGB.

NormalizedBurnRatio()

Create the Normalized Burn Ratio.

RocketPlume([night])

Create the Rocket Plume RGB.

SeaSpray(**kwargs)

Create the Sea Spray RGB.

SplitWindowDifference()

Split Window Difference RGB (greyscale).

SulfurDioxide()

Create the SulfurDioxide RGB.

TrueColor([gamma, pseudoGreen, night_IR])

Create a True Color RGB.

WaterVapor()

Create the Simple Water Vapor RGB.

__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

The x sweep in crs units (m); x * sat_height.

y

The y sweep in crs units (m); x * sat_height.
AirMass()[source]#

Create the Air Mass RGB.

(See Quick Guide for reference)

../_images/AirMass.png
AirMassTropical()[source]#

Create the Air Mass Tropical RGB.

(See Quick Guide for reference)

../_images/AirMassTropical.png
AirMassTropicalPac()[source]#

Create the Air Mass Tropical Pac RGB.

(See Blog Write-up for reference)

../_images/AirMassTropicalPac.png
Ash()[source]#

Create the Ash RGB.

(See Quick Guide for reference)

../_images/Ash.png
DayCloudConvection()[source]#

Create the Day Cloud Convection RGB.

(See Quick Guide for reference)

../_images/DayCloudConvection.png
DayCloudPhase()[source]#

Create the Day Cloud Phase Distinction RGB.

(See Quick Guide for reference)

../_images/DayCloudPhase.png
DayConvection()[source]#

Create the Day Convection RGB.

(See Quick Guide for reference)

../_images/DayConvection.png
DayLandCloud()[source]#

Create the Day Land Cloud Fire RGB.

(See Quick Guide for reference)

../_images/DayLandCloud.png
DayLandCloudFire()[source]#

Create the Day Land Cloud Fire RGB.

(See Quick Guide for reference)

../_images/DayLandCloudFire.png
DaySnowFog()[source]#

Day Snow-Fog RGB.

(See Quick Guide for reference)

../_images/DaySnowFog.png
DifferentialWaterVapor()[source]#

Differential Water Vapor RGB.

(See Quick Guide for reference)

../_images/DifferentialWaterVapor.png
Dust()[source]#

Create the SulfurDioxide RGB.

(See Quick Guide for reference)

../_images/Dust.png
FireTemperature()[source]#

Create the Fire Temperature RGB.

(See Quick Guide for reference)

../_images/FireTemperature.png
NaturalColor(gamma=0.8, pseudoGreen=True, night_IR=False)[source]#

Create a 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/NaturalColor.png ../_images/gamma_demo_NaturalColor-PsuedoGreen.png ../_images/gamma_demo_NaturalColor-VeggieGreen.png ../_images/Color-IR_demo.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)

../_images/NightFogDifference.png
NighttimeMicrophysics()[source]#

Create the Nighttime Microphysics RGB.

(See Quick Guide for reference)

../_images/NighttimeMicrophysics.png
NormalizedBurnRatio()[source]#

Create the 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]#

Create the Rocket Plume RGB.

For identifying rocket launches.

See this blog and the Quick Guide for reference

../_images/RocketPlume.png
Parameters:

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

SeaSpray(**kwargs)[source]#

Create the Sea Spray RGB.

(See Quick Guide for reference)

../_images/SeaSpray.png
SplitWindowDifference()[source]#

Split Window Difference RGB (greyscale).

(See Quick Guide for reference)

../_images/SplitWindowDifference.png
SulfurDioxide()[source]#

Create the SulfurDioxide RGB.

(See Quick Guide for reference)

../_images/SulfurDioxide.png
TrueColor(gamma=2.2, pseudoGreen=True, night_IR=True)[source]#

Create a 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.

../_images/TrueColor.png ../_images/gamma_demo_TrueColor.png ../_images/Color-IR_demo.png
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]#

Create the Simple Water Vapor RGB.

(See Quick Guide for reference)

../_images/WaterVapor.png
__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#

The x sweep in crs units (m); x * sat_height.

property y#

The y sweep in crs units (m); x * sat_height.