Note

This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being released.

ScatterTable¶

class ScatterTable[source]¶

A table-like dataset for the intermediate data used for curve fitting.

Default table columns are defined in the class attribute COLUMNS. This table cannot be expanded with user-provided column names.

In a standard CurveAnalysis subclass, a ScatterTable instance may be stored in the ExperimentData as an artifact. Users can retrieve the table data at a later time to rerun a fitting with a homemade program or with different fit options, or to visualize the curves in a preferred format. This table dataset is designed to seamlessly provide such information that an experimentalist may want to reuse for a custom workflow.

Note

This dataset is not thread safe. Do not use the same instance in multiple threads.

See the tutorial of Managing intermediate data for the role of each table column and how values are typically provided.

Attributes

COLUMNS = ['xval', 'yval', 'yerr', 'series_name', 'series_id', 'category', 'shots', 'analysis']¶

DTYPES = ['Float64', 'Float64', 'Float64', 'string', 'Int64', 'string', 'Int64', 'string']¶

analysis¶: Corresponding analysis name for each data point.

category¶: Array of categories of the data points.

data_allocation¶: Index of corresponding fit model.

Deprecated since version 0.6_pending: The property qiskit_experiments.curve_analysis.scatter_table.ScatterTable.data_allocation is pending deprecation as of qiskit-experiments 0.6. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Curve data uses dataframe representation. Call .series_id instead.

dataframe¶: Dataframe object of data points.

labels¶: List of model names.

Deprecated since version 0.6_pending: The property qiskit_experiments.curve_analysis.scatter_table.ScatterTable.labels is pending deprecation as of qiskit-experiments 0.6. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. No alternative is provided. Use .series_name with set operation.

series_id¶: Corresponding data UID for each data point.

series_name¶: Corresponding data name for each data point.

shots¶: Shot number used to acquire each data point.

x¶: X values.

y¶: Y values.

y_err¶: Standard deviation of Y values.

Methods

__len__()[source]¶: Return the number of data points stored in the table.

add_row(xval=<NA>, yval=<NA>, yerr=<NA>, series_name=<NA>, series_id=<NA>, category=<NA>, shots=<NA>, analysis=<NA>)[source]¶

Add new data point to the table.

Data must be the same length.

Parameters:

xval (float | pd.NA) – X value.
yval (float | pd.NA) – Y value.
yerr (float | pd.NA) – Standard deviation of y value.
series_name (str | pd.NA) – Name of this data series if available.
series_id (int | pd.NA) – Index of this data series if available.
category (str | pd.NA) – Data category if available.
shots (float | pd.NA) – Shot number used to acquire this data point.
analysis (str | pd.NA) – Analysis name if available.

filter(series=None, category=None, analysis=None)[source]¶

Filter data by series, category, and/or analysis name.

Parameters:

series (int | str | None) – Identifier of the data series, either integer series index or name.
category (str | None) – Name of data category.
analysis (str | None) – Name of analysis.

Returns:

New ScatterTable object with filtered data.

Return type:

ScatterTable

classmethod from_dataframe(data)[source]¶

Create new dataset with existing dataframe.

Parameters:: data (DataFrame) – Data dataframe object.
Returns:: A new ScatterTable instance.
Return type:: ScatterTable

get_subset_of(index)[source]¶

Filter data by series name or index.

Deprecated since version 0.6_pending: The method qiskit_experiments.curve_analysis.scatter_table.ScatterTable.get_subset_of() is pending deprecation as of qiskit-experiments 0.6. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Use filter method instead.

Parameters:: index (str | int) – Series index of name.
Returns:: A subset of data corresponding to a particular series.
Return type:: ScatterTable

iter_by_series_id()[source]¶

Iterate over subset of data sorted by the data series index.

Yields:: Tuple of data series index and subset of ScatterTable.
Return type:: Iterator[tuple[int, ScatterTable]]

iter_groups(*group_by)[source]¶

Iterate over the subset sorted by multiple column values.

Parameters:: group_by (str) – Names of columns to group by.
Yields:: Tuple of values for the grouped columns and the corresponding subset of the scatter table.
Return type:: Iterator[tuple[tuple[Any, …], ScatterTable]]

xvals(series=None, category=None, analysis=None, check_unique=True)[source]¶

Get subset of X values.

A convenient shortcut for getting X data with filtering.

Parameters:

series (int | str | None) – Identifier of the data series, either integer series index or name.
category (str | None) – Name of data category.
analysis (str | None) – Name of analysis.
check_unique (bool) – Set True to check if multiple series are contained. When multiple series are contained, it raises a user warning.

Returns:

Numpy array of X values.

Return type:

ndarray

yerrs(series=None, category=None, analysis=None, check_unique=True)[source]¶

Get subset of standard deviation of Y values.

A convenient shortcut for getting Y error data with filtering.

Parameters:

series (int | str | None) – Identifier of the data series, either integer series index or name.
category (str | None) – Name of data category.
analysis (str | None) – Name of analysis.
check_unique (bool) – Set True to check if multiple series are contained. When multiple series are contained, it raises a user warning.

Returns:

Numpy array of Y error values.

Return type:

ndarray

yvals(series=None, category=None, analysis=None, check_unique=True)[source]¶

Get subset of Y values.

A convenient shortcut for getting Y data with filtering.

Parameters:

series (int | str | None) – Identifier of the data series, either integer series index or name.
category (str | None) – Name of data category.
analysis (str | None) – Name of analysis.
check_unique (bool) – Set True to check if multiple series are contained. When multiple series are contained, it raises a user warning.

Returns:

Numpy array of Y values.

Return type:

ndarray