pygsti.protocols.protocol.ProtocolData

class ProtocolData(edesign, dataset=None, cache=None)

Bases: TreeNode, MongoSerializable

Represents the experimental data needed to run one or more QCVV protocols.

This class contains a ProtocolIput, which describes a set of circuits, and a DataSet (or MultiDataSet) that holds data for these circuits. These members correspond to the .edesign and .dataset attributes.

Parameters:

• edesign (ExperimentDesign) – The experiment design describing what circuits this object contains data for. If None, then an unstructured ExperimentDesign is created containing the circuits present in dataset.

• dataset (DataSet or MultiDataSet, optional) – The data counts themselves.

• cache (dict, optional) – A cache of values which holds values derived only from the experiment design and data in this object.

passes

A dictionary of the data on a per-pass basis (works even it there’s just one pass).

Type:

dict

Create a new ProtocolData object.

Parameters:

• edesign (ExperimentDesign) – The experiment design describing what circuits this object contains data for. If None, then an unstructured ExperimentDesign is created containing the circuits present in dataset.

• dataset (DataSet or MultiDataSet, optional) – The data counts themselves.

• cache (dict, optional) – A cache of values which holds values derived only from the experiment design and data in this object.

Return type:

ProtocolData

Methods

__init__(edesign[, dataset, cache])	Create a new ProtocolData object.
add_mongodb_write_ops(write_ops, mongodb[, ...])	Accumulate write and update operations for writing this object to a MongoDB database.
copy()	Make a copy of this object.
from_dir(dirname[, parent, name, ...])	Initialize a new ProtocolData object from dirname.
from_mongodb(mongodb, doc_id, **kwargs)	Create and initialize an object from a MongoDB instance.
from_mongodb_doc(mongodb, collection_name, ...)	Create and initialize an object from a MongoDB instance and pre-loaded primary document.
is_multipass()	Whether this protocol data contains multiple passes.
items()	An iterator over the (child_name, child_node) pairs of this node.
keys()	An iterator over the keys (child names) of this tree node.
prune_tree(paths[, paths_are_sorted])	Prune the tree rooted here to include only the given paths, discarding all else.
remove_from_mongodb(mongodb, doc_id[, ...])	Remove the documents corresponding to an instance of this class from a MongoDB database.
remove_me_from_mongodb(mongodb[, session, ...])
setup_nameddict(final_dict)	Initializes a set of nested NamedDict dictionaries describing this data.
to_dataframe([pivot_valuename, pivot_value, ...])	Create a Pandas dataframe with this data.
underlying_tree_paths()	Dictionary paths leading to data objects/nodes beneath this one.
view(keys_to_keep)	Get a "view" of this tree node that only has a subset of this node's children.
write([dirname, parent, edesign_already_written])	Write this protocol data to a directory.
write_to_mongodb(mongodb[, session, ...])	Write this object to a MongoDB database.

Attributes

