Skip to content

Read data

extract_h5_data(path, keys=None, schema=False)

Extract data at the given keys from an HDF5 file. If no keys are given (None) returns the data field of the object.

Parameters:

Name Type Description Default
path str

path to the HDF5 file or a folder in which is contained a data.ddh5 file

 required
keys None or List

list of keys to extract from file['data'], by default None

 None

Returns:

Type Description
Dict or Tuple[ndarray, ...]

The full data dictionary if keys = None. The tuple with the requested keys otherwise.
Example 
Extract the data object from the dataset:
>>> data = extract_h5_data(path)
Extracting only 'amp' and 'phase' from the dataset:
>>> amp, phase = extract_h5_data(path, ['amp', 'phase'])
Extracting only 'phase':
>>> phase, = extract_h5_data(path, ['phase'])
Source code in sqil_core/utils/_read.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def extract_h5_data(
    path: str, keys: list[str] | None = None, schema=False
) -> dict | tuple[np.ndarray, ...]:
    """Extract data at the given keys from an HDF5 file. If no keys are
    given (None) returns the data field of the object.

    Parameters
    ----------
    path : str
        path to the HDF5 file or a folder in which is contained a data.ddh5 file
    keys : None or List, optional
        list of keys to extract from file['data'], by default None

    Returns
    -------
    Dict or Tuple[np.ndarray, ...]
        The full data dictionary if keys = None.
        The tuple with the requested keys otherwise.

    Example
    -------
        Extract the data object from the dataset:
        >>> data = extract_h5_data(path)
        Extracting only 'amp' and 'phase' from the dataset:
        >>> amp, phase = extract_h5_data(path, ['amp', 'phase'])
        Extracting only 'phase':
        >>> phase, = extract_h5_data(path, ['phase'])
    """
    # If the path is to a folder open /data.ddh5
    if os.path.isdir(path):
        path = os.path.join(path, "data.ddh5")

    with h5py.File(path, "r") as h5file:
        data = h5file["data"]
        data_keys = data.keys()

        db_schema = None
        if schema:
            db_schema = json.loads(data.attrs.get("__schema__"))

        # Extract only the requested keys
        if bool(keys) and (len(keys) > 0):
            res = []
            for key in keys:
                key = str(key)
                if (not bool(key)) | (key not in data_keys):
                    res.append([])
                    continue
                res.append(np.array(data[key][:]))
            if not schema and len(res) == 1:
                return res[0]
            return tuple(res) if not schema else (*tuple(res), db_schema)
        # Extract the whole data dictionary
        h5_dict = _h5_to_dict(data)
        return h5_dict if not schema else {**h5_dict, "schema": db_schema}

extract_mapped_data(path)

Loads measurement data from an HDF5 file and maps it into x_data, y_data and sweeps. The map and the database schema on which it relies are also returned.

Parameters:

Name Type Description Default
path str or Path

Path to the HDF5 file containing experimental data and schema definitions.

 required

Returns:

Name Type Description
x_data ndarray

Array of x-axis values extracted according to the schema.
y_data ndarray

Array of measured data values (y-axis).
sweeps list[ndarray]

List of arrays for any additional swept parameters defined in the schema.
datadict_map dict

Mapping of keys used for "x_data", "y_data", and "sweeps" in the original file.
schema dict

The schema used to interpret the data structure and field roles.
Notes
  • This function expects the file to contain a top-level "schema" key that defines the role of each dataset (e.g., "data", "x-axis", "axis").
  • Uses extract_h5_data and map_data_dict internally for loading and interpretation.

Examples:

>>> x, y, sweeps, datadict_map, schema = extract_mapped_data(path)
Source code in sqil_core/utils/_read.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def extract_mapped_data(path: str):
    """
    Loads measurement data from an HDF5 file and maps it into x_data, y_data and sweeps.
    The map and the database schema on which it relies are also returned.

    Parameters
    ----------
    path : str or Path
        Path to the HDF5 file containing experimental data and schema definitions.

    Returns
    -------
    x_data : np.ndarray
        Array of x-axis values extracted according to the schema.
    y_data : np.ndarray
        Array of measured data values (y-axis).
    sweeps : list[np.ndarray]
        List of arrays for any additional swept parameters defined in the schema.
    datadict_map : dict
        Mapping of keys used for `"x_data"`, `"y_data"`, and `"sweeps"` in the original file.
    schema : dict
        The schema used to interpret the data structure and field roles.

    Notes
    -----
    - This function expects the file to contain a top-level "schema" key that defines the
      role of each dataset (e.g., "data", "x-axis", "axis").
    - Uses `extract_h5_data` and `map_data_dict` internally for loading and interpretation.

    Examples
    --------
    >>> x, y, sweeps, datadict_map, schema = extract_mapped_data(path)
    """

    datadict = extract_h5_data(path, schema=True)
    schema = datadict.get("schema")
    x_data, y_data, sweeps, datadict_map = map_data_dict(datadict)
    return x_data, y_data, sweeps, datadict_map, schema

