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

as_dimset()

Convert the Dimension to a DimensionSet containing only this Dimension.

Return type:

DimensionSet

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

append(new_dim, inplace=False)

Add a new dimension to the set at the end.

Parameters:

  • new_dim (Dimension) – The new dimension to add

  • 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 new dimension added

Return type:

DimensionSet | None

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

extend(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.

Parameters:

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

insert(index, new_dim, inplace=False)

Insert a new dimension to the set at the given index.

Parameters:

  • index (int) – The index at which to insert the new dimension

  • new_dim (Dimension) – The new dimension to add

  • 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 new dimension added

Return type:

DimensionSet | None

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.

prepare_other(other)

Check that the other object is a DimensionSet or Dimension, and convert if necessary.

Parameters:

other ('DimensionSet' | Dimension)

Return type:

DimensionSet

prepend(new_dim, inplace=False)

Add a new dimension to the set at the beginning. :param new_dim: The new dimension to add :type new_dim: Dimension :param inplace: If True, the operation is performed in place, otherwise a new DimensionSet is returned. Defaults to False. :type inplace: bool, optional

Returns:

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

Parameters:
Return type:

DimensionSet | None

remove(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

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

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 shape: tuple[int]

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

property string

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