Dimension and DimensionSet

pydantic model flodym.Dimension

One of multiple dimensions over which MFA arrays are defined.

Defined by a name, a letter for shorter addressing, and a list of items.

Example

>>> from flodym import Dimension
>>> regions = Dimension(name='Region', letter='r', items=['Earth', 'Moon', 'Sun'])

The list of items can be loaded using a flodym.DataReader object, or set directly, for example if a subset of an existing dimension is formed.

Fields:

  • dtype (type | None)

  • items (list)

  • letter (str)

  • name (str)

Validators:

  • items_have_datatype » all fields

field dtype: type | None = None

If given, a check is performed that all items have this datatype. Recommended for safety, especially in ambiguous cases such as calendar years (int or str)

field items: list [Required]

A list of items that are resolved along the dimension, e.g. years or regions

field letter: str [Required]

A single index letter for shorter addressing of the dimension

Constraints:

  • min_length = 1

  • max_length = 1

field name: str [Required]

The full name of the dimension

Constraints:

  • min_length = 2

classmethod from_df(df, definition)

Create Dimension object from definition and a pandas DataFrame for the items.

Parameters:

  • df (pd.DataFrame) – A single-column or single-row data frame, which is transformed to the dimension items.

  • definition (DimensionDefinition) – The definition of the dimension.

Returns:

The dimension object.

Return type:

Dimension

classmethod from_np(data, definition)

Create Dimension object from definition and a numpy array for the items. Performs checks on the array and transforms to list of items.

Parameters:

  • data (np.ndarray) – A numpy array where only one dimension exceeds size 1.

  • definition (DimensionDefinition) – The definition object

Returns:

The dimension object.

Return type:

Dimension

index(item)

Return the index of an item in the dimension.

Return type:

int

is_subset(other)

Check if the items of this dimension are a subset of the items of another dimension.

Parameters:

other (Dimension)

is_superset(other)

Check if the items of this dimension are a superset of the items of another dimension.

Parameters:

other (Dimension)

validator items_have_datatype  »  all fields

If a datatype is specified, check that all items have this datatype.

property len: int

The number of items in the dimension.

pydantic model flodym.DimensionSet

A set of Dimension objects which MFA arrays are defined over.

Example

>>> from flodym import Dimension, DimensionSet
>>> regions = Dimension(name='Region', letter='r', items=['Earth', 'Moon', 'Sun'])
>>> time = Dimension(name='Time', letter='t', items=[1990, 2000, 2010, 2020, 2030])
>>> dimensions = DimensionSet([regions, time])

It is expected that DimensionSet instances are created via the flodym.DataReader.

>>> from flodym import DataReader, DimensionDefinition, Dimension
>>> class MyDataReader(DataReader):
>>>    def read_dimension(self, dimension_definition: DimensionDefinition) -> Dimension:
>>>        if dimension_definition.letter == 't':
>>>            return Dimension(name='Time', letter='t', items=[1990, 2000, 2010, 2020, 2030])
>>>        elif dimension_definition.letter == 'r':
>>>            return Dimension(name='Region', letter='r', items=['Earth', 'Moon', 'Sun'])
>>>        raise ValueError('No data available for desired dimension')
>>> data_reader = MyDataReader()
>>> time_definition = DimensionDefinition(name='Time', letter='t', dtype=int)
>>> region_definition = DimensionDefinition(name='Region', letter='r', dtype=str)
>>> definitions = [time_definition, region_definition]
>>> dimensions = data_reader.read_dimensions(dimension_definitions=definitions)
Fields:

  • dim_list (list[flodym.dimensions.Dimension])

Validators:

  • no_repeated_dimensions » all fields

field dim_list: list[Dimension] [Required]

A list of Dimension objects defining the set

difference_with(other)

Get the set difference of two DimensionSets.

Parameters:

other (DimensionSet) – The other DimensionSet to compare with

Returns:

The difference of the two DimensionSets

Return type:

DimensionSet

drop(key, inplace=False)

Remove a dimension from the set.

Parameters:

  • key (str) – The name, index or letter of the dimension to drop

  • inplace (bool, optional) – If True, the operation is performed in place, otherwise a new DimensionSet is returned. Defaults to False.

Returns:

None if inplace=True, otherwise a new DimensionSet with the dimension removed

Return type:

DimensionSet | None

expand_by(added_dims)

Expands the DimensionSet by adding new dimensions to it.

Parameters:

added_dims (list[Dimension])

Return type:

DimensionSet

get_subset(dims=None)

Selects Dimension objects from the object attribute dim_list, according to the dims passed, which can be either letters or names. Returns a copy if dims are not given.

Parameters:

dims (tuple | None)

Return type:

DimensionSet

index(key)

Return the index of a dimension in the set.

intersect_with(other)

Get the intersection of two DimensionSets.

Parameters:

other (DimensionSet) – The other DimensionSet to intersect with

Returns:

The intersection of the two DimensionSets

Return type:

DimensionSet

validator no_repeated_dimensions  »  all fields

Check that all dimensions have unique letters.

replace(key, new_dim, inplace=False)

Replace a dimension in the set with a new one.

Parameters:

  • key (str) – The name, index or letter of the dimension to replace

  • new_dim (Dimension) – The new dimension to replace the old one

  • inplace (bool, optional) – If True, the operation is performed in place, otherwise a new DimensionSet is returned. Defaults to False.

Returns:

None if inplace=True, otherwise a new DimensionSet with the dimension replaced

shape(keys=None)

get the shape of the array that would be created with the dimensions in the set

Parameters:

keys (tuple, optional) – the names or letters of the dimensions to get the shape of. If None, all dimensions are used. Defaults to None.

size(key)

get the number of items in a dimension

Parameters:

key (str) – the name or letter of the dimension to get the size of

union_with(other)

Get the union of two DimensionSets.

Parameters:

other (DimensionSet) – The other DimensionSet to unite with

Returns:

The union of the two DimensionSets

Return type:

DimensionSet

property letters

A tuple of the letters of the dimensions in the set.

property names

A tuple of the names of the dimensions in the set.

property ndim

the number of dimensions in the set

property string

The letters of the dimensions in the set concatenated to a single string.