pycontrails.datalib.goes¶

Support for GOES access and analysis.

Resources¶

Module Attributes

`DEFAULT_BANDS`	Default bands 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.
`GOES_16_19_SWITCH_DATE`	The date at which GOES-19 data started being available.
`GOES_16_BUCKET`	The GCS bucket for GOES-East data before `GOES_16_19_SWITCH_DATE`.
`GOES_18_BUCKET`	The GCS bucket for GOES-West data.
`GOES_19_BUCKET`	The GCS bucket for GOES-East data after `GOES_16_19_SWITCH_DATE`.

Functions

`extract_goes_visualization`(da[, ...])	Extract artifacts for visualizing GOES data with the given color scheme.
`extract_visualization`(da[, color_scheme, ...])	Extract artifacts for visualizing GOES data with the given color scheme.
`gcs_goes_path`(time, region[, bands, bucket, fs])	Return GCS paths to GOES data at the given time for the given region and bands.
`to_true_color`(da[, gamma])	Compute 3d RGB array for the true color scheme.

Classes

`GOES`([region, bands, channels, cachestore, ...])	Support for GOES-16 data access via GCP.
`GOESRegion`(value[, names, module, qualname, ...])	GOES Region of interest.

pycontrails.datalib.goes.DEFAULT_BANDS = ('C11', 'C14', 'C15')¶: Default bands to use if none are specified. These are the bands required by the SEVIRI (MIT) ash color scheme.

class pycontrails.datalib.goes.GOES(region=GOESRegion.F, bands=None, *, channels=None, cachestore=<object object>, bucket=None, goes_bucket=None)¶

Bases: object

Support for GOES-16 data access via GCP.

This interface requires the gcsfs package.

Parameters:

region (GOESRegion | str, optional) – GOES Region of interest. Uses the following conventions.
- F: Full Disk
- C: CONUS
- M1: Mesoscale 1
- M2: Mesoscale 2
By default, Full Disk (F) is used.
bands (str | Iterable[str] | None) – Set of bands or bands for CMIP data. The 16 possible bands are represented by the strings “C01” to “C16”. For the SEVIRI ash color scheme, set bands=("C11", "C14", "C15"). For the true color scheme, set bands=("C01", "C02", "C03"). By default, the bands required by the SEVIRI ash color scheme are used. The bands 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, optional) – Cache store for GOES data. If None, data is downloaded directly into memory. By default, a cache.DiskCacheStore is used.
bucket (str | None, optional) – GCP bucket for GOES data. If None, the default option, the bucket is automatically set to GOES_16_BUCKET if the requested time is before GOES_16_19_SWITCH_DATE and GOES_19_BUCKET otherwise. The satellite number used for filename construction is derived from the last two characters of this bucket name.

See also

GOESRegion, gcs_goes_path

Examples

>>> goes = GOES(region="M1", bands=("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", bands=("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]], shape=(500, 500), dtype=float32)

gcs_goes_path(time, bands=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.
bands (set[str] | None) – Set of bands or bands for CMIP data. If None, the bands 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=<not given>, *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_16_19_SWITCH_DATE = datetime.datetime(2025, 4, 4, 0, 0)¶: The date at which GOES-19 data started being available. This is used to determine the source (GOES-16 or GOES-19) of requested. In particular, Mesoscale images are only available for GOES-East from GOES-19 after this date. See the NOAA press release.

pycontrails.datalib.goes.GOES_16_BUCKET = 'gcp-public-data-goes-16'¶: The GCS bucket for GOES-East data before GOES_16_19_SWITCH_DATE.

pycontrails.datalib.goes.GOES_18_BUCKET = 'gcp-public-data-goes-18'¶: The GCS bucket for GOES-West data. Note that GOES-17 has degraded data quality and is not recommended for use. This bucket isn’t used by the GOES handler by default.

pycontrails.datalib.goes.GOES_19_BUCKET = 'gcp-public-data-goes-19'¶: The GCS bucket for GOES-East data after GOES_16_19_SWITCH_DATE.

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='SEVIRI', 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 bands required by to_ash().
color_scheme (str) – Color scheme to use for visualization. Must be one of {“true”, “ash”}. If “true”, the da must contain bands C01, C02, and C03. If “ash”, the da must contain bands C11, C14, and C15 (SEVIRI convention) or bands C11, C13, C14, and C15 (standard convention).
ash_convention (str) – Passed into to_ash(). Only used if color_scheme="ash". Must be one of {“SEVIRI”, “standard”}. By default, “SEVIRI” is used.
gamma (float) – Passed into to_true_color(). Only used if color_scheme="true". By default, 2.2 is used.

Returns:

rgb (npt.NDArray[np.float32]) – 3D RGB array of shape (height, width, 3). Any nan values are replaced with 0.
src_crs (cartopy.crs.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.extract_visualization(da, color_scheme='ash', ash_convention='SEVIRI', 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 bands required by to_ash().
color_scheme (str) – Color scheme to use for visualization. Must be one of {“true”, “ash”}. If “true”, the da must contain bands C01, C02, and C03. If “ash”, the da must contain bands C11, C14, and C15 (SEVIRI convention) or bands C11, C13, C14, and C15 (standard convention).
ash_convention (str) – Passed into to_ash(). Only used if color_scheme="ash". Must be one of {“SEVIRI”, “standard”}. By default, “SEVIRI” is used.
gamma (float) – Passed into to_true_color(). Only used if color_scheme="true". By default, 2.2 is used.

Returns:

rgb (npt.NDArray[np.float32]) – 3D RGB array of shape (height, width, 3). Any nan values are replaced with 0.
src_crs (cartopy.crs.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, bands=None, bucket=None, fs=None)¶

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

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.
bands (str | Iterable[str] | None, optional) – Set of bands or bands for CMIP data. The 16 possible bands are represented by the strings “C01” to “C16”. For the SEVIRI ash color scheme, set bands=("C11", "C14", "C15"). For the true color scheme, set bands=("C01", "C02", "C03"). By default, the bands required by the SEVIRI ash color scheme are used.
bucket (str | None) – GCS bucket for GOES data. If None, the bucket is automatically set to GOES_16_BUCKET if time is before GOES_16_19_SWITCH_DATE and GOES_19_BUCKET otherwise.
fs (gcsfs.GCSFileSystem | None) – GCS file system instance. If None, a default anonymous instance is created.

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, bands=("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, bands=("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, bands="C01")
>>> pprint(paths)
['gcp-public-data-goes-16/ABI-L2-CMIPM/2023/093/02/OR_ABI-L2-CMIPM1-M6C01_G16_s20230930211249_e20230930211309_c20230930211386.nc']

>>> t = datetime.datetime(2025, 5, 4, 3, 2)
>>> paths = gcs_goes_path(t, GOESRegion.M2, bands="C01")
>>> pprint(paths)
['gcp-public-data-goes-19/ABI-L2-CMIPM/2025/124/03/OR_ABI-L2-CMIPM2-M6C01_G19_s20251240302557_e20251240303014_c20251240303092.nc']

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 bands C01, C02, C03.
gamma (float, optional) – Gamma correction for the RGB bands.

Returns:

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

References

Unidata’s true color recipe