Metadata-Version: 2.3
Name: nima_io
Version: 0.3.7
Summary: A project to read microscopy files.
Project-URL: Bug Tracker, https://github.com/darosio/nima_io/issues
Project-URL: Changelog, https://github.com/darosio/nima_io/blob/main/CHANGELOG.md
Project-URL: Documentation, https://nima-io.readthedocs.io
Project-URL: Github releases, https://github.com/darosio/nima_io/releases
Project-URL: Homepage, https://github.com/darosio/nima_io
Author-email: Daniele Arosio <darosio@duck.com>
License: Copyright (c) 2023, Daniele Arosio
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * 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.
        
        * Neither the name of NImA-io nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        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.txt
Keywords: Bioimage,Image Analysis,Metadata,Open Microscopy,Tiled Images
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Unix Shell
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.13,>=3.10
Requires-Dist: aicsimageio<=4.14.0
Requires-Dist: bfio<=2.3.6
Requires-Dist: bioio-bioformats<=1.0.0
Requires-Dist: click<=8.1.7
Requires-Dist: dask-image<=2023.8.1
Requires-Dist: jpype1<=1.5.0
Requires-Dist: lxml<=5.2.1
Requires-Dist: numpy<=1.26.4
Requires-Dist: pims<=0.6.1
Requires-Dist: pyometiff<=1.0.0
Requires-Dist: readlif<=0.6.5
Requires-Dist: scyjava<=1.9.1
Requires-Dist: setuptools
Provides-Extra: dev
Requires-Dist: commitizen<=3.21.3; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: jupyter; extra == 'dev'
Requires-Dist: matplotlib<=3.8.4; extra == 'dev'
Requires-Dist: pre-commit<=3.7.0; extra == 'dev'
Requires-Dist: pylsp-mypy; extra == 'dev'
Requires-Dist: ruff-lsp; extra == 'dev'
Requires-Dist: ruff<=0.3.5; extra == 'dev'
Requires-Dist: scikit-image<=0.22.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: autodocsumm<=0.2.12; extra == 'docs'
Requires-Dist: nbsphinx<=0.9.3; extra == 'docs'
Requires-Dist: pydata-sphinx-theme<=0.15.2; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints<=2.0.0; extra == 'docs'
Requires-Dist: sphinx-click<=5.1.0; extra == 'docs'
Requires-Dist: sphinx<=7.2.6; extra == 'docs'
Requires-Dist: sphinxcontrib-plantuml<=0.29; extra == 'docs'
Requires-Dist: xmltodict; extra == 'docs'
Provides-Extra: tests
Requires-Dist: coverage[toml]<=7.4.4; extra == 'tests'
Requires-Dist: mypy<=1.9.0; extra == 'tests'
Requires-Dist: pygments<=2.17.2; extra == 'tests'
Requires-Dist: pytest<=8.1.1; extra == 'tests'
Requires-Dist: types-click<=7.1.8; extra == 'tests'
Requires-Dist: xdoctest<=1.1.3; extra == 'tests'
Description-Content-Type: text/markdown

# NImA-io

[![PyPI](https://img.shields.io/pypi/v/nima_io.svg)](https://pypi.org/project/nima_io/)
[![CI](https://github.com/darosio/nima_io/actions/workflows/ci.yml/badge.svg)](https://github.com/darosio/nima_io/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/darosio/nima_io/branch/main/graph/badge.svg?token=OU6F9VFUQ6)](https://codecov.io/gh/darosio/nima_io)
[![RtD](https://readthedocs.org/projects/nima_io/badge/?version=latest)](https://nima-io.readthedocs.io/en/latest/?badge=latest)

<!-- [![RtD](https://readthedocs.org/projects/nima_io/badge/)](https://nima_io.readthedocs.io/) -->

This is a helper library designed for reading microscopy data supported by
[Bioformats](https://www.openmicroscopy.org/bio-formats/) using Python. The
package also includes a command-line interface for assessing differences between
images.

- Version: "0.3.7"

## Installation

You can get the library directly from [PyPI](https://pypi.org/project/nima_io/)
using `pip`:

    pip install nima_io

Alternatively, you can use [pipx](https://pypa.github.io/pipx/) to install it in
an isolated environment:

    pipx install nima_io

To enable auto completion for the `cli` command, follow these steps:

1.  Generate the completion script by running the following command:

        _IMGDIFF_COMPLETE=bash_source imgdiff > ~/.local/bin/imgdiff-complete.bash

2.  Source the generated completion script to enable auto completion:

        source ~/.local/bin/imgdiff-complete.bash

## Usage

You can check out the documentation on <https://darosio.github.io/nima_io> for
up to date usage information and examples.

### CLI

ii provides several command line interface tools for …

    imgdiff --help

### Python

ii can be imported and used as a Python package. The following modules are
available:

    nima_io.read - TODO DESCRIBE

To use nima_io in your python:

    from nima_io import read

## Features / Description

Despite the comprehensive python-bioformats package, Bioformats reading in
Python is not flawless. To assess correct reading and performance, I gathered a
set of test input files from real working data and established various
approaches for reading them:

1. Utilizing the external "showinf" and parsing the generated XML metadata.
2. Employing out-of-the-box python-bioformats.
3. Leveraging bioformats through the Java API.
4. Combining python-bioformats with Java for metadata (Download link: bio-formats 5.9.2).

At present, Solution No. 4 appears to be the most effective.

It's important to note that FEI files are not 100% OME compliant, and
understanding OME metadata can be challenging. For instance, metadata.getXXX is
sometimes equivalent to
metadata.getRoot().getImage(i).getPixels().getPlane(index).

The use of parametrized tests enhances clarity and consistency. The approach of
returning a wrapper to a Bioformats reader enables memory-mapped (a la memmap)
operations.

Notebooks are included in the documentation tutorials to aid development and
illustrate usage. Although there was an initial exploration of the TileStitch
Java class, the decision was made to implement TileStitcher in Python.

Future improvements can be implemented in the code, particularly for the
multichannel OME standard example, which currently lacks obj or resolutionX
metadata. Additionally, support for various instrument, experiment, or plate
metadata can be considered in future updates.

## License

We use a shared copyright model that enables all contributors to maintain the
copyright on their contributions.

All code is licensed under the terms of the [revised BSD license](LICENSE.txt).

## Contributing

If you are interested in contributing to the project, please read our
[contributing](https://darosio.github.io/nima_io/references/contributing.html)
and
[development environment](https://darosio.github.io/nima_io/references/development.html)
guides, which outline the guidelines and conventions that we follow for
contributing code, documentation, and other resources.

### Development

To begin development, follow these steps:

Create an .envrc file with the command:

    echo "layout hatch" > .envrc
    direnv allow

Update and initialize submodules:

    git submodule update --init --recursive

Navigate to the tests/data/ directory:

    cd tests/data/
    git co master

Configure Git Annex for SSH caching:

    git config annex.sshcaching true

Pull the necessary files using Git Annex:

    git annex pull

These commands set up the development environment and fetch the required data for testing.

Modify tests/data.filenames.txt and tests/data.filenames.md5 as needed and run:

    cd tests
    ./data.filenames.sh

### Note

This project was initialized using the [Cookiecutter Python
template](https://github.com/darosio/cookiecutter-python).
