livvext.common

module documentation

(source)

Generic class for LIVVkit Extensions.

This supplies several common methods for plotting and data analysis.

Class	`LEX`	Define a LIVVkit extension.
Function	`annotate_plot`	Add land / ocean, gridlines, colourbar.
Function	`area_avg`	Compute a masked and weighted area average of some field.
Function	`check_longitude`	Check that longitudes are -180 - +180.
Function	`closest_points`	Determine closest model points to set of observation x/y points.
Function	`compute_clevs`	Compute reasonable min / max levels for one to three arrays which are comparable.
Function	`gen_file_list`	Generate a list of files to be loaded for a particular dataset climatology.
Function	`gen_file_list_timeseries`	Similar to `gen_file_list` but for timeseries data. Generate list of files to load.
Function	`get_cycle`	Get the name of which type of averaging is used (annual, seasonal, monthly).
Function	`get_season_bounds`	Determine season bounds for climatology files.
Function	`img_file_prefix`	Convert the module name into a file prefix for the image output.
Function	`load_obs`	Load observational (or reanalysis) data.
Function	`load_timeseries_data`	Load data for timeseries.
Function	`parse_var`	Parse a data_var formula or name.
Function	`parse_var_name`	Parse a LIVVext `data_var` formula or native netCDF field name string.
Function	`plot_grid`	Undocumented
Function	`plot_points`	Undocumented
Function	`proc_climo_file`	Process the climatology file to maintain backward compatibility with standalone LEX.
Function	`summarize_result`	Provides a snapshot of the extension's results to be provided on the summary webpage and printed to STDOUT via the print_summary method
Function	`var_filename_format`	Fill in a LIVVext defined string template for a particular variable, season, and run.
Constant	`DAYS_PER_MONTH`	`np.ndarray` of number of days per month.
Constant	`DAYS_PER_SEASON`	Map seasonal (MMM) abbreviations to number of days per season.
Constant	`MON_NAMES`	List of short month names (Jan, Feb, ...).
Constant	`SEASON_NAME`	Map seasonal (MMM) abbreviations to human-readable names for seasons.
Constant	`TFORM`	Transform for data on a regular lat / lon grid.

def annotate_plot(axis, color_field=None, label=None): (source) ¶

Add land / ocean, gridlines, colourbar.

def area_avg(data: xr.DataArray | np.ndarray, config: dict, area_file: Path, area_var: str, mask_file: Path = None, mask_var: str = None, sum_out: bool = False, land_only: bool = False): (source) ¶

Compute a masked and weighted area average of some field.

data : array_like: Array of data to be averaged
config : dict: LIVVkit configuration dictionary, at least contains the variable maskv if mask_var is not set
area_file : Path: Path to a netCDF file containing the grid cell area which matches data
area_var : str: Name of the netCDF variable which contains the area data
mask_file : Path, optional: Path to a netCDF file containing the ice sheet mask whose shape matches data. If not set, the mask is assumed to be in the area_file file
mask_var : str, optional: Name of the netCDF variable which contains the ice sheet mask data, if not set, then use maskv from config
sum_out: bool, optional: Return the weighted sum rather than average. Defualt is False
land_only: bool, optional: Return the average or sum over grid cells which are 100% land so no ocean cells are included. Default is False

Returns
avg: `float` - Masked and area-weighted average of `data` isheet_mask: `array_like` - Mask of ice sheet used in generating `avg` area_maskice: `array_like` - Masked area used in generating `avg` _data: `array_like` - Input `data` masked by `isheet_mask`

def check_longitude(data: xr.Dataset | xr.DataArray, lon_coord: str = 'lon'): (source) ¶

Check that longitudes are -180 - +180.

def closest_points(model_x: np.ndarray, model_y: np.ndarray, obs_x: np.ndarray, obs_y: np.ndarray) -> tuple[np.ndarray]: (source) ¶

Determine closest model points to set of observation x/y points.

