FlodymArrays

pydantic model flodym.FlodymArray

Parent class for an array with pre-defined dimensions, which are addressed by name. Operations between different multi-dimensional arrays can than be performed conveniently, as the dimensions are automatically matched.

In order to ‘fix’ the dimensions of the array, the array has to be ‘declared’ by calling the FlodymArray object constructor with a set of dimensions before working with it. Basic mathematical operations between FlodymArrays are defined, which return a FlodymArray object as a result.

In order to set the values of a FlodymArray object to that of another one, the ellipsis slice (‘[…]’) can be used, e.g. foo[…] = bar. This ensures that the dimensionality of the array (foo) is not changed, and that the dimensionality of the right-hand side FlodymArray (bar) is consistent. While the syntaxes like of ‘foo = bar + baz’ are also possible (where ‘bar’ and ‘baz’ are FlodymArrays), it is not recommended, as it provides no control over the dimensionality of ‘foo’. Use foo[…] = bar + baz instead.

The values of the FlodymArray object are stored in a numpy array, and can be accessed directly via the ‘values’ attribute. So if type(bar) is np.ndarray, the operation foo.values[…] = bar is also possible. It is not recommended to use ‘foo.values = bar’ without the slice, as this might change the dimensionality of foo.values.

Subsets of arrays can be set or retrieved. Here, slicing information is passed instead of the ellipsis to the square brackets of the FlodymArray, i.e. foo[keys] = bar or foo = bar[keys]. For details on the allowed values of ‘keys’, see the docstring of the SubArrayHandler class.

The dimensions of a FlodymArray stored as a flodym.DimensionSet object in the ‘dims’ attribute.

Config:

  • arbitrary_types_allowed: bool = True

  • protected_namespaces: tuple = ()

Fields:

  • dims (flodym.dimensions.DimensionSet)

  • name (str | None)

  • values (numpy.ndarray | numbers.Number | None)

Validators:

  • copy_dims » all fields

  • validate_values » all fields

field dims: DimensionSet [Required]

Dimensions of the FlodymArray.

field name: str | None = 'unnamed'

Name of the FlodymArray.

field values: ndarray | Number | None = None

Values of the FlodymArray. Must have the same shape as the dimensions of the FlodymArray. If None, an array of zeros is created.

abs(inplace=False)
Parameters:

inplace (bool)

apply(func, kwargs={}, inplace=False)

Apply a function to the values of the FlodymArray.

Parameters:

  • func (callable) – Function to apply to the values. Must be a function that can be applied to a numpy array, and return a numpy array of the same shape.

  • kwargs (dict) – Keyword argument dictionary to pass to the function.

  • inplace (bool, optional) – Whether to apply the function in place. Defaults to False.

Returns:

FlodymArray object with the values transformed by the function.

Return type:

FlodymArray

cast_to(target_dims)

Cast the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the FlodymArray to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The FlodymArray cast to the new dimensions.

Return type:

FlodymArray

cast_values_to(target_dims)

Cast the values of the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the values to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The values of the FlodymArray cast to the new dimensions.

Return type:

np.ndarray

validator copy_dims  »  all fields

Ensure dims is always copied to avoid shared references.

cumsum(dim_letter, inplace=False)

Calculate the cumulative sum along a dimension.

Parameters:

  • dim_letter (str) – Dimension letter to calculate the cumulative sum along.

  • inplace (bool, optional) – Whether to apply the cumulative sum in place. Defaults to False.

Returns:

FlodymArray object with the cumulative sum along the given dimension.

Return type:

FlodymArray

classmethod from_df(dims, df, allow_missing_values=False, allow_extra_values=False, **kwargs)

Create a FlodymArray object from a DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • dims (DimensionSet) – Dimensions of the FlodymArray

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. tows with index items not present in the FlodymArray dimension items. Defaults to False.

Returns:

FlodymArray object with the values from the DataFrame

Return type:

FlodymArray

classmethod from_dims_superset(dims_superset, dim_letters=None, **kwargs)

Create a FlodymArray object from a superset of dimensions, by specifying which dimensions to take.

