cyclebane 24.5.0__py3-none-any.whl

cyclebane/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+# ruff: noqa: E402, F401
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+del importlib
+
+from .graph import Graph
+
+__all__ = ["Graph"]

cyclebane/graph.py

@@ -0,0 +1,461 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generator, Hashable, Iterable
+from uuid import uuid4
+
+import networkx as nx
+
+from .node_values import IndexName, IndexValue, NodeValues
+
+
+def _get_unique_sink(graph: nx.DiGraph) -> Hashable:
+    sink_nodes = [node for node in graph.nodes if graph.out_degree(node) == 0]
+    if len(sink_nodes) != 1:
+        raise ValueError('Graph must have exactly one sink node')
+    return sink_nodes[0]
+
+
+def _get_new_node_name(graph: nx.DiGraph) -> str:
+    while True:
+        name = str(uuid4())
+        if name not in graph:
+            return name
+
+
+def _remove_ancestors(graph: nx.DiGraph, node: Hashable) -> nx.DiGraph:
+    graph = graph.copy()
+    ancestors = nx.ancestors(graph, node)
+    ancestors_successors = {
+        ancestor: graph.successors(ancestor) for ancestor in ancestors
+    }
+    to_remove = []
+    for ancestor, successors in ancestors_successors.items():
+        # If any successor does not have node as descendant we must keep the node
+        if all(nx.has_path(graph, successor, node) for successor in successors):
+            to_remove.append(ancestor)
+    graph.remove_nodes_from(to_remove)
+    graph.remove_edges_from(list(graph.in_edges(node)))
+    return graph
+
+
+@dataclass(frozen=True, slots=True)
+class IndexValues:
+    """
+    Index values used as part of :py:class:`NodeName`.
+
+    Conceptually, this is a mapping from index names to index values.
+    """
+
+    axes: tuple[IndexName, ...]
+    values: tuple[IndexValue, ...]
+
+    @staticmethod
+    def from_tuple(t: tuple[tuple[IndexName, IndexValue], ...]) -> IndexValues:
+        names = tuple(name for name, _ in t)
+        values = tuple(value for _, value in t)
+        return IndexValues(axes=names, values=values)
+
+    def to_tuple(self) -> tuple[tuple[IndexName, IndexValue], ...]:
+        return tuple(zip(self.axes, self.values))
+
+    def merge_index(self, other: IndexValues) -> IndexValues:
+        return IndexValues(
+            axes=other.axes + self.axes, values=other.values + self.values
+        )
+
+    def __str__(self) -> str:
+        return ', '.join(
+            f'{name}={value}' for name, value in zip(self.axes, self.values)
+        )
+
+    def __len__(self) -> int:
+        return len(self.axes)
+
+
+@dataclass(frozen=True, slots=True)
+class NodeName:
+    """Node name with indices used for mapped nodes when converting to NetworkX."""
+
+    name: Hashable
+    index: IndexValues
+
+    def merge_index(self, other: IndexValues) -> NodeName:
+        return NodeName(name=self.name, index=self.index.merge_index(other))
+
+    def __str__(self) -> str:
+        return f'{self.name}({self.index})'
+
+
+@dataclass(frozen=True, slots=True)
+class MappedNode:
+    """
+    Key for a node in :py:class:`Graph` representing a collection of "mapped" nodes.
+    """
+
+    name: Hashable
+    indices: tuple[IndexName, ...]
+
+
+def _node_with_indices(node: Hashable, indices: tuple[IndexName, ...]) -> MappedNode:
+    if isinstance(node, MappedNode):
+        return MappedNode(name=node.name, indices=indices + node.indices)
+    return MappedNode(name=node, indices=indices)
+
+
+def _node_indices(node: Hashable) -> tuple[IndexName, ...]:
+    if isinstance(node, MappedNode):
+        return node.indices
+    return ()
+
+
+def _find_successors(
+    graph: nx.DiGraph, *, root_nodes: tuple[Hashable]
+) -> set[Hashable]:
+    successors = set()
+    for root in root_nodes:
+        if graph.in_degree(root) > 0:
+            raise ValueError(f"Mapped node '{root}' is not a source node")
+        successors.update(nx.descendants(graph, source=root) | {root})
+    return successors
+
+
+def _rename_successors(
+    graph: nx.DiGraph, *, successors: Iterable[Hashable], index: IndexValues
+) -> nx.DiGraph:
+    """Replace 'node' and all its successors with (node, suffix), and update all edges
+    accordingly."""
+    renamed_nodes = {
+        node: (
+            node.merge_index(index)
+            if isinstance(node, NodeName)
+            else NodeName(name=node, index=index)
+        )
+        for node in successors
+    }
+    return nx.relabel_nodes(graph, renamed_nodes, copy=True)
+
+
+def _yield_index(
+    indices: list[tuple[IndexName, Iterable[IndexValue]]]
+) -> Generator[tuple[tuple[IndexName, IndexValue], ...], None, None]:
+    """Given a multi-dimensional index, yield all possible combinations."""
+    name, index = indices[0]
+    for index_value in index:
+        if len(indices) == 1:
+            yield ((name, index_value),)
+        else:
+            for rest in _yield_index(indices[1:]):
+                yield ((name, index_value),) + rest
+
+
+class PositionalIndexer:
+    """
+    Helper class to allow slicing a named dim of a graph using positional indexing.
+    """
+
+    def __init__(self, graph: Graph, index_name: IndexName):
+        self.graph = graph
+        self.index_name = index_name
+
+    def __getitem__(self, key: int | slice) -> Graph:
+        # Supporting single indices may be conceptually ill-defined if the index
+        # `reduce` was applied to the graph, so we might never support this.
+        if isinstance(key, int):
+            raise NotImplementedError('Only slices are supported')
+        node_values = NodeValues(
+            {
+                name: (
+                    col.loc({self.index_name: key})
+                    if self.index_name in col.index_names
+                    else col
+                )
+                for name, col in self.graph._node_values.items()
+            }
+        )
+        return Graph(self.graph.graph, node_values=node_values)
+
+
+MappingToArrayLike = Any  # dict[str, Numpy|DataArray], DataFrame, etc.
+
+
+class Graph:
+    """
+    A Cyclebane graph is a directed acyclic graph with additional array-like structure.
+
+    The array-like structure selectively affects nodes in the graph by associating
+    source nodes with an array-like object. These source node and all their descendants
+    thus gain an additional index (or "dimension").
+
+    Nomenclature:
+
+    - Index: As in Pandas, and index is a sequence of values that label an axis.
+    - Index-value: A single value in an index.
+    - Index-name: The name of an index.
+
+
+    Notes
+    -----
+    The current implementation is not complete, there is a number of things to
+    improve:
+    - Overall, I would like to reduce the array-handling code and transparently forward
+      to the slicing code of the underlying array-like object (Pandas, NumPy, Xarray,
+      Scipp). Basically, we would like to use the slicing methods of the underlying
+      object. This may not be trivial, since we might mix different types of array-like
+      objects at nodes with multiple predecessors.
+    """
+
+    def __init__(self, graph: nx.DiGraph, *, node_values: NodeValues | None = None):
+        """
+        Initialize a graph from a directed NetworkX graph.
+
+        Parameters
+        ----------
+        graph:
+            The directed graph representing the data flow.
+        node_values:
+            A mapping from source node names to array-like objects. The implementation
+            assumes that the graph has been setup correctly. Do not use this argument
+            unless you know what you are doing.
+        """
+        self.graph = graph
+        self._node_values = node_values or NodeValues({})
+
+    def copy(self) -> Graph:
+        return Graph(self.graph.copy(), node_values=self._node_values)
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        """Names of the indices (dimensions) of the graph."""
+        return tuple(self.indices)
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        """Names and values of the indices of the graph."""
+        return self._node_values.indices
+
+    def map(self, node_values: MappingToArrayLike) -> Graph:
+        """
+        Map the graph over the given values by associating source nodes with values.
+
+        All successors of the mapped source nodes are replaced with new nodes, one for
+        each index value. The value is set as an attribute on the new source nodes
+        (but not their successors).
+
+        Parameters
+        ----------
+        node_values:
+            A mapping from source node names to array-like objects. The source nodes
+            are the roots of the branches to be mapped. The array-like objects must
+            support slicing, e.g., NumPy arrays, Xarray DataArrays, Pandas DataFrames,
+            etc.
+        """
+        new_values = NodeValues.from_mapping(
+            node_values, axis_zero=len(self.index_names)
+        )
+
+        # Make sure root nodes exist in graph, add them if not. This choice allows for
+        # mapping, e.g., with multiple columns from a DataFrame, representing labels
+        # used later for groupby operations.
+        graph = self.graph.copy()
+        graph.add_nodes_from(new_values)
+
+        successors = _find_successors(graph, root_nodes=new_values)
+        name_mapping: dict[Hashable, MappedNode] = {}
+        for node in successors:
+            name_mapping[node] = _node_with_indices(node, tuple(new_values.indices))
+
+        return Graph(
+            nx.relabel_nodes(graph, name_mapping),
+            node_values=self._node_values.merge(new_values),
+        )
+
+    def reduce(
+        self,
+        key: None | Hashable = None,
+        *,
+        index: None | Hashable = None,
+        axis: None | int = None,
+        name: None | Hashable = None,
+        attrs: None | dict[str, Any] = None,
+    ) -> Graph:
+        """
+        Reduce over the given index or axis previously created with :py:meth:`map`.
+
+        If neither index nor axis is given, all axes are reduced.
+
+        Parameters
+        ----------
+        key:
+            The name of the source node to reduce. This is the original name prior to
+            mapping. If not given, tries to find a unique sink node.
+        index:
+            The name of the index to reduce over. Only one of index and axis can be
+            given.
+        axis:
+            Integer axis index to reduce over. Only one of index and axis can be given.
+        name:
+            The name of the new node. If not given, a unique name is generated.
+        attrs:
+            Attributes to set on the new node(s).
+        """
+        key = key or _get_unique_sink(self.graph)
+        name = name or _get_new_node_name(self.graph)
+
+        attrs = attrs or {}
+        if index is not None and axis is not None:
+            raise ValueError('Only one of index and axis can be given')
+        key = self._from_orig_key(key)
+        indices = _node_indices(key)
+        if index is not None and index not in indices:
+            raise ValueError(f"Node '{key}' does not have index '{index}'.")
+        # TODO We can support indexing from the back in the future.
+        if axis is not None and (axis < 0 or axis >= len(indices)):
+            raise ValueError(f"Node '{key}' does not have axis '{axis}'.")
+        if index is not None:
+            new_index = tuple(value for value in indices if value != index)
+        elif axis is not None:
+            # TODO Should axis refer to axes of graph, or the node?
+            new_index = tuple(value for i, value in enumerate(indices) if i != axis)
+        else:
+            new_index = None
+        if name in self.graph:
+            raise ValueError(f"Node '{name}' already exists in the graph.")
+
+        graph = self.graph.copy()
+        name = MappedNode(name=name, indices=new_index) if new_index else name
+        graph.add_node(name, **attrs)
+        graph.add_edge(key, name)
+
+        return Graph(graph, node_values=self._node_values)
+
+    def _from_orig_key(self, key: Hashable) -> Hashable:
+        # Graph.map relabels nodes to include index names, which can be inconvenient
+        # for the user. Is this convenience of finding the node by its original name
+        # worth the complexity and a good idea?
+        if key not in self.graph:
+            matches = [
+                node
+                for node in self.graph.nodes
+                if isinstance(node, MappedNode) and node.name == key
+            ]
+            if len(matches) == 0:
+                raise KeyError(f"Node '{key}' does not exist in the graph.")
+            if len(matches) > 1:
+                raise KeyError(f"Node '{key}' is ambiguous. Found {matches}.")
+            return matches[0]
+        return key
+
+    def by_position(self, index_name: IndexName) -> PositionalIndexer:
+        return PositionalIndexer(self, index_name)
+
+    def to_networkx(self, value_attr: str = 'value') -> nx.DiGraph:
+        """
+        Convert to a NetworkX graph, spelling out the internal array structures as
+        explicit nodes.
+
+        Parameters
+        ----------
+        value_attr:
+            The name of the attribute on nodes that holds the array-like object.
+        """
+        graph = self.graph
+        for index_name, index in reversed(self.indices.items()):
+            # Find all nodes with this index
+            nodes = []
+            for node in graph.nodes():
+                if index_name in _node_indices(
+                    node.name if isinstance(node, NodeName) else node
+                ):
+                    nodes.append(node)
+            # Make a copy for each index value
+            graphs = [
+                _rename_successors(
+                    graph, successors=nodes, index=IndexValues.from_tuple(i)
+                )
+                for i in _yield_index([(index_name, index)])
+            ]
+            graph = nx.compose_all(graphs)
+        # Replace all MappingNodes with their name
+        new_names = {
+            node: NodeName(node.name.name, node.index)
+            for node in graph
+            if isinstance(node, NodeName) and isinstance(node.name, MappedNode)
+        }
+        graph = nx.relabel_nodes(graph, new_names)
+
+        # Get values using previously stored index values
+        for node in graph.nodes:
+            if (
+                isinstance(node, NodeName)
+                and (node_values := self._node_values.get(node.name)) is not None
+            ):
+                graph.nodes[node][value_attr] = node_values.sel(node.index.to_tuple())
+
+        return graph
+
+    def __getitem__(self, key: Hashable | slice) -> Graph:
+        """
+        Get the branch of the graph rooted at the given node.
+
+        The branch is a subgraph containing the given node and all its ancestors.
+        Think of this like a Git branch, where the given node is the head of the branch.
+        """
+        if isinstance(key, slice):
+            raise NotImplementedError('Only single nodes are supported ')
+        key = self._from_orig_key(key)
+        ancestors = nx.ancestors(self.graph, key)
+        ancestors.add(key)
+        # Drop all node values that are not in the branch
+        mapped = set(a.name for a in ancestors if isinstance(a, MappedNode))
+        keep_values = [key for key in self._node_values.keys() if key in mapped]
+        return Graph(
+            self.graph.subgraph(ancestors),
+            node_values=self._node_values.get_columns(keep_values),
+        )
+
+    def __setitem__(self, branch: Hashable | slice, other: Graph) -> None:
+        """
+        Set a new branch in place of the given branch.
+
+        The new branch must have a unique sink node. The branch at `branch` is replaced
+        with the new branch. The indices and node values are updated accordingly. The
+        edges to successors of the old branch are connected to the sink of the new
+        branch.
+        """
+        if isinstance(branch, slice):
+            raise NotImplementedError('Setting slice not supported yet.')
+        if not isinstance(other, Graph):
+            raise TypeError(f'Expected {Graph}, got {type(other)}')
+        new_branch = other.graph
+        sink = _get_unique_sink(new_branch)
+        # In the future, we could support this if BOTH sink and branch are MappedNodes
+        # with identical indices.
+        if isinstance(sink, MappedNode) or isinstance(branch, MappedNode):
+            raise NotImplementedError('Mapped nodes not supported yet in __setitem__')
+        new_branch = nx.relabel_nodes(new_branch, {sink: branch})
+        if branch in self.graph:
+            graph = _remove_ancestors(self.graph, branch)
+            graph.nodes[branch].clear()
+        else:
+            graph = self.graph
+
+        intersection_nodes = set(graph.nodes) & set(new_branch.nodes) - {branch}
+
+        for node in intersection_nodes:
+            if graph.pred[node] != new_branch.pred[node]:
+                raise ValueError(
+                    f"Node inputs differ for node '{node}':\n"
+                    f"  {graph.pred[node]}\n"
+                    f"  {new_branch.pred[node]}\n"
+                )
+            if graph.nodes[node] != new_branch.nodes[node]:
+                raise ValueError(f"Node data differs for node '{node}'")
+
+        graph = nx.compose(graph, new_branch)
+
+        # Delay setting graph until we know no step fails
+        self._node_values = self._node_values.merge(other._node_values)
+        self.graph = graph

