pytesdaqx 0.1.0__tar.gz → 0.2.2__tar.gz

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytesdaqx
-Version: 0.1.0
+Version: 0.2.2
 Summary: TES detector acquisition, instrument control, and raw-data recording
 Author: TESSERACT DAQ developers
 Classifier: Development Status :: 3 - Alpha

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/docs/developer/data_io.md

@@ -25,6 +25,7 @@ Important behavior:
 - Zarr v3 group and array metadata.
 - Continuous array shape `[channel, sample]`.
 - Finite array shape `[trace, channel, sample]`.
+- Finite `trace_time[trace]` array of float64 Unix acquisition timestamps.
 - Native zarr-python writing.
 - Optional compression and sharding configuration.
 - Stream metadata updated as read blocks or traces are appended.
@@ -32,6 +33,20 @@ Important behavior:
 
 Zarr does not use HDF5 file rotation. Recorder options such as `segments_per_file` are ignored for Zarr by the run controller.
 
+Finite-record timestamps are copied from `SegmentMetadata.segment_timestamp`
+to `trace_time`, preserving gaps between triggers. An absent timestamp is NaN;
+the recorder does not substitute its write time. `get_trace()` and
+`StreamReader` return the selected value as `trace_time`. Older stores without
+this array remain readable and omit the unavailable timestamp. The compact
+timestamp array is separate from waveform chunking/sharding and is not a JSONL
+sidecar.
+
+The NI run controller records `pretrigger_length_samples: 0` for finite
+acquisitions, whose digital/analog triggers start acquisition rather than
+referencing a pretrigger buffer. Historical pretrigger metadata is preserved
+by the readers; consumers must not assume that an arbitrary finite record is
+centered on its trigger.
+
 ## Compression and chunking defaults
 
 `ZarrRecorder` defaults to zstd compression (level 9) and to sharded arrays for

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pytesdaqx"
-version = "0.1.0"
+version = "0.2.2"
 description = "TES detector acquisition, instrument control, and raw-data recording"
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx/cli/view_traces.py

@@ -589,7 +589,16 @@ def iter_stream_traces(args, reader: StreamReader | None = None):
                     channels=_comma_list(args.detector_channels),
                     units=args.units,
                     include_metadata=True,
-                    **_record_kwargs(args),
+                    # Unlike the other _record_kwargs(args) call sites in this
+                    # file, this one must filter out unset (None) values:
+                    # read_next() forwards **record_kwargs all the way down to
+                    # backend.get_trace()/get_read_block() for a native Zarr
+                    # stream, and ZarrReader.get_trace() has no **kwargs catch-
+                    # all - it raises TypeError on any keyword it doesn't
+                    # explicitly declare (e.g. segment_trigger_index, an
+                    # HDF5-only concept), even when the caller only meant "not
+                    # set" by passing None.
+                    **{key: value for key, value in _record_kwargs(args).items() if value is not None},
                 )
             except StopIteration:
                 return

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx/io/zarr_reader.py

@@ -283,8 +283,7 @@ class ZarrReader:
         )
         info = self._native_info(
             record_type="trace",
-            trace_index=index,
-            n_samples=int(out.shape[1]),
+            **self._native_trace_info(index),
             selected_channels=selected_channels,
             units=units,
         )
@@ -505,10 +504,17 @@ class ZarrReader:
         return (out, info) if include_metadata else out
 
     def _native_trace_info(self, trace_index: int) -> dict[str, Any]:
-        return {
+        info = {
             "trace_index": int(trace_index),
             "n_samples": self.trace_length_samples,
         }
+        time_path = self.path / 'trace_time'
+        if is_array(time_path):
+            values = read_array_slice(time_path, (slice(trace_index, trace_index + 1),))
+            if np.asarray(values).size != 1:
+                raise ValueError('trace_time must contain one timestamp per finite trace')
+            info['trace_time'] = float(np.asarray(values).reshape(-1)[0])
+        return info
 
     def _native_read_block_info(self, read_block_index: int) -> dict[str, Any]:
         start, length = self._continuous_read_block_bounds(read_block_index)

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx/recorder/zarr.py

@@ -99,6 +99,7 @@ class ZarrRecorder:
         self._raw_path: Path | None = None
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
         self._native_raw_supports_shards = False
         self._raw_shape_model: str | None = None
         self._segment_length_samples: int | None = None
@@ -123,6 +124,7 @@ class ZarrRecorder:
         _require_zarr_python()
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
         self._native_raw_supports_shards = False
         try:
             self._open_stream_store()
@@ -182,6 +184,7 @@ class ZarrRecorder:
         self._raw_path = None
         self._native_group = None
         self._native_raw = None
+        self._native_trace_time = None
 
         if self.on_file_closed is not None:
             try:
@@ -209,6 +212,24 @@ class ZarrRecorder:
         self._native_raw.resize((n_traces, int(trace.shape[1]), int(trace.shape[2])))
         self._native_raw[int(trace_index), :, :] = np.ascontiguousarray(trace[0])
 
+    def _write_trace_time(self, trace_index: int, timestamp: float | None) -> None:
+        """Persist finite-record timestamps independently of waveform chunks.
+
+        Finite triggers need not be consecutive in time. Missing acquisition
+        timestamps remain NaN; write time is not an acquisition timestamp.
+        """
+        if self._native_trace_time is None:
+            self._native_trace_time = self._native_group.create_array(
+                'trace_time', shape=(0,), chunks=(1024,), dtype='float64',
+                fill_value=np.nan, dimension_names=('trace',),
+                attributes={'units': 's', 'time_reference': 'unix',
+                            'description': 'Acquisition timestamp for each finite trace'},
+            )
+        self._native_trace_time.resize((int(trace_index) + 1,))
+        self._native_trace_time[int(trace_index)] = (
+            np.nan if timestamp is None else float(timestamp)
+        )
+
     def write_segment(self, data, metadata: SegmentMetadata):
         if self._store is None:
             raise RuntimeError("ZarrRecorder is not open")
@@ -232,6 +253,7 @@ class ZarrRecorder:
         else:
             trace = data.reshape((1, int(data.shape[0]), int(data.shape[1])))
             self._write_native_trace(trace, segment_num - 1)
+            self._write_trace_time(segment_num - 1, metadata.segment_timestamp)
             self._chunk_shapes.append([1, int(data.shape[0]), int(data.shape[1])])
             self._n_samples_total = n_samples
 
@@ -244,8 +266,8 @@ class ZarrRecorder:
 
         # Zarr stores do not write per-block JSONL sidecars by default.
         # The stream/raw metadata carry n_samples, n_traces, chunking, and
-        # timing summaries; detailed per-write provenance can be added later
-        # behind an explicit debug/provenance option if needed.
+        # timing summaries. Finite acquisition timestamps live in the aligned
+        # trace_time array, because gaps cannot be recovered from trace indices.
 
         update_attrs(
             self._store,

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx/run/yaml_run.py

@@ -647,6 +647,10 @@ class YAMLRunController:
             "downsample_method": ds_method,
             "adc_physical_channels": [r.get("adc_physical_channel") for r in rows],
         }
+        # Finite NI tasks use start triggers (including analog threshold),
+        # not reference triggers with a pretrigger buffer.
+        if adc_mode.lower() == "finite":
+            adc_attrs["pretrigger_length_samples"] = 0
         return adc_attrs, rows
 
     def _build_detconfig_attrs(self, measurement_cfg: dict[str, Any], *, record_channels: list[str] | None = None) -> dict[str, Any]:

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx/services/tes_bias.py

@@ -819,7 +819,23 @@ class FEBPlusSignalGeneratorBiasPath(BaseBiasPath):
             self.feb_channel,
         )
         if source == "hardware" and value is not None:
