pycontrails.datalib.goes#

Support for GOES access and analysis.

Resources#

Module Attributes

DEFAULT_CHANNELS

Default channels to use if none are specified.

GOES_SCAN_MODE_CHANGE

The time at which the GOES scan mode changed from mode 3 to mode 6.

Functions

extract_goes_visualization(da[, ...])

Extract artifacts for visualizing GOES data with the given color scheme.

gcs_goes_path(time, region[, channels, ...])

Return GCS paths to GOES data at the given time for the given region and channels.

to_ash(da[, convention])

Compute 3d RGB array for the ASH color scheme.

to_true_color(da[, gamma])

Compute 3d RGB array for the true color scheme.

Classes

GOES([region, channels, cachestore, goes_bucket])

Support for GOES-16 data handling.

GOESRegion(value[, names, module, qualname, ...])

GOES Region of interest.
pycontrails.datalib.goes.DEFAULT_CHANNELS = ('C11', 'C14', 'C15')#

Default channels to use if none are specified. These are the channels required by the MIT ash color scheme.

class pycontrails.datalib.goes.GOES(region=GOESRegion.F, channels=None, cachestore=<object object>, goes_bucket='gcp-public-data-goes-16')#

Bases: object

Support for GOES-16 data handling.

Parameters:

  • region (GOESRegion | str = {"F", "C", "M1", "M2"}) – GOES Region of interest. Uses the following conventions.

    • F: Full Disk

    • C: CONUS

    • M1: Mesoscale 1

    • M2: Mesoscale 2

  • channels (str | set[str] | None) – Set of channels or bands for CMIP data. The 16 possible channels are represented by the strings “C01” to “C16”. For the MIT ash color scheme, set channels=("C11", "C14", "C15"). For the true color scheme, set channels=("C01", "C02", "C03"). By default, the channels required by the MIT ash color scheme are used. The channels must have a common horizontal resolution. The resolutions are:

    • C01: 1.0 km

    • C02: 0.5 km (treated as 1.0 km)

    • C03: 1.0 km

    • C04: 2.0 km

    • C05: 1.0 km

    • C06 - C16: 2.0 km

  • cachestore (cache.CacheStore | None) – Cache store for GOES data. If None, data is downloaded directly into memory. By default, a cache.DiskCacheStore is used.

  • goes_bucket (str = "gcp-public-data-goes-16") – GCP bucket for GOES data. AWS access is not supported.

See also

GOESRegion, gcs_goes_path

Examples

>>> goes = GOES(region="M1", channels=("C11", "C14"))
>>> da = goes.get("2021-04-03 02:10:00")
>>> da.shape
(2, 500, 500)

>>> da.dims
('band_id', 'y', 'x')

>>> da.band_id.values
array([11, 14], dtype=int32)

>>> # Print out a sample of the data
>>> da.sel(band_id=11).isel(x=slice(0, 50, 10), y=slice(0, 50, 10)).values
array([[266.8644 , 265.50812, 271.5592 , 271.45486, 272.75897],
       [250.53697, 273.28064, 273.80225, 270.77673, 274.8977 ],
       [272.8633 , 272.65466, 271.5592 , 274.01093, 273.12415],
       [274.16742, 274.11523, 276.5148 , 273.85443, 270.51593],
       [274.84555, 275.15854, 272.60248, 270.67242, 272.23734]],
      dtype=float32)

>>> # The data has been cached locally
>>> assert goes.cachestore.listdir()

>>> # Download GOES data directly into memory by setting cachestore=None
>>> goes = GOES(region="M2", channels=("C11", "C12", "C13"), cachestore=None)
>>> da = goes.get("2021-04-03 02:10:00")

>>> da.shape
(3, 500, 500)

>>> da.dims
('band_id', 'y', 'x')

>>> da.band_id.values
array([11, 12, 13], dtype=int32)

>>> da.attrs["long_name"]
'ABI L2+ Cloud and Moisture Imagery brightness temperature'

>>> da.sel(band_id=11).values
array([[251.31944, 249.59802, 249.65018, ..., 270.30725, 270.51593,
        269.83777],
       [250.53697, 249.0242 , 249.12854, ..., 270.15076, 270.30725,
        269.73346],
       [249.1807 , 249.33719, 251.99757, ..., 270.15076, 270.20294,
        268.7945 ],
       ...,
       [277.24512, 277.29727, 277.45377, ..., 274.42822, 274.11523,
        273.7501 ],
       [277.24512, 277.45377, 278.18408, ..., 274.6369 , 274.01093,
        274.06308],
       [276.8278 , 277.14078, 277.7146 , ..., 274.6369 , 273.9066 ,
        274.16742]], dtype=float32)
gcs_goes_path(time, channels=None)#

Return GCS paths to GOES data at given time.

Presently only supported for GOES data whose scan time minute coincides with the minute of the time parameter.

Parameters:

  • time (datetime.datetime) – Time of GOES data.

  • channels (set[str] | None) – Set of channels or bands for CMIP data. If None, the channels attribute is used.

Returns:

list[str] – List of GCS paths to GOES data.

get(time)#

Return GOES data at given time.

Parameters:

time (datetime.datetime | str) – Time of GOES data. This should be a timezone-naive datetime object or an ISO 8601 formatted string.

Returns:

xarray.DataArray – DataArray of GOES data with coordinates:

  • band_id: Channel or band ID

  • x: GOES x-coordinate

  • y: GOES y-coordinate

