mesofield 0.3.2b0__py3-none-any.whl

mesofield/datakit/sources/behavior/treadmill.py

@@ -0,0 +1,323 @@
+"""Treadmill loader.
+
+Data is reconstructed entirely from the central ``*_dataqueue.csv`` log: each
+``EncoderData(timestamp=..., distance=..., speed=...)`` payload row carries the
+full sample, already published on the master clock via ``queue_elapsed``. The
+per-session ``*_treadmill.csv`` is only consulted as a fallback when no
+dataqueue is available for that session (e.g. legacy fixtures used by the
+``treadmill_csv_fallback`` test).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+import numpy as np
+import pandas as pd
+
+from mesofield.datakit.config import settings
+from mesofield.datakit.sources.register import LoadContext, TimeseriesSource
+from mesofield.datakit.timeline import DataqueueIndex
+
+
+class TreadmillSource(TimeseriesSource):
+    """Load treadmill samples aligned to the experiment window."""
+
+    tag = "treadmill"
+    # Discovered from either the dataqueue (primary, parsed from EncoderData
+    # payloads) or — when no dataqueue exists for the session — the standalone
+    # treadmill CSV.
+    patterns = (
+        "**/*_dataqueue.csv",
+        "**/*_treadmill.csv",
+        "**/*_treadmill_data.csv",
+    )
+    camera_tag = None
+    requires = ("dataqueue",)
+
+    timestamp_column = "timestamp"
+    distance_columns = ("distance_mm", "distance")
+    speed_columns = ("speed_mm", "speed_mm_s", "speed")
+    output_distance_column = "distance_mm"
+    output_speed_column = "speed_mm"
+    timestamp_to_seconds = 1e-6
+
+    dataqueue_queue_column = settings.timeline.queue_column
+    dataqueue_device_id_column = "device_id"
+    dataqueue_payload_column = "payload"
+
+    dataqueue_payload_prefix = "EncoderData"
+    timeline_master_patterns = ("dhyana", "mesoscope")
+    _encoder_ts_re = re.compile(r"timestamp\s*=\s*(\d+)", re.IGNORECASE)
+    _encoder_payload_re = re.compile(
+        r"EncoderData\s*\("
+        r"\s*timestamp\s*=\s*(?P<ts>\d+)\s*,"
+        r"\s*distance\s*=\s*(?P<dist>-?\d+(?:\.\d+)?)"
+        r"(?:\s*[A-Za-z/]+)?\s*,"
+        r"\s*speed\s*=\s*(?P<speed>-?\d+(?:\.\d+)?)"
+        r"(?:\s*[A-Za-z/]+)?\s*\)",
+        re.IGNORECASE,
+    )
+
+    def build_timeseries(
+        self,
+        path: Path,
+        *,
+        context: LoadContext | None = None,
+    ) -> tuple[np.ndarray, pd.DataFrame, dict]:
+        context = self._require_context(context)
+        dq_path = context.path_for("dataqueue")
+
+        # Primary path: build from the dataqueue alone — the per-session
+        # treadmill CSV (if it exists) is ignored.
+        if dq_path is not None or context.dataqueue_frame is not None:
+            aligned, meta = self._build_from_dataqueue(
+                dq_path=dq_path,
+                dataqueue_frame=context.dataqueue_frame,
+                window=context.experiment_window,
+            )
+            t = aligned["time_elapsed_s"].to_numpy(dtype=np.float64)
+            meta = {
+                "source_file": str(dq_path) if dq_path is not None else None,
+                "dataqueue_file": str(dq_path) if dq_path is not None else None,
+                "n_samples": int(len(aligned)),
+                **meta,
+            }
+            return t, aligned, meta
+
+        # Fallback path: standalone treadmill CSV with no dataqueue available.
+        if path is None or not Path(path).exists() or Path(path).name.endswith("_dataqueue.csv"):
+            raise FileNotFoundError(
+                "TreadmillSource: no dataqueue available and no treadmill CSV path"
+            )
+        df = pd.read_csv(path)
+        dist = next((c for c in self.distance_columns if c in df.columns), None)
+        speed = next((c for c in self.speed_columns if c in df.columns), None)
+        if self.timestamp_column not in df.columns or dist is None or speed is None:
+            raise ValueError(f"Expected timestamp/distance/speed columns in {path}")
+        df = df.rename(columns={dist: self.output_distance_column, speed: self.output_speed_column})
+
+        aligned, meta = self._build_from_csv_fallback(df)
+        t = aligned["time_elapsed_s"].to_numpy(dtype=np.float64)
+        meta = {
+            "source_file": str(path),
+            "dataqueue_file": None,
+            "n_samples": int(len(aligned)),
+            **meta,
+        }
+        return t, aligned, meta
+
+    # --- dataqueue path -------------------------------------------------------
+
+    def _build_from_dataqueue(
+        self,
+        *,
+        dq_path: Path | None,
+        dataqueue_frame: pd.DataFrame | None,
+        window: tuple[float, float] | None,
+    ) -> tuple[pd.DataFrame, dict]:
+        t0, t1 = window or self._window(dq_path, dataqueue_frame)
+        duration = float(t1 - t0)
+        if not np.isfinite(duration) or duration <= 0:
+            raise ValueError(f"Invalid camera window duration from dataqueue: start={t0}, end={t1}")
+
+        samples = self._encoder_samples(dq_path, dataqueue_frame)
+        queue_elapsed = samples["queue_elapsed"]
+        distance = samples["distance_mm"]
+        speed = samples["speed_mm"]
+        encoder_ts = samples["encoder_ts"]
+
+        time_s = queue_elapsed - t0
+        finite_vals = np.isfinite(distance) & np.isfinite(speed)
+        mask = (
+            np.isfinite(time_s)
+            & finite_vals
+            & (time_s >= 0.0)
+            & (time_s <= duration)
+        )
+        if not np.any(mask):
+            # No treadmill samples in this session: return empty DataFrame and meta
+            aligned = pd.DataFrame({
+                self.timestamp_column: np.array([], dtype=np.float64),
+                self.output_distance_column: np.array([], dtype=np.float64),
+                self.output_speed_column: np.array([], dtype=np.float64),
+                "time_elapsed_s": np.array([], dtype=np.float64),
+            })
+            meta = {
+                "source_method": "dataqueue_encoder_payload",
+                "experiment_window": {"start": float(t0), "end": float(t1)},
+                "n_encoder_payloads": int(queue_elapsed.size),
+                "n_kept": 0,
+            }
+            return aligned, meta
+
+        aligned = pd.DataFrame(
+            {
+                self.timestamp_column: encoder_ts[mask],
+                self.output_distance_column: distance[mask],
+                self.output_speed_column: speed[mask],
+                "time_elapsed_s": time_s[mask],
+            }
+        )
+        aligned.sort_values("time_elapsed_s", inplace=True)
+        aligned.reset_index(drop=True, inplace=True)
+
+        meta = {
+            "source_method": "dataqueue_encoder_payload",
+            "experiment_window": {"start": float(t0), "end": float(t1)},
+            "n_encoder_payloads": int(queue_elapsed.size),
+            "n_kept": int(np.count_nonzero(mask)),
+        }
+        return aligned, meta
+
+    def _encoder_samples(
+        self,
+        dq_path: Path | None,
+        dataqueue_frame: pd.DataFrame | None,
+    ) -> dict[str, np.ndarray]:
+        """Return parallel arrays parsed from EncoderData payloads.
+
+        Treadmill owns this parsing — the ``dataqueue`` source intentionally
+        treats payloads as opaque. We use the upstream frame only if the
+        payload column is still in its original string dtype (which is no
+        longer the case once ``DataqueueSource`` has run), otherwise we
+        re-read the raw CSV via ``dq_path``.
+        """
+
+        dq = dataqueue_frame
+        if dq is not None:
+            payload = dq.get(self.dataqueue_payload_column)
+            if payload is not None and (
+                pd.api.types.is_object_dtype(payload) or pd.api.types.is_string_dtype(payload)
+            ):
+                return self._parse_dataqueue_payloads(dq)
+        if dq_path is None:
+            raise ValueError(
+                "TreadmillSource: dataqueue payload is not string-typed and no path is "
+                "available to re-read EncoderData strings"
+            )
+        raw = pd.read_csv(
+            dq_path,
+            usecols=[self.dataqueue_queue_column, self.dataqueue_payload_column],
+            low_memory=False,
+        )
+        return self._parse_dataqueue_payloads(raw)
+
+    def _parse_dataqueue_payloads(self, dq: pd.DataFrame) -> dict[str, np.ndarray]:
+        if (
+            self.dataqueue_payload_column not in dq.columns
+            or self.dataqueue_queue_column not in dq.columns
+        ):
+            raise ValueError("Dataqueue frame missing payload or queue_elapsed column")
+
+        payload = dq[self.dataqueue_payload_column].astype(str)
+        mask = payload.str.contains(self.dataqueue_payload_prefix, na=False)
+        if not np.any(mask):
+            raise ValueError("No EncoderData payloads found in dataqueue")
+
+        sub_payloads = payload.loc[mask].to_numpy()
+        queue_full = pd.to_numeric(dq.loc[mask, self.dataqueue_queue_column], errors="coerce").to_numpy(dtype=np.float64)
+
+        ts_list: list[float] = []
+        dist_list: list[float] = []
+        speed_list: list[float] = []
+        q_list: list[float] = []
+        for value, q in zip(sub_payloads, queue_full):
+            if not np.isfinite(q):
+                continue
+            m = self._encoder_payload_re.search(value or "")
+            if m is None:
+                continue
+            ts_list.append(float(int(m.group("ts"))))
+            dist_list.append(float(m.group("dist")))
+            speed_list.append(float(m.group("speed")))
+            q_list.append(float(q))
+
+        if not ts_list:
+            raise ValueError("No parseable EncoderData payloads in dataqueue")
+
+        return {
+            "queue_elapsed": np.asarray(q_list, dtype=np.float64),
+            "encoder_ts": np.asarray(ts_list, dtype=np.float64),
+            "distance_mm": np.asarray(dist_list, dtype=np.float64),
+            "speed_mm": np.asarray(speed_list, dtype=np.float64),
+        }
+
+    def _window(
+        self,
+        dq_path: Path | None,
+        dataqueue_frame: pd.DataFrame | None,
+    ) -> tuple[float, float]:
+        dq = dataqueue_frame
+        if dq is None:
+            if dq_path is None:
+                raise FileNotFoundError("TreadmillSource: dataqueue path not available")
+            dq = pd.read_csv(
+                dq_path,
+                usecols=[self.dataqueue_queue_column, self.dataqueue_device_id_column],
+                low_memory=False,
+            )
+        device = dq.get(self.dataqueue_device_id_column, pd.Series(dtype=str)).astype(str)
+
+        mask = np.zeros(len(dq), dtype=bool)
+        for pattern in self.timeline_master_patterns:
+            mask |= device.str.contains(pattern, case=False, na=False, regex=False).to_numpy()
+
+        rows = pd.to_numeric(dq.loc[mask, self.dataqueue_queue_column], errors="coerce").dropna()
+        if len(rows) < 2:
+            raise ValueError("Could not find >=2 master camera rows in dataqueue")
+        return float(rows.iloc[0]), float(rows.iloc[-1])
+
+    # --- CSV-only fallback ----------------------------------------------------
+
+    def _build_from_csv_fallback(
+        self, treadmill_df: pd.DataFrame
+    ) -> tuple[pd.DataFrame, dict]:
+        ts = pd.to_numeric(treadmill_df[self.timestamp_column], errors="coerce").to_numpy(dtype=np.float64)
+        finite = np.isfinite(ts)
+        if not np.any(finite):
+            raise ValueError("No valid treadmill timestamp samples")
+
+        aligned = treadmill_df.loc[finite].copy()
+        ts = ts[finite]
+        ts_i64 = np.rint(ts).astype(np.int64)
+
+        unwrapped = DataqueueIndex.fix_32bit_wraparound(ts_i64).astype(np.float64)
+        # If the file contains a wrap, samples after the wrap may be out of order.
+        # Sort by unwrapped timestamp before computing elapsed time.
+        sort_idx = np.argsort(unwrapped)
+        unwrapped = unwrapped[sort_idx]
+        aligned = aligned.iloc[sort_idx].reset_index(drop=True)
+        elapsed = DataqueueIndex.relative(unwrapped) * self.timestamp_to_seconds
+        aligned["_elapsed"] = elapsed
+
+        aligned[self.output_distance_column] = pd.to_numeric(
+            aligned[self.output_distance_column], errors="coerce"
+        )
+        aligned[self.output_speed_column] = pd.to_numeric(
+            aligned[self.output_speed_column], errors="coerce"
+        )
+        aligned = aligned.dropna(
+            subset=[self.output_distance_column, self.output_speed_column, "_elapsed"]
+        )
+        if aligned.empty:
+            raise ValueError("Treadmill fallback produced no finite elapsed samples")
+
+        elapsed = aligned.pop("_elapsed").to_numpy(dtype=np.float64)
+        if elapsed.size > 1:
+            keep = np.concatenate(([True], np.diff(elapsed) > 0))
+            aligned = aligned.iloc[keep].copy()
+            elapsed = elapsed[keep]
+        if elapsed.size == 0:
+            raise ValueError("Treadmill fallback produced no usable samples after cleaning")
+
+        aligned["time_elapsed_s"] = elapsed
+        aligned.sort_values("time_elapsed_s", inplace=True)
+        aligned.reset_index(drop=True, inplace=True)
+
+        return aligned, {
+            "source_method": "treadmill_csv_fallback",
+            "experiment_window": None,
+            "alignment": None,
+        }

mesofield/datakit/sources/behavior/wheel.py

@@ -0,0 +1,277 @@
+"""Wheel encoder behavioral data source with dda synchronized timeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from ..._utils._logger import get_logger
+
+from mesofield.datakit.sources.register import LoadContext, TimeseriesSource
+from mesofield.datakit.timeline import DataqueueIndex
+
+logger = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class _WheelSummary:
+    """Aggregate metrics extracted from a wheel run."""
+
+    duration_s: float
+    total_distance_mm: float
+    total_click_delta: int
+    start_ts: Optional[str]
+    stop_ts: Optional[str]
+
+
+class WheelEncoder(TimeseriesSource):
+    """Load wheel encoder streams recorded alongside nidaq pulses.
+
+    The raw CSV emitted by the behavioral rig contains incremental click counts,
+    elapsed time in seconds, and instantaneous speed estimates. The loader
+    converts this information into a strictly increasing timeline anchored to
+    acquisition start, computes cumulative distance, and exposes rich metadata
+    for downstream alignment against the nidaq-driven master clock.
+    """
+
+    tag = "wheel"
+    patterns = ("**/*_wheel.csv",)
+    camera_tag = None  # Not bound to camera
+    requires = ("dataqueue",)
+
+    required_columns = ("Clicks", "Time", "Speed")
+    time_column = "Time"
+    click_column = "Clicks"
+    speed_column = "Speed"
+    cumulative_column = "click_delta"
+    anchor_filter_pattern = "encoder"
+    queue_elapsed_column = "queue_elapsed"
+    dataqueue_payload_column = "payload"
+    alignment_min_points = 2
+    alignment_time_basis_dataqueue = "dataqueue"
+    alignment_time_basis_wheel = "wheel_clock"
+    alignment_poly_degree = 1
+    distance_integration_method = "trapezoid"
+    absolute_device_id = "encoder"
+    alignment_origin_device_id = "ThorCam"
+    def build_timeseries(
+        self,
+        path: Path,
+        *,
+        context: LoadContext | None = None,
+    ) -> tuple[np.ndarray, pd.DataFrame, dict]:
+        context = self._require_context(context)
+        raw = pd.read_csv(path)
+
+        if not set(self.required_columns).issubset(raw.columns):
+            raise ValueError(
+                f"Wheel file is missing required columns {self.required_columns}: {path}"
+            )
+
+        df = self._prepare_frame(raw)
+        df_aligned, alignment_meta = self._align_to_dataqueue(df, context)
+        summary = self._summarize(df_aligned, raw)
+        df_aligned = df_aligned.rename(columns={"time_s": "time_elapsed_s", "time_raw_s": "time_reference_s"})
+
+        meta = {
+            "source_file": str(path),
+            "n_samples": int(len(df_aligned)),
+            "start_time": summary.start_ts,
+            "stop_time": summary.stop_ts,
+            "duration_s": summary.duration_s,
+            "total_distance_mm": summary.total_distance_mm,
+            "total_click_delta": summary.total_click_delta,
+            "source_method": "wheel_csv_v2",
+            **alignment_meta,
+        }
+
+        return df_aligned["time_elapsed_s"].to_numpy(dtype=np.float64), df_aligned, meta
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _prepare_frame(self, raw: pd.DataFrame) -> pd.DataFrame:
+        """Type cast and derive the canonical wheel dataframe."""
+
+        frame = pd.DataFrame()
+        frame["time_s"] = pd.to_numeric(raw[self.time_column], errors="coerce")
+        frame["click_delta"] = pd.to_numeric(raw[self.click_column], errors="coerce")
+        frame["speed_mm"] = pd.to_numeric(raw[self.speed_column], errors="coerce")
+
+        frame = frame.dropna(subset=["time_s"]).sort_values("time_s").reset_index(drop=True)
+
+        if frame.empty:
+            frame = pd.DataFrame(
+            {
+                "time_s": [0.0, 0.0],
+                "click_delta": [0, 0],
+                "speed_mm": [0.0, 0.0],
+            })
+
+        # Ensure speed/clicks missing entries become zeros
+        frame["click_delta"] = frame["click_delta"].fillna(0)
+        frame["speed_mm"] = frame["speed_mm"].fillna(0.0)
+
+        # Re-zero the timeline relative to the first available sample
+        frame["time_raw_s"] = frame["time_s"].to_numpy(dtype=np.float64)
+        t = frame["time_raw_s"].copy()
+        t0 = float(t[0])
+        t -= t0
+        frame["time_s"] = t
+
+        # Derive cumulative click position for quick sanity checks
+        frame["click_position"] = np.cumsum(frame["click_delta"].to_numpy(dtype=np.int64))
+
+        # Integrate speed to distance using trapezoidal rule
+        speed = frame["speed_mm"].to_numpy(dtype=np.float64)
+        distance = np.zeros_like(speed)
+        if speed.size > 1:
+            dt = np.diff(t)
+            trapezoids = 0.5 * (speed[:-1] + speed[1:]) * dt
+            distance[1:] = np.cumsum(trapezoids)
+        frame["distance_mm"] = distance
+
+        return frame[["time_s", "time_raw_s", "click_delta", "click_position", "speed_mm", "distance_mm"]]
+
+    def _summarize(self, frame: pd.DataFrame, raw: pd.DataFrame) -> _WheelSummary:
+        """Build aggregate metadata for diagnostics and alignment hints."""
+
+        duration = float(frame["time_s"].iloc[-1]) if len(frame) else 0.0
+        total_distance = float(frame["distance_mm"].iloc[-1]) if len(frame) else 0.0
+        total_clicks = int(frame["click_delta"].sum())
+
+        start_ts = self._extract_timestamp(raw.get("Started"))
+        stop_ts = self._extract_timestamp(raw.get("Stopped"))
+
+        return _WheelSummary(
+            duration_s=duration,
+            total_distance_mm=total_distance,
+            total_click_delta=total_clicks,
+            start_ts=start_ts,
+            stop_ts=stop_ts,
+        )
+
+    # ------------------------------------------------------------------
+    # Alignment helpers
+    # ------------------------------------------------------------------
+    def _align_to_dataqueue(self, frame: pd.DataFrame, context: LoadContext) -> tuple[pd.DataFrame, dict]:
+        """Map wheel timestamps onto the nidaq master clock via dataqueue anchors."""
+        dq_path = context.path_for("dataqueue")
+        dataqueue_file = str(dq_path) if dq_path is not None else None
+        timeline = None
+
+        if context.dataqueue_frame is not None:
+            encoder_times = self._extract_times(context.dataqueue_frame, self.anchor_filter_pattern)
+            origin_times = self._extract_times(context.dataqueue_frame, self.alignment_origin_device_id)
+        else:
+            if dq_path is None:
+                raise FileNotFoundError("WheelEncoder: dataqueue path not available")
+            timeline = DataqueueIndex.from_path(dq_path)
+            encoder_slice = timeline.slice(
+                lambda ids: ids.str.contains(self.anchor_filter_pattern, case=False, na=False, regex=False)
+            )
+            encoder_times = encoder_slice.queue_elapsed().to_numpy(dtype=np.float64)
+            origin_slice = timeline.slice(
+                lambda ids: ids.str.contains(self.alignment_origin_device_id, case=False, na=False, regex=False)
+            )
+            origin_times = origin_slice.queue_elapsed().to_numpy(dtype=np.float64)
+            dataqueue_file = str(timeline.source_path)
+        if encoder_times.size < 2:
+            logger.warning(
+                "WheelEncoder: insufficient encoder anchors (%d). "
+                "Returning unaligned wheel timeline.",
+                encoder_times.size,
+            )
+            return frame.copy(), {
+                "time_basis": self.alignment_time_basis_wheel,
+                "dataqueue_file": dataqueue_file,
+                "dataqueue_alignment": "insufficient_anchors",
+                "dataqueue_anchors": int(encoder_times.size),
+                "alignment_device": self.anchor_filter_pattern,
+            }
+        if origin_times.size == 0:
+            logger.warning(
+                "WheelEncoder: %s anchors missing for alignment. "
+                "Returning unaligned wheel timeline.",
+                self.alignment_origin_device_id,
+            )
+            return frame.copy(), {
+                "time_basis": self.alignment_time_basis_wheel,
+                "dataqueue_file": dataqueue_file,
+                "dataqueue_alignment": "missing_origin_anchors",
+                "dataqueue_anchors": int(encoder_times.size),
+                "alignment_device": self.anchor_filter_pattern,
+                "alignment_origin_device": self.alignment_origin_device_id,
+            }
+
+        n_samples = len(frame)
+        n_anchors = int(encoder_times.size)
+        if n_anchors == n_samples:
+            aligned_times = encoder_times
+            method = "direct"
+        else:
+            anchor_index = np.arange(n_anchors, dtype=np.float64)
+            frame_index = np.linspace(0.0, float(n_anchors - 1), num=n_samples, dtype=np.float64)
+            aligned_times = np.interp(frame_index, anchor_index, encoder_times)
+            method = "resampled"
+
+        origin = float(origin_times[0])
+        aligned = frame.copy()
+        aligned["time_s"] = aligned_times - origin
+
+        encoder_start = float(encoder_times[0])
+        origin_offset = encoder_start - origin
+
+        if timeline is not None:
+            elapsed_abs = timeline.absolute_for_device(self.absolute_device_id)
+        else:
+            elapsed_abs = None
+        if elapsed_abs:
+            elapsed, absolute = elapsed_abs
+            elapsed = elapsed + origin_offset
+            aligned_t = aligned["time_s"].to_numpy(dtype=np.float64)
+            aligned["time_absolute"] = np.interp(aligned_t, elapsed, np.arange(len(absolute))).astype(int)
+            aligned["time_absolute"] = aligned["time_absolute"].map(
+                lambda i: absolute[i] if 0 <= i < len(absolute) else None
+            )
+
+        return aligned, {
+            "time_basis": self.alignment_time_basis_dataqueue,
+            "dataqueue_file": dataqueue_file,
+            "dataqueue_alignment": method,
+            "dataqueue_anchors": n_anchors,
+            "alignment_device": self.anchor_filter_pattern,
+            "alignment_origin_device": self.alignment_origin_device_id,
+            "alignment_origin_queue_elapsed": origin,
+            "alignment_origin_offset": float(origin_offset),
+        }
+
+    def _extract_times(self, frame: pd.DataFrame, pattern: str) -> np.ndarray:
+        if self.queue_elapsed_column not in frame.columns or "device_id" not in frame.columns:
+            return np.array([], dtype=np.float64)
+        device_series = frame["device_id"].astype(str)
+        mask = device_series.str.contains(pattern, case=False, na=False, regex=False)
+        times = pd.to_numeric(frame.loc[mask, self.queue_elapsed_column], errors="coerce").dropna()
+        return times.to_numpy(dtype=np.float64)
+
+    @staticmethod
+    def _extract_timestamp(series: Optional[pd.Series]) -> Optional[str]:
+        """Return an ISO8601 string if the provided column encodes a timestamp."""
+
+        if series is None:
+            return None
+
+        first = series.dropna().astype(str).head(1)
+        if first.empty:
+            return None
+
+        try:
+            ts = pd.to_datetime(first.iloc[0], utc=False, errors="raise")
+        except (TypeError, ValueError):
+            return None
+
+        return ts.isoformat()

mesofield/datakit/sources/camera/mesoscope.py

@@ -0,0 +1,32 @@
+"""Mesoscope camera metadata data source."""
+
+from mesofield.datakit.sources.camera.metadata_json import MetadataJSON
+
+
+class MesoMetadataSource(MetadataJSON):
+    """Load mesoscope camera metadata JSON files as a table."""
+    tag = "meso_metadata"
+    patterns = ("**/*_mesoscope.ome.tiff_frame_metadata.json",
+                "**/*_meso.ome.tiff_frame_metadata.json")
+    camera_tag = "meso_metadata"
+    flatten_payload = False
+    drop_columns = (
+        "camera_metadata",
+        "property_values",
+        "version",
+        "format",
+        "ROI-X-start",
+        "ROI-Y-start",
+        "mda_event",
+        "Height",
+        "Width",
+        "camera_device",
+        "pixel_size_um",
+        "images_remaining_in_buffer",
+        "PixelType",
+        "hardware_triggered",
+        # Redundant timestamp columns: time_elapsed_s + time_absolute already
+        # cover the same clock at smaller dtypes.
+        "ElapsedTime-ms",
+        "TimeReceivedByCore",
+    )