Metadata-Version: 2.4
Name: etiket_sync_agent_labber
Version: 0.3.0b1
Summary: Labber backend for eTiKeT sync agent
Author: QHarbor team
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://qharbor.nl
Project-URL: Documentation, https://docs.qharbor.nl
Keywords: etiket,sync,backend,labber,quantum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: etiket_sync_agent>=0.3.0b1
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: h5netcdf
Dynamic: license-file

# 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

```bash
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

```python
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

```python
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

```python
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](LICENCE) for details.