CACHE_COLLECTION_NAME
collection_name
passes	A dictionary of the data on a per-pass basis (works even it there's just one pass).

add_mongodb_write_ops(write_ops, mongodb, overwrite_existing=False, **kwargs)

Accumulate write and update operations for writing this object to a MongoDB database.

Similar to write_to_mongodb() but collects write operations instead of actually executing any write operations on the database. This function may be preferred to write_to_mongodb() when this object is being written as a part of a larger entity and executing write operations is saved until the end.

As in write_to_mongodb(), self.collection_name is the collection name and _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

• write_ops (WriteOpsByCollection) – An object that keeps track of pymongo write operations on a per-collection basis. This object accumulates write operations to be performed at some point in the future.

• mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

• overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

copy()

Make a copy of this object.

Return type:

ProtocolData

classmethod from_dir(dirname, parent=None, name=None, preloaded_edesign=None, quick_load=False, record_zero_counts=True)

Initialize a new ProtocolData object from dirname.

Parameters:

• dirname (str) – The root directory name (under which there are ‘edesign’ and ‘data’ subdirectories).

• parent (ProtocolData, optional) – The parent data object, if there is one. This is needed for sub-data objects which reference/inherit their parent’s dataset. Primarily used internally - if in doubt, leave this as None.

• name (str, optional) – The sub-name of the object being loaded, i.e. the key of this data object beneath parent. Only used when parent is not None.

• preloaded_edesign (ExperimentDesign, optional) – In the case that the ExperimentDesign object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.

• quick_load (bool, optional) – Setting this to True skips the loading of components that may take a long time, e.g. the actual raw data set(s). This can be useful when loading takes a long time and all the information of interest lies elsewhere, e.g. in an encompassing results object.

• record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in the datasets held within this ProtocolData object.

Return type:

ProtocolData

classmethod from_mongodb(mongodb, doc_id, **kwargs)

Create and initialize an object from a MongoDB instance.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to load from.

• doc_id (bson.objecctid.ObjectId or dict) – The object ID or filter used to find a single object ID within the database. This document is loaded from the collection given by the collection_name attribute of this class.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

classmethod from_mongodb_doc(mongodb, collection_name, doc, **kwargs)

Create and initialize an object from a MongoDB instance and pre-loaded primary document.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to load from.

• collection_name (str) – The collection name within mongodb that doc was loaded from. This is needed for the sole purpose of setting the created (returned) object’s database “coordinates”.

• doc (dict) – The already-retrieved main document for the object being loaded. This takes the place of giving an identifier for this object.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

is_multipass()

Whether this protocol data contains multiple passes.

More accurately, whether the .dataset of this object is a MultiDataSet.

Return type:

bool

items()

An iterator over the (child_name, child_node) pairs of this node.

keys()

An iterator over the keys (child names) of this tree node.

prune_tree(paths, paths_are_sorted=False)

Prune the tree rooted here to include only the given paths, discarding all else.

Returns a new ProtocolData object with a subset of the data-tree paths contained under this one.

Parameters:

• paths (list) – A list of the paths to keep. Each path is a tuple of keys, delineating a path in the data-tree.

• paths_are_sorted (bool, optional) – Whether paths has already been sorted lexicographically.

Return type:

ProtocolData

classmethod remove_from_mongodb(mongodb, doc_id, collection_name=None, session=None, recursive='default')

Remove the documents corresponding to an instance of this class from a MongoDB database.

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to remove documents from.

• doc_id (bson.objectid.ObjectId) – The identifier of the root document stored in the database.

• collection_name (str, optional) – the MongoDB collection within mongodb where the main document resides. If None, then <this_class>.collection_name is used (which is usually what you want).

• session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

• recursive (RecursiveRemovalSpecification, optional) – An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Return type:

None

setup_nameddict(final_dict)

Initializes a set of nested NamedDict dictionaries describing this data.

This function is used by ProtocolResults objects when they’re creating nested dictionaries of their contents. The final nested dictionary is set to be final_dict, which allows additional result quantities to easily be added.

Parameters:

final_dict (NamedDict) – the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Return type:

NamedDict

to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False)

Create a Pandas dataframe with this data.

Parameters:

• pivot_valuename (str, optional) – If not None, the resulting dataframe is pivoted using pivot_valuename as the column whose values name the pivoted table’s column names. If None and pivot_value is not None,`”ValueName”` is used.

• pivot_value (str, optional) – If not None, the resulting dataframe is pivoted such that values of the pivot_value column are rearranged into new columns whose names are given by the values of the pivot_valuename column. If None and pivot_valuename is not None,`”Value”` is used.

• drop_columns (bool or list, optional) – A list of column names to drop (prior to performing any pivot). If True appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when drop_columns == False.

Return type:

pandas.DataFrame

underlying_tree_paths()

Dictionary paths leading to data objects/nodes beneath this one.

Returns:

A list of tuples, each specifying the tree traversal to a child node. The first tuple is the empty tuple, referring to this (root) node.

Return type:

list

view(keys_to_keep)

Get a “view” of this tree node that only has a subset of this node’s children.

Parameters:

keys_to_keep (iterable) – A sequence of key names to keep.

Return type:

TreeNode

write(dirname=None, parent=None, edesign_already_written=False)

Write this protocol data to a directory.

Parameters:

• dirname (str) – The root directory to write into. This directory will have ‘edesign’ and ‘data’ subdirectories, which will be created if needed and overwritten if present. If None, then the path this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).

• parent (ProtocolData, optional) – The parent protocol data, when a parent is writing this data as a sub-protocol-data object. Otherwise leave as None.

• edesign_already_written (bool, optional) – If True, the experiment design within this data object is not written to disk, and it is left to the caller to ensure the experiment design is saved.

Return type:

None

write_to_mongodb(mongodb, session=None, overwrite_existing=False, **kwargs)

Write this object to a MongoDB database.

The collection name used is self.collection_name, and the _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

• mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

• session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

• overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

• **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

property passes

A dictionary of the data on a per-pass basis (works even it there’s just one pass).

Return type:

dict