-            return {"value": value, "units": self.last_dc_units, "source": "hardware"}
+            # last_dc_units is only populated by a set_dc() call made this
+            # session - if the FEB was already biased beforehand (the usual
+            # case: bias set once, then a viewer/reader process attaches
+            # later), it's still None here. Unlike PXI4322BiasPath (whose
+            # get_dc() falls back to "V", correctly paired with returning a
+            # raw voltage in that same branch), this class's `value` is the
+            # FEB's own already-calibrated current reading - falling back to
+            # None left callers with no unit at all, which a units-string
+            # lookup (e.g. PytesdaqxBoardReader.read_tes_bias) can silently
+            # misread as "not a recognized current unit, must be volts" and
+            # divide by a bias resistor instead of doing nothing - turning a
+            # ~uA reading into a value several orders of magnitude off.
+            return {
+                "value": value,
+                "units": self.last_dc_units or self.dc_default_units or "uA",
+                "source": "hardware",
+            }
         return super().get_dc()
 
     def configure_ac(

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytesdaqx
-Version: 0.1.0
+Version: 0.2.2
 Summary: TES detector acquisition, instrument control, and raw-data recording
 Author: TESSERACT DAQ developers
 Classifier: Development Status :: 3 - Alpha

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/pytesdaqx.egg-info/SOURCES.txt

@@ -172,6 +172,7 @@ tests/test_distribution_readiness.py
 tests/test_facility_catalog_metadata.py
 tests/test_feb_driver.py
 tests/test_feb_signal_generator_didv.py
+tests/test_finite_record_metadata.py
 tests/test_io_coordinate_cleanup.py
 tests/test_lakeshore372_driver.py
 tests/test_laser_configuration_ownership.py

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/tests/test_feb_signal_generator_didv.py

@@ -225,3 +225,24 @@ def test_preflight_fails_on_generator_clipping_and_leaves_feb_disconnected():
     assert ("output_off", 1) in sg.calls
     assert ("connect_tes_ac", "A", False) in feb.calls
     assert ("connect_tes_ac", "B", False) in feb.calls
+
+
+def test_get_dc_falls_back_to_configured_units_when_never_set_this_session():
+    # Regression test: the FEB is normally already biased before a viewer
+    # process ever attaches (bias set once, kept for the whole run) - so
+    # set_dc() (the only thing that used to populate last_dc_units) is often
+    # never called this session at all. get_dc() used to return units=None
+    # in that case, unlike PXI4322BiasPath.get_dc() (which falls back to
+    # "V", correctly paired with the raw voltage it returns in that same
+    # branch). A caller that maps a units *string* to a conversion factor
+    # (e.g. pytesscope's PytesdaqxBoardReader.read_tes_bias) can silently
+    # read units=None as "not a recognized current unit, must be volts" and
+    # divide the FEB's already-in-uA reading by a bias resistor instead -
+    # producing a value several orders of magnitude off, with no error
+    # raised anywhere.
+    service, feb, _sg = _service()
+
+    state = service.get_dc("TES_A")
+
+    assert state["value"] == feb.bias_by_channel["A"]
+    assert state["units"] == "uA"  # from dc_default_units, not left as None

pytesdaqx-0.2.2/tests/test_finite_record_metadata.py

@@ -0,0 +1,89 @@
+"""Finite acquisition timing must survive recording and reader selection."""
+
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+import zarr
+
+from pytesdaqx.io import StreamReader
+from pytesdaqx.io.zarr_utils import read_array, read_attrs
+from pytesdaqx.recorder import HDF5Recorder, RunMetadata, SegmentMetadata, ZarrRecorder
+from pytesdaqx.run.yaml_run import YAMLRunController
+
+
+def run_metadata(tmp_path):
+    return RunMetadata(
+        run_name='threshold_I2_D20260914_T120001', output_dir=tmp_path,
+        detector_channels=['TES_A'], sample_rate_hz=1000.,
+        root_attrs={'measurement': 'threshold', 'measurement_type': 'threshold',
+                    'stream_start': 1000., 'facility': 2},
+        adc_attrs={'adc_mode': 'finite', 'sample_rate_hz': 1000.,
+                   'pretrigger_length_samples': 0},
+    )
+
+
+@pytest.mark.parametrize('storage', ['hdf5', 'zarr'])
+def test_finite_timestamps_and_pretrigger_survive_recording(tmp_path, storage):
+    recorder = HDF5Recorder() if storage == 'hdf5' else ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    timestamps = [1000.125, 1007.75, 1018.3125]
+    for index, timestamp in enumerate(timestamps):
+        recorder.write_segment(np.full((1, 32), index, dtype=np.int16), SegmentMetadata(
+            measurement='threshold', sample_rate_hz=1000., segment_timestamp=timestamp))
+    recorder.close()
+
+    with StreamReader(tmp_path) as reader:
+        records = list(reader.iter_records())
+        assert len(records) == 3
+        for index, (trace, info) in enumerate(records):
+            np.testing.assert_array_equal(trace, np.full((1, 32), index))
+            key = 'segment_time' if storage == 'hdf5' else 'trace_time'
+            assert info[key] == timestamps[index]
+            assert info['pretrigger_length_samples'] == 0
+        if storage == 'zarr':
+            _, info = reader.read_record({'trace_index': 1})
+            assert info['trace_time'] == timestamps[1]
+    if storage == 'zarr':
+        time_path = next(tmp_path.glob('*.zarr')) / 'trace_time'
+        np.testing.assert_array_equal(read_array(time_path), timestamps)
+        assert read_attrs(time_path)['time_reference'] == 'unix'
+
+
+def test_missing_finite_timestamp_is_not_replaced_with_write_time(tmp_path):
+    recorder = ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    recorder.write_segment(np.zeros((1, 32)), SegmentMetadata(measurement='threshold', sample_rate_hz=1000.))
+    recorder.close()
+    with StreamReader(tmp_path) as reader:
+        _, info = reader.read_next()
+        assert np.isnan(info['trace_time'])
+
+
+def test_older_finite_zarr_without_timestamp_array_still_reads(tmp_path):
+    recorder = ZarrRecorder()
+    recorder.open(run_metadata(tmp_path))
+    recorder.write_segment(np.zeros((1, 32)), SegmentMetadata(measurement='threshold', sample_rate_hz=1000.))
+    recorder.close()
+    group = zarr.open_group(str(next(tmp_path.glob('*.zarr'))), mode='a')
+    del group['trace_time']
+    with StreamReader(tmp_path) as reader:
+        _, info = reader.read_next()
+        assert info['trace_index'] == 0
+        assert 'trace_time' not in info
+
+
+@pytest.mark.parametrize('trigger', ['none', 'analog_threshold', 'digital_edge'])
+@pytest.mark.parametrize('mode', ['finite', 'continuous'])
+def test_acquisition_builder_records_zero_pretrigger_for_finite_start_triggers(mode, trigger):
+    # Metadata building is hardware independent; the configured NI finite
+    # implementation uses start triggers, not reference-trigger buffers.
+    controller = SimpleNamespace(processors=[], _channel_map_for=lambda channels: [
+        {'detector_channel': channels[0], 'array_index': 0, 'adc_physical_channel': 'Dev1/ai0'}])
+    attrs, _ = YAMLRunController._build_adc_metadata(controller, {
+        'adc': {'mode': mode, 'sample_rate': 1000.}, 'trigger': {'type': trigger},
+    }, record_channels=['TES_A'])
+    if mode == 'finite':
+        assert attrs['pretrigger_length_samples'] == 0
+    else:
+        assert 'pretrigger_length_samples' not in attrs

{pytesdaqx-0.1.0 → pytesdaqx-0.2.2}/tests/test_view_trace_partitions.py

@@ -266,6 +266,34 @@ def test_stream_trigger_requires_trigger_window(tmp_path: Path):
         read_selected_trace(args)
 
 
+def test_iter_stream_traces_reads_native_zarr_trace_stream_without_trigger_flags(tmp_path: Path):
+    # Regression test: iter_stream_traces's non-partition branch always
+    # passed segment_trigger_index/segment_trigger_time_s/trace_length_samples/
+    # pretrigger_length_samples/trace_duration_s/pretrigger_duration_s through
+    # to reader.read_next() unconditionally - including as None when the CLI
+    # flag was never set. For a native Zarr trace stream that forwards
+    # straight to ZarrReader.get_trace(), whose signature has no **kwargs
+    # catch-all, so even a None-valued HDF5-only kwarg like
+    # segment_trigger_index raised TypeError: get_trace() got an unexpected
+    # keyword argument 'segment_trigger_index' - reproduced by pytesdaqx-scope
+    # (a downstream package) running `pytesdaqx-view-traces <didv zarr>
+    # --units volts --detector-channels <channel>` with no trigger flags at
+    # all, exactly this call shape.
+    acquisition, _, didv_id = _write_acquisition(tmp_path)
+    args = parse_args(
+        [
+            str(acquisition),
+            "--stream-id", didv_id,
+            "--units", "adc",
+            "--detector-channels", "TES_A",
+            "--no-show",
+        ]
+    )
+    records = list(iter_stream_traces(args))
+
+    assert [data.tolist() for data, _ in records] == [[[1, 2, 3, 4]], [[5, 6, 7, 8]]]
+
+
 def test_trace_index_selects_complete_zarr_trace(tmp_path: Path):
     acquisition, _, didv_id = _write_acquisition(tmp_path)
     args = parse_args(