Metadata-Version: 2.4
Name: msw-io
Version: 1.12.0
Summary: Murine Shift Work session data IO: file codec, namespace utilities, and session readers.
Author-email: "Lars B. Rollik" <lars@rollik.me>
License: Copyright (c) 2020-present Lars B. Rollik. All rights reserved.
        
        Permission is granted, free of charge, to use, copy, modify, and distribute
        this software and associated documentation files (the "Software") for
        non-commercial research or academic purposes only, subject to the following
        conditions:
        
        1. This copyright notice and permission notice must be included in all copies
           or substantial portions of the Software.
        
        2. Any publication, presentation, or product that uses or builds upon the
           Software must give clear attribution to the original work and its authors.
        
        3. Commercial use is prohibited without a separate written commercial licence
           agreement with the copyright holder. Commercial use means incorporation of
           the Software into anything for which fees or other compensation are charged
           or received, including commercial products and commercial services.
        
        4. No patent licence, express or implied, is granted under these terms. Any
           use that would require a patent licence from the copyright holder requires
           a separate written agreement.
        
        5. Redistribution, in source or binary form, is permitted only for
           non-commercial purposes and must retain this notice unmodified.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
        DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
        SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
        
        For commercial or patent licensing enquiries contact: lars@rollik.me
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: acquisition-namespace>=1.3.1
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml
Requires-Dist: ttl-barcoder>=0.4.2
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>
