gemseo / utils

data_conversion module¶

A set of functions to convert data structures.

gemseo.utils.data_conversion.array_to_dict(array, names_to_sizes, *names, check_consistency=False)

Split a NumPy array into a dictionary of NumPy arrays.

Examples

>>> result_1 = split_array_to_dict_of_arrays(
...     array([1.0, 2.0, 3.0]), {"x": 1, "y": 2}, ["x", "y"]
... )
>>> print(result_1)
{'x': array([1.]), 'y': array([2., 3.])}
>>> result_2 = split_array_to_dict_of_arrays(
...     array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]),
...     {"y1": 1, "y2": 2, "x2": 2, "x1": 1},
...     ["y1", "y2"],
...     ["x1", "x2"],
... )
>>> print(result_2)
{
    "y1": {"x1": array([[1.0]]), "x2": array([[2.0, 3.0]])},
    "y2": {"x1": array([[4.0], [7.0]]), "x2": array([[5.0, 6.0], [8.0, 9.0]])},
}

Parameters:

array (ndarray) – The NumPy array.
names_to_sizes (Mapping[str, int]) – The sizes of the values related to names.
*names (Iterable[str]) – The names related to the NumPy array dimensions, starting from the last one; in the second example (see result_2), the last dimension of array represents the variables ["y1", "y2"] while the penultimate one represents the variables ["x1", "x2"].
check_consistency (bool) –
Whether to check the consistency of the sizes of *names with the array shape.

By default it is set to False.

Returns:

A dictionary of NumPy arrays related to *names.

Raises:

ValueError – When check_consistency is True and the sizes of the *names is inconsistent with the array shape.

Return type:

dict[str, ndarray | dict[str, ndarray]]

gemseo.utils.data_conversion.concatenate_dict_of_arrays_to_array(dict_of_arrays, names)[source]

Concatenate some values of a dictionary of NumPy arrays.

The concatenation is done according to the last dimension of the NumPy arrays. This dimension apart, the NumPy arrays must have the same shape.

Examples

>>> result = concatenate_dict_of_arrays_to_array(
...     {"x": array([1.0]), "y": array([2.0]), "z": array([3.0, 4.0])},
...     ["x", "z"],
... )
>>> print(result)
array([1., 3., 4.])

Parameters:

dict_of_arrays (Mapping[str, ArrayLike]) – The dictionary of NumPy arrays.
names (Iterable[str]) – The keys of the dictionary for which to concatenate the values.

Returns:

The concatenated array if names is not empty, otherwise an empty array.

Return type:

ndarray

gemseo.utils.data_conversion.deepcopy_dict_of_arrays(dict_of_arrays, names=None)[source]

Perform a deep copy of a dictionary of NumPy arrays.

This treats the NumPy arrays specially using array.copy() instead of deepcopy.

Examples

>>> result = deepcopy_dict_of_arrays(
...     {"x": array([1.0]), "y": array([2.0])}, ["x"]
... )
>>> print(result)
>>> {"x": array([1.0])}

Parameters:

dict_of_arrays (DataMapping) – The dictionary of NumPy arrays to be copied.
names (Iterable[str] | None) – The keys of the dictionary for which to deepcopy the items. If None, consider all the dictionary keys.

Returns:

A deep copy of the dictionary of NumPy arrays.

Return type:

DataMapping

gemseo.utils.data_conversion.dict_to_array(dict_of_arrays, names)

Concatenate some values of a dictionary of NumPy arrays.

The concatenation is done according to the last dimension of the NumPy arrays. This dimension apart, the NumPy arrays must have the same shape.

Examples

>>> result = concatenate_dict_of_arrays_to_array(
...     {"x": array([1.0]), "y": array([2.0]), "z": array([3.0, 4.0])},
...     ["x", "z"],
... )
>>> print(result)
array([1., 3., 4.])

Parameters:

dict_of_arrays (Mapping[str, ArrayLike]) – The dictionary of NumPy arrays.
names (Iterable[str]) – The keys of the dictionary for which to concatenate the values.

Returns:

The concatenated array if names is not empty, otherwise an empty array.

Return type:

ndarray

gemseo.utils.data_conversion.flatten_nested_bilevel_dict(nested_dict, separator='#&#')[source]

Flatten a nested bi-level dictionary whose sub-dictionaries have the same keys.

Examples

>>> result = flatten_nested_bilevel_dict({"y": {"x": array([[1.0], [2.0]])}})
>>> print(result)
{"y#&#x": array([[1.0], [2.0]])}

Parameters:

nested_dict (DataMapping) – The dictionary to be flattened.
separator (str) –
The keys separator, to be used as {parent_key}{separator}{child_key}.

By default it is set to “#&#”.

Returns:

A flat dictionary.

Return type:

DataMapping

gemseo.utils.data_conversion.flatten_nested_dict(nested_dict, prefix='', separator='#&#')[source]

Flatten a nested dictionary.

Examples

