Metadata-Version: 2.1
Name: aicscytoparam
Version: 0.1.2
Summary: Cytoplasm parameterization using spherical harmonics
Home-page: https://github.com/AllenCell/aics-cytoparam
Author: Matheus Viana
Author-email: matheus.viana@alleninstitute.org
License: Allen Institute Software License
Keywords: aicscytoparam
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Free for non-commercial use
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: aicsshparam (>=0.0.14)
Requires-Dist: tqdm
Requires-Dist: numpy
Requires-Dist: vtk (>=9.0.0)
Requires-Dist: aicsimageio (<4.0.0,>=3.0.0)
Requires-Dist: scipy
Requires-Dist: scikit-image (>=0.15.0)
Provides-Extra: all
Requires-Dist: aicsshparam (>=0.0.14) ; extra == 'all'
Requires-Dist: tqdm ; extra == 'all'
Requires-Dist: numpy ; extra == 'all'
Requires-Dist: vtk (>=9.0.0) ; extra == 'all'
Requires-Dist: aicsimageio (<4.0.0,>=3.0.0) ; extra == 'all'
Requires-Dist: scipy ; extra == 'all'
Requires-Dist: scikit-image (>=0.15.0) ; extra == 'all'
Requires-Dist: pytest-runner (>=5.2) ; extra == 'all'
Requires-Dist: black (>=19.10b0) ; extra == 'all'
Requires-Dist: codecov (>=2.1.4) ; extra == 'all'
Requires-Dist: flake8 (>=3.8.3) ; extra == 'all'
Requires-Dist: flake8-debugger (>=3.2.1) ; extra == 'all'
Requires-Dist: pytest (>=5.4.3) ; extra == 'all'
Requires-Dist: pytest-cov (>=2.9.0) ; extra == 'all'
Requires-Dist: pytest-raises (>=0.11) ; extra == 'all'
Requires-Dist: bump2version (>=1.0.1) ; extra == 'all'
Requires-Dist: coverage (>=5.1) ; extra == 'all'
Requires-Dist: ipython (>=7.15.0) ; extra == 'all'
Requires-Dist: m2r2 (>=0.2.7) ; extra == 'all'
Requires-Dist: Sphinx (>=3.4.3) ; extra == 'all'
Requires-Dist: sphinx-rtd-theme (>=0.5.1) ; extra == 'all'
Requires-Dist: tox (>=3.15.2) ; extra == 'all'
Requires-Dist: twine (>=3.1.1) ; extra == 'all'
Requires-Dist: wheel (>=0.34.2) ; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-runner (>=5.2) ; extra == 'dev'
Requires-Dist: black (>=19.10b0) ; extra == 'dev'
Requires-Dist: codecov (>=2.1.4) ; extra == 'dev'
Requires-Dist: flake8 (>=3.8.3) ; extra == 'dev'
Requires-Dist: flake8-debugger (>=3.2.1) ; extra == 'dev'
Requires-Dist: pytest (>=5.4.3) ; extra == 'dev'
Requires-Dist: pytest-cov (>=2.9.0) ; extra == 'dev'
Requires-Dist: pytest-raises (>=0.11) ; extra == 'dev'
Requires-Dist: bump2version (>=1.0.1) ; extra == 'dev'
Requires-Dist: coverage (>=5.1) ; extra == 'dev'
Requires-Dist: ipython (>=7.15.0) ; extra == 'dev'
Requires-Dist: m2r2 (>=0.2.7) ; extra == 'dev'
Requires-Dist: Sphinx (>=3.4.3) ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme (>=0.5.1) ; extra == 'dev'
Requires-Dist: tox (>=3.15.2) ; extra == 'dev'
Requires-Dist: twine (>=3.1.1) ; extra == 'dev'
Requires-Dist: wheel (>=0.34.2) ; extra == 'dev'
Provides-Extra: setup
Requires-Dist: pytest-runner (>=5.2) ; extra == 'setup'
Provides-Extra: test
Requires-Dist: black (>=19.10b0) ; extra == 'test'
Requires-Dist: codecov (>=2.1.4) ; extra == 'test'
Requires-Dist: flake8 (>=3.8.3) ; extra == 'test'
Requires-Dist: flake8-debugger (>=3.2.1) ; extra == 'test'
Requires-Dist: pytest (>=5.4.3) ; extra == 'test'
Requires-Dist: pytest-cov (>=2.9.0) ; extra == 'test'
Requires-Dist: pytest-raises (>=0.11) ; extra == 'test'

# 3D Cell Parameterization

