scipp.transform_coords#

scipp.transform_coords(x, targets=None, /, graph=None, *, rename_dims=True, keep_aliases=True, keep_intermediate=True, keep_inputs=True, quiet=False, **kwargs)#

Compute new coords based on transformations of input coords.

See the section in the user guide on Coordinate transformations for detailed explanations.

Parameters
  • x (Union[DataArray, Dataset]) – Input object with coords.

  • targets (Union[str, Iterable[str], None], default: None) – Name or list of names of desired output coords.

  • graph (Optional[Dict[Union[str, Tuple[str, ...]], Union[str, Callable]]], default: None) –

    A graph defining how new coords can be computed from existing coords. This may be done in multiple steps. The graph is given by a dict where:

    • Dict keys are str or tuple of str, defining the names of outputs generated by a dict value.

    • Dict values are str or a callable (function). If str, this is a synonym for renaming a coord. If a callable, it must either return a single variable or a dict of variables. The argument names of callables must be coords in x or be computable by other nodes in graph. The coord names can be overridden by the callable by providing a __transform_coords_input_keys__ property, returning a list of coord names in the same order as the function arguments.

  • rename_dims (bool, default: True) – Rename dimensions if the corresponding dimension coords are used as inputs and there is a single output coord that can be associated with that dimension. See the user guide for more details and examples. Default is True.

  • keep_aliases (bool, default: True) – If True, aliases for coords defined in graph are included in the output. Default is True.

  • keep_intermediate (bool, default: True) – Keep attributes created as intermediate results. Default is True.

  • keep_inputs (bool, default: True) – Keep consumed input coordinates or attributes. Default is True.

  • quiet (bool, default: False) – If True, no log output is produced. Otherwise, transform_coords produces a log of its actions.

  • **kwargs – Mapping of coords to callables. This can be used as an alternate and brief way of specifying targets and graph. If provided, neither targets nor graph may be given.

Returns

Union[DataArray, Dataset] – New object with desired coords. Existing data and meta-data is shallow-copied.

Examples

Transform input coordinates x and y to a new output coordinate xy:

>>> da = sc.data.table_xyz(nrow=10)
>>> transformed = da.transform_coords(xy=lambda x, y: x + y)

Equivalent full syntax based on a target name and a graph:

>>> da = sc.data.table_xyz(nrow=10)
>>> transformed = da.transform_coords('xy', graph={'xy': lambda x, y: x + y})

Multiple new coordinates can be computed at once. Here z2 is setup as an alias of z:

>>> da = sc.data.table_xyz(nrow=10)
>>> transformed = da.transform_coords(xy=lambda x, y: x + y, z2='z')

This is equivalent to

>>> da = sc.data.table_xyz(nrow=10)
>>> graph = {'xy': lambda x, y: x + y, 'z2':'z'}
>>> transformed = da.transform_coords(['xy', 'z2'], graph=graph)

Multi-step transformations that do not keep intermediate results as coordinates can be performed with a graph containing nodes that depend on outputs of other nodes:

>>> da = sc.data.table_xyz(nrow=10)
>>> graph = {'xy': lambda x, y: x + y, 'xyz': lambda xy, z: xy + z}
>>> transformed = da.transform_coords('xyz', graph=graph)