Metadata-Version: 2.4
Name: labnirs2snirf
Version: 0.1.3
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://pypi.org/project/labnirs2snirf/)
[![PyPI version](https://img.shields.io/pypi/v/labnirs2snirf.svg)](https://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

```bash
# 1. install labnirs2snirf from PyPI
pip install labnirs2snirf

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

# 3. convert labnirs file to .snirf
# You can use one of the data files on the project repository for testing, e.g.
# https://raw.githubusercontent.com/zEdS15B3GCwq/labnirs2snirf/refs/heads/main/data/test/small_labnirs.txt
labnirs2snirf small_labnirs.txt small.snirf
```

<!-- INDEX_END -->

## Documentation

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