Parameters:

  • dims_superset (DimensionSet) – DimensionSet from which the objects dimensions are derived

  • dim_letters (tuple | None) – specify which dimensions to take from dims_superset

  • kwargs – additional keyword arguments passed to the FlodymArray constructor

Returns:

cls instance

Return type:

FlodymArray

classmethod full(dims, fill_value, **kwargs)

Create a FlodymArray filled with a constant value for the provided dimensions.

Parameters:

  • dims (DimensionSet) – DimensionSet defining the dimensions of the FlodymArray.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of dims.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray filled with the specified value.

Return type:

FlodymArray

classmethod full_like(other, fill_value, dtype=None, **kwargs)

Create a FlodymArray filled with a constant value, matching another array’s dimensions.

Parameters:

  • other (FlodymArray) – FlodymArray whose dimensions will be used for the new array.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of other.

  • dtype (Optional[Union[type, np.dtype]], optional) – Data type of the new array. If None, the data type of fill_value is used. Defaults to None.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray with the same dimensions as other,

filled with the specified value.

Return type:

FlodymArray

get_shares_over(dim_letters)

Get shares of the FlodymArray along a tuple of dimensions, indicated by letter.

Parameters:

dim_letters (tuple)

Return type:

FlodymArray

items_where(condition)

Get the dimension item tuples of all entries where a condition is met.

Parameters:

condition (Callable) – A function that takes the values of the FlodymArray and returns a boolean array.

Returns:

A 2d numpy array of strings, where each row corresponds to a dimension item tuple

Return type:

np.array

maximum(other)
minimum(other)
classmethod scalar(value, **kwargs)

Create a scalar (zero-dimensional) FlodymArray.

Parameters:

  • value (Number) – The scalar value to store in the FlodymArray.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A zero-dimensional FlodymArray containing the scalar value.

Return type:

FlodymArray

set_values(values)

Set the values of the FlodymArray and check if the shape is correct.

For safety reasons, broadcasting smaller arrays is not allowed, i.e. the shape of the values must match the shape of the FlodymArray.

As a less safe but more flexible alternative, you can use e.g. flodym_array.values[…] = foo to set the values directly.

Parameters:

values (ndarray)

set_values_from_df(df_in, allow_missing_values=False, allow_extra_values=False)

Set the values of the FlodymArray from a pandas DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. rows with index items not present in the FlodymArray dimension items. Defaults to False.

  • df_in (DataFrame)

sign(inplace=False)
Parameters:

inplace (bool)

split(dim_letter)

Reverse the flodym_array_stack, returns a dictionary of FlodymArray objects associated with the item in the dimension that has been split. Method can be applied to classes FlodymArray, StockArray, Parameter and Flow.

Parameters:

dim_letter (str)

Return type:

dict

sum_over(sum_over_dims=())

Return the FlodymArray summed over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the FlodymArray object is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_to(result_dims=())

Return the FlodymArray summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of the dimensions to sum to. If not given, the sum over all dimensions is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_values()

Return the sum of all values in the FlodymArray.

sum_values_over(sum_over_dims=())

Return the sum of the FlodymArray over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the values array is returned.

Returns:

The partially summed values of the FlodymArray.

Return type:

np.ndarray

sum_values_to(result_dims=())

Return the values of the FlodymArray partially summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, the sum over all dimensions is returned.

to_df(index=True, dim_to_columns=None, sparse=False)

Export the FlodymArray to a pandas DataFrame.

Parameters:

  • index (bool, optional) – Whether to include the dimension items as a Multi-Index (True) or as columns of the DataFrame (False). Defaults to True.

  • dim_to_columns (str, optional) – Name of the dimension the items of which are to form the columns of the DataFrame. If not given, the DataFrame is returned in long format with a single ‘value’ column.

  • sparse (bool, optional) – Whether to return a sparse DataFrame with only non-zero values. Defaults to False.

Returns:

DataFrame representation of the FlodymArray.

Return type:

pd.DataFrame

validator validate_values  »  all fields
property shape: tuple[int]

