Metadata-Version: 2.4
Name: labnirs2snirf
Version: 0.1.1
Summary: Converts exported Shimadzu LabNirs recordings to SNIRF format.
Project-URL: Homepage, https://zeds15b3gcwq.github.io/labnirs2snirf/
Project-URL: Repository, https://github.com/zEdS15B3GCwq/labnirs2snirf
Project-URL: Documentation, https://zeds15b3gcwq.github.io/labnirs2snirf/
Project-URL: Bug Tracker, https://github.com/zEdS15B3GCwq/labnirs2snirf/issues
Author-email: Tamas Fehervari <58502181+zEdS15B3GCwq@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2025 Tamas
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: Labnirs,Shimadzu,convert,nirs,snirf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: h5py>=3.15.1
Requires-Dist: numpy>=2.3.5
Requires-Dist: polars>=1.35.2
Description-Content-Type: text/markdown

# labnirs2snirf

[![ci](https://github.com/zEdS15B3GCwq/labnirs2snirf/actions/workflows/ci.yml/badge.svg)](https://github.com/zEdS15B3GCwq/labnirs2snirf/actions/workflows/ci.yml)
[![CodeQL](https://github.com/zEdS15B3GCwq/labnirs2snirf/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/zEdS15B3GCwq/labnirs2snirf/actions/workflows/github-code-scanning/codeql)
[![Coverage](https://img.shields.io/endpoint?url=https://zEdS15B3GCwq.github.io/labnirs2snirf/badges/coverage.json)](https://zEdS15B3GCwq.github.io/labnirs2snirf/htmlcov/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://zEdS15B3GCwq.github.io/labnirs2snirf/)
[![python support](https://img.shields.io/badge/Python-3.12%20%7C%203.13%20%7C%203.14-blue?logo=python)](https://test.pypi.org/project/labnirs2snirf/)

<!-- INDEX_START -->
This package provides tools to convert fNIRS experimental data exported from
Shimadzu LabNIRS software to the Shared Near Infrared Spectroscopy Format (SNIRF),
enabling compatibility with analysis tools like MNE-Python and other NIRS analysis
software.

## Features

- Convert LabNIRS export files to SNIRF/HDF5 format
- Your data is untouched (no unnecessary Hb -> OD -> raw conversion)
- Support for importing probe positions from layout file
(.sfp format only, for now)
- Command-line interface and API
- Exclude data based on type and wavelength (e.g. only include raw data for
2 wavelengths), to allow 3rd-party tools with specific requirements to read
the file.

## Motivation

Most popular analytical tools (Homer, MNE, etc.) do not support reading LabNirs
data files and LabNirs has no official converter either. The recommended way
for conversion, as far as I know, is to use the `Shimadzu2nirs.m` Matlab script
to convert to .nirs format that Homer can import and save as .snirf.

However, the script takes haemoglobin concentration data and converts it back
to OD and then to intensity, and I would prefer to use untouched raw data
directly without any unnecessary transformation steps. I also just simply
prefer to avoid using Matlab where possible.

This tool aims to simplify the process. Data exported from LabNirs (Hb or voltage
or both) can be converted to .snirf in one step, without unnecessary conversion.

## Current state of the project

The conversion tool is functional, with the following caveats:

1. The expected file format is based on data from one single LabNIRS machine.
Other machines or versions of the LabNIRS software could have a different output
format, which is likely to lead to errors.

2. I only use the recording mode in which task changes are marked by event
triggers. Metadata fields may have a different meaning in other modi of operandi.

3. Analysis tools (e.g. MNE, Homer) sometimes have their own limitations regarding
snirf data format, and while **labnirs2snirf** produces valid .snirf files, those
tools may not be able to read just any valid file. To help with this, it is
possible to limit what is included in the .snirf file (e.g. only 2 wavelengths,
only Hb or voltage data) using the `--type` and `--drop` options.

4. LabNirs stores more metadata (e.g. task duration, pre and post rest periods)
in additional files, that is not exported. In theory, I may implement reading
metadata from those files in the future, but no guarantees. It may be easier
to just add the missing information using other software.

5. For now, probe location data can only be supplied in the .sfp file format.
I may add support for more formats later. It is also possible not to include
layout data (in which case all probes have all-zero coordinates), but that will
not make 3rd party tools happy.

## Quick Start

Once the package is published on PyPI, the installation will be as simple as
`pip install labnirs2snirf`.

For now, you need to download the source files either by cloning this repository
or downloading a .zipped package.

```bash
# 1. clone the files from the repository (or download a .zip)
git clone https://github.com/zEdS15B3GCwq/labnirs2snirf.git

# 2. step into the project folder
cd labnirs2snirf

# 3. create a Python virtual environment
python -m venv .venv

# 4. activate the virtual environment
./.venv/Scripts/activate

# 5. install labnirs2snirf and dependencies
python -m pip install .

# 6. run without parameters or with --help to print out usage instructions
labnirs2snirf
labnirs2snirf --help

# 7. convert labnirs file to .snirf
labnirs2snirf tests/small_labnirs.txt small.snirf
```

<!-- INDEX_END -->
## Documentation

Check the [documentation](https://zEdS15B3GCwq.github.io/labnirs2snirf/)
for further details.
