Callbacks and Data Output

polar-bits supports three data output streams, all configured through iconfig.yml and loaded automatically during startup.

---

SPEC Data Files

Status: Enabled by default.

SPEC .dat files are written by id4_common.callbacks.spec_data_file_writer. After startup, three helpers are available:

# Create a new SPEC file for this session
newSpecFile("my_experiment")
# → creates a file like: 0409_my_experiment.dat

# Add a free-form comment to the current SPEC file
spec_comment("Sample aligned, beam 50x50 µm")

# The callback instance (subscribes to the RunEngine)
specwriter

newSpecFile prepends the current month+day, appends the .dat extension, and resets RE.md["scan_id"] to the last scan number in the file if the file already exists.

iconfig.yml settings

SPEC_DATA_FILES:
  ENABLE: true
  FILE_EXTENSION: dat

Set ENABLE: false to disable SPEC output entirely.

---

NeXus / HDF5 Data Files

Status: Opt-in (disabled by default).

NeXus output is written by id4_common.callbacks.nexus_data_file_writer. Enable it in iconfig.yml:

NEXUS_DATA_FILES:
  ENABLE: true
  FILE_EXTENSION: hdf

After enabling, nxwriter is available in the session:

nxwriter   # NeXus callback instance

Files are written in the NeXus/HDF5 format with standard /entry/instrument/... hierarchy.

---

Dichroism Stream

The dichroism stream callback (id4_common.callbacks.dichro_stream) is always loaded at startup. It processes circular dichroism data in real time:

dichro                    # DichroStream device
dichro_bec                # Best Effort Callback for the dichro stream
plot_dichro_settings()    # configure dichro plots

The dichro callback subscribes to the RunEngine and accumulates positive/negative helicity readings for on-the-fly XMCD calculation.

---

Best Effort Callback (BEC)

The standard Bluesky BEC is configured by the BEC block in iconfig.yml:

BEC:
  BASELINE: true    # print baseline readings at scan start
  HEADING: true     # print column headers
  PLOTS: false      # disable live plots (useful in non-GUI sessions)
  TABLE: true       # print scan data as a table

bec and peaks are available in the session:

bec           # BestEffortCallback instance
peaks         # peak-finding helper (populated after each scan)

# After a scan:
peaks.com     # center-of-mass position
peaks.max     # position of maximum
peaks.cen     # centroid position

---

Baseline Supplemental Stream

Devices labelled "baseline" in devices.yml are read at the start and end of every scan and stored in the baseline stream of the run document:

# devices.yml
- name: some_device
  labels: ["core", "baseline"]

Enable the baseline label collection in iconfig.yml:

BASELINE_LABEL:
  ENABLE: true