cyclebane/node_values.py

@@ -0,0 +1,400 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import abc
+from typing import TYPE_CHECKING, Any, Hashable, Iterable, Mapping, Sequence
+
+if TYPE_CHECKING:
+    import numpy
+    import pandas
+    import scipp
+    import xarray
+
+IndexName = Hashable
+IndexValue = Hashable
+
+
+class ValueArray(ABC):
+    """
+    Abstract base class for a series of values with an index that can be sliced.
+
+    Used by :py:class:`NodeValues` to store the values of a given node in a graph. The
+    abstraction allows for the use of different data structures to store the values of
+    nodes in a graph, such as pandas.DataFrame, xarray.DataArray, numpy.ndarray, or
+    simple Python iterables.
+    """
+
+    _registry = []
+
+    def __init_subclass__(cls) -> None:
+        super().__init_subclass__()
+        ValueArray._registry.append(cls)
+
+    @staticmethod
+    def from_array_like(values: Any, *, axis_zero: int = 0) -> ValueArray:
+        # Reversed to ensure SequenceAdapter is tried last, as it is the most general
+        # SequenceAdapter is defined right after this class so it is registered first
+        for subclass in reversed(ValueArray._registry):
+            if (a := subclass.try_from(values, axis_zero=axis_zero)) is not None:
+                return a
+        raise ValueError(f'Cannot create ValueArray from {values}')
+
+    @staticmethod
+    @abstractmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> ValueArray | None:
+        ...
+
+    @abstractmethod
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        """Return data by selecting from index with given name and index value."""
+
+    def loc(self, key: dict[IndexName, slice]) -> ValueArray:
+        if not all(isinstance(i, slice) for i in key.values()):
+            raise ValueError('ValueArray.loc only accepts slices, not integers')
+        if not set(key).issubset(set(self.index_names)):
+            raise ValueError(
+                f'ValueArray.loc got {key.keys()}, not a subset of {self.index_names}'
+            )
+        return self[key]
+
+    @abstractmethod
+    def __getitem__(self, key: dict[IndexName, slice]) -> ValueArray:
+        pass
+
+    @property
+    @abstractmethod
+    def shape(self) -> tuple[int, ...]:
+        pass
+
+    @property
+    @abstractmethod
+    def index_names(self) -> tuple[IndexName, ...]:
+        pass
+
+    @property
+    @abstractmethod
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        pass
+
+
+class SequenceAdapter(ValueArray):
+    def __init__(
+        self,
+        values: Sequence[Any],
+        *,
+        index: Iterable[IndexValue] | None = None,
+        axis_zero: int = 0,
+    ):
+        self._values = values
+        self._index = index or range(len(values))
+        self._axis_zero = axis_zero
+
+    @staticmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> SequenceAdapter | None:
+        return SequenceAdapter(obj, axis_zero=axis_zero)
+
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        if len(key) != 1:
+            raise ValueError('SequenceAdapter only supports single index')
+        _, i = key[0]
+        return self._values[self._index.index(i)]
+
+    def __getitem__(self, key: dict[IndexName, slice]) -> SequenceAdapter:
+        _, i = next(iter(key.items()))
+        return SequenceAdapter(
+            self._values[i], index=self._index[i], axis_zero=self._axis_zero
+        )
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return (len(self._values),)
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        return (f'dim_{self._axis_zero}',)
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        return {f'dim_{self._axis_zero}': self._index}
+
+
+class PandasSeriesAdapter(ValueArray):
+    def __init__(self, series: 'pandas.Series', *, axis_zero: int = 0):
+        self._series = series
+        self._axis_zero = axis_zero
+
+    @staticmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> PandasSeriesAdapter | None:
+        try:
+            import pandas
+        except ModuleNotFoundError:
+            return None
+        if isinstance(obj, pandas.Series):
+            return PandasSeriesAdapter(obj, axis_zero=axis_zero)
+
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        if len(key) != 1:
+            raise ValueError('PandasSeriesAdapter only supports single index')
+        index_name, i = key[0]
+        if index_name != self.index_names[0]:
+            raise ValueError(
+                f'Unexpected index name {index_name} for PandasSeriesAdapter with '
+                f'index names {self.index_names}'
+            )
+        return self._series.loc[i]
+
+    def __getitem__(self, key: dict[IndexName, slice]) -> PandasSeriesAdapter:
+        _, i = next(iter(key.items()))
+        return PandasSeriesAdapter(self._series[i], axis_zero=self._axis_zero)
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return (len(self._series),)
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        index_name = (
+            self._series.index.name
+            if self._series.index.name is not None
+            else f'dim_{self._axis_zero}'
+        )
+        return (index_name,)
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        return {self.index_names[0]: self._series.index}
+
+
+class XarrayDataArrayAdapter(ValueArray):
+    def __init__(
+        self,
+        data_array: 'xarray.DataArray',
+    ):
+        default_indices = {
+            dim: range(size)
+            for dim, size in data_array.sizes.items()
+            if dim not in data_array.coords
+        }
+        self._data_array = data_array.assign_coords(default_indices)
+
+    @staticmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> XarrayDataArrayAdapter | None:
+        try:
+            import xarray
+
+            if isinstance(obj, xarray.DataArray):
+                return XarrayDataArrayAdapter(obj)
+        except ModuleNotFoundError:
+            pass
+
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        return self._data_array.sel(dict(key))
+
+    def __getitem__(self, key: dict[IndexName, slice]) -> XarrayDataArrayAdapter:
+        return XarrayDataArrayAdapter(self._data_array.isel(key))
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return self._data_array.shape
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        return tuple(self._data_array.dims)
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        return {
+            dim: self._data_array.coords[dim].values for dim in self._data_array.dims
+        }
+
+
+class ScippDataArrayAdapter(ValueArray):
+    def __init__(self, data_array: 'scipp.DataArray'):
+        import scipp
+
+        default_indices = {
+            dim: scipp.arange(dim, size, unit=None)
+            for dim, size in data_array.sizes.items()
+            if dim not in data_array.coords
+        }
+        self._data_array = data_array.assign_coords(default_indices)
+
+    @staticmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> ScippDataArrayAdapter | None:
+        try:
+            import scipp
+
+            if isinstance(obj, scipp.Variable):
+                return ScippDataArrayAdapter(scipp.DataArray(obj))
+            if isinstance(obj, scipp.DataArray):
+                return ScippDataArrayAdapter(obj)
+        except ModuleNotFoundError:
+            pass
+
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        import scipp
+
+        values = self._data_array
+        for dim, value in key:
+            # Reconstruct label, to use label-based indexing instead of positional
+            if isinstance(value, tuple):
+                value, unit = value
+            else:
+                unit = None
+            label = scipp.scalar(value, unit=unit)
+            # Scipp indexing uses a comma to separate dimension label from the index,
+            # unlike Numpy and other libraries where it separates the indices for
+            # different axes.
+            values = values[dim, label]
+        return values
+
+    def __getitem__(self, key: dict[IndexName, slice]) -> ScippDataArrayAdapter:
+        values = self._data_array
+        for dim, i in key:
+            values = values[dim, i]
+        return ScippDataArrayAdapter(values)
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return self._data_array.shape
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        return tuple(self._data_array.dims)
+
+    def _index_for_dim(self, dim: str) -> list[tuple[Any, 'scipp.Unit']]:
+        # Work around some NetworkX errors. Probably scipp.Variable lacks functionality.
+        # For now we return a list of tuples, where the first element is the value and
+        # the second is the unit.
+        coord = self._data_array.coords[dim]
+        unit = coord.unit
+        if unit is None:
+            return coord.values
+        unit = str(unit)
+        return [(value, unit) for value in coord.values]
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        return {dim: self._index_for_dim(dim) for dim in self._data_array.dims}
+
+
+class NumpyArrayAdapter(ValueArray):
+    def __init__(
+        self,
+        array: 'numpy.ndarray',
+        *,
+        indices: dict[IndexName, Iterable[IndexValue]] | None = None,
+        axis_zero: int = 0,
+    ):
+        import numpy as np
+
+        self._array = np.asarray(array)
+        if indices is None:
+            indices = {
+                f'dim_{i+axis_zero}': range(size)
+                for i, size in enumerate(self._array.shape)
+            }
+        self._indices = indices
+        self._axis_zero = axis_zero
+
+    @staticmethod
+    def try_from(obj: Any, *, axis_zero: int = 0) -> NumpyArrayAdapter | None:
+        try:
+            import numpy
+        except ModuleNotFoundError:
+            return None
+        if isinstance(obj, numpy.ndarray):
+            return NumpyArrayAdapter(obj, axis_zero=axis_zero)
+
+    def sel(self, key: tuple[tuple[IndexName, IndexValue], ...]) -> Any:
+        index_tuple = tuple(self._indices[k].index(i) for k, i in key)
+        return self._array[index_tuple]
+
+    def __getitem__(self, key: dict[IndexName, slice]) -> NumpyArrayAdapter:
+        return NumpyArrayAdapter(
+            self._array[tuple(key.get(k, slice(None)) for k in self._indices)],
+            indices={
+                index_name: (index_values[key.get(index_name, slice(None))])
+                for index_name, index_values in self._indices.items()
+            },
+            axis_zero=self._axis_zero,
+        )
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        return self._array.shape
+
+    @property
+    def index_names(self) -> tuple[IndexName, ...]:
+        return tuple(self._indices)
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        return self._indices
+
+
+class NodeValues(abc.Mapping[Hashable, ValueArray]):
+    """
+    A collection of pandas.DataFrame-like objects with distinct indices.
+
+    This is used by :py:class:`Graph` to store the values of nodes in a graph.
+    """
+
+    def __init__(self, values: Mapping[Hashable, ValueArray]):
+        self._values = values
+
+    def __len__(self) -> int:
+        """Return the number of columns."""
+        return len(self._values)
+
+    def __iter__(self) -> Iterable[Hashable]:
+        """Iterate over the column names."""
+        return iter(self._values)
+
+    def __getitem__(self, key: Hashable) -> ValueArray:
+        """Return the column with the given name."""
+        return self._values[key]
+
+    @staticmethod
+    def from_mapping(
+        values: Mapping[Hashable, Sequence[Any]], axis_zero: int
+    ) -> NodeValues:
+        """Construct from a mapping of node names to value sequences."""
+        value_arrays = {
+            key: ValueArray.from_array_like(value, axis_zero=axis_zero)
+            for key, value in values.items()
+        }
+        shapes = {array.shape for array in value_arrays.values()}
+        if len(shapes) > 1:
+            raise ValueError(
+                'All value sequences in a map operation must have the same shape. '
+                'Use multiple map operations if necessary.'
+            )
+        return NodeValues(value_arrays)
+
+    def merge(self, value_arrays: Mapping[Hashable, ValueArray]) -> NodeValues:
+        if value_arrays:
+            named = next(iter(value_arrays.values())).index_names
+            if any([name in self.indices for name in named]):
+                raise ValueError(
+                    f'Conflicting new index names {named} with existing '
+                    f'{tuple(self.indices)}'
+                )
+        for node in value_arrays:
+            if node in self:
+                raise ValueError(f"Node '{node}' has already been mapped")
+        return NodeValues({**self._values, **value_arrays})
+
+    def get_columns(self, keys: list[Hashable]) -> NodeValues:
+        """Select a subset of columns."""
+        return NodeValues({key: self._values[key] for key in keys})
+
+    @property
+    def indices(self) -> dict[IndexName, Iterable[IndexValue]]:
+        """Return the indices of the NodeValues object."""
+        value_indices = [value.indices for value in self._values.values()]
+        return {
+            name: index for indices in value_indices for name, index in indices.items()
+        }