map_data_dict(data_dict)

Maps experimental data to standardized arrays using a provided schema.

This function interprets the structure of a measurement data dictionary (obtained using extract_h5_data) by extracting relevant data fields according to roles specified in the database schema. It returns the x-axis values, y-axis data, any additional sweep parameters, and a mapping of keys used for each role.

Parameters:

Name Type Description Default
data_dict dict

Dictionary containing measurement data and an associated 'schema' key that defines the role of each field (e.g., "x-axis", "data", "axis").

 required

Returns:

Name Type Description
x_data ndarray

Array containing the x-axis values.
y_data ndarray

Array containing the y-axis (measured) data.
sweeps list[ndarray]

List of additional swept parameter arrays (if any).
key_map dict

Dictionary with keys "x_data", "y_data", and "sweeps" indicating the corresponding keys used in the original data_dict.
Notes
  • If the schema is missing, the function prints a warning and returns empty arrays.
  • Each item in the schema must be a dictionary with a "role" key.

Examples:

>>> x, y, sweeps, mapping = map_data_dict(experiment_data)
>>> print(f"x-axis data from key: {mapping['x_data']}")
Source code in sqil_core/utils/_read.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def map_data_dict(data_dict: dict):
    """
    Maps experimental data to standardized arrays using a provided schema.

    This function interprets the structure of a measurement data dictionary
    (obtained using extract_h5_data) by extracting relevant data fields according
    to roles specified in the database schema. It returns the x-axis values, y-axis data,
    any additional sweep parameters, and a mapping of keys used for each role.

    Parameters
    ----------
    data_dict : dict
        Dictionary containing measurement data and an associated 'schema' key
        that defines the role of each field (e.g., "x-axis", "data", "axis").

    Returns
    -------
    x_data : np.ndarray
        Array containing the x-axis values.
    y_data : np.ndarray
        Array containing the y-axis (measured) data.
    sweeps : list[np.ndarray]
        List of additional swept parameter arrays (if any).
    key_map : dict
        Dictionary with keys `"x_data"`, `"y_data"`, and `"sweeps"` indicating
        the corresponding keys used in the original `data_dict`.

    Notes
    -----
    - If the schema is missing, the function prints a warning and returns empty arrays.
    - Each item in the schema must be a dictionary with a `"role"` key.

    Examples
    --------
    >>> x, y, sweeps, mapping = map_data_dict(experiment_data)
    >>> print(f"x-axis data from key: {mapping['x_data']}")
    """

    schema = data_dict.get("schema", None)
    if schema is None:
        print(
            "Cannot automatically read data: no database schema was provided by the experiment."
        )

    x_data, y_data, sweeps = np.array([]), np.array([]), []
    key_map = {"x_data": "", "y_data": "", "sweeps": []}

    for key, value in schema.items():
        if type(value) is not dict:
            continue
        role = value.get("role", None)
        if role == "data":
            key_map["y_data"] = key
            y_data = data_dict[key]
        elif role == "x-axis":
            key_map["x_data"] = key
            x_data = data_dict[key]
        elif role == "axis":
            key_map["sweeps"].append(key)
            sweeps.append(data_dict[key])

    return x_data, y_data, sweeps, key_map

read_json(path)

Reads a json file and returns the data as a dictionary.

Source code in sqil_core/utils/_read.py 
222
223
224
225
226
def read_json(path: str) -> dict:
    """Reads a json file and returns the data as a dictionary."""
    with open(path) as f:
        dictionary = json.load(f)
    return dictionary

read_qpu(dir_path, filename)

Reads QPU file stored in dir_path/filename using laboneq serializers.

Source code in sqil_core/utils/_read.py 
237
238
239
240
def read_qpu(dir_path: str, filename: str) -> QPU:
    """Reads QPU file stored in dir_path/filename using laboneq serializers."""
    qpu = serializers.load(os.path.join(dir_path, filename))
    return qpu