Metadata-Version: 2.5
Name: msw-open-ephys
Version: 3.5.1
Summary: Remote control for Open Ephys GUI v1+ — session naming and recording management
Project-URL: Homepage, https://github.com/murineshiftwork/msw-open-ephys
Project-URL: Issue Tracker, https://github.com/murineshiftwork/msw-open-ephys/issues
Author-email: "Lars B. Rollik" <lars@rollik.me>
License: BSD-3-Clause-NonCommercial
        
        Copyright (c) 2020-present, Lars B. Rollik.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted for NON-COMMERCIAL research, academic, and
        educational purposes only, provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software
           without specific prior written permission.
        
        4. Any use of this software or its derivatives for COMMERCIAL purposes -
           including sale, paid licensing, or providing paid services built on it -
           requires a separate commercial licence. Contact lars@rollik.me.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: electrophysiology,neuroscience,open-ephys,recording,remote-control
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: msw-io>=1.14.1
Requires-Dist: msw-plugin-api>=0.3.0
Requires-Dist: requests
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: commitizen; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.8; extra == 'docs'
Description-Content-Type: text/markdown

# msw-open-ephys

Remote control for [Open Ephys GUI](https://open-ephys.org/gui) v1+ — session naming, recording management, and metadata writing for MSW acquisition workflows.

## Install

```bash
pip install msw-open-ephys
```

Or editable from the repo:

```bash
pip install -e external/msw-open-ephys
```

## CLI

```
oe-remote status   --remote-ip 10.0.10.111
oe-remote preview  --remote-ip 10.0.10.111
oe-remote record   --remote-ip 10.0.10.111 --subject m1099 \
                   --acquisition-extension ephys_multi_behavior \
                   --session-extension pxi
oe-remote record   --remote-ip 10.0.10.111 --subject m1099 \
                   --session-extension intan_ttl --child @last
oe-remote stop     --remote-ip 10.0.10.111
```

### Session modes

| Mode | When | OE records to |
|---|---|---|
| Standalone | no `--acquisition-extension`, no `--child` | `remote/{subject}/{subject__dt__session}/` |
| Parent | `--acquisition-extension` set | `remote/{subject}/{subject__dt__acq}/{subject__dt__session}/` |
| Child | `--child ACQ_PATH` or `--child @last` | `remote/{acq_path}/{subject__dt__session}/` |

`--child @last` reuses the acquisition path cached by the most recent parent or record command.

## Python API

```python
from msw_open_ephys.controller import OEController
from msw_open_ephys.session import Session

oe = OEController(ip="10.0.10.111")
oe.preview()
oe.configure_recording(parent_directory=r"E:\OE_DATA", base_text="m1099/acq/session")
oe.record()
```

## Integration with MSW

`msw run --parent openephys` calls the OE REST API directly via `murineshiftwork.hardware.parent_session` (uses `open-ephys-python-tools`, not this package). This package provides the **`oe-remote` CLI** used to start the acquisition side before launching MSW tasks.

Set `open_ephys_url` in the setup YAML so MSW can attach automatically:

```yaml
# msw_configs/setups/setup-npxb.yaml
open_ephys_url: 10.0.10.111
```