>>> result = flatten_nested_dict({"y": {"x": array([[1.0], [2.0]])}})
>>> print(result)
{"y#&#x": array([[1.0], [2.0]])}

Parameters:

nested_dict (DataMapping) – The dictionary to be flattened.
prefix (str) –
The prefix to be prepended to the keys.

By default it is set to “”.
separator (str) –
The keys separator, to be used as {parent_key}{separator}{child_key}.

By default it is set to “#&#”.

Returns:

A flat dictionary.

Return type:

DataMapping

gemseo.utils.data_conversion.nest_flat_bilevel_dict(flat_dict, separator='#&#')[source]

Nest a flat bi-level dictionary where sub-dictionaries will have the same keys.

Examples

>>> result = nest_flat_bilevel_dict({"a_b": 1, "c_b": 2}, "_")
>>> print(result)
{"a": {"b": 1}, "c": {"b": 2}}

Parameters:

flat_dict (DataMapping) – The dictionary to be nested.
separator (str) –
The keys separator, to be used as {parent_key}{sep}{child_key}.

By default it is set to “#&#”.

Returns:

A nested dictionary.

Return type:

DataMapping

gemseo.utils.data_conversion.nest_flat_dict(flat_dict, prefix='', separator='#&#')[source]

Nest a flat dictionary.

Examples

>>> result = nest_flat_dict({"a_b": 1, "c_b": 2}, separator="_")
>>> print(result)
{"a": {"b": 1}, "c": {"b": 2}}

Parameters:

flat_dict (DataMapping) – The dictionary to be nested.
prefix (str) –
The prefix to be removed from the keys.

By default it is set to “”.
separator (str) –
The keys separator, to be used as {parent_key}{separator}{child_key}.

By default it is set to “#&#”.

Returns:

A nested dictionary.

Return type:

DataMapping

gemseo.utils.data_conversion.split_array_to_dict_of_arrays(array, names_to_sizes, *names, check_consistency=False)[source]

Split a NumPy array into a dictionary of NumPy arrays.

Examples

>>> result_1 = split_array_to_dict_of_arrays(
...     array([1.0, 2.0, 3.0]), {"x": 1, "y": 2}, ["x", "y"]
... )
>>> print(result_1)
{'x': array([1.]), 'y': array([2., 3.])}
>>> result_2 = split_array_to_dict_of_arrays(
...     array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]),
...     {"y1": 1, "y2": 2, "x2": 2, "x1": 1},
...     ["y1", "y2"],
...     ["x1", "x2"],
... )
>>> print(result_2)
{
    "y1": {"x1": array([[1.0]]), "x2": array([[2.0, 3.0]])},
    "y2": {"x1": array([[4.0], [7.0]]), "x2": array([[5.0, 6.0], [8.0, 9.0]])},
}

Parameters:

array (ndarray) – The NumPy array.
names_to_sizes (Mapping[str, int]) – The sizes of the values related to names.
*names (Iterable[str]) – The names related to the NumPy array dimensions, starting from the last one; in the second example (see result_2), the last dimension of array represents the variables ["y1", "y2"] while the penultimate one represents the variables ["x1", "x2"].
check_consistency (bool) –
Whether to check the consistency of the sizes of *names with the array shape.

By default it is set to False.

Returns:

A dictionary of NumPy arrays related to *names.

Raises:

ValueError – When check_consistency is True and the sizes of the *names is inconsistent with the array shape.

Return type:

dict[str, ndarray | dict[str, ndarray]]

gemseo.utils.data_conversion.update_dict_of_arrays_from_array(dict_of_arrays, names, array, copy=True, cast_complex=False)[source]

Update some values of a dictionary of NumPy arrays from a NumPy array.

The order of the data in array follows the order of names. The original data type is kept except if array is complex and cast_complex is False.

Examples

>>> result = update_dict_of_arrays_from_array(
...     {"x": array([0.0, 1.0]), "y": array([2.0]), "z": array([3, 4])},
...     ["y", "z"],
...     array([0.5, 1.0, 2.0]),
... )
>>> print(result)
{"x": array([0.0, 1.0]), "y": array([0.5]), "z": array([1, 2])}

Parameters:

dict_of_arrays (Mapping[str, ndarray]) – The dictionary of NumPy arrays to be updated.
names (Iterable[str]) – The keys of the dictionary for which to update the values.
array (ndarray) – The NumPy array with which to update the dictionary of NumPy arrays.
copy (bool) –
Whether to update a copy reference_input_data.

By default it is set to True.
copy –
Whether to update dict_of_arrays or a copy of dict_of_arrays.

By default it is set to True.
cast_complex (bool) –
Whether to cast array when its data type is complex.

By default it is set to False.

Returns:

A deep copy of dict_of_arrays whose values of names, if any, have been updated with array.

Raises:

TypeError – If array is not a NumPy array.
ValueError –
- If a name of names is not a key of dict_of_arrays. * If the size of array is inconsistent with the shapes of the values of dict_of_arrays.

Return type:

Mapping[str, ndarray]