Promote analysis results deprecation (#1532)

* Replace `deprecate_arg` with `warn_from_qe` for issuing deprecation
warnings from internal qiskit-experiments code. `deprecate_arg` was not
working for the cases it was being used for (deprecating the default
value of a keyword argument, deprecating the type of an argument in a
function that could be called at different stack levels). `warn_from_qe`
blames the caller of qiskit-experiments. The docstring deprecation
message has to be added separately.
* Promote the deprecation of
`ExperimentData.add_analysis_results(results)`. This was previously a
pending deprecation. Now results must be added via keyword arguments for
their properties. All internal usage was updated not to issue
deprecation warnings. `add_analysis_result` was added as an alias to
reflect that only one result should be added at a time now.
* Promote deprecation of
`ExperimentData.analysis_results(dataframe=False)`. All internal usage
was updated not to trigger deprecation warnings. The default remains
`dataframe=False` for backwards compatibility. This default should not
change in the near term because this is a major user-facing change.
* Update `RBAnalysis` to accept the dataframe version of the analysis
result as the `epg_1_qubit` option.
* Add `AnalysisResultData.as_table_element` for convenience in passing a
result data object to `add_analysis_result`.
* Use `warn_from_qe` to warn about slice and integer arguments to
`analysis_results`. This might result in warnings being visible that
were previously hidden by stack level.

Author: wshanks

docs/howtos/cloud_service.rst

@@ -67,51 +67,11 @@ Now we can display the figure from the loaded experiment data:
 
 .. image:: ./experiment_cloud_service/t1_loaded.png
 
-The analysis results have been retrieved as well:
+The analysis results have been retrieved as well and can be accessed normally.
 
 .. jupyter-input::
 
-    for result in load_expdata.analysis_results():
-        print(result)
-
-.. jupyter-output::
-
-    AnalysisResult
-    - name: T1
-    - value: 0.0001040+/-0.0000028
-    - χ²: 0.8523786276663019
-    - quality: good
-    - extra: <1 items>
-    - device_components: ['Q0']
-    - verified: False
-    AnalysisResult
-    - name: @Parameters_T1Analysis
-    - value: CurveFitResult:
-    - fitting method: least_squares
-    - number of sub-models: 1
-    * F_exp_decay(x) = amp * exp(-x/tau) + base
-    - success: True
-    - number of function evals: 9
-    - degree of freedom: 9
-    - chi-square: 7.671407648996717
-    - reduced chi-square: 0.8523786276663019
-    - Akaike info crit.: 0.6311217041870707
-    - Bayesian info crit.: 2.085841653551072
-    - init params:
-    * amp = 0.923076923076923
-    * tau = 0.00016946294665316433
-    * base = 0.033466533466533464
-    - fit params:
-    * amp = 0.9266620487665083 ± 0.007096409569790425
-    * tau = 0.00010401411623191737 ± 2.767679521974391e-06
-    * base = 0.036302726197354626 ± 0.0037184540724124844
-    - correlations:
-    * (tau, base) = -0.6740808746060173
-    * (amp, base) = -0.4231810882291163
-    * (amp, tau) = 0.09302612202500576
-    - quality: good
-    - device_components: ['Q0']
-    - verified: False
+    results = load_expdata.analysis_results(dataframe=True))
 
 Discussion
 ----------

docs/manuals/characterization/t1.rst

@@ -75,8 +75,7 @@ for qubit 0.
 
     # Print the result
     display(exp_data.figure(0))
-    for result in exp_data.analysis_results():
-        print(result)
+    print(exp_data.analysis_results(dataframe=True))
 
 
 :math:`T_1` experiments with kerneled measurement
@@ -135,8 +134,7 @@ that is close to a logical value '0'.
 
     # Displaying results
     display(expdataT1_kerneled.figure(0))
-    for result in expdataT1_kerneled.analysis_results():
-        print(result)
+    display(expdataT1_kerneled.analysis_results(dataframe=True))
 
 See also
 --------

docs/manuals/characterization/t2hahn.rst

