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.

Example

>>> result_1 = split_array_to_dict_of_arrays(
...     array([1., 2., 3.]), {"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.

Example

>>> result = concatenate_dict_of_arrays_to_array(
...     {'x': array([1.]), 'y': array([2.]), 'z': array([3., 4.])}, ['x', 'z']
... )
>>> print(result)
array([1., 3., 4.])
Parameters
  • dict_of_arrays (Mapping[str, numpy.ndarray]) – 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

numpy.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.

Example

>>> result = deepcopy_dict_of_arrays(
...     {"x": array([1.]), "y": array([2.])}, ["x"]
... )
>>> print(result)
>>> {"x": array([1.])}
Parameters
  • dict_of_arrays (Mapping[str, ndarray]) – 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.

    By default it is set to None.

Returns

A deep copy of the dictionary of NumPy arrays.

Return type

dict[str, ndarray]

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.

Example

>>> result = concatenate_dict_of_arrays_to_array(
...     {'x': array([1.]), 'y': array([2.]), 'z': array([3., 4.])}, ['x', 'z']
... )
>>> print(result)
array([1., 3., 4.])
Parameters
  • dict_of_arrays (Mapping[str, numpy.ndarray]) – 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

numpy.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.

Example

>>> result = flatten_nested_bilevel_dict({"y": {"x": array([[1.0], [2.0]])}})
>>> print(result)
{"y#&#x": array([[1.0], [2.0]])}
Parameters
  • nested_dict (Mapping[str, Any]) – 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

dict[str, Any]

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

Flatten a nested dictionary.

Example

>>> result = flatten_nested_dict({"y": {"x": array([[1.0], [2.0]])}})
>>> print(result)
{"y#&#x": array([[1.0], [2.0]])}
Parameters
  • nested_dict (Mapping[str, Any]) – 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

dict[str, Any]

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.

Example

>>> result = nest_flat_bilevel_dict({"a_b": 1, "c_b": 2}, "_")
>>> print(result)
{"a": {"b": 1}, "c": {"b": 2}}
Parameters
  • flat_dict (Mapping[str, Any]) – 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

dict[str, Any]

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

Nest a flat dictionary.

Example

>>> result = nest_flat_dict({"a_b": 1, "c_b": 2}, separator="_")
>>> print(result)
{"a": {"b": 1}, "c": {"b": 2}}
Parameters
  • flat_dict (Mapping[str, Any]) – 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

dict[str, Any]

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.

Example

>>> result_1 = split_array_to_dict_of_arrays(
...     array([1., 2., 3.]), {"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.

Example

>>> 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, numpy.ndarray]) – The dictionary of NumPy arrays to be updated.

  • names (Iterable[str]) – The keys of the dictionary for which to update the values.

  • array (numpy.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, numpy.ndarray]