etiket-sync-agent-labber 0.3.0b1

Labber backend for eTiKeT sync agent

eTiKeT Sync Agent - Labber Backend

Backend for synchronizing Labber measurement files with the eTiKeT platform. This backend reads HDF5 files from Labber's data directory, extracts metadata, and converts measurements to xarray-compatible formats.

Installation

pip install etiket_sync_agent_labber

The package is automatically discovered by etiket_sync_agent through the entry-point system.

What Gets Synchronized

When a Labber measurement is synced, the following data is extracted and uploaded:

Labber Data	eTiKeT Field	Description
Dataset name	name	Name of the Labber measurement
{name}_{timestamp}	alt_uid	Unique identifier combining name and creation time
Creation time	collected	When the measurement was created
Tags from file	tags	User-defined tags from Labber
Variable names/units	tags	Auto-extracted from measured data and traces
Starred status	ranking	Starred = +1 ranking
Config set_up	attributes.set-up	Experimental setup from configuration

Files Uploaded

File	Format	Description
original.hdf5	HDF5	The original Labber file in its proprietary format
settings.json	JSON	Extracted measurement settings
instruments.json	JSON	Extracted instrument configuration
ds_converted.hdf5	NetCDF4/HDF5	Converted xarray dataset for tools like xarray

Note: If a Labber file contains multiple datasets, multiple converted files are uploaded (ds_converted_0.hdf5, ds_converted_1.hdf5, etc.)

Metadata Extraction

The backend automatically extracts metadata from multiple sources:

1. User Tags: Custom tags defined in the Labber file
2. Measurement Data: Names and units of all measured variables
3. Traces: Names, units, setpoint names, and setpoint units from trace data
4. Starred Status: Whether the measurement was marked as starred in Labber

---

Configuration

The Labber backend requires a LabberConfigData configuration with the following fields:

Field	Type	Required	Description
labber_directory	Path or str	Yes	Path to the Labber data directory containing .hdf5 files
set_up	str	Yes	Name of the experimental setup (added as set-up attribute)

Example Configuration

from pathlib import Path
from etiket_sync_agent_labber import LabberConfigData

config = LabberConfigData(
    labber_directory=Path.home() / "Labber" / "Data",
    set_up="dilution_fridge_1"
)

Labber Directory Structure

Labber organizes its data folder with the following structure:

Labber/
└── Data/
    ├── Database.hdf5                              # Labber database file
    └── <year>/
        └── <month>/
            └── Data_<monthday>/
                ├── dataset_name_1.hdf5            # Measurement files
                ├── dataset_name_2.hdf5
                └── ...

Important: Set labber_directory to the Data/ directory (e.g., ~/Labber/Data), not the root Labber folder or a subdirectory.

Path Validation

The configuration validates:

• The directory exists and is accessible
• The Database.hdf5 file exists (confirms it's a valid Labber data folder)
• The directory doesn't conflict with other Labber sync sources (no overlapping paths)

---

Using the Labber Dataset Converter

The Labber backend includes utilities for reading and converting Labber files, which can also be used standalone:

Reading a Labber File

from etiket_sync_agent_labber.labber_ds.dataset import read_labber_file

# Read the Labber file
labber_ds = read_labber_file("/path/to/measurement.hdf5")

# Access dataset properties
print(labber_ds.dataset_name)       # Name of the measurement
print(labber_ds.creation_time)      # When it was created
print(labber_ds.tags)               # User-defined tags
print(labber_ds.settings)           # Measurement settings
print(labber_ds.is_starred)         # Whether it's starred

Converting to xarray

from etiket_sync_agent_labber.labber_ds.dataset import read_labber_file
from etiket_sync_agent_labber.labber_ds.to_xarray import to_xarray

# Read and convert
labber_ds = read_labber_file("/path/to/measurement.hdf5")

# Convert the first dataset content to xarray
xr_ds = to_xarray(labber_ds.dataset_content[0])

# Now you can use standard xarray operations
print(xr_ds)
xr_ds.to_netcdf("converted.hdf5")

Dataset Structure

The LabberDataset object contains:

Attribute	Type	Description
dataset_name	str	Name of the measurement
creation_time	datetime	When the measurement was created
tags	dict	User-defined tags
settings	dict	Measurement settings
is_starred	bool	Whether the measurement is starred
dataset_content	list[LabberDataContent]	List of data content objects

Each LabberDataContent contains:

Attribute	Description
data	List of measured data items with names and units
traces	Dictionary of trace objects with setpoint information
instruments	Instrument configuration
instrument_config	Detailed instrument settings
log_list	Names of the measurement setpoints
step_config	Step configuration for sweeps
step_list	List with names of the variables

---

Features

• Direct Labber integration: Reads HDF5 files from Labber's native format
• Automatic metadata extraction: Tags, names, units, and starred status
• xarray conversion: Converts to NetCDF4-compatible format for analysis
• Instrument preservation: Saves complete instrument configurations as JSON
• Settings export: Extracts and uploads measurement settings

Live Sync

Live sync is not implemented for the Labber backend and technically not possible. Measurements must be completed before they can be synchronized.

Requirements

• Python >= 3.10
• h5py
• xarray
• h5netcdf

License

Copyright © 2025 QHarbor. All Rights Reserved. See LICENCE for details.