@@ -105,8 +105,7 @@ The resulting graph will have the form:
 .. jupyter-execute::
 
     # Print results
-    for result in expdata1.analysis_results():
-        print(result)
+    display(expdata1.analysis_results(dataframe=True))
 
 
 Providing initial user estimates
@@ -136,8 +135,7 @@ computed for other qubits.
 .. jupyter-execute::
 
     # Print results
-    for result in expdata_with_p0.analysis_results():
-        print(result)
+    display(expdata_with_p0.analysis_results(dataframe=True))
 
 
 

docs/manuals/characterization/t2ramsey.rst

@@ -98,8 +98,7 @@ frequency.
 .. jupyter-execute::
 
     # Print results
-    for result in expdata1.analysis_results():
-        print(result)
+    display(expdata1.analysis_results(dataframe=True))
 
 
 Providing initial user estimates
@@ -137,8 +136,7 @@ computed for other qubits.
 .. jupyter-execute::
 
     # Print results
-    for result in expdata_with_p0.analysis_results():
-        print(result)
+    display(expdata_with_p0.analysis_results(dataframe=True))
 
 
 See also

docs/manuals/characterization/tphi.rst

@@ -66,21 +66,20 @@ Run the experiment and print results:
 .. jupyter-execute::
 
     expdata = exp.run(backend=backend, seed_simulator=100).block_for_results()
-    result = expdata.analysis_results("T_phi")
-    print(result)
+    display(expdata.analysis_results("T_phi", dataframe=True))
 
 You can also retrieve the results and figures of the constituent experiments. :class:`.T1`:
 
 .. jupyter-execute::
 
-    print(expdata.analysis_results("T1"))
+    display(expdata.analysis_results("T1", dataframe=True))
     display(expdata.figure(0))
 
 And :class:`.T2Hahn`:
 
 .. jupyter-execute::
 
-    print(expdata.analysis_results("T2"))
+    display(expdata.analysis_results("T2", dataframe=True))
     display(expdata.figure(1))
 
 Let's now run the experiment with :class:`.T2Ramsey` by setting the ``t2type`` option to
@@ -102,7 +101,7 @@ Run and display results:
 .. jupyter-execute::
 
     expdata = exp.run(backend=backend, seed_simulator=100).block_for_results()
-    print(expdata.analysis_results("T_phi"))
+    display(expdata.analysis_results("T_phi", dataframe=True))
     display(expdata.figure(1))
 
 Because we are using a simulator that doesn't model inhomogeneous broadening, the

docs/manuals/measurement/readout_mitigation.rst

@@ -70,7 +70,7 @@ circuits, one for all “0” and one for all “1” results.
 
     exp.analysis.set_options(plot=True)
     result = exp.run(backend)
-    mitigator = result.analysis_results("Local Readout Mitigator").value
+    mitigator = result.analysis_results("Local Readout Mitigator", dataframe=True).iloc[0].value
 
 The resulting measurement matrix can be illustrated by comparing it to
 the identity.

docs/manuals/verification/quantum_volume.rst

@@ -100,17 +100,7 @@ Extra data included in the analysis results includes
     # View result data
     display(expdata.figure(0))
 
-    for result in expdata.analysis_results():
-        print(result)
-
-
-.. jupyter-execute::
-
-    # Print extra data
-    for result in expdata.analysis_results():
-        print(f"\n{result.name} extra:")
-        for key, val in result.extra.items():
-            print(f"- {key}: {val}")
+    display(expdata.analysis_results(dataframe=True))
 
 
 Adding trials
@@ -131,8 +121,7 @@ re-running the experiment.
 
     # View result data
     display(expdata2.figure(0))
-    for result in expdata2.analysis_results():
-        print(result)
+    display(expdata2.analysis_results(dataframe=True))
 
 
 Calculating Quantum Volume using a batch experiment
@@ -157,10 +146,7 @@ Extracting the maximum Quantum Volume.
 
 .. jupyter-execute::
 