The shape of the array, determined by the dimensions.

property size: int

The number of elements in the array.

pydantic model flodym.Flow

The values of Flow objects are the main computed outcome of the MFA system. A Flow object connects two Process objects. The name of the Flow object is set as a combination of the names of the two processes it connects.

Flow is a subclass of FlodymArray, so most of its methods are inherited.

Example

>>> from flodym import DimensionSet, Flow, Process
>>> goods = Dimension(name='Good', letter='g', items=['Car', 'Bus', 'Bicycle'])
>>> time = Dimension(name='Time', letter='t', items=[1990, 2000, 2010, 2020, 2030])
>>> dimensions = DimensionSet([goods, time])
>>> fabrication = Process(name='fabrication', id=2)
>>> use = Process(name='use', id=3)
>>> flow = Flow(from_process='fabrication', to_process='use', dims=dimensions)

In the above example, we did not pass any values when initialising the Flow instance, and these would get filled with zeros. See the validation (filling) method in FlodymArray.

Config:

  • arbitrary_types_allowed: bool = True

  • protected_namespaces: tuple = ()

Fields:

  • dims ()

  • from_process (flodym.processes.Process)

  • name ()

  • to_process (flodym.processes.Process)

  • values ()

Validators:

  • copy_dims » all fields

  • validate_values » all fields

field dims: DimensionSet [Required]

Dimensions of the FlodymArray.

field from_process: Process [Required]

Process from which the flow originates.

field name: str | None = 'unnamed'

Name of the FlodymArray.

field to_process: Process [Required]

Process to which the flow goes.

field values: np.ndarray | Number | None = None

Values of the FlodymArray. Must have the same shape as the dimensions of the FlodymArray. If None, an array of zeros is created.

abs(inplace=False)
Parameters:

inplace (bool)

apply(func, kwargs={}, inplace=False)

Apply a function to the values of the FlodymArray.

Parameters:

  • func (callable) – Function to apply to the values. Must be a function that can be applied to a numpy array, and return a numpy array of the same shape.

  • kwargs (dict) – Keyword argument dictionary to pass to the function.

  • inplace (bool, optional) – Whether to apply the function in place. Defaults to False.

Returns:

FlodymArray object with the values transformed by the function.

Return type:

FlodymArray

cast_to(target_dims)

Cast the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the FlodymArray to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The FlodymArray cast to the new dimensions.

Return type:

FlodymArray

cast_values_to(target_dims)

Cast the values of the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the values to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The values of the FlodymArray cast to the new dimensions.

Return type:

np.ndarray

validator copy_dims  »  all fields

Ensure dims is always copied to avoid shared references.

cumsum(dim_letter, inplace=False)

Calculate the cumulative sum along a dimension.

Parameters:

  • dim_letter (str) – Dimension letter to calculate the cumulative sum along.

  • inplace (bool, optional) – Whether to apply the cumulative sum in place. Defaults to False.

Returns:

FlodymArray object with the cumulative sum along the given dimension.

Return type:

FlodymArray

classmethod from_df(dims, df, allow_missing_values=False, allow_extra_values=False, **kwargs)

Create a FlodymArray object from a DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • dims (DimensionSet) – Dimensions of the FlodymArray

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. tows with index items not present in the FlodymArray dimension items. Defaults to False.

Returns:

FlodymArray object with the values from the DataFrame

Return type:

FlodymArray

classmethod from_dims_superset(dims_superset, dim_letters=None, **kwargs)

Create a FlodymArray object from a superset of dimensions, by specifying which dimensions to take.

Parameters:

  • dims_superset (DimensionSet) – DimensionSet from which the objects dimensions are derived

  • dim_letters (tuple | None) – specify which dimensions to take from dims_superset

  • kwargs – additional keyword arguments passed to the FlodymArray constructor

Returns:

cls instance

Return type:

FlodymArray

classmethod full(dims, fill_value, **kwargs)

Create a FlodymArray filled with a constant value for the provided dimensions.

