clisops.parameter package

Parameter module for CLISOPS.

Submodules

clisops.parameter._utils module

Utility functions and classes for handling parameters in CLISOPS.

class clisops.parameter._utils.Interval(*data)

Bases: object

A simple class for handling an interval of any type.

It holds a start and end but does not try to resolve the range, it is just a container to be used by other tools. The contents can be of any type, such as datetimes, strings etc.

Parameters:

*data (str or Sequence[str]) – The input data to parse into a start and end value. Can be a string like “start/end”, a sequence of two values, or a single value.

class clisops.parameter._utils.Series(*data)

Bases: object

A simple class for handling a series selection, created by any sequence as input.

It has a value that holds the sequence as a list.

Parameters:

*data (Sequence or str or bytes or FileMapper) – The input data to parse into a sequence. Can be a string of comma-separated values, a sequence, or a FileMapper object.

class clisops.parameter._utils.TimeComponents(year=None, month=None, day=None, hour=None, minute=None, second=None)

Bases: object

A simple class for parsing and representing a set of time components.

The components are stored in a dictionary of {time_comp: values}, such as: {“year”: [2000, 2001], “month”: [1, 2, 3]}

Note that you can provide month strings as strings or numbers, e.g.: “feb”, “Feb”, “February”, 2.

Parameters:

• year (int or str, optional) – The year component, e.g., 2020.

• month (int or str, optional) – The month component, e.g., 1 for January or “feb” for February.

• day (int or str, optional) – The day component, e.g., 15 for the 15th of the month.

• hour (int or str, optional) – The hour component, e.g., 12 for noon.

• minute (int or str, optional) – The minute component, e.g., 30 for half past the hour.

• second (int or str, optional) – The second component, e.g., 45 for 45 seconds past the minute.

_parse_component(time_comp, value)

clisops.parameter._utils.area

alias of Series

clisops.parameter._utils.collection

alias of Series

clisops.parameter._utils.dimensions

alias of Series

clisops.parameter._utils.interval

alias of Interval

clisops.parameter._utils.level_interval

alias of Interval

clisops.parameter._utils.level_series

alias of Series

clisops.parameter._utils.parse_datetime(dt, defaults=None)

Parse string to datetime and returns isoformat string for it.

If defaults is set, use that in case dt is None.

Parameters:

• dt (str) – The datetime string to parse, in ISO 8601 format.

• defaults (list[int] | None) – A list of default values to use if dt is None. Should contain year, month, day, hour, minute, second.

Returns:

str – The ISO 8601 formatted string representation of the datetime.

clisops.parameter._utils.parse_range(x, caller)

Parse a range input into a start and end value.

Parameters:

• x (str or Sequence[str or Sequence[str]]) – The input range to parse. Can be a string like “start/end”, a sequence of two values, or a single value.

• caller (str) – The name of the caller for error messages, used to indicate where the error occurred.

Return type:

tuple[str | None, str | None]

Returns:

tuple[str or None, str or None] – A tuple containing the start and end values. If the input is “/”, both values will be None.

clisops.parameter._utils.parse_sequence(x, caller)

Parse a sequence input into a list of values.

Parameters:

• x (Sequence | str | bytes | FileMapper) – The input sequence to parse. Can be a string of comma-separated values, a sequence, or a FileMapper object.

• caller (str) – The name of the caller for error messages, used to indicate where the error occurred.

Return type:

Sequence

Returns:

Sequence – A list of values parsed from the input. If the input is None or an empty string, returns None.

clisops.parameter._utils.series

alias of Series

clisops.parameter._utils.string_to_dict(s, splitters=('|', ':', ','))

Convert a string to a dictionary of dictionaries, based on splitting rules (splitters).

Parameters:

• s (str) – The input string to convert, formatted as “key1:value1,value2|key2:value3,value4”.

• splitters (tuple[str, str, str]) – A tuple of strings used to split the input string into keys and values. The first element is used to split the main entries, the second for key-value pairs, and the third for value lists.

Returns:

dict – A dictionary where each key maps to a list of values.

clisops.parameter._utils.time_components

alias of TimeComponents

clisops.parameter._utils.time_interval

alias of Interval

