Metadata-Version: 2.1
Name: aicsimageio
Version: 3.1.1
Summary: Python library for reading and writing image data with special handlers for bio-formats from Allen Institute for Cell Science.
Home-page: https://github.com/AllenCellModeling/aicsimageio
Author: Allen Institute for Cell Science
Author-email: jacksonb@alleninstitute.org, bowdenm@spu.edu
License: BSD-3-Clause
Keywords: aicsimageio,allen cell,imaging,computational biology
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: aicspylibczi (>=2.5.0)
Requires-Dist: dask (>=2.9.0)
Requires-Dist: distributed (>=2.9.3)
Requires-Dist: numpy (>=1.16)
Requires-Dist: imageio (>=2.3.0)
Requires-Dist: lxml (>=4.4.2)
Requires-Dist: tifffile (>=2019.7.26.2)
Requires-Dist: toolz (>=0.10.0)
Provides-Extra: all
Requires-Dist: aicspylibczi (>=2.5.0) ; extra == 'all'
Requires-Dist: dask (>=2.9.0) ; extra == 'all'
Requires-Dist: distributed (>=2.9.3) ; extra == 'all'
Requires-Dist: numpy (>=1.16) ; extra == 'all'
Requires-Dist: imageio (>=2.3.0) ; extra == 'all'
Requires-Dist: lxml (>=4.4.2) ; extra == 'all'
Requires-Dist: tifffile (>=2019.7.26.2) ; extra == 'all'
Requires-Dist: toolz (>=0.10.0) ; extra == 'all'
Requires-Dist: codecov ; extra == 'all'
Requires-Dist: flake8 ; extra == 'all'
Requires-Dist: napari ; extra == 'all'
Requires-Dist: psutil ; extra == 'all'
Requires-Dist: pytest ; extra == 'all'
Requires-Dist: pytest-cov ; extra == 'all'
Requires-Dist: pytest-raises ; extra == 'all'
Requires-Dist: pytest-runner ; extra == 'all'
Requires-Dist: bumpversion (>=0.5.3) ; extra == 'all'
Requires-Dist: coverage (>=5.0a4) ; extra == 'all'
Requires-Dist: flake8 (>=3.7.7) ; extra == 'all'
Requires-Dist: gitchangelog (>=3.0.4) ; extra == 'all'
Requires-Dist: ipython (>=7.5.0) ; extra == 'all'
Requires-Dist: m2r (>=0.2.1) ; extra == 'all'
Requires-Dist: pytest (>=4.3.0) ; extra == 'all'
Requires-Dist: pytest-cov (==2.6.1) ; extra == 'all'
Requires-Dist: pytest-raises (>=0.10) ; extra == 'all'
Requires-Dist: pytest-runner (>=4.4) ; extra == 'all'
Requires-Dist: Sphinx (>=2.0.0b1) ; extra == 'all'
Requires-Dist: sphinx-rtd-theme (>=0.1.2) ; extra == 'all'
Requires-Dist: tox (>=3.5.2) ; extra == 'all'
Requires-Dist: twine (>=1.13.0) ; extra == 'all'
Requires-Dist: wheel (>=0.33.1) ; extra == 'all'
Requires-Dist: altair ; extra == 'all'
Requires-Dist: bokeh ; extra == 'all'
Requires-Dist: jupyterlab ; extra == 'all'
Requires-Dist: matplotlib ; extra == 'all'
Requires-Dist: napari (>=0.2.10) ; extra == 'all'
Requires-Dist: pillow ; extra == 'all'
Provides-Extra: dev
Requires-Dist: bumpversion (>=0.5.3) ; extra == 'dev'
Requires-Dist: coverage (>=5.0a4) ; extra == 'dev'
Requires-Dist: flake8 (>=3.7.7) ; extra == 'dev'
Requires-Dist: gitchangelog (>=3.0.4) ; extra == 'dev'
Requires-Dist: ipython (>=7.5.0) ; extra == 'dev'
Requires-Dist: m2r (>=0.2.1) ; extra == 'dev'
Requires-Dist: pytest (>=4.3.0) ; extra == 'dev'
Requires-Dist: pytest-cov (==2.6.1) ; extra == 'dev'
Requires-Dist: pytest-raises (>=0.10) ; extra == 'dev'
Requires-Dist: pytest-runner (>=4.4) ; extra == 'dev'
Requires-Dist: Sphinx (>=2.0.0b1) ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme (>=0.1.2) ; extra == 'dev'
Requires-Dist: tox (>=3.5.2) ; extra == 'dev'
Requires-Dist: twine (>=1.13.0) ; extra == 'dev'
Requires-Dist: wheel (>=0.33.1) ; extra == 'dev'
Provides-Extra: interactive
Requires-Dist: altair ; extra == 'interactive'
Requires-Dist: bokeh ; extra == 'interactive'
Requires-Dist: jupyterlab ; extra == 'interactive'
Requires-Dist: matplotlib ; extra == 'interactive'
Requires-Dist: napari (>=0.2.10) ; extra == 'interactive'
Requires-Dist: pillow ; extra == 'interactive'
Provides-Extra: setup
Requires-Dist: pytest-runner ; extra == 'setup'
Provides-Extra: test
Requires-Dist: codecov ; extra == 'test'
Requires-Dist: flake8 ; extra == 'test'
Requires-Dist: napari ; extra == 'test'
Requires-Dist: psutil ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest-raises ; extra == 'test'