Parameters:

  • dims (DimensionSet) – DimensionSet defining the dimensions of the FlodymArray.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of dims.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray filled with the specified value.

Return type:

FlodymArray

classmethod full_like(other, fill_value, dtype=None, **kwargs)

Create a FlodymArray filled with a constant value, matching another array’s dimensions.

Parameters:

  • other (FlodymArray) – FlodymArray whose dimensions will be used for the new array.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of other.

  • dtype (Optional[Union[type, np.dtype]], optional) – Data type of the new array. If None, the data type of fill_value is used. Defaults to None.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray with the same dimensions as other,

filled with the specified value.

Return type:

FlodymArray

get_shares_over(dim_letters)

Get shares of the FlodymArray along a tuple of dimensions, indicated by letter.

Parameters:

dim_letters (tuple)

Return type:

FlodymArray

items_where(condition)

Get the dimension item tuples of all entries where a condition is met.

Parameters:

condition (Callable) – A function that takes the values of the FlodymArray and returns a boolean array.

Returns:

A 2d numpy array of strings, where each row corresponds to a dimension item tuple

Return type:

np.array

maximum(other)
minimum(other)
classmethod scalar(value, **kwargs)

Create a scalar (zero-dimensional) FlodymArray.

Parameters:

  • value (Number) – The scalar value to store in the FlodymArray.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A zero-dimensional FlodymArray containing the scalar value.

Return type:

FlodymArray

set_values(values)

Set the values of the FlodymArray and check if the shape is correct.

For safety reasons, broadcasting smaller arrays is not allowed, i.e. the shape of the values must match the shape of the FlodymArray.

As a less safe but more flexible alternative, you can use e.g. flodym_array.values[…] = foo to set the values directly.

Parameters:

values (ndarray)

set_values_from_df(df_in, allow_missing_values=False, allow_extra_values=False)

Set the values of the FlodymArray from a pandas DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. rows with index items not present in the FlodymArray dimension items. Defaults to False.

  • df_in (DataFrame)

sign(inplace=False)
Parameters:

inplace (bool)

split(dim_letter)

Reverse the flodym_array_stack, returns a dictionary of FlodymArray objects associated with the item in the dimension that has been split. Method can be applied to classes FlodymArray, StockArray, Parameter and Flow.

Parameters:

dim_letter (str)

Return type:

dict

sum_over(sum_over_dims=())

Return the FlodymArray summed over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the FlodymArray object is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_to(result_dims=())

Return the FlodymArray summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of the dimensions to sum to. If not given, the sum over all dimensions is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_values()

Return the sum of all values in the FlodymArray.

sum_values_over(sum_over_dims=())

Return the sum of the FlodymArray over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the values array is returned.

Returns:

The partially summed values of the FlodymArray.

Return type:

np.ndarray

sum_values_to(result_dims=())

Return the values of the FlodymArray partially summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, the sum over all dimensions is returned.

to_df(index=True, dim_to_columns=None, sparse=False)

Export the FlodymArray to a pandas DataFrame.

Parameters:

  • index (bool, optional) – Whether to include the dimension items as a Multi-Index (True) or as columns of the DataFrame (False). Defaults to True.

  • dim_to_columns (str, optional) – Name of the dimension the items of which are to form the columns of the DataFrame. If not given, the DataFrame is returned in long format with a single ‘value’ column.

  • sparse (bool, optional) – Whether to return a sparse DataFrame with only non-zero values. Defaults to False.

Returns:

DataFrame representation of the FlodymArray.

Return type:

pd.DataFrame

validator validate_values  »  all fields
property from_process_id

ID of the process from which the flow originates.

property shape: tuple[int]

The shape of the array, determined by the dimensions.

property size: int

The number of elements in the array.

property to_process_id

ID of the process to which the flow goes.

pydantic model flodym.StockArray

Stocks allow accumulation of material at a process, i.e. between two flows.

StockArray inherits all its functionality from FlodymArray. StockArray’s are used in the flodym.Stock for the inflow, outflow and stock.

Config:

  • arbitrary_types_allowed: bool = True

  • protected_namespaces: tuple = ()