clisops.parameter._utils.time_series

alias of Series

clisops.parameter._utils.to_float(i, allow_none=True)

Convert a value to a float, allowing for None if specified.

Parameters:

• i (Any | None) – The input value to convert to a float.

• allow_none (bool, optional) – If True, allows the input to be None and returns None. Defaults to True.

Return type:

float | None

Returns:

float or None – The converted float value, or None if the input is None and allow_none is True.

clisops.parameter.area_parameter module

Area parameter for subsetting operations.

class clisops.parameter.area_parameter.AreaParameter(input)

Bases: _BaseParameter

Class for area parameter used in subsetting operation.

Area can be input as:

A string of comma separated values: “0.,49.,10.,65”

A sequence of strings: (“0”, “-10”, “120”, “40”)

A sequence of numbers: [0, 49.5, 10, 65]

An area must have four values.

Validates the area input and parses the values into numbers.

_parse()

allowed_input_types = [<class 'collections.abc.Sequence'>, <class 'str'>, <class 'clisops.parameter._utils.Series'>, <class 'NoneType'>]

asdict()

Return a dictionary of the area values.

Returns:

dict – A dictionary with keys “lon_bnds” and “lat_bnds” containing tuples of the longitude and latitude bounds.

clisops.parameter.base_parameter module

Base class for parameters used in operations (e.g. subset, average etc.).

class clisops.parameter.base_parameter._BaseIntervalOrSeriesParameter(input)

Bases: _BaseParameter

A base class for a parameter that can be instantiated from either and Interval or Series class instance.

It has a type and a value reflecting the type, e.g.:

• type: “interval” –> value: (start, end)

• type: “series” –> value: [item1, item2, …, item_n]

_parse()

_parse_as_interval()

_parse_as_series()

_value_as_tuple()

allowed_input_types = [<class 'clisops.parameter._utils.Interval'>, <class 'clisops.parameter._utils.Series'>, <class 'NoneType'>, <class 'str'>]

class clisops.parameter.base_parameter._BaseParameter(input)

Bases: object

Base class for parameters used in operations (e.g. subset, average etc.).

_check_input_type()

_parse()

allowed_input_types = None

get_bounds()

Returns a tuple of the (start, end) times, calculated from the value of the parameter. Either will default to None.

clisops.parameter.collection_parameter module

Collection Parameter Module.

class clisops.parameter.collection_parameter.CollectionParameter(input)

Bases: _BaseParameter

Class for collection parameter used in operations.

A collection can be input as:

• A string of comma separated values: e.g. “cmip5.output1.INM.inmcm4.rcp45.mon.ocean.Omon.r1i1p1.latest.zostoga, cmip5.output1.MPI-M.MPI-ESM-LR.rcp45.mon.ocean.Omon.r1i1p1.latest.zostoga”

• A sequence of strings: e.g. (“cmip5.output1.INM.inmcm4.rcp45.mon.ocean.Omon.r1i1p1.latest.zostoga”, “cmip5.output1.MPI-M.MPI-ESM-LR.rcp45.mon.ocean.Omon.r1i1p1.latest.zostoga”)

• A sequence of clisops.utils.file_utils.FileMapper objects

Validates the input and parses the items.

_parse()

allowed_input_types = [<class 'collections.abc.Sequence'>, <class 'str'>, <class 'clisops.parameter._utils.Series'>, <class 'clisops.utils.file_utils.FileMapper'>]

clisops.parameter.dimension_parameter module

Averaging dimensions parameter for clisops operations.

class clisops.parameter.dimension_parameter.DimensionParameter(input)

Bases: _BaseParameter

Class for dimensions parameter used in averaging operation.

Area can be input as:

A string of comma separated values: “time,latitude,longitude”

A sequence of strings: (“time”, “longitude”)

Dimensions can be None or any number of options from time, latitude, longitude and level provided these exist in the dataset being operated on.

Validates the dims input and parses the values into a sequence of strings.

_parse()

allowed_input_types = [<class 'collections.abc.Sequence'>, <class 'str'>, <class 'clisops.parameter._utils.Series'>, <class 'NoneType'>]

asdict()

Return a dictionary of the dimensions.