Parameters
model_x:`np.ndarray`	Model x coordinate array (lon)
model_y:`np.ndarray`	Model y coordinate array (lat)
obs_x:`np.ndarray`	Observation x locations (lon)
obs_y:`np.ndarray`	Observation y locations (lat)

Returns
`tuple[np.ndarray]`	Array of closest points, Array of indicies for observations on the model mesh (nobs, ny, nx)

def compute_clevs(data, bnds=(5, 95), even=False, round=True, keys=None): (source) ¶

Compute reasonable min / max levels for one to three arrays which are comparable.

Parameters
data:`dict`	Masked array of data for which to compute contour levels
bnds:`tuple, optional`	Upper / lower percentiles to use for bounds (default: (5%, 95%))
even:`bool, optional`	Use an even interval about 0 (default: False)
round	Undocumented
keys:`list, optional`	List of keys within `data` for which bounds will be computed, default is all keys in `data`

Returns
`float`	bnd_l, bnd_h - Lower, upper bounds for contouring

def gen_file_list(config: dict, var_name: list | tuple | str, overs: str, sea: list | tuple | str, cycle: str) -> list[Path]: (source) ¶

Generate a list of files to be loaded for a particular dataset climatology.

Parameters
config:`dict`	LIVVext configuratrion dictionary. Must have keys: `file_patterns`: the file match pattern for each dataset `in_dirs`: Absolute path to directory for each dataset `clim_years`: Start and end year for climatology `icesheet`: Icesheet identifier (optional, defaults to gis)
var_name:`list \| tuple \| str`	Name or list/tuple of names of fields to be loaded, each in a separate file
overs:`str`	Observation version (dset_a, dset_b, ..., or model)
sea:`list \| tuple \| str`	Season or list/tuple of seasons to be loaded
cycle:`str`	Climatology averaging period (e.g. ann, sea, mon)

Returns
`list[Path]`	List of full file paths to be loaded

def gen_file_list_timeseries(config: dict, var_name: list | tuple | str, overs: str): (source) ¶

Similar to gen_file_list but for timeseries data. Generate list of files to load.

Parameters
config:`dict`	LIVVext configuratrion dictionary.
var_name:`list \| tuple \| str`	Field name or list/tuple of field names to be loaded
overs:`str`	"Observational" dataset version (e.g. dset_a, dset_b, ..., or model)

Returns
`list[Path]`	List of absolute paths to input dataset files

def get_cycle(sea): (source) ¶

Get the name of which type of averaging is used (annual, seasonal, monthly).

def get_season_bounds(season: str | int | float, year_s: int, year_e: int, mon_s: int = None, mon_e: int = None) -> tuple[str]: (source) ¶

Determine season bounds for climatology files.

def img_file_prefix(config: dict) -> str: (source) ¶

Convert the module name into a file prefix for the image output.

def load_obs(config, sea='ANN', mode='climoS', single_ds=None, expect_one_time=True): (source) ¶

Load observational (or reanalysis) data.

Parameters
config:`dict`	LIVVext configuratrion dictionary. Must have keys: `in_dirs`: the input directories each dataset `data_vars`: the variables to be analyzed `file_patterns`: the file match pattern for each dataset `in_dirs`: Absolute path to directory for each dataset `clim_years`: Start and end year for climatology `icesheet`: Icesheet identifier (optional, defaults to gis)
sea:`str, optional`	Season or month (e.g. ANN, DJF, '01', 1), by default "ANN"
mode:`str, optional`	Climatology mode, for sum (climoS), average (climoA), by default "climoS"
single_ds:`str, optional`	Load only one dataset, by default None, load all datasets in `config["in_dirs"]`
expect_one_time:`bool, optional`	Assume dataset has a single time per file, by default True

Returns
`dict[xr.Dataset]`	Dictionary of `xr.Dataset` s, one for each dataset in `config["in_dirs"]`.

@logger.catch

def load_timeseries_data(config: dict): (source) ¶

Load data for timeseries.

