Readout

Readout operations consume container state and produce structured data results.

Readout families:

Family	Purpose
img(...)	Image/optical readout.
ecp(...)	Electrochemical/chemical-property readout.
phy(...)	Physical measurement readout.

Physical Readout

Example from the public environment/readout file:

let obs = phy(sample = reactor, quantity = ReadoutQuantity.TEMPERATURE);

Readout operations are data-producing steps. They should not be understood as material mutations.

Shared Shape

The three readout families share this pattern:

let obs = family(sample = container_or_group, quantity = quantity_name);

For complex or custom result shapes, use schema_ref with a declared data_schema(...).

let schema = data_schema(label = "GelImage", fields = [band_count, signal]);
let obs = img(sample = lane, quantity = ReadoutQuantity.CUSTOMIZED, schema_ref = schema);

quantity uses the closed ReadoutQuantity enum. Each operation accepts the subset listed below: for example, ReadoutQuantity.PH is valid for ecp. ReadoutQuantity.CUSTOMIZED requires schema_ref for all three operations. Equivalent bare tokens and strings remain accepted.

img(...)

let obs = img(sample = diluted_mix, quantity = ReadoutQuantity.FLUORESCENCE);

img quantities:

Quantity	Meaning
ReadoutQuantity.UV_ABSORBANCE	UV/absorbance readout.
ReadoutQuantity.FLUORESCENCE	Fluorescence readout.
ReadoutQuantity.COLORIMETRIC	Colorimetric readout.
ReadoutQuantity.CUSTOMIZED	Custom image/readout shape; requires schema_ref.

ecp(...)

let obs = ecp(sample = tube, quantity = ReadoutQuantity.PH);

ecp quantities:

Quantity	Meaning
ReadoutQuantity.PH	pH.
ReadoutQuantity.CONDUCTIVITY	Conductivity.
ReadoutQuantity.DISSOLVED_OXYGEN	Dissolved oxygen.
ReadoutQuantity.ORP	Oxidation-reduction potential.
ReadoutQuantity.CUSTOMIZED	Custom electrochemical result; requires schema_ref.

phy(...)

let obs = phy(sample = reactor, quantity = ReadoutQuantity.TEMPERATURE);

phy quantities:

Quantity	Meaning
ReadoutQuantity.TEMPERATURE	Temperature.
ReadoutQuantity.PRESSURE	Pressure.
ReadoutQuantity.FLOW_RATE	Flow rate.
ReadoutQuantity.MASS	Mass.
ReadoutQuantity.VOLUME	Volume.
ReadoutQuantity.HUMIDITY	Humidity.
ReadoutQuantity.CURRENT	Electrical current response; may use schema_ref.
ReadoutQuantity.CUSTOMIZED	Custom physical result; requires schema_ref.

Return Shape

Single-container input returns a data_ref.

Group input returns a data_group_ref aligned with the input group order.

Readout results are structured information references. They are not containers, and indexing a single data_ref as if it were a group is a semantic error.

Raw Artifacts

Readout calls may use save_raw = true.

let obs = img(sample = lane, quantity = ReadoutQuantity.CUSTOMIZED, schema_ref = schema, save_raw = true);

Raw artifacts are associated with the result. They do not replace the structured result fields.