pyvista.MultiBlock.move_nested_field_data_to_root

pyvista.MultiBlock.move_nested_field_data_to_root#

MultiBlock.move_nested_field_data_to_root(
*,
copy: bool | None = None,
field_data_mode: Literal['preserve', 'prepend'] = 'preserve',
user_dict_mode: Literal['preserve', 'prepend', 'flat', 'nested'] = 'preserve',
separator: str = '::',
check_duplicate_keys: bool = True,
) → None[source]#

Move or copy field data from all nested MultiBlock blocks.

Any nested MultiBlock blocks will have its field_data contents moved to the root block, (i.e. this MultiBock). By default, this data will be cleared from the nested block(s) but a copy may be made instead.

If any nested MultiBlock blocks define a user_dict, the root user-dict is also updated to include the nested block’s user-dict data.

All field data and user-dict keys are directly updated from the nested blocks by default. Optionally, different modes are provided to control the key names and/or how the data is moved. The move is done safely such that no key values will be overwritten and no data is lost. If any nested keys are duplicates of the root keys, an error is raised.

Note

This operation only applies to nested MultiBlock blocks. Field data associated with DataSet blocks is not affected.

Added in version 0.45.

Parameters:
copybool, optional

Set this value to copy the data. If True, deep-copy the data from nested MultiBlock blocks to the root block. Both the root and nested blocks will share the same keys and refer to separate copies of the data. If False, both the root and nested blocks will share the same keys but refer to the same data. By default, no copy is made; the nested field data is moved to the root block and cleared from the nested MultiBlock blocks.

Note

This option does not apply to any nested user_dict data. User-dict data is always deep-copied.

field_data_mode‘preserve’ | ‘prepend’, default: ‘preserve’

Mode for naming the root field data keys when moving nested field data.

  • 'preserve': The array names of nested field data are preserved.

  • 'prepend': Preserve the array names and prepend the parent names.

user_dict_mode‘preserve’ | ‘prepend’ | ‘flat’ | ‘nested’, default: ‘preserve’

Mode for naming the root user_dict keys when nested MultiBlock blocks define a user-dict.

  • 'preserve': Update the root user dict directly with the items of any nested user-dict.

  • 'nested': Create nested keys in the root user-dict which match the nested hierarchy of any nested MultiBlock blocks.

  • 'flat': Create a new key in the root user dict for each nested MultiBlock that has a user-dict.

  • 'prepend': Similar to 'flat' except the key names are prepended with the parent block names.

Note

If there is only a single level of nesting the 'flat', 'nested' and 'prepend' modes are all equivalent. They only differ when there is at least two levels of nesting.

separatorstr, default: ‘::’

String separator to use when 'prepend' mode is enabled for either field data or for the user-dict. The separator is inserted between parent and child block names.

check_duplicate_keysbool, default: True

Update the root data safely without overwriting existing data. If True, an error is raised if any nested keys match the root block’s keys. If False, nested data is moved without checking if a key already exists, and data may be overwritten.

Raises:
ValueError

If any field data keys in nested MultiBlock blocks are duplicated in the root block and check_duplicate_keys is True.

See also

flatten

Examples

Create a MultiBlock with field data.

>>> import pyvista as pv
>>> multi = pv.MultiBlock()
>>> multi.field_data['data'] = [1, 2, 3]

Nest the dataset inside another MultiBlock.

>>> root = pv.MultiBlock([multi])

Show that the root block does not have any field data.

>>> root.field_data.keys()
[]

Move the nested field data to the root.

>>> root.move_nested_field_data_to_root()

The field data is now at the root.

>>> root.field_data.keys()
['data']

And no longer exists in the nested MultiBlock.

>>> multi.field_data.keys()
[]

Add more field data to the nested block.

>>> multi.field_data['more_data'] = [4, 5, 6]

Move it to the root again, but this time prepend the name of the block the data came from.

>>> root.move_nested_field_data_to_root(field_data_mode='prepend')
>>> root.field_data.keys()
['data', 'Block-00::more_data']

The user_dict is also field data which is moved to the root block’s user-dict.

Add sample data to the nested block and move it to the root.

>>> data = dict(foo='bar')
>>> multi.user_dict = data
>>> root.move_nested_field_data_to_root()

Check the root’s user-dict. By default, the key names are preserved and the root dict is updated with the nested dict.

>>> root.user_dict
{"foo": "bar"}

Clear the field data and re-add data to the nested user-dict.

>>> root.clear_field_data()
>>> multi.user_dict = data

Move the data again but use the 'flat' mode. This time, a new key is added which matches the nested block’s name.

>>> root.move_nested_field_data_to_root(user_dict_mode='flat')
>>> root.user_dict
{"Block-00": {"foo": "bar"}}
Contents