Fields:

  • dims ()

  • name ()

  • values ()

Validators:

  • copy_dims » all fields

  • validate_values » all fields

field dims: DimensionSet [Required]

Dimensions of the FlodymArray.

field name: str | None = 'unnamed'

Name of the FlodymArray.

field values: np.ndarray | Number | None = None

Values of the FlodymArray. Must have the same shape as the dimensions of the FlodymArray. If None, an array of zeros is created.

abs(inplace=False)
Parameters:

inplace (bool)

apply(func, kwargs={}, inplace=False)

Apply a function to the values of the FlodymArray.

Parameters:

  • func (callable) – Function to apply to the values. Must be a function that can be applied to a numpy array, and return a numpy array of the same shape.

  • kwargs (dict) – Keyword argument dictionary to pass to the function.

  • inplace (bool, optional) – Whether to apply the function in place. Defaults to False.

Returns:

FlodymArray object with the values transformed by the function.

Return type:

FlodymArray

cast_to(target_dims)

Cast the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the FlodymArray to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The FlodymArray cast to the new dimensions.

Return type:

FlodymArray

cast_values_to(target_dims)

Cast the values of the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the values to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The values of the FlodymArray cast to the new dimensions.

Return type:

np.ndarray

validator copy_dims  »  all fields

Ensure dims is always copied to avoid shared references.

cumsum(dim_letter, inplace=False)

Calculate the cumulative sum along a dimension.

Parameters:

  • dim_letter (str) – Dimension letter to calculate the cumulative sum along.

  • inplace (bool, optional) – Whether to apply the cumulative sum in place. Defaults to False.

Returns:

FlodymArray object with the cumulative sum along the given dimension.

Return type:

FlodymArray

classmethod from_df(dims, df, allow_missing_values=False, allow_extra_values=False, **kwargs)

Create a FlodymArray object from a DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • dims (DimensionSet) – Dimensions of the FlodymArray

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. tows with index items not present in the FlodymArray dimension items. Defaults to False.

Returns:

FlodymArray object with the values from the DataFrame

Return type:

FlodymArray

classmethod from_dims_superset(dims_superset, dim_letters=None, **kwargs)

Create a FlodymArray object from a superset of dimensions, by specifying which dimensions to take.

Parameters:

  • dims_superset (DimensionSet) – DimensionSet from which the objects dimensions are derived

  • dim_letters (tuple | None) – specify which dimensions to take from dims_superset

  • kwargs – additional keyword arguments passed to the FlodymArray constructor

Returns:

cls instance

Return type:

FlodymArray

classmethod full(dims, fill_value, **kwargs)

Create a FlodymArray filled with a constant value for the provided dimensions.

Parameters:

  • dims (DimensionSet) – DimensionSet defining the dimensions of the FlodymArray.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of dims.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray filled with the specified value.

Return type:

FlodymArray

classmethod full_like(other, fill_value, dtype=None, **kwargs)

Create a FlodymArray filled with a constant value, matching another array’s dimensions.

Parameters:

  • other (FlodymArray) – FlodymArray whose dimensions will be used for the new array.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of other.

  • dtype (Optional[Union[type, np.dtype]], optional) – Data type of the new array. If None, the data type of fill_value is used. Defaults to None.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray with the same dimensions as other,

filled with the specified value.

Return type:

FlodymArray

get_shares_over(dim_letters)

Get shares of the FlodymArray along a tuple of dimensions, indicated by letter.

Parameters:

dim_letters (tuple)

Return type:

FlodymArray

items_where(condition)

Get the dimension item tuples of all entries where a condition is met.

Parameters:

condition (Callable) – A function that takes the values of the FlodymArray and returns a boolean array.

Returns:

A 2d numpy array of strings, where each row corresponds to a dimension item tuple

Return type:

np.array

maximum(other)
minimum(other)
classmethod scalar(value, **kwargs)

Create a scalar (zero-dimensional) FlodymArray.

Parameters:

  • value (Number) – The scalar value to store in the FlodymArray.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A zero-dimensional FlodymArray containing the scalar value.