[![Build Status](https://github.com/AllenCell/aics-cytoparam/workflows/Build%20Main/badge.svg)](https://github.com/AllenCell/aics-cytoparam/actions)
[![Documentation](https://github.com/AllenCell/aics-cytoparam/workflows/Documentation/badge.svg)](https://AllenCell.github.io/aics-cytoparam/)
[![Code Coverage](https://codecov.io/gh/AllenCell/aics-cytoparam/branch/main/graph/badge.svg)](https://codecov.io/gh/AllenCell/aics-cytoparam)

### Spherical harmonics coefficients-based parameterization of the cytoplasm and nucleoplasm for 3D cells

![Cuboid cell](docs/logo.jpg)

---
## Installation

**Stable Release:** `pip install aicscytoparam`<br>
**Development Head:** `pip install git+https://github.com/AllenCell/aics-cytoparam.git`

## How to use

Here we outline an example of how to use `aicscytoparam` to create a parameterization of a 3D cell. In this case, the 3D cells will be represented by a cell segementation, nuclear segmentation and a fluorescent protein (FP) image representing the fluorescent signal of a tagged protein.

```python
# Import required packages
import numpy as np
import matplotlib.pyplot as plt
from aicscytoparam import cytoparam
from skimage import morphology as skmorpho
```

```python
# First create a cuboid cell with an off-center cuboid nucleus
# and get the spherical harmonics coefficients of this cell and nucleus:
w = 100
mem = np.zeros((w, w, w), dtype = np.uint8)
mem[20:80, 20:80, 20:80] = 1
nuc = np.zeros((w, w, w), dtype = np.uint8)
nuc[40:60, 40:60, 30:50] = 1

# Create an FP signal located in the top half of the cell and outside the
# nucleus:
gfp = np.random.rand(w**3).reshape(w,w,w)
gfp[mem==0] = 0
gfp[:, w//2:] = 0
gfp[nuc>0] = 0

# Vizualize a center xy cross-section of our cell:
plt.imshow((mem + nuc)[w//2], cmap='gray')
plt.imshow(gfp[w // 2], cmap='gray', alpha=0.25)
plt.axis('off')
```

![Cuboid cell](docs/im1.jpg)

```python
# Use aicsshparam to expand both cell and nuclear shapes in terms of spherical
# harmonics:
coords, coeffs_centroid = cytoparam.parameterize_image_coordinates(
    seg_mem=mem,
    seg_nuc=nuc,
    lmax=16, # Degree of the spherical harmonics expansion
    nisos=[32, 32] # Number of interpolation layers
)
coeffs_mem, centroid_mem, coeffs_nuc, centroid_nuc = coeffs_centroid

# Run the cellular mapping to create a parameterized intensity representation
# for the FP image:
gfp_representation = cytoparam.cellular_mapping(
    coeffs_mem=coeffs_mem,
    centroid_mem=centroid_mem,
    coeffs_nuc=coeffs_nuc,
    centroid_nuc=centroid_nuc,
    nisos=[32, 32],
    images_to_probe=[('gfp', gfp)]
).data.squeeze()

# The FP image is now encoded into a representation of its shape:
print(gfp_representation.shape)
```

`(65, 8194)`

```python
# Now we want to morph the FP image into a round cell.
# First we create the round cell:

from skimage import morphology as skmorpho
mem_round = skmorpho.ball(w // 3) # radius of our round cell
nuc_round = skmorpho.ball( w// 3) # radius of our round nucleus
# Erode the nucleus so it becomes smaller than the cell
nuc_round = skmorpho.binary_erosion(
    nuc_round, selem=np.ones((20, 20, 20))
    ).astype(np.uint8)

# Vizualize a center xy cross-section of our round cell:
plt.imshow((mem_round + nuc_round)[w // 3], cmap='gray')
plt.axis('off')
```

![Cuboid cell](docs/im2.jpg)

```python
# Next we need to parameterize the coordinates of our round
# cell:
coords_round, _ = cytoparam.parameterize_image_coordinates(
    seg_mem=mem_round,
    seg_nuc=nuc_round,
    lmax=16,
    nisos=[32, 32]
)

# Now we are ready to morph the FP image into our round cell:
gfp_morphed = cytoparam.morph_representation_on_shape(
    img=mem_round + nuc_round,
    param_img_coords=coords_round,
    representation=gfp_representation
)
# Visualize the morphed FP image:
plt.imshow((mem_round + nuc_round)[w // 3], cmap='gray')
plt.imshow(gfp_morphed[w // 3], cmap='gray', alpha=0.25)
plt.axis('off')
```

![Cuboid cell](docs/im3.jpg)

## Reference

For an example of how this package was used to analyse a dataset of over 200k single-cell images at the Allen Institute for Cell Science, please check out our paper in [bioaRxiv](https://www.biorxiv.org/content/10.1101/2020.12.08.415562v1).

## Development

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

## Questions?

If you have any questions, feel free to leave a comment in our Allen Cell forum: [https://forum.allencell.org/](https://forum.allencell.org/). 


***Free software: Allen Institute Software License***


