Juice Identifiers and Run IDs#

Juice provides functionality to attach identifiers to your data. These identifiers can be customized per user-needs. For example, run_IDs, cycle_IDs, system_IDs

We recommend using run IDs to track runs of experiments.

Why use run IDs?

Tagging data with run IDs allows easy trace back of data to a specific run under which it was generated, which is especially useful for organizing and analyzing experimental data.

Juice provides an example implementation for run identifiers. This guide explains how to configure and use run IDs using the identifier configuration.

A run ID is an identifier for tagging data as part of a measurement run. A run ID is typically generated at the start of an measurement session and is used to uniquely identify and track the data associated with that specific run. When a new run ID is generated, it is associated with the service name and current timestamp to ensure uniqueness.

Data is not automatically tagged with run IDs, so it’s up to the user to ensure that the current run ID is retrieved and included in the data when it is reported by the service.

Getting started#

To start using run IDs, follow these steps:

  1. Configuration: Configure run ID generation for your Juice service.

  2. Generating run IDs: Generate new run IDs as needed during your experiments or measurement sessions.

  3. Retrieving run IDs: Retrieve the latest run ID.

Configuration#

To enable run ID usage in an OrangeQS Juice service, the run ID generation settings must be configured in the identifiers.toml configuration file.

[services."device"]
# This tells Juice that the run IDs for this service are generated by the service named "device".
run = "device"

To utilize the run_id within the “device” service, ensure that this service is also defined in the Juice system’s orchestration.toml configuration. For more details on services and configuration, see Adding services.

For example, add the following to orchestration.toml to set up “device” service.

[services."device"]
# No configuration options yet.

Please note that only a system administrator with access to the host system’s configuration files can perform these changes. After updating the configuration, activate the new service by running sudo juice install in the host system terminal.

After editing this file, check that the configuration is valid by running the following command in a JupyterLab terminal. It should show the contents you just added without any errors.

juice config list identifiers

Finally, restart your Juice service to apply the new configuration using restart_service() You can run this from a Python notebook or script in JupyterLab.

from orangeqs.juice.client.service import restart_service

restart_service("device")

Generating run IDs#

To generate a new run ID for your Juice service, you can use the orangeqs.juice.identifiers.run_id module This function can only be called from the service that we just configured to generate run IDs. Start an IPython console with the Service: device kernel in JupyterLab to run the following code in the service:

# Execute this code in the device service.
from orangeqs.juice.identifiers.run_id import new_run_id

new_run_id()

This will generate a new run ID for the device service and set it as the current run ID. It is good practice to call this function automatically when the service starts by adding it to the init module of your Juice service. Still, you can call this function manually whenever you want to change to a new run ID.

Now that a run ID has been generated, all data reported by this service should be tagged with the current run ID. To do this, orangeqs.juice.identifiers.run_id.current_run_id function to get the current run ID can be used. Note that this function can only be called from the service that generated the run ID.

# Execute this code in the <service name> service.
from orangeqs.juice_ext.device_and_instruments import current_run_id

# Dummy example of reporting data with the current run ID.
my_data = run_measurement()
my_data["run_id"] = current_run_id()  # <-- Tag data with current run ID.
store_data(my_data)

This way, all data reported by the service can be traced back to the specific run ID under which it was generated. The current_run_id() function is inexpensive to call, it should be called every time data is reported to ensure it is always tagged with the most up-to-date run ID.

Retrieving run IDs#

To retrieve the latest run ID for your Juice service, you can use the orangeqs.juice.identifiers.run_id.latest_run_id function You can call this function from any Juice service or user container that needs to access the run ID. For example, to get the latest run ID for the device service, you can run the following code:

# Execute this code from any service or user container.
from orangeqs.juice.identifiers.run_id import latest_run_id

run_id = latest_run_id()

# Dummy example of using the retrieved run ID.
load_data_for_run(run_id)

The latest_run_id() function is cheap to call, it should be called every time data is reported to ensure it is always tagged with the most up-to-date run ID.