Rework experiment options (#39)

Author: chriseclectic

qiskit_experiments/analysis/plotting.py

@@ -35,7 +35,7 @@ def plot_curve_fit(
 ):
     """Generate plot of a curve fit analysis result.
 
-    Wraps ``matplotlib.pyplot.plot``.
+    Wraps :func:`matplotlib.pyplot.plot`.
 
     Args:
         func: the fit function for curve_fit.

qiskit_experiments/base_analysis.py

@@ -16,25 +16,46 @@
 from abc import ABC, abstractmethod
 from typing import List, Tuple
 
+from qiskit.providers.options import Options
 from qiskit.exceptions import QiskitError
 
-from .experiment_data import ExperimentData, AnalysisResult
+from qiskit_experiments.experiment_data import ExperimentData, AnalysisResult
+
+# pylint: disable = unused-import
+from qiskit_experiments.matplotlib import pyplot
 
 
 class BaseAnalysis(ABC):
-    """Base Analysis class for analyzing Experiment data."""
+    """Base Analysis class for analyzing Experiment data.
+
+    The data produced by experiments (i.e. subclasses of BaseExperiment)
+    are analyzed with subclasses of BaseExperiment. The analysis is
+    typically run after the data has been gathered by the experiment.
+    For example, an analysis may perform some data processing of the
+    measured data and a fit to a function to extract a parameter.
+
+    When designing Analysis subclasses default values for any kwarg
+    analysis options of the `run` method should be set by overriding
+    the `_default_options` class method. When calling `run` these
+    default values will be combined with all other option kwargs in the
+    run method and passed to the `_run_analysis` function.
+    """
 
     # Expected experiment data container for analysis
     __experiment_data__ = ExperimentData
 
+    @classmethod
+    def _default_options(cls) -> Options:
+        return Options()
+
     def run(
         self,
         experiment_data: ExperimentData,
         save: bool = True,
         return_figures: bool = False,
         **options,
     ):
-        """Run analysis and update stored ExperimentData with analysis result.
+        """Run analysis and update ExperimentData with analysis result.
 
         Args:
             experiment_data: the experiment data to analyze.
@@ -43,14 +64,13 @@ def run(
             return_figures: if true return a pair of
                             ``(analysis_results, figures)``,
                             otherwise return only analysis_results.
-            options: kwarg options for analysis function.
+            options: additional analysis options. See class documentation for
+                     supported options.
 
         Returns:
-            AnalysisResult: the output of the analysis that produces a
-                            single result.
             List[AnalysisResult]: the output for analysis that produces
                                   multiple results.
-            tuple: If ``return_figures=True`` the output is a pair
+            Tuple: If ``return_figures=True`` the output is a pair
                    ``(analysis_results, figures)`` where  ``analysis_results``
                    may be a single or list of :class:`AnalysisResult` objects, and
                    ``figures`` may be None, a single figure, or a list of figures.
@@ -63,10 +83,15 @@ def run(
                 f"Invalid experiment data type, expected {self.__experiment_data__.__name__}"
                 f" but received {type(experiment_data).__name__}"
             )
+        # Get analysis options
+        analysis_options = self._default_options()
+        analysis_options.update_options(**options)
+        analysis_options = analysis_options.__dict__
+
         # Run analysis
         # pylint: disable=broad-except
         try:
-            analysis_results, figures = self._run_analysis(experiment_data, **options)
+            analysis_results, figures = self._run_analysis(experiment_data, **analysis_options)
             analysis_results["success"] = True
         except Exception as ex:
             analysis_results = AnalysisResult(success=False, error_message=ex)
@@ -88,18 +113,19 @@ def run(
 
     @abstractmethod
     def _run_analysis(
-        self, data: ExperimentData, **options
-    ) -> Tuple[List[AnalysisResult], List["matplotlib.figure.Figure"]]:
+        self, experiment_data: ExperimentData, **options
+    ) -> Tuple[List[AnalysisResult], List["pyplot.Figure"]]:
         """Run analysis on circuit data.
 
         Args:
             experiment_data: the experiment data to analyze.
-            options: kwarg options for analysis function.
+            options: additional options for analysis. By default the fields and
+                     values in :meth:`options` are used and any provided values
+                     can override these.
 
         Returns:
-            tuple: A pair ``(analysis_results, figures)`` where
-                   ``analysis_results`` may be a single or list of
-                   AnalysisResult objects, and ``figures`` is a list of any
-                   figures for the experiment.
+            A pair ``(analysis_results, figures)`` where ``analysis_results``
+            may be a single or list of AnalysisResult objects, and ``figures``
+            is a list of any figures for the experiment.
         """
         pass