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.
`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.
`gcs_goes_path`(time, region[, channels, ...])	Return GCS paths to GOES data at the given time for the given region and channels.
`parallax_correct`(longitude, latitude, ...)	Apply parallax correction to WGS84 geodetic coordinates based on satellite perspective.
`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 SEVIRI (MIT) ash color scheme.

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

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 SEVIRI 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 SEVIRI 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 | None = None) – GCP bucket for GOES data. If None, 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", 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]], shape=(500, 500), 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=<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 channels required by to_ash().
color_scheme (str = {"ash", "true"}) – Color scheme to use for visualization.
ash_convention (str = {"SEVIRI", "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=None, 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 SEVIRI 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 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, 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']

>>> t = datetime.datetime(2025, 5, 4, 3, 2)
>>> paths = gcs_goes_path(t, GOESRegion.M2, channels="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.parallax_correct(longitude, latitude, altitude, goes_da)¶

Apply parallax correction to WGS84 geodetic coordinates based on satellite perspective.

This function considers the ray from the satellite to the points of interest and finds the intersection of this ray with the WGS84 ellipsoid. The intersection point is then returned as the corrected longitude and latitude coordinates.

@ satellite
 \
  \
   \
    \
     \
      * aircraft
       \
        \
         x parallax corrected aircraft
 -------------------------  surface

If the point of interest is not visible from the satellite (ie, on the opposite side of the earth), the function returns nan for the corrected coordinates.

This function requires the pyproj package to be installed.

Parameters:

longitude (npt.NDArray[np.floating]) – A 1D array of longitudes in degrees.
latitude (npt.NDArray[np.floating]) – A 1D array of latitudes in degrees.
altitude (npt.NDArray[np.floating]) – A 1D array of altitudes in meters.
goes_da (xarray.DataArray) – DataArray containing the GOES projection information. Only the goes_imager_projection field of the xr.DataArray.attrs is used.

Returns:

tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]] – A tuple containing the corrected longitude and latitude coordinates.

pycontrails.datalib.goes.to_ash(da, convention='SEVIRI')¶

Compute 3d RGB array for the ASH color scheme.

Parameters:

da (xarray.DataArray) – DataArray of GOES data with appropriate channels.
convention (str = {"SEVIRI", "standard"}) – Convention for color space.
- SEVIRI convention requires channels C11, C14, C15. Used in [Kulik, 2019].
- 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

Unidata’s true color recipe