pycontrails.datalib.google_forecast.GoogleForecast¶

class pycontrails.datalib.google_forecast.GoogleForecast(time, variables=(MetVariable(short_name='contrails', standard_name='contrails', long_name='Contrail Severity Index', level_type=None, ecmwf_id=None, grib1_id=None, grib2_id=None, units='1', amip=None, description='The severity (0-4) of forecasted contrail warming.'),), key=None, url='https://contrails.googleapis.com/v2/grids', cachestore=None)¶

Bases: MetDataSource

Google Forecast datalib to download precomputed contrail forecasts from API sources.

This class provides an interface to the Google Contrails Forecast API. It returns a MetDataset containing the forecast severity and/or energy forcing.

Added in version 0.60.3.

Parameters:

time (metsource.TimeInput | None) – The time range for data retrieval, either a single datetime or (start, end) datetime range. Input must be datetime-like or tuple of datetime-like (datetime, pd.Timestamp, np.datetime64) specifying the (start, end) of the date range, inclusive.
variables (metsource.VariableInput) – Variable name (i.e. “contrails”, “eeef_per_m”, [“contrails”, “eeef_per_m”])
key (str | google.auth.credentials.Credentials | None, optional) – Google Cloud Platform credentials or API key. If None, looks for GOOGLE_API_KEY environment variable. If that is not found, uses google.auth.default().
url (str, optional) – Google Contrails Forecast API URL. Defaults to “https://contrails.googleapis.com/v2/grids”.
cachestore (cache.CacheStore | None, optional) – Cache data store for Google Forecast files. If a cache store is provided, forecasts will be first retrieved from the cache store and only from the API if not yet cached. Since the Google Forecast API frequently recomputes forecasts, using the cache store may result in stale data. It is not recommended to cache future forecasts for longer than one hour. Defaults to None (no caching).

__init__(time, variables=(MetVariable(short_name='contrails', standard_name='contrails', long_name='Contrail Severity Index', level_type=None, ecmwf_id=None, grib1_id=None, grib2_id=None, units='1', amip=None, description='The severity (0-4) of forecasted contrail warming.'),), key=None, url='https://contrails.googleapis.com/v2/grids', cachestore=None)¶

Methods

`__init__`(time[, variables, key, url, cachestore])
`cache_dataset`(dataset)	Cache data from data source.
`create_cachepath`(t)	Return cachepath to local data file based on datetime.
`download`(**xr_kwargs)	Confirm all data files are downloaded and available locally in the `cachestore`.
`download_dataset`(times)	Download data from Google API, updating the cache if configured.
`is_datafile_cached`(t, **xr_kwargs)	Check datafile defined by datetime for variables and pressure levels in class.
`list_timesteps_cached`(**xr_kwargs)	Get a list of data files available locally in the `cachestore`.
`list_timesteps_not_cached`(**xr_kwargs)	Get a list of data files not available locally in the `cachestore`.
`open_dataset`(disk_paths, **xr_kwargs)	Open multi-file dataset in xarray.
`open_metdataset`([dataset, xr_kwargs])	Open MetDataset from the Google Contrails Forecast API.
`set_metadata`(ds)	Set metadata.

Attributes

`cachestore`	Cache store for intermediates while processing data source If None, cache is turned off.
`url`	Google Contrails Forecast API URL
`grid`	Lat / Lon grid spacing
`hash`	Generate a unique hash for this datasource.
`is_single_level`	Return True if the datasource is single level data.
`paths`	Path to local source files to load.
`pressure_level_variables`	Parameters available from data source.
`pressure_levels`	List of pressure levels.
`single_level_variables`	Parameters available from data source.
`supported_pressure_levels`	Pressure levels available from datasource.
`supported_variables`	Get supported variables.
`timesteps`	List of individual timesteps from data source derived from `time` Use `parse_time()` to handle `TimeInput`.
`variable_shortnames`	Return a list of variable short names.
`variable_standardnames`	Return a list of variable standard names.
`variables`	Variables requested from data source Use `parse_variables()` to handle `VariableInput`.

cache_dataset(dataset)¶

Cache data from data source.

If the cache path already exists, this method will merge the new data with the existing cached data. This allows different variables to be cached in the same file.

cachestore¶: Cache store for intermediates while processing data source If None, cache is turned off.

create_cachepath(t)¶: Return cachepath to local data file based on datetime.

download(**xr_kwargs)¶

Confirm all data files are downloaded and available locally in the cachestore.

Parameters:: **xr_kwargs – Passed into xarray.open_dataset() via is_datafile_cached().

download_dataset(times)¶: Download data from Google API, updating the cache if configured.

grid¶: Lat / Lon grid spacing

property hash¶: Generate a unique hash for this datasource.

is_datafile_cached(t, **xr_kwargs)¶

Check datafile defined by datetime for variables and pressure levels in class.

If using a cloud cache store (i.e. cache.GCPCacheStore), this is where the datafile will be mirrored to a local file for access.

Parameters:

t (datetime) – Datetime of datafile
**xr_kwargs (Any) – Additional kwargs passed directly to xarray.open_mfdataset() when opening files. By default, the following values are used if not specified:
- chunks: {“time”: 1}
- engine: “netcdf4”
- parallel: False

Returns:

bool – True if data file exists for datetime with all variables and pressure levels, False otherwise

property is_single_level¶: Return True if the datasource is single level data.

Added in version 0.50.0.

list_timesteps_cached(**xr_kwargs)¶

Get a list of data files available locally in the cachestore.

Parameters:: **xr_kwargs – Passed into xarray.open_dataset() via is_datafile_cached().

list_timesteps_not_cached(**xr_kwargs)¶

Get a list of data files not available locally in the cachestore.

Parameters:: **xr_kwargs – Passed into xarray.open_dataset() via is_datafile_cached().

open_dataset(disk_paths, **xr_kwargs)¶

Open multi-file dataset in xarray.

Parameters:

disk_paths (str | list[str] | pathlib.Path | list[pathlib.Path]) – list of string paths to local files to open
**xr_kwargs (Any) – Additional kwargs passed directly to xarray.open_mfdataset() when opening files. By default, the following values are used if not specified:
- chunks: {“time”: 1}
- engine: “netcdf4”
- parallel: False
- lock: False

Returns:

xarray.Dataset – Open xarray dataset

open_metdataset(dataset=None, xr_kwargs=None, **kwargs)¶: Open MetDataset from the Google Contrails Forecast API.

paths¶: Path to local source files to load. Set to the paths of files cached in cachestore if no paths input is provided on init.

property pressure_level_variables¶

Parameters available from data source.

Returns:: list[MetVariable] | None – List of MetVariable available in datasource

pressure_levels¶: List of pressure levels. Set to [-1] for data without level coordinate. Use parse_pressure_levels() to handle PressureLevelInput.

set_metadata(ds)¶: Set metadata.

property single_level_variables¶

Parameters available from data source.

Returns:: list[MetVariable] | None – List of MetVariable available in datasource

property supported_pressure_levels¶

Pressure levels available from datasource.

Returns:: list[int] | None – List of integer pressure levels for class. If None, no pressure level information available for class.

property supported_variables¶: Get supported variables.

timesteps¶: List of individual timesteps from data source derived from time Use parse_time() to handle TimeInput.

url¶: Google Contrails Forecast API URL

property variable_shortnames¶

Return a list of variable short names.

Returns:: list[str] – Lst of variable short names.

property variable_standardnames¶

Return a list of variable standard names.

Returns:: list[str] – Lst of variable standard names.

variables¶: Variables requested from data source Use parse_variables() to handle VariableInput.