Cube Helper Module

cube_helper module

cube_helper.add_categorical(cubes, categorical, coord='time', season='djf', seasons=('djf', 'mam', 'jja', 'son'))

Adds a coordinate categorisation(s) to the iterable of Iris Cubes.

Currently this function provides a wrapper for the following standalone and compound categoricals:

day_of_month:

Add a day-of-month coordinate, vals 1-31.

day_of_year:

Add a day-of-year coordinate, vals 1-365 (366 in leap years).

month:

Add a month coordinate, vals ‘Jan’-’Dec’.

month_fullname:

Add a month coordinate, vals ‘January’-’December’.

month_number:

Add a month coordinate, vals 1-12.

season:

Add a season-of-year coordinate, with specified seasons.

clim_season:

Add a climatalogical season-of-year coordinate, with specified seasons.

season_membership:

Add a season membership coordinate for a specified season.

season_number:

Add a season-of-year coordinate, values 0..(N-1) where N is the number of user specified seasons.

season_year:

Add a categorical year-of-season coordinate, with specified seasons.

weekday:

Add a weekday coordinate, vals ‘Mon’-’Sun’.

weekday_fullname:

Add a weekday coordinate, vals ‘Monday’-’Sunday’.

weekday_number:

Add a weekday coordinate, vals 0-6 [0=Monday].

year:

Add a calendar-year coordinate.

annual_seasonal_mean:

Add a clim_season and a season_year coordinate.

Args:

cubes: A cube, a list of Loaded Cubes or a CubeList.

categorical: A string or list of strings specifying the categorisation you wish to add. Additionally a compound categorisation can be added. E.g ‘annual_seasonal_mean’.

coord: The coordinate you wish to add a categorisation to. Set to ‘time’ by default.

season: The season you need for the categorisation (where required). set to ‘djf’ by default.

seasons: The seasons required for categorisation.

Returns:

cubes: An iterable of Cubes, either a list of loaded Cubes or an Iris CubeList.

cube_helper.aggregate_categorical(cube, categorical, coord='time', season='djf', seasons=('djf', 'mam', 'jja', 'son'), agg_method=<iris.analysis.WeightedAggregator object>)

Adds a coordinate categorisation(s) to the iterable of Iris Cubes, then aggregates them by the given categoricals. Categoricals used are the same as the ones supported by add_categorical().

Args:

cube: A cube, a list of loaded Cubes or a CubeList.

categorical: A string or list of strings specifying the categorisation you wish to add. Additionally a compound categorisation can be added. E.g ‘annual_seasonal_mean’.

coord: The coordinate you wish to add a categorisation to. Set to ‘time’ by default.

season: The season you need for the categorisation (where required). set to ‘djf’ by default.

seasons: The seasons required for categorisation.

agg_method: An Iris aggregator object, e.g iris.analysis.MEAN

Returns:

cubes: A cube, a list of loaded Cubes, or an Iris CubeList aggregated by a given categorical.

cube_helper.compare_cubes(cubes)

Examines coordinates and attributes across iterable of iris cubes And calls equalise functions (with comp_only arg set to true) where appropriate.

Args:

cubes: An iterable of iris Cubes or CubeList to be compared for inconsistencies.

Returns:

A printed string detailing the inconsistencies in the cubes.

cube_helper.concatenate(cubes)

Concatenates a list of Iris Cubes. Equalises the list of cubes first then concatenates.

Args:

cubes: An iterable of Iris Cubes to concatenate, either list of loaded cubes or a CubeList

Returns:

cube: A concatenated Iris Cube.

cube_helper.equalise_all(cubes)

Invokes equalise_aux_coords, equalise_attributes, equalise_dim_coords and equalise_time units all at once. Used before cube_load concatenates the cubes.

Args:

cubes: Cubes to be equalised.

Returns:

cubes: Cubes equalised across metadata and coords.

cube_helper.equalise_attributes(cubes, comp_only=False)

Equalises Cubes for concatenation and merging, cycles through the iterable of cubes (either a list of loaded cubes or aan iris CubeList) and removes any that are not common across all cubes, metadata, and variables.

Args:

cubes: Cubes to be equalised of attributes.

comp_only: A boolean value, if set to True it will examine the cubes attributes and print inconsistencies but not equalise them.

Returns:

Equalised cube_dataset to the CubeHelp class

cube_helper.equalise_aux_coords(cubes, comp_only=False)

Equalises auxiliary coordinates of cubes.

Args:

cubes: CubeList or list of Cubes to equalise.

comp_only: A boolean value, if set to True it will examine the Cube’s aux coordinates and print inconsistencies but not equalise them.

Returns:

Cubes equalised across auxiliary coordinates.

cube_helper.equalise_data_type(cubes, data_type='float32')