Return type:

FlodymArray

set_values(values)

Set the values of the FlodymArray and check if the shape is correct.

For safety reasons, broadcasting smaller arrays is not allowed, i.e. the shape of the values must match the shape of the FlodymArray.

As a less safe but more flexible alternative, you can use e.g. flodym_array.values[…] = foo to set the values directly.

Parameters:

values (ndarray)

set_values_from_df(df_in, allow_missing_values=False, allow_extra_values=False)

Set the values of the FlodymArray from a pandas DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. rows with index items not present in the FlodymArray dimension items. Defaults to False.

  • df_in (DataFrame)

sign(inplace=False)
Parameters:

inplace (bool)

split(dim_letter)

Reverse the flodym_array_stack, returns a dictionary of FlodymArray objects associated with the item in the dimension that has been split. Method can be applied to classes FlodymArray, StockArray, Parameter and Flow.

Parameters:

dim_letter (str)

Return type:

dict

sum_over(sum_over_dims=())

Return the FlodymArray summed over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the FlodymArray object is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_to(result_dims=())

Return the FlodymArray summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of the dimensions to sum to. If not given, the sum over all dimensions is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_values()

Return the sum of all values in the FlodymArray.

sum_values_over(sum_over_dims=())

Return the sum of the FlodymArray over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the values array is returned.

Returns:

The partially summed values of the FlodymArray.

Return type:

np.ndarray

sum_values_to(result_dims=())

Return the values of the FlodymArray partially summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, the sum over all dimensions is returned.

to_df(index=True, dim_to_columns=None, sparse=False)

Export the FlodymArray to a pandas DataFrame.

Parameters:

  • index (bool, optional) – Whether to include the dimension items as a Multi-Index (True) or as columns of the DataFrame (False). Defaults to True.

  • dim_to_columns (str, optional) – Name of the dimension the items of which are to form the columns of the DataFrame. If not given, the DataFrame is returned in long format with a single ‘value’ column.

  • sparse (bool, optional) – Whether to return a sparse DataFrame with only non-zero values. Defaults to False.

Returns:

DataFrame representation of the FlodymArray.

Return type:

pd.DataFrame

validator validate_values  »  all fields
property shape: tuple[int]

The shape of the array, determined by the dimensions.

property size: int

The number of elements in the array.

pydantic model flodym.Parameter

Parameter’s can be used when defining the flodym.MFASystem.compute() of a specific MFA system, to quantify the links between specific flodym.Stock and Flow objects, for example as the share of flows that go into one branch when the flow splits at a process.

Parameter inherits all its functionality from FlodymArray.

Config:

  • arbitrary_types_allowed: bool = True

  • protected_namespaces: tuple = ()

Fields:

  • dims ()

  • name ()

  • values ()

Validators:

  • copy_dims » all fields

  • validate_values » all fields

field dims: DimensionSet [Required]

Dimensions of the FlodymArray.

field name: str | None = 'unnamed'

Name of the FlodymArray.

field values: np.ndarray | Number | None = None

Values of the FlodymArray. Must have the same shape as the dimensions of the FlodymArray. If None, an array of zeros is created.

abs(inplace=False)
Parameters:

inplace (bool)

apply(func, kwargs={}, inplace=False)

Apply a function to the values of the FlodymArray.

Parameters:

  • func (callable) – Function to apply to the values. Must be a function that can be applied to a numpy array, and return a numpy array of the same shape.

  • kwargs (dict) – Keyword argument dictionary to pass to the function.

  • inplace (bool, optional) – Whether to apply the function in place. Defaults to False.

Returns:

FlodymArray object with the values transformed by the function.

Return type:

FlodymArray

cast_to(target_dims)

Cast the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the FlodymArray to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The FlodymArray cast to the new dimensions.

Return type:

FlodymArray

cast_values_to(target_dims)

Cast the values of the FlodymArray to a new set of dimensions.

Parameters:

target_dims (DimensionSet) – New dimensions to cast the values to. Must be given as a DimensionSet object, as the new dimensions are otherwise not known to the FlodymArray object.

