Data processing

qiskit_experiments/data_processing/__init__.py

@@ -0,0 +1,22 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Qiskit experiments calibration data processing roots."""
+
+from .data_action import DataAction
+from .nodes import (
+    Probability,
+    ToImag,
+    ToReal,
+)
+
+from .data_processor import DataProcessor

qiskit_experiments/data_processing/data_action.py

@@ -0,0 +1,76 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Defines the steps that can be used to analyse data."""
+
+from abc import ABCMeta, abstractmethod
+from typing import Any
+
+
+class DataAction(metaclass=ABCMeta):
+    """
+    Abstract action done on measured data to process it. Each subclass of DataAction must
+    define the way it formats, validates and processes data.
+    """
+
+    def __init__(self, validate: bool = True):
+        """
+        Args:
+            validate: If set to False the DataAction will not validate its input.
+        """
+        self._validate = validate
+
+    @abstractmethod
+    def _process(self, datum: Any) -> Any:
+        """
+        Applies the data processing step to the data.
+
+        Args:
+            datum: A single item of data which will be processed.
+
+        Returns:
+            processed data: The data that has been processed.
+        """
+
+    @abstractmethod
+    def _format_data(self, datum: Any, validate: bool = True) -> Any:
+        """
+        Check that the given data has the correct structure. This method may
+        additionally change the data type, e.g. converting a list to a numpy array.
+
+        Args:
+            datum: The data instance to check and format.
+            validate: If True the DataAction checks that the format of the datum is valid.
+
+        Returns:
+            datum: The data that was checked.
+
+        Raises:
+            DataProcessorError: If the data does not have the proper format.
+        """
+
+    def __call__(self, data: Any) -> Any:
+        """
+        Call the data action of this node on the data.
+
+        Args:
+            data: The data to process. The action nodes in the data processor will
+                raise errors if the data does not have the appropriate format.
+
+        Returns:
+            processed data: The data processed by self.
+        """
+        return self._process(self._format_data(data, self._validate))
+
+    def __repr__(self):
+        """String representation of the node."""
+        return f"{self.__class__.__name__}(validate: {self._validate})"

qiskit_experiments/data_processing/data_processor.py

@@ -0,0 +1,119 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Actions done on the data to bring it in a usable form."""
+
+from typing import Any, Dict, List, Set, Tuple
+
+from qiskit_experiments.data_processing.data_action import DataAction
+from qiskit_experiments.data_processing.exceptions import DataProcessorError
+
+
+class DataProcessor:
+    """
+    A DataProcessor defines a sequence of operations to perform on experimental data.
+    The DataProcessor.format_data() method applies this sequence on its input argument.
+    A DataProcessor is created with a list of DataAction objects. Each DataAction
+    specifies a set of node_inputs that it accepts and a __node_output__ that it
+    provides. The __node_output__ of each DataAction must be contained in the node_inputs
+    of the following DataAction in the DataProcessor's list. DataProcessor.format_data()
+    usually takes in one entry from the data property of an ExperimentData object
+    (i.e. a dict containing metadata and memory keys and possibly counts, like the
+    Result.data property) and produces a new dict containing the formatted data. The data
+    passed to DataProcessor.format_data() is passed to the first DataAction and the
+    output is passed on in turn to each DataAction. DataProcessor.format_data() returns
+    the data produced by the last DataAction.
+    """
+
+    def __init__(self, input_key: str, data_actions: List[DataAction] = None):
+        """Create a chain of data processing actions.
+
+        Args:
+            input_key: The initial key in the datum Dict[str, Any] under which the data processor
+                will find the data to process.
+            data_actions: A list of data processing actions to construct this data processor with.
+                If None is given an empty DataProcessor will be created.
+        """
+        self._input_key = input_key
+        self._nodes = []
+
+        if data_actions:
+            for node in data_actions:
+                self.append(node)
+
+    def append(self, node: DataAction):
+        """
+        Append new data action node to this data processor.
+
+        Args:
+            node: A DataAction that will process the data.
+        """
+        self._nodes.append(node)
+
+    def __call__(self, datum: Dict[str, Any]) -> Tuple[Any, Any]:
+        """
+        Call self on the given datum. This method sequentially calls the stored data actions
+        on the datum.
+
+        Args:
+            datum: A single item of data, typically from an ExperimentData instance, that needs
+                to be processed. This dict also contains the metadata of each experiment.
+
+        Returns:
+            processed data: The data processed by the data processor.
+
+        Raises:
+            DataProcessorError: if no nodes are present.
+        """
+        if len(self._nodes) == 0:
+            raise DataProcessorError("Cannot call an empty data processor.")
+
+        datum_ = datum[self._input_key]
+
+        for node in self._nodes:
+            datum_ = node(datum_)
+
+        return datum_
+
+    def call_with_history(
+        self, datum: Dict[str, Any], history_nodes: Set = None
+    ) -> Tuple[Dict[str, Any], List]:
+        """
+        Call self on the given datum. This method sequentially calls the stored data actions
+        on the datum and also returns the history of the processed data.
+
+        Args:
+            datum: A single item of data, typically from an ExperimentData instance, that
+                needs to be processed.
+            history_nodes: The nodes, specified by index in the data processing chain, to
+                include in the history.
+
+        Returns:
+            processed data: The datum processed by the data processor.
+            history: The datum processed at each node of the data processor.
+
+        Raises:
+            DataProcessorError: If no nodes are present.
+        """
+        if len(self._nodes) == 0:
+            raise DataProcessorError("Cannot call an empty data processor.")
+
+        datum_ = datum[self._input_key]
+
+        history = []
+        for index, node in enumerate(self._nodes):
+            datum_ = node(datum_)
+
+            if history_nodes is None or (history_nodes and index in history_nodes):
+                history.append((node.__class__.__name__, datum_, index))
+
+        return datum_, history

qiskit_experiments/data_processing/exceptions.py

@@ -0,0 +1,28 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Exceptions for data processing."""
+
+from qiskit.exceptions import QiskitError
+
+
+class DataProcessorError(QiskitError):
+    """Errors raised by the calibration module."""
+
+    def __init__(self, *message):
+        """Set the error message."""
+        super().__init__(*message)
+        self.message = " ".join(message)
+
+    def __str__(self):
+        """Return the message."""
+        return repr(self.message)