Casts datatypes in iris numpy array to be of the same datatype.

Args:

cubes: Cubes to have their datatypes equalised.

data_type: String specifying datatype, default is float32.

Returns:

cubes: Cubes with their data types identical.

cube_helper.equalise_dim_coords(cubes, comp_only=False)

Equalises dimensional coordinates of Cubes, specifically long_name, standard_name, and var_name.

Args:

cubes: CubeList or list of Cubes to equalise.

comp_only: A boolean value, if set to True it will examine the cubes dimension coordinates and print inconsistencies but not equalise them.

Returns:

Cubes equalised across dimension coordinates.

cube_helper.equalise_time_units(cubes, comp_only=False)

Equalises time units by cycling through each cube in the given CubeList or list of loaded cubes.

Args:

cubes: Cubes to equalised of time coords.

comp_only: A boolean value, if set to True it will examine the cubes time_coordinates and print inconsistencies but not equalise them.

Returns:

cubes with time coordinates unified.

cube_helper.examine_dim_bounds(cubes, cube_files)

Examines the dimensional bounds of time should concatenate fail. Cycles through cubes and determines if the times are contiguous.

Args:

cubes: Iris cubes to examine the time bounds of

cube_files: the respective files of cubes, to give users info as to what cubes are causing problems with concatenation.

Returns:

A printed string detailing any overlap in the time bounds.

cube_helper.extract(cube, constraint)

Extracts a constraint on an Iris cube, and will fix common issues associated with time constraints and partial datetimes.

Note: This function will not be able to rectify constraints using lambda functions. An extract_bounds function will be added to a future release of cube_helper to help with more complex time extractions.

Args:

cube: A cube or a CubeList.

constraint: A constraint to extract.

Returns:

the cube or CubeList extracted along the constraint.

cube_helper.extract_categorical(cube, categorical, constraint, coord='time', season='djf', seasons=('djf', 'mam', 'jja', 'son'), agg_method=<iris.analysis.WeightedAggregator object>)

Adds a coordinate categorical, aggregates by said categorical, then extracts the given constraint. The categoricals used are the then extracts the given constraint. Categoricals used are the same as the ones supported by add_categorical() and aggregate_categorical().

Args:

cube: A cube, a list of Loaded Cubes or a CubeList.

categorical: A string or list of strings specifying the categorisation you wish to add. Additionally a compound categorisation can be added. E.g ‘annual_seasonal_mean’.

constraint: An Iris constraint you wish to extract.

coord: The coordinate you wish to add a categorisation to. Set to ‘time’ by default.

season: The season you need for the categorisation (where required). set to ‘djf’ by default.

seasons: The seasons required for categorisation.

agg_method: An Iris aggregator object, e.g iris.analysis.MEAN.

Returns:

cubes: A cube, a list of loaded Cubes, or an Iris CubeList extracted from a given constraint.

cube_helper.fix_known_issues(cube)

Identify any issues that are known about in the input cube, fix these in-place and warn the user what has been fixed.

The issues currently fixed are:

FixCmip6CasFgoals mip_era CMIP6 institution_id CAS source_id FGOALS-f3-L: remove the latitude and longitude bounds, which are not contiguous, and use iris.coords.Coord.guess_bounds() to calculate new bounds for these two coordinates.

FixCmip6FioqlnmFioesm20Latitude mip_era CMIP6 institution_id FIO-QLNM source_id FIO-ESM-2-0 and latitude is an auxiliary coordinate: remove the latitude and longitude bounds, which are invalid, and use iris.coords.Coord.guess_bounds() to calculate new bounds for these two coordinates, which are identical to the bounds in other FIO-ESM-2-0 experiments. latitude is then promoted to a dimension coordinate.

Args:

cube: the iris.cube.Cube to fix

cube_helper.load(directory, filetype='.nc', constraints=None)

A function that loads and concatenates Iris Cubes.

Args:

directory: A String specifying the directory or filename of the Cubes you wish to concatenate. Accepts either directory location or a list or glob object of individual Cubes.

filetype: Extension of Iris Cubes to Load. set to ‘.nc’ by default.

constraints: Any constraints to be applied to Cubes on load.

Returns:

result: A concatenated Iris Cube.

cube_helper.muffle_logger()

A function that switches the logging level to ERROR or higher, thereby muffling all output other than error messages. As this option obscures the user to changes made to cubes on load (as well as inconsistencies) it is advised not to use this function unless absolutely necessary.

cube_helper.remove_attributes(cubes)

Sets all cube attributes to an empty string. be unaffected.

Args:

cubes: Cubes to have attributes stripped.

Returns:

Cubes with attributes replaced with empty string ‘’.

cube_helper.reset_logger()

A function that switches the level to INFO or higher, allowing cube_helper’s logger to detail changes and inconsistencies as usual