class pycontrails.datalib.goes.GOESRegion(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

GOES Region of interest.

Uses the following conventions.

  • F: Full Disk

  • C: CONUS

  • M1: Mesoscale 1

  • M2: Mesoscale 2

C = 2#
F = 1#
M1 = 3#
M2 = 4#
pycontrails.datalib.goes.GOES_SCAN_MODE_CHANGE = datetime.datetime(2019, 4, 2, 16, 0)#

The time at which the GOES scan mode changed from mode 3 to mode 6. This is used to determine the scan time resolution. See GOES ABI scan information.

pycontrails.datalib.goes.extract_goes_visualization(da, color_scheme='ash', ash_convention='MIT', gamma=2.2)#

Extract artifacts for visualizing GOES data with the given color scheme.

Parameters:

  • da (xarray.DataArray) – DataArray of GOES data as returned by GOES.get(). Must have the channels required by to_ash().

  • color_scheme (str = {"ash", "true"}) – Color scheme to use for visualization.

  • ash_convention (str = {"MIT", "standard"}) – Passed into to_ash(). Only used if color_scheme="ash".

  • gamma (float = 2.2) – Passed into to_true_color(). Only used if color_scheme="true".

Returns:

  • rgb (npt.NDArray[np.float32]) – 3D RGB array of shape (height, width, 3). Any nan values are replaced with 0.

  • src_crs (ccrs.Geostationary) – The Geostationary projection built from the GOES metadata.

  • src_extent (tuple[float, float, float, float]) – Extent of GOES data in the Geostationary projection

pycontrails.datalib.goes.gcs_goes_path(time, region, channels=None, bucket='gcp-public-data-goes-16', fs=None)#

Return GCS paths to GOES data at the given time for the given region and channels.

Presently only supported for GOES data whose scan time minute coincides with the minute of the time parameter.

Parameters:

  • time (datetime.datetime) – Time of GOES data. This should be a timezone-naive datetime object or an ISO 8601 formatted string.

  • region (GOESRegion) – GOES Region of interest.

  • channels (str | Iterable[str]) – Set of channels or bands for CMIP data. The 16 possible channels are represented by the strings “C01” to “C16”. For the MIT ash color scheme, set channels=("C11", "C14", "C15"). For the true color scheme, set channels=("C01", "C02", "C03"). By default, the channels required by the MIT ash color scheme are used.

Returns:

list[str] – List of GCS paths to GOES data.

Examples

>>> from pprint import pprint
>>> t = datetime.datetime(2023, 4, 3, 2, 10)

>>> paths = gcs_goes_path(t, GOESRegion.F, channels=("C11", "C12", "C13"))
>>> pprint(paths)
['gcp-public-data-goes-16/ABI-L2-CMIPF/2023/093/02/OR_ABI-L2-CMIPF-M6C11_G16_s20230930210203_e20230930219511_c20230930219586.nc',
 'gcp-public-data-goes-16/ABI-L2-CMIPF/2023/093/02/OR_ABI-L2-CMIPF-M6C12_G16_s20230930210203_e20230930219516_c20230930219596.nc',
 'gcp-public-data-goes-16/ABI-L2-CMIPF/2023/093/02/OR_ABI-L2-CMIPF-M6C13_G16_s20230930210203_e20230930219523_c20230930219586.nc']

>>> paths = gcs_goes_path(t, GOESRegion.C, channels=("C11", "C12", "C13"))
>>> pprint(paths)
['gcp-public-data-goes-16/ABI-L2-CMIPC/2023/093/02/OR_ABI-L2-CMIPC-M6C11_G16_s20230930211170_e20230930213543_c20230930214055.nc',
 'gcp-public-data-goes-16/ABI-L2-CMIPC/2023/093/02/OR_ABI-L2-CMIPC-M6C12_G16_s20230930211170_e20230930213551_c20230930214045.nc',
 'gcp-public-data-goes-16/ABI-L2-CMIPC/2023/093/02/OR_ABI-L2-CMIPC-M6C13_G16_s20230930211170_e20230930213557_c20230930214065.nc']

>>> t = datetime.datetime(2023, 4, 3, 2, 11)
>>> paths = gcs_goes_path(t, GOESRegion.M1, channels="C01")
>>> pprint(paths)
['gcp-public-data-goes-16/ABI-L2-CMIPM/2023/093/02/OR_ABI-L2-CMIPM1-M6C01_G16_s20230930211249_e20230930211309_c20230930211386.nc']
pycontrails.datalib.goes.to_ash(da, convention='MIT')#

Compute 3d RGB array for the ASH color scheme.

Parameters:

  • da (xarray.DataArray) – DataArray of GOES data with appropriate channels.

  • convention (str = {"MIT", "standard"}) – Convention for color space.

    • MIT convention requires channels C11, C14, C15

    • Standard convention requires channels C11, C13, C14, C15

Returns:

npt.NDArray[np.float32] – 3d RGB array with ASH color scheme according to convention.

References

Examples

>>> goes = GOES(region="M2", channels=("C11", "C14", "C15"))
>>> da = goes.get("2022-10-03 04:34:00")
>>> rgb = to_ash(da)
>>> rgb.shape
(500, 500, 3)

>>> rgb[0, 0, :]
array([0.0127004 , 0.22793579, 0.3930847 ], dtype=float32)
pycontrails.datalib.goes.to_true_color(da, gamma=2.2)#

Compute 3d RGB array for the true color scheme.

Parameters:

  • da (xarray.DataArray) – DataArray of GOES data with channels C01, C02, C03.

  • gamma (float = 2.2) – Gamma correction for the RGB channels.

Returns:

npt.NDArray[np.float32] – 3d RGB array with true color scheme.

References