-    qv_values = [
-        batch_expdata.analysis_results("quantum_volume")[i].value
-        for i in range(batch_exp.num_experiments)
-    ]
+    qv_values = batch_expdata.analysis_results("quantum_volume", dataframe=True).value.tolist()
 
     print(f"Max quantum volume is: {max(qv_values)}")
 
@@ -170,8 +156,7 @@ Extracting the maximum Quantum Volume.
     for i in range(batch_exp.num_experiments):
         print(f"\nComponent experiment {i}")
         display(batch_expdata.figure(i))
-    for result in batch_expdata.analysis_results():
-        print(result)
+    display(batch_expdata.analysis_results(dataframe=True))
 
 References
 ----------

docs/manuals/verification/randomized_benchmarking.rst

@@ -109,14 +109,11 @@ interleaved RB experiment will always give you accurate error value :math:`e_i`.
     # Run an RB experiment on qubit 0
     exp1 = StandardRB(qubits, lengths, num_samples=num_samples, seed=seed)
     expdata1 = exp1.run(backend).block_for_results()
-    results1 = expdata1.analysis_results()
 
     # View result data
     print("Gate error ratio: %s" % expdata1.experiment.analysis.options.gate_error_ratio)
     display(expdata1.figure(0))
-    for result in results1:
-        print(result)
-
+    display(expdata1.analysis_results(dataframe=True))
 
 
 Running a 2-qubit RB experiment
@@ -193,16 +190,15 @@ The EPGs of two-qubit RB are analyzed with the corrected EPC if available.
     exp_2q = StandardRB(qubits, lengths_2_qubit, num_samples=num_samples, seed=seed)
 
     # Use the EPG data of the 1-qubit runs to ensure correct 2-qubit EPG computation
-    exp_2q.analysis.set_options(epg_1_qubit=expdata_1q.analysis_results())
+    exp_2q.analysis.set_options(epg_1_qubit=expdata_1q.analysis_results(dataframe=True))
 
     # Run the 2-qubit experiment
     expdata_2q = exp_2q.run(backend).block_for_results()
 
     # View result data
     print("Gate error ratio: %s" % expdata_2q.experiment.analysis.options.gate_error_ratio)
     display(expdata_2q.figure(0))
-    for result in expdata_2q.analysis_results():
-        print(result)
+    display(expdata_2q.analysis_results(dataframe=True))
 
 
 Note that ``EPC_corrected`` value is smaller than one of raw ``EPC``, which indicates
@@ -280,14 +276,13 @@ Let's run an interleaved RB experiment on two qubits:
         circuits.CXGate(), qubits, lengths, num_samples=num_samples, seed=seed)
 
     int_expdata2 = int_exp2.run(backend).block_for_results()
-    int_results2 = int_expdata2.analysis_results()
+    int_results2 = int_expdata2.analysis_results(dataframe=True)
 
 .. jupyter-execute::
 
     # View result data
     display(int_expdata2.figure(0))
-    for result in int_results2:
-        print(result)
+    display(int_results2)
 
 
 References

docs/manuals/verification/state_tomography.rst

@@ -45,9 +45,7 @@ to describe the preparation circuit.
     qstdata1 = qstexp1.run(backend, seed_simulation=100).block_for_results()
 
     # Print results
-    for result in qstdata1.analysis_results():
-        print(result)
-
+    display(qstdata1.analysis_results(dataframe=True))
 
 
 Tomography Results
@@ -58,15 +56,16 @@ The main result for tomography is the fitted state, which is stored as a
 
 .. jupyter-execute::
 
-    state_result = qstdata1.analysis_results("state")
+    state_result = qstdata1.analysis_results("state", dataframe=True).iloc[0]
     print(state_result.value)
 
 We can also visualize the density matrix:
 
 .. jupyter-execute::
 
     from qiskit.visualization import plot_state_city
-    plot_state_city(qstdata1.analysis_results("state").value, title='Density Matrix')
+    state = qstdata1.analysis_results("state", dataframe=True).iloc[0].value
+    plot_state_city(state, title='Density Matrix')
 
 The state fidelity of the fitted state with the ideal state prepared by
 the input circuit is stored in the ``"state_fidelity"`` result field.