Return type:

dict | None

Returns:

dict or None – A dictionary with a single key “dims” containing the dimensions to average over. If no dimensions are specified, returns None.

clisops.parameter.level_parameter module

LevelParameter class for handling level inputs in subsetting operations.

class clisops.parameter.level_parameter.LevelParameter(input)

Bases: _BaseIntervalOrSeriesParameter

Class for level parameter used in subsetting operation.

Level can be input as:

• A string of slash separated values: “1000/2000”

• A sequence of strings: e.g. (“1000.50”, “2000.60”)

• A sequence of numbers: e.g. (1000.50, 2000.60)

A level input must be two (2) values.

If using a string input, a trailing slash indicates you want to use the lowest/highest level of the dataset. E.g. “/2000” will subset from the lowest level in the dataset to 2000.

Validates the level input and parses the values into numbers.

_parse_as_interval()

_parse_as_series()

asdict()

Return a dictionary of the level values.

Returns:

dict – A dictionary containing the level values, either as a range (first and last level) or as a series of level values.

clisops.parameter.parameterise module

Parameterise inputs to roocs parameter classes.

clisops.parameter.parameterise.parameterise(collection=None, area=None, level=None, time=None, time_components=None)

Parameterise inputs to instances of parameter classes, allowing them to be used throughout roocs.

For supported formats for each input, please see their individual classes.

Parameters:

• collection (str, Path, xr.DataArray, xr.Dataset, or any other supported format) – Input collection to be parameterised.

• area (str, Path, dict, or any other supported format) – Input area to be parameterised.

• level (str, Path, dict, or any other supported format) – Input level to be parameterised.

• time (str, Path, dict, or any other supported format) – Input time to be parameterised.

• time_components (str, Path, dict, or any other supported format) – Input time components to be parameterised.

Returns:

dict – A dictionary containing the parameterised inputs as instances of their respective classes.

clisops.parameter.time_components_parameter module

TimeComponentsParameter class for handling time components in subsetting operations.

class clisops.parameter.time_components_parameter.TimeComponentsParameter(input)

Bases: _BaseParameter

Class for time components parameter used in subsetting operation.

The Time Components are any, or none of:

• year: [list of years]

• month: [list of months]

• day: [list of days]

• hour: [list of hours]

• minute: [list of minutes]

• second: [list of seconds]

month is special: you can use either strings or values:

“feb”, “mar” == 2, 3 == “02,03”

Validates the times input and parses them into a dictionary.

_parse()

allowed_input_types = [<class 'dict'>, <class 'str'>, <class 'clisops.parameter._utils.TimeComponents'>, <class 'NoneType'>]

asdict()

Return a dictionary of the time components.

Returns:

dict – A dictionary with a single key “time_components” containing the time components.

get_bounds()

Return a tuple of the (start, end) times, calculated from the value of the parameter.

Either will default to None.

Returns:

tuple – A tuple containing the start and end times in ISO format. If no year is specified, both will be None.

clisops.parameter.time_parameter module

Time Parameter Class.

class clisops.parameter.time_parameter.TimeParameter(input)

Bases: _BaseIntervalOrSeriesParameter

Class for time parameter used in subsetting operation.

Time can be input as:

A string of slash separated values: “2085-01-01T12:00:00Z/2120-12-30T12:00:00Z”.

A sequence of strings: e.g. (“2085-01-01T12:00:00Z”, “2120-12-30T12:00:00Z”).

A time input must be 2 values.

If using a string input a trailing slash indicates you want to use the earliest/latest time of the dataset. e.g. “2085-01-01T12:00:00Z/” will subset from 01/01/2085 to the final time in the dataset.

Validates the times input and parses the values into isoformat.

_parse_as_interval()

_parse_as_series()

asdict()

Return a dictionary of the time values.

Returns:

dict or None – A dictionary with keys “start_time” and “end_time” for interval type, or “time_values” for series type. If the parameter is of type “none”, returns an empty dictionary.

get_bounds()

Return a tuple of the (start, end) times, calculated from the value of the parameter.

Either will default to None.

Returns:

tuple – A tuple containing the start and end times in ISO format. If no year is specified, both will be None.