Returns:

The values of the FlodymArray cast to the new dimensions.

Return type:

np.ndarray

validator copy_dims  »  all fields

Ensure dims is always copied to avoid shared references.

cumsum(dim_letter, inplace=False)

Calculate the cumulative sum along a dimension.

Parameters:

  • dim_letter (str) – Dimension letter to calculate the cumulative sum along.

  • inplace (bool, optional) – Whether to apply the cumulative sum in place. Defaults to False.

Returns:

FlodymArray object with the cumulative sum along the given dimension.

Return type:

FlodymArray

classmethod from_df(dims, df, allow_missing_values=False, allow_extra_values=False, **kwargs)

Create a FlodymArray object from a DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • dims (DimensionSet) – Dimensions of the FlodymArray

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. tows with index items not present in the FlodymArray dimension items. Defaults to False.

Returns:

FlodymArray object with the values from the DataFrame

Return type:

FlodymArray

classmethod from_dims_superset(dims_superset, dim_letters=None, **kwargs)

Create a FlodymArray object from a superset of dimensions, by specifying which dimensions to take.

Parameters:

  • dims_superset (DimensionSet) – DimensionSet from which the objects dimensions are derived

  • dim_letters (tuple | None) – specify which dimensions to take from dims_superset

  • kwargs – additional keyword arguments passed to the FlodymArray constructor

Returns:

cls instance

Return type:

FlodymArray

classmethod full(dims, fill_value, **kwargs)

Create a FlodymArray filled with a constant value for the provided dimensions.

Parameters:

  • dims (DimensionSet) – DimensionSet defining the dimensions of the FlodymArray.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of dims.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray filled with the specified value.

Return type:

FlodymArray

classmethod full_like(other, fill_value, dtype=None, **kwargs)

Create a FlodymArray filled with a constant value, matching another array’s dimensions.

Parameters:

  • other (FlodymArray) – FlodymArray whose dimensions will be used for the new array.

  • fill_value (Union[Number, np.ndarray]) – Value to fill the array with. Can be a scalar or an array that is broadcastable to the shape of other.

  • dtype (Optional[Union[type, np.dtype]], optional) – Data type of the new array. If None, the data type of fill_value is used. Defaults to None.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A new FlodymArray with the same dimensions as other,

filled with the specified value.

Return type:

FlodymArray

get_shares_over(dim_letters)

Get shares of the FlodymArray along a tuple of dimensions, indicated by letter.

Parameters:

dim_letters (tuple)

Return type:

FlodymArray

items_where(condition)

Get the dimension item tuples of all entries where a condition is met.

Parameters:

condition (Callable) – A function that takes the values of the FlodymArray and returns a boolean array.

Returns:

A 2d numpy array of strings, where each row corresponds to a dimension item tuple

Return type:

np.array

maximum(other)
minimum(other)
classmethod scalar(value, **kwargs)

Create a scalar (zero-dimensional) FlodymArray.

Parameters:

  • value (Number) – The scalar value to store in the FlodymArray.

  • **kwargs – Additional keyword arguments passed to the FlodymArray constructor (e.g., name).

Returns:

A zero-dimensional FlodymArray containing the scalar value.

Return type:

FlodymArray

set_values(values)

Set the values of the FlodymArray and check if the shape is correct.

For safety reasons, broadcasting smaller arrays is not allowed, i.e. the shape of the values must match the shape of the FlodymArray.

As a less safe but more flexible alternative, you can use e.g. flodym_array.values[…] = foo to set the values directly.

Parameters:

values (ndarray)

set_values_from_df(df_in, allow_missing_values=False, allow_extra_values=False)

Set the values of the FlodymArray from a pandas DataFrame. In case of errors, turning on debug logging might help to understand the process.

