qcodes.data.data_array
- class qcodes.data.data_array.DataArray(parameter=None, name=None, full_name=None, label=None, snapshot=None, array_id=None, set_arrays=(), shape=None, action_indices=(), unit=None, units=None, is_setpoint=False, preset_data=None)[source]
Bases:
DelegateAttributes
A container for one parameter in a measurement loop.
If this is a measured parameter, This object doesn’t contain the data of the setpoints it was measured at, but it references the DataArray objects of these parameters. Those objects only have the dimensionality at which they were set - ie the inner loop setpoint the same dimensionality as the measured parameter, but the outer loop setpoint(s) have lower dimensionality
When it’s first created, a DataArray has no dimensionality, you must call .nest for each dimension.
If preset_data is provided it is used to initialize the data, and the array can still be nested around it (making many copies of the data). Otherwise it is an error to nest an array that already has data.
Once the array is initialized, a DataArray acts a lot like a numpy array, because we delegate attributes through to the numpy array
- Parameters
parameter (Optional[Parameter]) – The parameter whose values will populate this array, if any. Will copy
name
,full_name
,label
,unit
, andsnapshot
from here unless you provide them explicitly.name (Optional[str]) – The short name of this array. TODO: use full_name as name, and get rid of short name
full_name (Optional[str]) – The complete name of this array. If the array is based on a parameter linked to an instrument, this is typically ‘<instrument_name>_<param_name>’
label (Optional[str]) – A description of the values in this array to use for axis and colorbar labels on plots.
snapshot (Optional[dict]) – Metadata snapshot to save with this array.
array_id (Optional[str]) – A name for this array that’s unique within its
DataSet
. Typically the full_name, but when theDataSet
is constructed we will append ‘_<i>’ (i
is an integer starting from 1) if necessary to differentiate arrays with the same id. TODO: this only happens for arrays provided to the DataSet constructor, not those added with add_array. Fix this! Also, do we really need array_id and full_name (let alone name but I’ve already said we should remove this)?set_arrays (Optional[Tuple[DataArray]]) – If this array is being created with shape already, you can provide one setpoint array per dimension. The first should have one dimension, the second two dimensions, etc.
shape (Optional[Tuple[int]]) – The shape (as in numpy) of the array. Will be prepended with new dimensions by any calls to
nest
.action_indices (Optional[Tuple[int]]) – If used within a
Loop
, these are the indices at each level of nesting within theLoop
of the loop action that’s populating this array. TODO: this shouldn’t be in DataArray at all, the loop should handle converting this to array_id internally (maybe it already does?)unit (Optional[str]) – The unit of the values stored in this array.
units (Optional[str]) – DEPRECATED, redirects to
unit
.is_setpoint (bool) – True if this is a setpoint array, False if it is measured. Default False.
preset_data (Optional[Union[numpy.ndarray, Sequence]]) – Contents of the array, if already known (for example if this is a setpoint array).
shape
will be inferred from this array instead of from theshape
argument.
- SNAP_ATTRS = ('array_id', 'name', 'shape', 'unit', 'label', 'action_indices', 'is_setpoint')
- COPY_ATTRS_FROM_INPUT = ('name', 'label', 'unit')
- SNAP_OMIT_KEYS = ('ts', 'value', '__class__', 'set_arrays', 'shape', 'array_id', 'action_indices')
- property data_set
The DataSet this array belongs to.
A DataArray can belong to at most one DataSet. TODO: make this a weakref
- nest(size, action_index=None, set_array=None)[source]
Nest this array inside a new outer loop.
You cannot call
nest
afterinit_data
unless this is a setpoint array. TODO: is this restriction really useful? And should we maintain a distinction between _preset and is_setpoint, or can wejust use is_setpoint?- Parameters
size (int) – Length of the new loop.
action_index (Optional[int]) – Within the outer loop at this nesting level, which action does this array derive from?
set_array (Optional[DataArray]) – The setpoints of the new outer loop. If this DataArray is a setpoint array, you should omit both
action_index
andset_array
, and it will reference itself as the inner setpoint array.
- Returns
- self, in case you want to construct the array with
chained method calls.
- Return type
- init_data(data=None)[source]
Create the actual numpy array to hold data.
The array will be sized based on either
self.shape
or data provided here.Idempotent: will do nothing if the array already exists.
If data is provided, this array is marked as a preset meaning it can still be nested around this data. TODO: per above, perhaps remove this distinction entirely?
- Parameters
data (Optional[Union[numpy.ndarray, Sequence]]) – If provided, we fill the array with this data. Otherwise the new array will be filled with NaN.
- Raises
ValueError – if
self.shape
does not matchdata.shape
ValueError – if the array was already initialized with a different shape than we’re about to create
- __setitem__(loop_indices, value)[source]
Set data values.
Follows numpy syntax, allowing indices of lower dimensionality than the array, if value makes up the extra dimension(s)
Also update the record of modifications to the array. If you don’t want this overhead, you can access
self.ndarray
directly.
- delegate_attr_objects: List[str] = ['ndarray']
A list of names (strings) of objects which are (or will be) attributes of
self
, whose attributes should be passed through toself
.
- __len__()[source]
Array length.
Must be explicitly delegated, because len() will look for this attribute to already exist.
- flat_index(indices, index_fill=None)[source]
Generate the raveled index for the given indices.
This is the index you would have if the array is reshaped to 1D, looping over the indices from inner to outer.
- Parameters
indices (Sequence) – indices of an element or slice of this array.
index_fill (Optional[Sequence]) – extra indices to use if
indices
has less dimensions than the array, ie it points to a slice rather than a single element. Use zeros to get the beginning of this slice, and [d - 1 for d in shape] to get the end of the slice.
- Returns
the resulting flat index.
- Return type
- mark_saved(last_saved_index)[source]
Mark certain outstanding modifications as saved.
- Parameters
last_saved_index (int) – The flat index of the last point saved. If
modified_range
extends beyond this, the data pastlast_saved_index
will still be marked modified, otherwisemodified_range
is cleared entirely.
- clear_save()[source]
Make previously saved parts of this array look unsaved (modified).
This can be used to force overwrite or rewrite, like if we’re moving or copying the
DataSet
.
- get_synced_index()[source]
Get the last index which has been synced from the server.
Will also initialize the array if this hasn’t happened already. TODO: seems hacky to init_data here.
- Returns
- the last flat index which has been synced from the server,
or -1 if no data has been synced.
- Return type
- get_changes(synced_index)[source]
Find changes since the last sync of this array.
- Parameters
synced_index (int) – The last flat index which has already been synced.
- Returns
- None if there is no new data. If there is,
- returns a dict with keys:
start (int): the flat index of the first returned value. stop (int): the flat index of the last returned value. vals (List[float]): the new values
- Return type
Union[dict, None]
- apply_changes(start, stop, vals)[source]
Insert new synced values into the array.
To be be called in a
PULL_FROM_SERVER
DataSet
using results returned byget_changes
from theDataServer
.TODO: check that vals has the right length?
- fraction_complete()[source]
Get the fraction of this array which has data in it.
Or more specifically, the fraction of the latest point in the array where we have touched it.
- Returns
fraction of array which is complete, from 0.0 to 1.0
- Return type
- delegate_attr_dicts: List[str] = []
A list of names (strings) of dictionaries which are (or will be) attributes of
self
, whose keys should be treated as attributes ofself
.
- omit_delegate_attrs: List[str] = []
A list of attribute names (strings) to not delegate to any other dictionary or object.
- qcodes.data.data_array.data_array_to_xarray_dictionary(data_array: DataArray) Dict[str, Any] [source]
Convert DataArray to a dictionary in xarray format.
- Parameters
data_array – The DataArray to convert.
- Returns
A dictionary containing the data in xarray format.
- Return type
- qcodes.data.data_array.xarray_data_array_dictionary_to_data_array(array_id: str, array_dictionary: Dict[str, Any], is_setpoint: bool = False, preset_data=None)[source]
Convert xarray dictionary to a DataArray
This conversion is for bith the data array and the the internal xarray structure, e.g. the datavars and coords. :param array_id: Create the new DataArray with this id :param array_dictionary: Data to convert :param is_setpoint: Passed to the DataArray constructor :param preset_data: If None use the data from the dictionary, otherwise use the specified data.
- Returns
A dictionary containing the data in xarray format.
- Return type