Introduce dataframe to ExperimentData (step1) (#1133)

### Summary

Executing approved design proposal in
https://github.com/Qiskit/rfcs/blob/master/0007-experiment-dataframe.md.
Introduction of the `Artifact` will be done in the followup.

This PR introduces dataframe to `ExperimentData` and replaces the
conventional
[AnalysisResult](https://github.com/Qiskit/qiskit-experiments/blob/main/qiskit_experiments/framework/analysis_result.py)
with it. With this PR, experimentalist can visualize all analysis
results with a single html table by `dataframe=True`.


![image](https://user-images.githubusercontent.com/39517270/230959307-d5a4d471-1659-4cf4-974e-cdb21e625ad8.png)

Once can control the columns to show in the html table with `columns`
option.


### Details and comments

Experiment analysis is a local operation on client side, and data
generated there must be agnostic to the payload format of remote
service. In the current implementation, `AnalysisResult` appears in the
`BaseAnalysis` and the data generated by the analysis is implicitly
typecasted to this class. Note that `AnalysisResult` *not only* defines
canonical data format *but also* implements the API for the IBM
Experiment service. This tight coupling to the IBM Experiment service
may limit data expressibility and an analysis class author always need
to be aware of the data structure of the remote service.

In this PR, internal data structure is replaced with the flat dataframe,
and one should be able to add arbitrary key-value pair to the analysis
result without concerning about data model. Added key creates a new
column in the table, which must be internally formatted and absorbed by
extra field of the payload at a later time when these results are saved.
This is implemented by
`qiskit_experiments.framework.experiment_data._series_to_service_result`.
Bypassing the generation of `AnalysisResult` object also drastically
improves the performance of heavily parallelized analysis that generates
huge amount of data.

---------

Co-authored-by: Helena Zhang <[email protected]>

Author: nkanazawa1989

qiskit_experiments/database_service/device_component.py

@@ -81,9 +81,10 @@ def to_component(string: str) -> DeviceComponent:
     Raises:
         ValueError: If input string is not a valid device component.
     """
+    if isinstance(string, DeviceComponent):
+        return string
     if string.startswith("Q"):
         return Qubit(int(string[1:]))
-    elif string.startswith("R"):
+    if string.startswith("R"):
         return Resonator(int(string[1:]))
-    else:
-        return UnknownComponent(string)
+    return UnknownComponent(string)

qiskit_experiments/database_service/utils.py

@@ -19,12 +19,14 @@
 from abc import ABC, abstractmethod
 from collections import OrderedDict
 from datetime import datetime, timezone
-from typing import Callable, Tuple, Dict, Any, Union, Type, Optional
+from typing import Callable, Tuple, List, Dict, Any, Union, Type, Optional
 import json
 
+import pandas as pd
 import dateutil.parser
 import pkg_resources
 from dateutil import tz
+
 from qiskit.version import __version__ as terra_version
 
 from qiskit_ibm_experiment import (
@@ -276,3 +278,199 @@ def append(self, value):
         """Append to the list."""
         with self._lock:
             self._container.append(value)
+
+
+class ThreadSafeDataFrame(ThreadSafeContainer):
+    """Thread safe data frame.
+
+    This class wraps pandas dataframe with predefined column labels,
+    which is specified by the class method `_default_columns`.
+    Subclass can override this method to provide default labels specific to its data structure.
+
+    This object is expected to be used internally in the ExperimentData.
+    """
+
+    def __init__(self, init_values=None):
+        """ThreadSafeContainer constructor."""
+        self._columns = self._default_columns()
+        self._extra = []
+        super().__init__(init_values)
+
+    @classmethod
+    def _default_columns(cls) -> List[str]:
+        return []
+
+    def _init_container(self, init_values: Optional[Union[Dict, pd.DataFrame]] = None):
+        """Initialize the container."""
+        if init_values is None:
+            return pd.DataFrame(columns=self.get_columns())
+        if isinstance(init_values, pd.DataFrame):
+            input_columns = list(init_values.columns)
+            if input_columns != self.get_columns():
+                raise ValueError(
+                    f"Input data frame contains unexpected columns {input_columns}. "
+                    f"{self.__class__.__name__} defines {self.get_columns()} as default columns."
+                )
+            return init_values
+        if isinstance(init_values, dict):
+            return pd.DataFrame.from_dict(
+                data=init_values,
+                orient="index",
+                columns=self.get_columns(),
+            )
+        raise TypeError(f"Initial value of {type(init_values)} is not valid data type.")
+
+    def get_columns(self) -> List[str]:
+        """Return current column names.
+
+        Returns:
+            List of column names.
+        """
+        with self._lock:
+            return self._columns.copy()
+
+    def add_columns(self, *new_columns: str, default_value: Any = None):
+        """Add new columns to the table.
+
+        This operation mutates the current container.
+
+        Args:
+            new_columns: Name of columns to add.
+            default_value: Default value to fill added columns.
+        """
+        with self._lock:
+            # Order sensitive
+            new_columns = [c for c in new_columns if c not in self.get_columns()]
+            if len(new_columns) == 0:
+                return
+
+            # Update columns
+            for new_column in new_columns:
+                self._container.insert(len(self._container.columns), new_column, default_value)
+            self._columns.extend(new_columns)
+            self._extra.extend(new_columns)
+
+    def clear(self):
+        """Remove all elements from this container."""
+        with self._lock:
+            self._container = self._init_container()
+            self._columns = self._default_columns()
+            self._extra = []
+
+    def container(
+        self,
+        collapse_extra: bool = True,
+    ) -> pd.DataFrame:
+        """Return bare pandas dataframe.
+
+        Args:
+            collapse_extra: Set True to show only default columns.
+
+        Returns:
+            Bare pandas dataframe. This object is no longer thread safe.
+        """
+        with self._lock:
+            container = self._container.copy()
+
+        if collapse_extra:
+            return container[self._default_columns()]
+        return container
+
+    def drop_entry(
+        self,
+        index: str,
+    ):
+        """Drop entry from the dataframe.
+
+        Args:
+            index: Name of entry to drop.
+
+        Raises:
+            ValueError: When index is not in this table.
+        """
+        with self._lock:
+            if index not in self._container.index:
+                raise ValueError(f"Table index {index} doesn't exist in this table.")
+            self._container.drop(index, inplace=True)
+
+    def get_entry(
+        self,
+        index: str,
+    ) -> pd.Series:
+        """Get entry from the dataframe.
+
+        Args:
+            index: Name of entry to acquire.
+
+        Returns:
+            Pandas Series of acquired entry. This doesn't mutate the table.
+
+        Raises:
+            ValueError: When index is not in this table.
+        """
+        with self._lock:
+            if index not in self._container.index:
+                raise ValueError(f"Table index {index} doesn't exist in this table.")
+
+            return self._container.loc[index]
+
+    def add_entry(
+        self,
+        index: str,
+        **kwargs,
+    ) -> pd.Series:
+        """Add new entry to the dataframe.
+
+        Args:
+            index: Name of this entry. Must be unique in this table.
+            kwargs: Description of new entry to register.
+
+        Returns:
+            Pandas Series of added entry. This doesn't mutate the table.
+
+        Raises:
+            ValueError: When index is not unique in this table.
+        """
+        with self._lock:
+            if index in self._container.index:
+                raise ValueError(f"Table index {index} already exists in the table.")
+
+            if kwargs.keys() - set(self.get_columns()):
+                self.add_columns(*kwargs.keys())
+
+            template = dict.fromkeys(self.get_columns())
+            template.update(kwargs)
+
+            if not isinstance(index, str):
+                index = str(index)
+            self._container.loc[index] = list(template.values())
+
+            return self._container.iloc[-1]
+
+    def _repr_html_(self) -> Union[str, None]:
+        """Return HTML representation of this dataframe."""
+        with self._lock:
+            # Remove underscored columns.
+            return self._container._repr_html_()
+
+    def __json_encode__(self) -> Dict[str, Any]:
+        with self._lock:
+            return {
+                "class": "ThreadSafeDataFrame",
+                "data": self._container.to_dict(orient="index"),
+                "columns": self._columns,
+                "extra": self._extra,
+            }
+
+    @classmethod
+    def __json_decode__(cls, value: Dict[str, Any]) -> "ThreadSafeDataFrame":
+        if not value.get("class", None) == "ThreadSafeDataFrame":
+            raise ValueError("JSON decoded value for ThreadSafeDataFrame is not valid class type.")
+
+        instance = object.__new__(cls)
+        # Need to update self._columns first to set extra columns in the dataframe container.
+        instance._columns = value.get("columns", cls._default_columns())
+        instance._extra = value.get("extra", [])
+        instance._lock = threading.RLock()
+        instance._container = instance._init_container(init_values=value.get("data", {}))
+        return instance

qiskit_experiments/framework/__init__.py

@@ -86,6 +86,7 @@
     AnalysisStatus
     AnalysisResult
     AnalysisResultData
+    AnalysisResultTable
     ExperimentConfig
     AnalysisConfig
     ExperimentEncoder
@@ -137,6 +138,7 @@
 from .backend_timing import BackendTiming
 from .configs import ExperimentConfig, AnalysisConfig
 from .analysis_result_data import AnalysisResultData
+from .analysis_result_table import AnalysisResultTable
 from .experiment_data import ExperimentData
 from .composite import (
     ParallelExperiment,

qiskit_experiments/framework/analysis_result_data.py

@@ -16,21 +16,80 @@
 import logging
 from typing import Optional, Dict, Any, List
 
+from qiskit_experiments.database_service.device_component import DeviceComponent
+
+
 LOG = logging.getLogger(__name__)
 
 
 @dataclasses.dataclass
 class AnalysisResultData:
     """Dataclass for experiment analysis results"""
 
-    # TODO: move stderr and unit into custom value class
     name: str
     value: Any
+    experiment: str = None
     chisq: Optional[float] = None
     quality: Optional[str] = None
+    experiment_id: Optional[str] = None
+    result_id: Optional[str] = None
+    tags: List = dataclasses.field(default_factory=list)
+    backend: Optional[str] = None
+    run_time: Optional[str] = None
+    created_time: Optional[str] = None
     extra: Dict[str, Any] = dataclasses.field(default_factory=dict, hash=False, compare=False)
     device_components: List = dataclasses.field(default_factory=list)
 
+    @classmethod
+    def from_table_element(
+        cls,
+        name: str,
+        value: Any,
+        experiment: Optional[str] = None,
+        components: Optional[List[DeviceComponent]] = None,
+        quality: Optional[str] = None,
+        experiment_id: Optional[str] = None,
+        result_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        backend: Optional[str] = None,
+        run_time: Optional[str] = None,
+        created_time: Optional[str] = None,
+        **extra,
+    ):
+        """A factory method of AnalysisResultData from a single element in AnalysisResultTable.
+
+        Args:
+            name: Name of this entity.
+            value: Result value.
+            experiment: Type of experiment.
+            components: Device component that the experiment was run on.
+            quality: Quality of this result.
+            experiment_id: ID of associated experiment.
+            result_id: Unique ID of this data entry in the storage.
+            tags: List of tags.
+            backend: Device name that the experiment was run on.
+            run_time: A time at the experiment was run.
+            created_time: A time at this value was computed.
+            **extra: Extra information.
+        """
+        chisq = extra.pop("chisq", None)
+
+        return AnalysisResultData(
+            name=name,
+            value=value,
+            experiment=experiment,
+            chisq=chisq,
+            quality=quality,
+            experiment_id=experiment_id,
+            result_id=result_id,
+            tags=tags,
+            backend=backend,
+            run_time=run_time,
+            created_time=created_time,
+            device_components=components,
+            extra=extra,
+        )
+
     def __str__(self):
         out = f"{self.name}:"
         out += f"\n- value:{self.value}"
@@ -47,3 +106,35 @@ def __str__(self):
     def __iter__(self):
         """Return iterator of data fields (attr, value)"""
         return iter((field.name, getattr(self, field.name)) for field in dataclasses.fields(self))
+
+
+def as_table_element(
+    result_data: AnalysisResultData,
+) -> Dict[str, Any]:
+    """Python dataclass as_dict-like function to return
+    canonical data for analysis AnalysisResultTable.
+
+    Args:
+        result_data: AnalysisResultData dataclass to format.
+
+    Returns:
+        Formatted data representation in dictionary format.
+    """
+    out = {
+        "name": result_data.name,
+        "experiment": result_data.experiment,
+        "components": result_data.device_components,
+        "value": result_data.value,
+        "quality": result_data.quality,
+        "experiment_id": result_data.experiment_id,
+        "result_id": result_data.result_id,
+        "tags": result_data.tags,
+        "backend": result_data.backend,
+        "run_time": result_data.run_time,
+        "created_time": result_data.created_time,
+    }
+    if result_data.chisq is not None:
+        out["chisq"] = result_data.chisq
+    out.update(result_data.extra)
+
+    return out