Parameters:

  • df (DataFrame) – pandas DataFrame containing the values of the FlodymArray. Dimensions of the named dim array can be given in DataFrame columns or the index. The DataFrame can be in long or wide format, that is there can either be one value column, or the value columns are named by items of one FlodymArray dimension. If dimension names or letters are not given in the respective index or column, they are inferred from the items of the dimensions of the FlodymArray. It is advisable to give the dimension names in the DataFrame, as this makes the error messages more informative if there are typos in the items or if items are missing. Ordering of rows and columns is arbitrary, but the items across each dimension must be given. Dimensions with only one item do not need to be given in the DataFrame. Supersets of dimensions (i.e. additional values) will lead to an error.

  • allow_missing_values (bool, optional) – Whether to allow missing values in the DataFrame. This includes both missing rows, and NaN values in the value column. Defaults to False.

  • allow_extra_values (bool, optional) – Whether to allow extra rows in the DataFrame, i.e. rows with index items not present in the FlodymArray dimension items. Defaults to False.

  • df_in (DataFrame)

sign(inplace=False)
Parameters:

inplace (bool)

split(dim_letter)

Reverse the flodym_array_stack, returns a dictionary of FlodymArray objects associated with the item in the dimension that has been split. Method can be applied to classes FlodymArray, StockArray, Parameter and Flow.

Parameters:

dim_letter (str)

Return type:

dict

sum_over(sum_over_dims=())

Return the FlodymArray summed over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the FlodymArray object is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_to(result_dims=())

Return the FlodymArray summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of the dimensions to sum to. If not given, the sum over all dimensions is returned.

Returns:

FlodymArray object with the summed values and the reduced dimensions.

Return type:

FlodymArray

sum_values()

Return the sum of all values in the FlodymArray.

sum_values_over(sum_over_dims=())

Return the sum of the FlodymArray over a given tuple of dimensions.

Parameters:

sum_over_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, no summation is performed and the values array is returned.

Returns:

The partially summed values of the FlodymArray.

Return type:

np.ndarray

sum_values_to(result_dims=())

Return the values of the FlodymArray partially summed, such that only the dimensions given in the result_dims tuple are left.

Parameters:

result_dims (tuple, optional) – Tuple of dimension letters to sum over. If not given, the sum over all dimensions is returned.

to_df(index=True, dim_to_columns=None, sparse=False)

Export the FlodymArray to a pandas DataFrame.

Parameters:

  • index (bool, optional) – Whether to include the dimension items as a Multi-Index (True) or as columns of the DataFrame (False). Defaults to True.

  • dim_to_columns (str, optional) – Name of the dimension the items of which are to form the columns of the DataFrame. If not given, the DataFrame is returned in long format with a single ‘value’ column.

  • sparse (bool, optional) – Whether to return a sparse DataFrame with only non-zero values. Defaults to False.

Returns:

DataFrame representation of the FlodymArray.

Return type:

pd.DataFrame

validator validate_values  »  all fields
property shape: tuple[int]

The shape of the array, determined by the dimensions.

property size: int

The number of elements in the array.

flodym.flow_naming.process_names_with_arrow(from_process, to_process)

Return the name of a flow as a string containing the process it starts from and the process it ends in, separated by an arrow.

Parameters:
Return type:

str

flodym.flow_naming.process_names_no_spaces(from_process, to_process)

Return the name of a flow as a string containing the process it starts from and the process it ends in, separated by ‘_to_’, without spaces.

Parameters:
Return type:

str

flodym.flow_naming.process_ids(from_process, to_process)

Return the name of a flow as a string containing the id of the process it starts from and the id of the process it ends in, e.g. F1_2.

Parameters:
Return type:

str

flodym.make_empty_flows(processes, flow_definitions, dims, naming=<function process_names_with_arrow>)

Initialize all defined flows with zero values.

Parameters:

  • processes (dict[str, Process]) – Dictionary of processes, with process names as keys.

  • flow_definitions (list[FlowDefinition]) – List of flow definitions.

  • dims (DimensionSet) – DimensionSet object containing all dimensions.

  • naming (Callable[[Process, Process], str]) – Function to generate names for flows. Default is process_names_with_arrow.

Returns:

Dictionary of flows, with flow names as keys.

Return type:

dict[str, Flow]