Parameters
config:`dict`	LIVVext configuration dictionary. Should have keys: `timeseries_dirs` `data_vars` `dataset_names` Other keys as required by `get_file_list_timeseries`

Returns
`dict[xr.Dataset]`	Dictionary of datasets for each dataset in `config["timeseries_dirs"]`

def parse_var(data_var: list | tuple | str, dataset: xr.Dataset, scale: float | int | str) -> xr.DataArray: (source) ¶

Parse a data_var formula or name.

Parameters
data_var:`list \| tuple \| str`	data_var definition, if a list or tuple, this is a formula for computing a derived field, if a string, this is a native output field from the dataset. See `livvext.utils.extract_ds` for more details.
dataset:`xr.Dataset`	Input `xr.Dataset`
scale:`float \| int \| str`	Scale the `data_var` field after computation by `scale`. Can be numeric or a string representation (e.g. 1e-6, 32.5, or "365 * 24"). See `livvext.utils.eval_expr` for more details.

Returns
`xr.DataArray`	Xarray DataArray of the field of intrest

def parse_var_name(data_var: list | tuple | str) -> str: (source) ¶

Parse a LIVVext data_var formula or native netCDF field name string.

Parameters
data_var:`list \| tuple \| str`	LIVVext `data_var` formula if list or tuple, native output field name if string

Returns
`str`	String representation of the output field or formula

def plot_grid(lon, lat, data, axis, cmap=None, vmin=None, vmax=None, outline=False): (source) ¶

Undocumented

def plot_points(lon, lat, data, axis, cmap=None, vmin=None, vmax=None, outline=False): (source) ¶

Undocumented

def proc_climo_file(config: dict, file_tag: str, sea: str) -> str: (source) ¶

Process the climatology file to maintain backward compatibility with standalone LEX.

Parameters
config:`dict`	LIVVkit /LEX configuration dict
file_tag:`str`	Configuration item which points to climatology filename to be formatted, usually `climo` or `climo_remap`
sea:`str`	Season identifier

Returns
`str`	climo_file - Formatted name of climatology file

def summarize_result(result): (source) ¶

Provides a snapshot of the extension's results to be provided on the summary webpage and printed to STDOUT via the print_summary method

def var_filename_format(file_pattern, _var, isheet, _sea, year_s, year_e, sep='_'): (source) ¶

Fill in a LIVVext defined string template for a particular variable, season, and run.

Parameters
file_pattern:`str`	Filename template with spots for variable, icesheet, and season start / end
_var:`str`	Model or observational field name
isheet:`str`	Icesheet name (gis or ais)
_sea:`str`	Season name or month number (e.g. ANN, DJF,..., '01' or 1)
year_s:`int`	Start year of climatology
year_e:`int`	End year of climatology
sep:`str, optional`	Separator within the template, if defined. By default "_"

Returns
`str`	Formatted filename

DAYS_PER_MONTH = (source) ¶

np.ndarray of number of days per month.

Value

np.array([31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31])

DAYS_PER_SEASON = (source) ¶

Map seasonal (MMM) abbreviations to number of days per season.

Value

{'DJF': 31 + 31 + 28,
 'MAM': 31 + 30 + 31,
 'JJA': 30 + 31 + 31,
 'SON': 30 + 31 + 30,
 'JFM': 31 + 28 + 31,
 'AMJ': 30 + 31 + 30,
 'JAS': 31 + 31 + 30,
...

MON_NAMES = (source) ¶

List of short month names (Jan, Feb, ...).

Value

[dt.datetime(2000, mon, 1).strftime('%b') for mon in range(1, 12 + 1)]

SEASON_NAME: dict[str, str] = (source) ¶

Map seasonal (MMM) abbreviations to human-readable names for seasons.

Value

{'ANN': 'annual',
 'DJF': 'winter',
 'JJA': 'summer',
 'MAM': 'spring',
 'SON': 'autumn'}

TFORM = (source) ¶

Transform for data on a regular lat / lon grid.

Value

ccrs.PlateCarree()