msw-io 1.0.2__py3-none-any.whl

msw_io-1.0.2.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: msw-io
+Version: 1.0.2
+Summary: Murine Shift Work session data IO: file codec, namespace utilities, and session readers.
+Author-email: "Lars B. Rollik" <lars@rollik.me>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: acquisition-namespace>=1.2.2
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml
+Requires-Dist: ttl-barcoder>=0.4.1
+Provides-Extra: dev
+Requires-Dist: commitizen; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyarrow; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# msw-io
+
+[![PyPI](https://img.shields.io/pypi/v/msw-io.svg)](https://pypi.org/project/msw-io)
+
+Murine Shift Work session data IO: file codec, namespace utilities, and session readers.
+
+Provides a lean, installable library for reading and writing MSW session data without
+requiring the full `murineshiftwork` acquisition stack.  Install it in analysis
+environments where you only need to load sessions, not run them.
+
+## Key features
+
+- **Session readers** - load MSW session data (JSONL, PKL, YAML) into structured `MswSession` models
+- **Namespace utilities** - build and parse MSW session paths from the canonical `subject__datetime__task` spec
+- **IO codec** - save and load trial data with numpy/tuple encoding
+- **Standalone** - no dependency on the `murineshiftwork` acquisition stack
+
+## Installation
+
+```bash
+pip install msw-io
+```
+
+## Quick start
+
+```python
+from murineshiftwork.readers import load_session
+
+session = load_session("/data/mouse_01/session__20260514_143022_123456__gonogo")
+print(session.subject, session.task, session.n_trials)
+```
+
+Load an entire acquisition (all sessions in a container directory):
+
+```python
+from murineshiftwork.readers import load_acquisition
+
+sessions = load_acquisition("/data/mouse_01/session__20260514_143022_123456__session_gonogo")
+for s in sessions:
+    print(s.basename, s.is_complete)
+```
+
+Generate session paths for a new recording:
+
+```python
+from murineshiftwork.namespace import generate_session_paths
+
+paths = generate_session_paths("mouse_01", "gonogo", "/data", printout=False)
+print(paths["session_folder"])
+```
+
+## Documentation
+
+Full documentation including API reference: <https://murineshiftwork.github.io/msw-io>

msw_io-1.0.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+murineshiftwork/_version.py,sha256=913Ea4P4y2ZD15ebE66os1ChbBKutOXqQ54_tjABoS0,520
+murineshiftwork/io/__init__.py,sha256=DYoxKuTRF2ZKI6FrvKnwGKXkjbjKbh7waug_3xUukls,4602
+murineshiftwork/namespace/__init__.py,sha256=merw31cRsjycjHJGpfJBvuMckAwkaLHyZ1A2GZ0Yixs,847
+murineshiftwork/namespace/manifest.py,sha256=hapuQTQXzatd2XbcWQDjmpFZy7rClvlrA5Of1amP7Io,4778
+murineshiftwork/namespace/msw_files.py,sha256=nXNtRvtgRFzsoYc-YZLj23H0TsPcVfMWxV_cvRx1TXU,1774
+murineshiftwork/namespace/namespace.msw.yaml,sha256=L0twEJZKssZvQhJWYw3u21g6JOHr_ruryzPdqyJHrT4,771
+murineshiftwork/namespace/paths.py,sha256=iI6w5EPvdS9P-yHnN7YPF5zM3DpN9KTbuiC14MA8UCc,7394
+murineshiftwork/namespace/spec.py,sha256=Rn9QzVel-AWAqtsyutc7pRDY616T9GE7rOvMAv2CWlg,282
+murineshiftwork/readers/__init__.py,sha256=oJkm1N5_jzMnACAMH4_1CBgd4Nx2FDCcBsuSGIiU0gU,372
+murineshiftwork/readers/alignment.py,sha256=7T3ZgNmEoManzWVUlNSS4gahA5o2TA5fHJAAkSKa4HA,10842
+murineshiftwork/readers/batch.py,sha256=z42sQfc3b9RvgwqqB5rBS2EO6kCKX-O0JFThwxt_OyY,6166
+murineshiftwork/readers/files.py,sha256=qa0oEyNBrpkQFxwrlYe_RUibuZMu-xTulWB7qIkj1ZQ,3379
+murineshiftwork/readers/models.py,sha256=fdVJHWrqsVqobzIbbIXZ8r44OxsXqjLVkY3DUnUEmbI,4271
+murineshiftwork/readers/namespace.py,sha256=G8A7oH6QQ7Udik16XtB3AeD4w0H_ymWRBqKK0_VpNOM,4506
+murineshiftwork/readers/session.py,sha256=lvfl2SkfRyQ_5KFoZZCAYJ490TAjhp3SxvDKGPWhiY8,7923
+murineshiftwork/readers/validate.py,sha256=RpWCa8xQXC8HNhUA04t4PRvzna7hc3BZVU1QHyIcrP8,2770
+msw_io-1.0.2.dist-info/METADATA,sha256=u9tCh1xNvJ7mccyVbAm6FRs8WUwjqwOu3c5TP1dFm7o,2567
+msw_io-1.0.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+msw_io-1.0.2.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msw_io-1.0.2.dist-info/RECORD,,

msw_io-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

murineshiftwork/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.2'
+__version_tuple__ = version_tuple = (1, 0, 2)
+
+__commit_id__ = commit_id = None

murineshiftwork/io/__init__.py

@@ -0,0 +1,134 @@
+"""JSONL trial data codec for MSW sessions (MSW_FILE_VERSION 1.0.0).
+
+Format: newline-delimited JSON. First line is a version header.
+Numpy arrays are serialised as plain lists; on load they remain lists,
+which is compatible with all downstream DataFrame operations.
+
+Tuple preservation
+------------------
+JSON has no tuple type: both lists and tuples serialise as arrays. To preserve
+Python tuples across the round-trip, tuples are encoded as {"__tuple__": [...]}
+and decoded back to tuples on load. This keeps the computational interface
+identical between JSONL and legacy pkl sessions (e.g. block_type_values).
+"""
+
+import json
+import logging
+from pathlib import Path
+
+import numpy as np
+
+MSW_FILE_VERSION = "1.0.0"
+
+
+def _encode_tuples(obj):
+    """Recursively replace tuples with {"__tuple__": [...]} before JSON encoding."""
+    if isinstance(obj, tuple):
+        return {"__tuple__": [_encode_tuples(v) for v in obj]}
+    if isinstance(obj, dict):
+        return {k: _encode_tuples(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_encode_tuples(v) for v in obj]
+    return obj
+
+
+def _decode_tuples(obj):
+    """Recursively restore {"__tuple__": [...]} sentinels to Python tuples."""
+    if isinstance(obj, dict):
+        if "__tuple__" in obj and len(obj) == 1:
+            return tuple(_decode_tuples(v) for v in obj["__tuple__"])
+        return {k: _decode_tuples(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_decode_tuples(v) for v in obj]
+    return obj
+
+
+_FLOAT_DECIMALS = 4
+
+
+def _round_floats(obj):
+    """Recursively round all floats to _FLOAT_DECIMALS decimal places."""
+    if isinstance(obj, float):
+        return round(obj, _FLOAT_DECIMALS)
+    if isinstance(obj, dict):
+        return {k: _round_floats(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_round_floats(v) for v in obj]
+    if isinstance(obj, tuple):
+        return tuple(_round_floats(v) for v in obj)
+    if isinstance(obj, np.ndarray):
+        if np.issubdtype(obj.dtype, np.floating):
+            return obj.round(_FLOAT_DECIMALS).tolist()
+        return obj.tolist()
+    if isinstance(obj, np.floating):
+        return round(float(obj), _FLOAT_DECIMALS)
+    if isinstance(obj, np.integer):
+        return int(obj)
+    if isinstance(obj, np.bool_):
+        return bool(obj)
+    return obj
+
+
+class _NumpyEncoder(json.JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, np.ndarray):
+            if np.issubdtype(obj.dtype, np.floating):
+                return obj.round(_FLOAT_DECIMALS).tolist()
+            return obj.tolist()
+        if isinstance(obj, np.integer):
+            return int(obj)
+        if isinstance(obj, np.floating):
+            return round(float(obj), _FLOAT_DECIMALS)
+        if isinstance(obj, np.bool_):
+            return bool(obj)
+        return super().default(obj)
+
+
+def save_trial_data(trial_data_list: list, filepath: str | Path) -> None:
+    """Save a list of trial dicts to a JSONL file.
+
+    Overwrites any existing file.  The first line is a version header;
+    subsequent lines are one JSON object per trial.  Numpy arrays are
+    converted to lists; tuples are encoded as ``{"__tuple__": [...]}``
+    so they survive the round-trip through ``load_trial_data``.
+
+    Args:
+        trial_data_list: List of per-trial dicts as returned by the task.
+        filepath: Destination path (parent directories are created if absent).
+    """
+    filepath = Path(filepath)
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    with filepath.open("w") as f:
+        f.write(json.dumps({"_msw_version": MSW_FILE_VERSION}) + "\n")
+        for trial in trial_data_list:
+            f.write(
+                json.dumps(_round_floats(_encode_tuples(trial)), cls=_NumpyEncoder)
+                + "\n"
+            )
+    logging.debug(f"Saved {len(trial_data_list)} trials to {filepath}")
+
+
+def load_trial_data(filepath) -> list:
+    """Load trial dicts from a JSONL file written by ``save_trial_data``.
+
+    Skips the version header line and restores ``{"__tuple__": [...]}``
+    sentinels back to Python tuples.
+
+    Args:
+        filepath: Path to the ``.jsonl`` file.
+
+    Returns:
+        List of per-trial dicts with tuples restored.
+    """
+    filepath = Path(filepath)
+    trials = []
+    with filepath.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            obj = json.loads(line)
+            if "_msw_version" in obj:
+                continue
+            trials.append(_decode_tuples(obj))
+    return trials

murineshiftwork/namespace/__init__.py

@@ -0,0 +1,16 @@
+from murineshiftwork.namespace.msw_files import is_msw_file as is_msw_file
+from murineshiftwork.namespace.msw_files import msw_artifact as msw_artifact
+from murineshiftwork.namespace.msw_files import msw_file as msw_file
+from murineshiftwork.namespace.paths import (
+    CURRENT_NAMESPACE_VERSION as CURRENT_NAMESPACE_VERSION,
+)
+from murineshiftwork.namespace.paths import NAMESPACE_LEGACY as NAMESPACE_LEGACY
+from murineshiftwork.namespace.paths import NAMESPACE_V1 as NAMESPACE_V1
+from murineshiftwork.namespace.paths import build_data_paths as build_data_paths
+from murineshiftwork.namespace.paths import (
+    generate_session_paths as generate_session_paths,
+)
+from murineshiftwork.namespace.paths import get_msw_builder as get_msw_builder
+from murineshiftwork.namespace.paths import (
+    parse_session_basename as parse_session_basename,
+)

murineshiftwork/namespace/manifest.py

@@ -0,0 +1,163 @@
+"""Acquisition and session manifest writers.
+
+Manifests are YAML files written progressively during a session:
+  acquisition_manifest.yaml : inside the acquisition dir; lists sessions
+  session_manifest.yaml     : inside the session dir; lists subprotocols (opto) or empty
+
+All write operations are atomic (write temp file, rename).
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def _read_yaml(path: Path) -> dict:
+    return yaml.safe_load(path.read_text()) or {}
+
+
+def _write_yaml(path: Path, data: dict) -> None:
+    tmp = path.with_suffix(".yaml.tmp")
+    with tmp.open("w") as f:
+        yaml.dump(
+            data, f, default_flow_style=False, allow_unicode=True, sort_keys=False
+        )
+    tmp.replace(path)
+
+
+# ---------------------------------------------------------------------------
+# Acquisition manifest
+
+
+def init_acquisition_manifest(
+    acquisition_folder: str | Path, acquisition_name: str
+) -> None:
+    """Create acquisition_manifest.yaml if it does not exist."""
+    p = Path(acquisition_folder) / "acquisition_manifest.yaml"
+    if p.exists():
+        return
+    _write_yaml(
+        p,
+        {
+            "msw_manifest_version": 1,
+            "type": "acquisition",
+            "acquisition_name": acquisition_name,
+            "sessions": [],
+        },
+    )
+
+
+def append_session_to_acquisition(
+    acquisition_folder: str | Path,
+    session_basename: str,
+    started_at: str | None = None,
+) -> None:
+    """Add a session entry (status=running). Call at TaskProcess init."""
+    p = Path(acquisition_folder) / "acquisition_manifest.yaml"
+    data: dict[str, Any] = (
+        _read_yaml(p)
+        if p.exists()
+        else {"msw_manifest_version": 1, "type": "acquisition", "sessions": []}
+    )
+    sessions = data.setdefault("sessions", [])
+    if not any(s.get("basename") == session_basename for s in sessions):
+        sessions.append(
+            {
+                "basename": session_basename,
+                "started_at": started_at or _now_iso(),
+                "ended_at": None,
+                "status": "running",
+            }
+        )
+    _write_yaml(p, data)
+
+
+def finalize_session_in_acquisition(
+    acquisition_folder: str | Path,
+    session_basename: str,
+    status: str = "complete",
+    ended_at: str | None = None,
+) -> None:
+    """Set status and ended_at. Call at TaskProcess exit."""
+    p = Path(acquisition_folder) / "acquisition_manifest.yaml"
+    if not p.exists():
+        return
+    data = _read_yaml(p)
+    for s in data.get("sessions", []):
+        if s.get("basename") == session_basename:
+            s["status"] = status
+            s["ended_at"] = ended_at or _now_iso()
+            break
+    _write_yaml(p, data)
+
+
+# ---------------------------------------------------------------------------
+# Session manifest
+
+
+def init_session_manifest(session_folder: str | Path, session_basename: str) -> None:
+    """Write session_manifest.yaml with empty subprotocols. Call at session start."""
+    p = Path(session_folder) / "session_manifest.yaml"
+    if p.exists():
+        return
+    _write_yaml(
+        p,
+        {
+            "msw_manifest_version": 1,
+            "type": "session",
+            "session_basename": session_basename,
+            "subprotocols": [],
+        },
+    )
+
+
+def append_subprotocol(
+    session_folder: str | Path,
+    name: str,
+    filename: str,
+    barcode_start: int | None = None,
+) -> None:
+    """Add a subprotocol entry (status=running). Call before each opto protocol."""
+    p = Path(session_folder) / "session_manifest.yaml"
+    data: dict[str, Any] = (
+        _read_yaml(p)
+        if p.exists()
+        else {"msw_manifest_version": 1, "type": "session", "subprotocols": []}
+    )
+    protos = data.setdefault("subprotocols", [])
+    if not any(sp.get("name") == name for sp in protos):
+        protos.append(
+            {
+                "name": name,
+                "file": filename,
+                "barcode_start": barcode_start,
+                "barcode_end": None,
+                "status": "running",
+            }
+        )
+    _write_yaml(p, data)
+
+
+def finalize_subprotocol(
+    session_folder: str | Path,
+    name: str,
+    barcode_end: int | None = None,
+    status: str = "complete",
+) -> None:
+    """Set barcode_end and status. Call in finally block after each opto protocol."""
+    p = Path(session_folder) / "session_manifest.yaml"
+    if not p.exists():
+        return
+    data = _read_yaml(p)
+    for sp in data.get("subprotocols", []):
+        if sp.get("name") == name:
+            sp["barcode_end"] = barcode_end
+            sp["status"] = status
+            break
+    _write_yaml(p, data)

murineshiftwork/namespace/msw_files.py

@@ -0,0 +1,57 @@
+"""MSW session file naming: the .msw. artifact namespace.
+
+Session-derived files follow the pattern defined in namespace.msw.yaml:
+    {session_basename}.msw.{artifact}
+
+Use msw_file() for non-task callers; TaskRunner.get_path() for task code
+that already has self available.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def msw_file(session_file_path: str | Path, artifact: str) -> Path:
+    """Return the full Path for a session-derived .msw.{artifact} file.
+
+    Args:
+        session_file_path: Base session path (session_paths["session_file_path"]).
+        artifact: Artifact name suffix (e.g. "session.yaml", "df.jsonl", "log").
+    """
+    from murineshiftwork.namespace.paths import get_msw_builder
+
+    p = Path(session_file_path)
+    b = get_msw_builder()
+    values = b.extract_level_values("session", p.name)
+    values["artifact"] = artifact
+    return p.parent / b.build_path("file", values)
+
+
+def is_msw_file(path: str | Path) -> bool:
+    """Return True if the filename matches the MSW .msw. file pattern."""
+    from murineshiftwork.namespace.paths import get_msw_builder
+
+    try:
+        get_msw_builder().extract_level_values("file", Path(path).name)
+        return True
+    except ValueError:
+        return False
+
+
+def msw_artifact(path: str | Path) -> str:
+    """Extract the artifact suffix from an MSW filename.
+
+    E.g. "subject__dt__task.msw.session.yaml" -> "session.yaml"
+
+    Raises:
+        ValueError: If the path is not an MSW file.
+    """
+    from murineshiftwork.namespace.paths import get_msw_builder
+
+    try:
+        return get_msw_builder().extract_level_values("file", Path(path).name)[
+            "artifact"
+        ]
+    except ValueError:
+        raise ValueError(f"Not an MSW file: {path!r}") from None

murineshiftwork/namespace/namespace.msw.yaml

@@ -0,0 +1,25 @@
+version: "3.0"
+description: "MSW acquisition namespace: subject > session > acquisition > file."
+hierarchy:
+  - subject
+  - session
+  - acquisition
+  - file
+optional_levels: []
+levels:
+  subject:
+    template: "{subject}"
+    regex: "(?P<subject>[\\w\\-]+)"
+    optional_fields: []
+  session:
+    template: "{subject}__{datetime}__{task}"
+    regex: "(?P<subject>[\\w\\-]+)__(?P<datetime>\\d{8}_\\d{6}(?:_\\d{6})?)__(?P<task>[\\w\\-]+)"
+    optional_fields: []
+  acquisition:
+    template: "{subject}__{datetime}__{task}"
+    regex: "(?P<subject>[\\w\\-]+)__(?P<datetime>\\d{8}_\\d{6}(?:_\\d{6})?)__(?P<task>[\\w\\-]+)"
+    optional_fields: []
+  file:
+    template: "{session}.msw.{artifact}"
+    regex: "(?P<session>.+)\\.msw\\.(?P<artifact>.+)"
+    optional_fields: []