m3resp.DataModelRecorder#

class m3resp.DataModelRecorder(session, store=None, *, case=None)[source]#

Store a session’s recordings, results and processing provenance.

Construction creates or registers a case and a recording session in the store. Assign the recorder to session.datamodel to record session actions and workflow results automatically.

Variables:

session – Runtime session being recorded.
store – DataModelStore receiving records.
case – Case associated with the session.
recording_session – Stored session record.

Parameters:

session (M3Session)
store (DataModelStore | None)
case (Case | None)

Methods

`record_interval_data`	Add values per interval or event to the store as derived features.
`record_parameter`	Materialize a `ParameterResult` as a `DerivedFeature`.
`record_parameter_file`	Record an exported array file and link it to its processing run.
`record_pixel_grid`	Add a pixel map or mask to the store as a derived-feature record.
`record_processing_step`	Store one processing step as a ProcessingRun with kind=step.
`record_provenance`	Store one session action as a ProcessingRun with kind=session_action.
`record_quality_flag`	Convert a `QualityFlag` into a stored `QualityAnnotation`.
`record_signal`	Record a `Signal` as a `SignalStream` (+ `DataFile`).
`record_synchronization`	Copy each recording's synchronization onto its recorded streams.
`record_workflow_result`	Store a workflow run and its recognized output values.

record_interval_data(interval_data, *, processing_run_id)[source]#

Add values per interval or event to the store as derived features.

Scalar values create one feature per item. Times are copied in seconds on the input’s clock; an event uses the same time for both ends of its window. Missing None or NaN values are stored as None. Values that fail numeric conversion are stored as None with a logged warning.

A result containing any array values creates one feature for the whole result, with value=None. Array data is kept in the separate export archive.

Parameters:

interval_data (IntervalData | EventData) – IntervalData or EventData with values in item order and their physical unit.
processing_run_id (str) – Identifier of the run already in the store.

Returns:

Stored features in item order for scalar: values, or one feature for a result containing arrays.

Return type:

list[DerivedFeature]

Raises:

DataModelStoreError – If the processing run is absent from the store.

record_parameter(parameter, *, processing_run_id)[source]#

Materialize a ParameterResult as a DerivedFeature.

Parameters:

parameter (ParameterResult)
processing_run_id (str)

Return type:

DerivedFeature

record_parameter_file(path, *, processing_run_id)[source]#

Record an exported array file and link it to its processing run.

Exporting again to the same path replaces the earlier link to that path in the run’s parameter_file_ids. The earlier DataFile remains in the store as a record of the earlier export.

Parameters:

path (str | Path) – Existing array-results file, such as interval_data_arrays.npz or pixel_masks.npz.
processing_run_id (str) – Identifier of the run already in the store.

Returns:

Stored file record with role 'parameter', a SHA-256: checksum and file size in bytes.

Return type:

DataFile

Raises:

OSError – If the file cannot be read or its size determined.
KeyError – If the processing run is absent from the store.

record_pixel_grid(grid, *, processing_run_id)[source]#

Add a pixel map or mask to the store as a derived-feature record.

Parameters:

grid (PixelMap | PixelMask) – PixelMap or PixelMask with its name and modality. A pixel map also supplies the feature’s unit.
processing_run_id (str) – Identifier of the run already in the store.

Returns:

Stored record with value=None. The numeric: grid is kept in a separate export archive.

Return type:

DerivedFeature

Raises:

DataModelStoreError – If the processing run is absent from the store.

record_processing_step(step)[source]#

Store one processing step as a ProcessingRun with kind=step.

Parameters:

step (ProcessingStep) – ProcessingStep with a name, timestamp, input keys and settings.

Returns:

Record added to the store with the step’s name, parsed: timestamp and JSON-compatible settings. Known input-file keys are linked. Other run fields use ProcessingRun defaults.

Return type:

ProcessingRun

record_provenance(provenance)[source]#

Store one session action as a ProcessingRun with kind=session_action.

Loading actions first record the raw signal and source file when available. The session’s current synchronization settings are also copied to recorded streams.

Parameters:

provenance (ProvenanceRecord) – Session action with a timestamp, modality and settings.

Returns:

Stored action record with converted settings and any: known source-file link for its modality.

Return type:

ProcessingRun

record_quality_flag(flag, *, target_type=None, target_id=None)[source]#

Convert a QualityFlag into a stored QualityAnnotation.

One flag gives one annotation. The flag’s fields are copied as follows:

QualityFlag	QualityAnnotation	Notes
`start_time`, `end_time`	`time_window_start`, `time_window_end`	Seconds.
`breath_id` or `breath_ids`	`breath_ids`	One `breath_id` becomes a list of one. None if no breath is set.
`passed`	`quality_label`	`"valid"` or `"suspect"`.
`name`	`annotator_ref`

annotation_source is always "automated".

If target_id is None, the annotation points to the SignalStream recorded for the flag’s modality, matched on category when the flag sets one. If the flag has no modality, or no stream is recorded for it yet, the annotation points to the session, with target_type "session" and the session ID as target_id.

Parameters:

flag (QualityFlag) – The QualityFlag to convert.
target_type (Literal['signal', 'file', 'session', 'event', 'feature'] | None) – Kind of record the annotation points to. Defaults to "signal".
target_id (str | None) – ID of the record the annotation points to. If None, it is looked up from the flag as described above.

Returns:

The annotation added to the store.

Return type:

QualityAnnotation

record_signal(signal, *, file_path=None, file_role='raw')[source]#

Record a Signal as a SignalStream (+ DataFile).

A signal whose modality is not one the data model has a stream type for (for example the default "unknown" modality, before the signal has been tagged as EIT/EMG/ventilator) cannot be stored, so it is skipped with a warning rather than stopping the whole recording. Returns the new stream, or None when the signal was skipped.

Parameters:

signal (Signal)
file_path (str | Path | None)
file_role (Literal['raw', 'processed', 'derived', 'annotation', 'parameter', 'report'])

Return type:

SignalStream | None

record_synchronization()[source]#

Copy each recording’s synchronization onto its recorded streams.

Sets SignalStream.sync_method from session.sync_methods ("manual", "none") and SignalStream.time_offset_ms from the recording’s start time on the shared clock. A stream whose recording was never synchronized gets None for both. Ventilator data from the EIT or EMG file takes that file’s synchronization.

Return type:: None

record_workflow_result(result)[source]#

Store a workflow run and its recognized output values.

Nested lists, tuples and dictionaries are visited recursively. Signals, measurements, per-event/per-interval results, pixel grids and quality flags use their corresponding recorder methods. Bare numeric outputs become derived features named by context key; booleans and unsupported objects are skipped.

Parameters:

result (WorkflowResult) – Completed WorkflowResult containing named outputs.

Returns:

Stored record with kind=workflow and the workflow name.: Native measurement, signal and grouped-result provenance is kept in parameters[“outputs”]. Array values remain in exported archives. All input files known to this recorder are linked, including files from earlier runs on the same session. Status and run_time use ProcessingRun defaults.

Return type:

ProcessingRun