Dimensions and DimensionSets

Dimensions

Dimension objects are what flodym datasets are differentiated by.

They are defined by a name, index letter, and their items. The index letters must have length one, i.e. only be one letter.

Optionally, a data type can be given. If doing so, it is ensured that all items have this data type. When loading items from file, it can be useful to check that for example years are integers and not converted to strings.

from flodym import Dimension

regions = Dimension(name="Region", letter="r", items=["EU", "US", "MEX"])

Never give Dimension objects with different item sets the same name or letter, even though it is tempting!

# historic and future time
time = Dimension(name="Time", letter="t", items=["2010", "2020", "2030"])
# Historic time - a subset of time

# WRONG! (same letter t)
historic_time = Dimension(name="Historic Time", letter="t", items=["2010", "2020"])

# Correct
historic_time = Dimension(name="Historic Time", letter="h", items=["2010", "2020"])

DimensionSets

Multiple dimensions are grouped in a DimensionSet object:

from flodym import DimensionSet

dims = DimensionSet(
    dim_list=[
        Dimension(name="Region", letter="r", items=["EU", "US", "MEX"]),
        Dimension(name="Product", letter="p", items=["A", "B"]),
        Dimension(name="Time", letter="t", items=[2020]),
    ]
)

The MFASystem class has a dims attribute, which is a DimensionSet object containing all dimensions ever used in the system.

Each FlodymArray object also has a dims attribute, with a subset of dimensions that this array is defined over.

Subsets and single dimensions can be extracted by indexing. A single index in square brackets returns a Dimension. Several indexes in the square brackets, or a tuple (even with a single item inside), return a DimensionSet.

item_by_letter = dims["r"]
print(f"Item by letter | type: {type(item_by_letter)}, name: {item_by_letter.name}")

item_by_name = dims["Region"]
print(f"Item by name | type: {type(item_by_name)}, name: {item_by_name.name}")

subset = dims["r", "p"]
print(f"Subset | type: {type(subset)}, names: {subset.names}")

subset_size_1_tuple = dims[("r",)]
print(f"Size 1 subset | type: {type(subset_size_1_tuple)}, names: {subset_size_1_tuple.names}")

Item by letter | type: <class 'flodym.dimensions.Dimension'>, name: Region
Item by name | type: <class 'flodym.dimensions.Dimension'>, name: Region
Subset | type: <class 'flodym.dimensions.DimensionSet'>, names: ('Region', 'Product')
Size 1 subset | type: <class 'flodym.dimensions.DimensionSet'>, names: ('Region',)

DimensionSet objects have several attributes (like names or letters) and a range of methods to modify or combine them. For a full list and documentation, refer to the API Reference. Here we list the few most important ones.

# Transform single Dimension to DimensionSet
dim_as_set = dims["r"].as_dimset()
print(f"Dimension as DimensionSet | type: {type(dim_as_set)}, names: {dim_as_set.names}")

# Set union of two DimensionSets
combined_dims = dims["r", "p"] | dims["p", "t"]
print(f"Combined DimensionSet | type: {type(combined_dims)}, names: {combined_dims.names}")

# Set intersection of two DimensionSets
intersected_dims = dims["r", "p"] & dims["p", "t"]
print(f"Intersected DimensionSet | type: {type(intersected_dims)}, names: {intersected_dims.names}")

# Remove dimensions from DimensionSet
reduced_dims = dims - dims["t"]
print(f"Reduced DimensionSet | type: {type(reduced_dims)}, names: {reduced_dims.names}")