cyclebane-24.5.0.dist-info/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Scipp contributors (https://github.com/scipp)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cyclebane-24.5.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: cyclebane
+Version: 24.5.0
+Summary: Transform directed acyclic graphs using map-reduce and groupby operations
+Author: Scipp contributors
+License: BSD 3-Clause License
+        
+        Copyright (c) 2024, Scipp contributors (https://github.com/scipp)
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Bug Tracker, https://github.com/scipp/cyclebane/issues
+Project-URL: Documentation, https://scipp.github.io/cyclebane
+Project-URL: Source, https://github.com/scipp/cyclebane
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![PyPI badge](http://img.shields.io/pypi/v/cyclebane.svg)](https://pypi.python.org/pypi/cyclebane)
+[![Anaconda-Server Badge](https://anaconda.org/scipp/cyclebane/badges/version.svg)](https://anaconda.org/scipp/cyclebane)
+[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE)
+
+# Cyclebane
+
+## About
+
+Transform directed acyclic graphs using map-reduce and groupby operations
+
+This library is an attempt to merge the concepts of directed acyclic graphs (DAG) with array-like objects such as NumPy arrays, Pandas DataFrames, or Xarray/Scipp DataArrays.
+This could be useful for describing tasks graphs, e.g., when a series of tasks is applied to chunks of an array.
+These tasks also have an array structure.
+After an reduction operation of chunks, the graph loses this structure, i.e., only a subset of the graph's nodes has array structure.
+What if we could work with this structure, even though only parts of the graph follows it?
+And what if we could use the power of array slicing with named dimensions, or select by label?
+This is what Cyclebane tries to do.
+
+Our initial goal is to support:
+
+- `map` operations of a DAG's source nodes over an array-like (https://docs.dask.org/en/latest/high-level-graphs.html).
+  Cyclebane will effectively copy all descendants of those nodes, once for each array element.
+  Cyclebane will support joint mappings of multiple source nodes by mapping over, e.g., a DataFrame with multiple columns, as well as chaining independent map operations at different source nodes.
+  In the latter case this will effectively broadcast at descendant nodes that depend on multiple such source nodes.
+- `reduce` operations at descendants of mapped nodes.
+  This will add a new node with edges to all copies of the mapped node being reduced.
+  Cyclebane will support reducing only individual axes or all axes, similar to Numpy.
+- `groupby` operations similar to Pandas and Xarray (albeit more limited).
+- Positional and label-based indexing.
+  Cyclebane will support selecting branches that were creating during `map` (or `groupby`) operations based on their indices.
+  The graph structure will be left untouched, i.e., nodes after a `reduce` operation will be preserved, but fewer edges will lead to the reduce node.
+
+See also Dask's [High Level Graphs](https://docs.dask.org/en/latest/high-level-graphs.html) for a related concept (without the direct support for any such operations).
+
+## Installation
+
+```sh
+python -m pip install cyclebane
+```

cyclebane-24.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cyclebane/__init__.py,sha256=YGeabZhJkCjRwK-c5kfL4G7viTRXljZRK4_a78fJMoY,371
+cyclebane/graph.py,sha256=M3bX2BTgKhfNM9QnTa1RZiF0KiXvRhFFU_4w5_JCiQU,17165
+cyclebane/node_values.py,sha256=ju6sfSZsLuIdL9Pxcc9cXsNHNJPzx0YCkDsKlfk-3XY,13588
+cyclebane/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cyclebane-24.5.0.dist-info/LICENSE,sha256=nVEiume4Qj6jMYfSRjHTM2jtJ4FGu0g-5Sdh7osfEYw,1553
+cyclebane-24.5.0.dist-info/METADATA,sha256=0nEYg9Ssl5SpZUxf8_mLBy2CdMbicvabPpGCMywA-l0,5400
+cyclebane-24.5.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+cyclebane-24.5.0.dist-info/top_level.txt,sha256=KVv2uZtZFY3P-omQCsFyxjazWD32M_ym0Kpt-rUxn8Q,10
+cyclebane-24.5.0.dist-info/RECORD,,

cyclebane-24.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.43.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cyclebane-24.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cyclebane