The APyT local database module

This module provides a lightweight Python interface to a local database stored in YAML format. It implements convenience functions for downloading, querying, and updating measurement records.

The primary design goal is to provide a consistent API for accessing experimental data in Python (see also the SQL module).

Configuration

General database settings are configured in the [localdb] section of the global TOML configuration file.

Typical use cases

  • Fetching structured measurement data from the database for analysis.

  • Updating metadata keys (e.g., experiment or evaluation parameters) of existing records.

  • Executing queries for specific records and keys.

Example local database structure

The local database is stored in YAML format. Each entry corresponds to a measurement record and is indexed by a numeric key (the measurement ID).

1:
  file: W_calibration_tap_01.raw
  device: tap
  custom_id: W_calibration_tap_01
  parameters: {}

2:
  file: my_measurement_01.raw
  device: metap
  custom_id: my_id_01
  parameters: {}

Explanation

  • Top-level keys (1, 2, …): Numeric identifiers representing measurement records. Each key corresponds to one entry in the local database.

  • file: Name of the raw measurement data file (relative to the configured localdb.data directory).

  • device Identifier of the atom probe device. Must match one of the devices defined in the global configuration file.

  • custom_id: A user-defined identifier for the measurement. This may be any string and is useful for referencing records by name rather than by numeric ID.

  • parameters: An initially empty dictionary that must be present for compatibility and defined as {}.

The keys file, device, custom_id, and parameters are mandatory. Additional keys may be added as needed and will be populated automatically by the APyT modules (e.g., analysis parameters or metadata).

List of functions

  • download(): Download measurement data from a local file.

  • query(): Query one or more keys from a database record.

  • update(): Update a specific key of a database record.

Implementation notes

  • Binary measurement datasets are read and converted directly into structured NumPy arrays.

  • Error handling and logging are integrated throughout the code.

  • The API is designed to be fully compatible with the SQL module.

apyt.io.localdb.download(id)[source]

Load measurement data from a local file.

Retrieves measurement data stored in a local file associated with a database record. The data are returned as a structured NumPy array with predefined fields (e.g., detector positions, voltage signals, and timing information).

Parameters:

id (int) – The measurement ID of the record in the local database.

Returns:

  • status (int) – Status code for compatibility with the SQL module.

    • 200 indicates success.

  • data (numpy.ndarray) – A structured NumPy array containing the measurement events.

Raises:

FileNotFoundError – If the local measurement file cannot be found.

Notes

  • Errors are logged with the module-level logger.

  • The status code is returned only for compatibility with the SQL module.

apyt.io.localdb.query(id, keys)[source]

Retrieve one or more keys from a local database record.

This function reads a measurement entry from a local YAML database file and returns the requested keys as a dictionary mapping keys to values.

Parameters:

  • id (int) – The measurement ID of the record in the local database.

  • keys (str or iterable of str) – The key(s) to retrieve from the database entry. If a single string is provided, it is automatically converted to a tuple.

Returns:

  • status (int) – Status code for compatibility with the SQL module.

    • 200 indicates success.

  • result (dict) – Dictionary containing the requested keys.

Raises:

  • FileNotFoundError – If the local database file does not exist.

  • KeyError – If the requested record or any requested key is missing.

Notes

  • If the key 'custom_id' is present, it is converted to str (in case of a numeric-only custom ID).

  • Errors are logged with the module-level logger.

  • The status code is returned only for compatibility with the SQL module.

apyt.io.localdb.update(id, key, value)[source]

Update a specific key of a database record.

This function modifies an existing entry in the local YAML database by updating a single key–value pair. Before updating, a timestamped backup of the database file is created.

Parameters:

  • id (int) – The measurement ID of the record in the local database.

  • key (str) – The key name to update in the database entry.

  • value (str) – The new value for the specified key.

Returns:

  • status (int) – Status code for compatibility with the SQL module.

    • 200 indicates success, all other codes indicate failure.

  • response (str) – "OK" when the update is successful. Otherwise, an error message is returned.

Notes

  • The status code is returned only for compatibility with the SQL module.