# AICSImageIO

[![Build Status](https://github.com/AllenCellModeling/aicsimageio/workflows/Build%20Master/badge.svg)](https://github.com/AllenCellModeling/aicsimageio/actions)
[![Documentation](https://github.com/AllenCellModeling/aicsimageio/workflows/Documentation/badge.svg)](https://allencellmodeling.github.io/aicsimageio)
[![Code Coverage](https://codecov.io/gh/AllenCellModeling/aicsimageio/branch/master/graph/badge.svg)](https://codecov.io/gh/AllenCellModeling/aicsimageio)

A Python library for reading and writing image data with specific support for handling bio-formats.

---

## Features
* Supports reading metadata and imaging data for:
    * `CZI`
    * `OME-TIFF`
    * `TIFF`
    * Any additional format supported by [`imageio`](https://github.com/imageio/imageio)
* Supports writing metadata and imaging data for:
    * `OME-TIFF`

## Installation
**Stable Release:** `pip install aicsimageio`<br>
**Development Head:** `pip install git+https://github.com/AllenCellModeling/aicsimageio.git`

## Documentation
For full package documentation please visit
[allencellmodeling.github.io/aicsimageio](https://allencellmodeling.github.io/aicsimageio/index.html).

## Quick Start

### Full Image Reading
```python
from aicsimageio import AICSImage, imread

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.data  # returns 6D STCZYX numpy array
img.dims  # returns string "STCZYX"
img.shape  # returns tuple of dimension sizes in STCZYX order
img.size("STC")  # returns tuple of dimensions sizes for just STC
img.get_image_data("CZYX", S=0, T=0)  # returns 4D CZYX numpy array

# Get 6D STCZYX numpy array
data = imread("my_file.tiff")
```

### Delayed Image Slice Reading
```python
from aicsimageio import AICSImage, imread_dask

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.dask_data  # returns 6D STCZYX dask array
img.dims  # returns string "STCZYX"
img.shape  # returns tuple of dimension sizes in STCZYX order
img.size("STC")  # returns tuple of dimensions sizes for just STC
img.get_image_dask_data("CZYX", S=0, T=0)  # returns 4D CZYX dask array

# Read specified portion of dask array
lazy_s0t0 = img.get_image_dask_data("CZYX", S=0, T=0)  # returns 4D CZYX dask array
s0t0 = lazy_s0t0.compute()  # returns 4D CZYX numpy array

# Or use normal numpy array slicing
lazy_data = imread_dask("my_file.tiff")
lazy_s0t0 = lazy_data[0, 0, :]
s0t0 = lazy_s0t0.compute()
```

When using the `dask_data` array, it is important to know when to `compute` or `persist` data and when to keep
chaining computation. [Here is a good rundown on the trade offs.](https://stackoverflow.com/questions/41806850/dask-difference-between-client-persist-and-client-compute#answer-41807160)


### Speed up IO and Processing with Dask Clients and Clusters
```python
from aicsimageio import AICSImage, dask_utils

# Create a local dask cluster and client for the duration of the context manager
with AICSImage("filename.ome.tiff") as img:
    # do your work like normal
    print(img.dask_data.shape)

# Specify arguments for the local cluster initialization
with AICSImage("filename.ome.tiff", dask_kwargs={"nworkers": 4}) as img:
    # do your work like normal
    print(img.dask_data.shape)

# Connect to a dask client for the duration of the context manager
with AICSImage("filename.ome.tiff", dask_kwargs={"address": "tcp://localhost:12345"}) as img:
    # do your work like normal
    print(img.dask_data.shape)

# Or spawn a local cluster and / or connect to a client outside of a context manager
# This uses the same "address" and dask kwargs as above
# If you pass an address in, it will create and shutdown the client and no cluster will be created.
# Similar to AICSImage, these objects will be connected and useable for the lifespan of the context manager.
with dask_utils.cluster_and_client() as (cluster, client):

    img1 = AICSImage("1.tiff")
    img2 = AICSImage("2.tiff")
    img3 = AICSImage("3.tiff")

    # Do your image processing work
```

### Metadata Reading
```python
from aicsimageio import AICSImage

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.metadata  # returns the metadata object for this image type
img.get_channel_names()  # returns a list of string channel names if found in the metadata
```

### Napari Interactive Viewer
[napari](https://github.com/Napari/napari) is a fast, interactive, multi-dimensional image viewer for python and
it is pretty useful for imaging data that this package tends to interact with.
```python
from aicsimageio import AICSImage

# Get an AICSImage object
img = AICSImage("my_file.tiff")
img.view_napari()  # launches napari GUI and viewer
```

## Notes
* Image `data` and `dask_data` are always returned as six dimensional in dimension order `STCZYX`
or `Scene`, `Time`, `Channel`, `Z`, `Y`, and `X`.
* Each file format may use a different metadata parser it is dependent on the reader's implementation.
* The `AICSImage` object will only pull the `Scene`, `Time`, `Channel`, `Z`, `Y`, `X` dimensions from the reader.
If your file has dimensions outside of those, use the base reader classes `CziReader`, `OmeTiffReader`, `TiffReader`,
or `DefaultReader`.
* We make some choices for the user based off the image data during `img.view_napari`.
If you don't want this behavior, simply pass the `img.dask_data` into `napari.view_image` instead.

## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code.

***Free software: BSD-3-Clause***