@@ -76,22 +75,19 @@ state cannot be automatically generated and this field will be set to
 
 .. jupyter-execute::
 
-    fid_result = qstdata1.analysis_results("state_fidelity")
+    fid_result = qstdata1.analysis_results("state_fidelity", dataframe=True).iloc[0]
     print("State Fidelity = {:.5f}".format(fid_result.value))
 
 
 
 Additional state metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Additional data is stored in the tomography under the
-``"state_metadata"`` field. This includes
+Additional data is stored in the tomography under additional fields. This includes
 
 - ``eigvals``: the eigenvalues of the fitted state 
 - ``trace``: the trace of the fitted state 
 - ``positive``: Whether the eigenvalues are all non-negative 
-- ``positive_delta``: the deviation from positivity given by 1-norm of negative
-  eigenvalues.
 
 If trace rescaling was performed this dictionary will also contain a ``raw_trace`` field
 containing the trace before rescaling. Futhermore, if the state was rescaled to be
@@ -100,7 +96,8 @@ eigenvalues before rescaling was performed.
 
 .. jupyter-execute::
 
-    state_result.extra
+    for col in ["eigvals", "trace", "positive"]:
+        print(f"{col}: {state_result[col]}")
 
 To see the effect of rescaling, we can perform a “bad” fit with very low
 counts:
@@ -109,14 +106,11 @@ counts:
 
     # QST Experiment
     bad_data = qstexp1.run(backend, shots=10, seed_simulation=100).block_for_results()
-    bad_state_result = bad_data.analysis_results("state")
+    bad_state_result = bad_data.analysis_results("state", dataframe=True).iloc[0]
 
     # Print result
-    print(bad_state_result)
-    
-    # Show extra data
-    bad_state_result.extra
-
+    for key, val in bad_state_result.items():
+        print(f"{key}: {val}")
 
 
 Tomography Fitters
@@ -144,11 +138,9 @@ PSD without requiring rescaling.
         # Re-run experiment
         qstdata2 = qstexp1.run(backend, seed_simulation=100).block_for_results()
 
-        state_result2 = qstdata2.analysis_results("state")
-        print(state_result2)   
-        print("\nextra:")
-        for key, val in state_result2.extra.items():
-            print(f"- {key}: {val}")
+        state_result2 = qstdata2.analysis_results("state", dataframe=True).iloc[0]
+        for key, val in state_result2.items():
+            print(f"{key}: {val}")
 
     except ModuleNotFoundError:
         print("CVXPY is not installed")
@@ -175,20 +167,14 @@ For example if we want to perform 1-qubit QST on several qubits at once:
     parexp = ParallelExperiment(subexps)
     pardata = parexp.run(backend, seed_simulation=100).block_for_results()
 
-    for result in pardata.analysis_results():
-        print(result)
+    display(pardata.analysis_results(dataframe=True))
 
-View component experiment analysis results:
+View experiment analysis results for one component:
 
 .. jupyter-execute::
 
-    for i, expdata in enumerate(pardata.child_data()):
-        state_result_i = expdata.analysis_results("state")
-        fid_result_i = expdata.analysis_results("state_fidelity")
-        
-        print(f'\nPARALLEL EXP {i}')
-        print("State Fidelity: {:.5f}".format(fid_result_i.value))
-        print("State: {}".format(state_result_i.value))
+    results = pardata.analysis_results(dataframe=True)
+    display(results[results.components.apply(lambda x: x == ["Q0"])])
 
 References
 ----------

docs/release_notes.rst

@@ -2483,7 +2483,7 @@ Upgrade Notes
 - The data format of analysis result data value has been replaced from
   :class:`FitVal` to ``uncertainties.ufloat`` from the Python
   `uncertainties <https://pythonhosted.org/uncertainties/>`__ package to support
-  error propatation for post analysis computation.
+  error propagation for post analysis computation.
 
   .. code-block:: python