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 (DataArray | Dataset) – Input object with coords.

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

  • graph (dict[str | tuple[str, ...], str | Callable[..., Variable]] | None, 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, include aliases in the output. Default is True.

  • keep_intermediate (bool, default: True) – If True, include intermediate results in the output. Default is True.

  • keep_inputs (bool, default: True) – Include consumed input coordinates in the output. Default is True.

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

  • **kwargs (Callable[..., Variable]) – 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:

Same type as input – 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)