Skip to content

Access BEC History

Overview

Retrieve previous scans from bec.history and inspect their metadata and data in a BEC client session.

Prerequisites

  • You are connected to a running BEC client session.
  • The scans you want to inspect are still available in the BEC history and their files are readable from your current machine.

bec.history keeps a local history of recent scans. In current BEC, this history is limited to the last 10 000 readable scans. Each lookup returns a ScanDataContainer, the same data container type you also get from scan reports.

The structure of this container is similar to the layout BEC writes under entry/collection in the HDF5 file. For example, metadata corresponds to entry/collection/metadata, and the device and readout access paths are built from entry/collection/readout_groups.

1. Check how many scans are available in history

In a BEC IPython session, run:

Check the history length
len(bec.history)

This returns the number of scans currently available in the local history cache.

2. Find the scan data container

Depending on what information you already have, there are several ways to retrieve a ScanDataContainer.

To get the most recent scan:

Get the most recent scan
scan = bec.history[-1]

Here the index is the offset in the history: -1 is the last scan, -2 is the second-to-last scan, and so on.

To get a scan by scan number:

Get a scan by scan number
scan_number = 1234
scan = bec.history.get_by_scan_number(scan_number)

If the scan number exists only once in the history, you get a single ScanDataContainer. If it appears multiple times, BEC returns a list of ScanDataContainer objects.

If you get a list, select one element first before accessing attributes such as metadata, devices, or readout_groups:

Select one result from several scan-number matches
scan_number = 1234
matches = bec.history.get_by_scan_number(scan_number)

To get a scan by scan ID:

Get a scan by scan ID
scan_id = "your-scan-id"
scan = bec.history.get_by_scan_id(scan_id)

This is useful when you already copied the scan ID from a report, log, or notebook.

To get several recent scans at once:

Get several recent scans at once
recent_scans = bec.history[-5:]

This returns a list of ScanDataContainer objects.

As above, access metadata or device data on one scan container, for example recent_scans[0], not on the list itself.

3. Inspect the scan container

Printing the container is often a good first check:

scan

ScanDataContainer:
    Start time: ...
    End time: ...
    Elapsed time: ... s
    Scan ID: ...
    Scan number: ...
    Scan name: line_scan
    Status: closed
    Number of points (monitored): 5
    File: ...

This shows a compact summary such as scan ID, scan number, scan name, status, number of points, and the file path.

4. Access metadata and scan data

Once you have a scan object, you can inspect metadata:

Inspect scan metadata
scan.metadata["bec"]
scan.metadata["bec"]["scan_number"]

To read full monitored or baseline groups:

Read monitored and baseline groups
scan.readout_groups.monitored_devices.read()
scan.readout_groups.baseline_devices.read()

To work with one device and all of its signals:

Read one device from the scan container
scan.devices.samx.read()

To work with a single signal:

Read one signal from the scan container
scan.devices.samx.samx.get()
scan.data.samx_setpoint.get()

scan.devices is convenient when you want to explore a device-oriented view. scan.data is useful when you already know the signal name and want to access it directly.

These access paths resemble the HDF5 structure written by the file writer: metadata is stored under entry/collection/metadata, while monitored and baseline device data are exposed from entry/collection/readout_groups.

Congratulations!

You have successfully accessed previous scans through bec.history.

Common pitfalls

  • Requesting a scan number or scan ID that is not present in the current history cache.
  • Expecting one result from get_by_scan_number(...) when multiple scans share the same scan number.
  • Assuming the history contains every past scan. It only keeps a bounded set of recent readable scans.
  • Trying to access file-backed data when the underlying HDF5 file is no longer readable on the current machine.