/pyparty

Drawing and analyzing particles on images

Primary LanguageHTMLOtherNOASSERTION

alternate text

pyparty: Python (py) particles (party)

pyparty is a small library for drawing, labeling, patterning and manipulating particles in 2d images. pyparty was built atop the excellent image processing library, scikit-image.

What's New

Check out this study on sickle cells using pyparty and skimage from Clay Mortin.

pyparty is now published.

Check out Object Hunter, a pyparty script for identifying, summarizing and plotting groups of objects in an image.

Getting Started

Videos

Check out Zhaowen Liu's great screencast on using Ilastik to segregate AuNP types on SEM images.

The current documentation is a series of example notebooks (IPython Notebook), which cover most of the basics. These have been linked below:

Notebooks were initialized with pylab:

ipython notebook --pylab=inline

Having trouble viewing/editing notebooks? Consider using Enthought Canopy, which has a notebook kernel builtin, as well as a graphical package manager. For simple viewing, paste the github url of each notebook into the IPython Notebook viewer.

These notebooks are free for redistribution. If referencing in publication, please cite as:

Support

For help, please write to our group, pyparty@googlegroups.com

Have a feature request, or want to report a bug? Please fill out a github issue with the appropriate label.

License

3-Clause Revised BSD_

Overview and Features

pyparty provides a simple API for particle analysis in 2d images, while streamlining common operations in the image processing pipeline.

Some key features include:

  1. Pythonic ParticleManager for storing and manipulating particles from image labels OR builtin shapes. Some highlights of Particles include:

    • A common datastructure for array operations like rotations and translations.
    • skimage descriptors as primary attributes on all particles.
    • Filtering and mapping based with numpy logical indexing syntax.

  2. A Grid system for patterning particles, as well as mesh utilities for creating image backgrounds.

  3. A Canvas to easily integrate Grids, Particles and flexible Backgrounds. In addition, Canvas also provides simplified interfaces for:

    • binarization / thresholding
    • plotting
    • slicing and other pythonic container operations
  4. A plotting API based on matplotlib.imshow() that generally supports

    rasterizaztions AND matplotlib patches.

  5. Flexible color designations ('red', (1,0,0), 00FF00), and strict typing to ensure consistency in data and plots.

  6. General ndarray operations such as rotations and translations supported by ALL particle types.

  7. API for adding Noise to images.

What are some use cases, and will pyparty help to me?

Tasks well-suited for pyparty include:

1. Filtering and characterization of cells based on descriptors like eccentricit and area.

  1. Patterning a grid of particles over a shadowed background to compare performance of thresholding algorithms.
  2. Manipulating particles in a pythonic manner:
    • delete all particles that have area > 50 pixels.
    • sort and color ellipses in order of increasing eccentricity.
    • dilate all particles appearing in bottom half of an image
  3. Scripting without leaving Python.
  4. Plot particles as rasterizations or matplotlib patches side-by-side.

In short, you may consider using pyparty if you are doing image analysis and find generating, managing or labeling particles as a bottleneck.

License

3-Clause Revised BSD_

Dependencies

pyparty requires scikit-image, Traits and their dependencies, which include many core packages such as numpy and matplotlib. If you are new to Python for scientific computing, consider downloading a packaged distribution.

pyparty uses Traits because it is well-suited for writing clean, type-checked object-oriented classes. You will not need to understand or use Traits unless you develop for pyparty; it is not used in the public API, and may be removed in future installments after the core functionality is stable.

Installation

I would recommend using Enthought Canopy and installing Traits and scikit-image through the package manager; however, pyparty is also registered on PyPi.

Pip Install

Make sure you have pip installed:

sudo apt-get install python-pip

Then:

pip install pyparty

To install all of the dependencies (scikit-image, traits and their various dependencies), download pyparty from github, navigate to the base directory and type:

pip install -r requirements.txt
Installation from source

In the pyparty base directory run:

python setup.py install

The developmental version can be cloned from github:

git clone https://github.com/hugadams/pyparty.git

This will not install any dependencies.

Testing

To quickly test your installation, open python and type:

from pyparty import *

If this results in no errors, the installation probably went smoothly.

While a proper nosetests platform is still under development, there is a quasi-regression test suite in pyparty/testing/REGRESSION.ipynb. This will run all of the available pyparty ipython notebooks located in pyparty/examples/Notebooks, and capture the output. If any of the operations in these notebooks raises an error, it will be reported back to the REGRESSION notebook. This requires ipython 3.0.0 to run!

A static version of the test suite may be viewed here.

Archive

pyparty is archived on Zenodo (DOI 10.5281/zenodo.11194)

http://dx.doi.org/10.5281/zenodo.11194

Related Libraries

Interested in the Python ecosystem? Check out some of these related libraries:

  • NumPy (Fundamental vectorized numerics in Python)
  • SciPy (Collection of core, numpy-based scientific libraries)
  • scikit-image (Scipy image processing suite)
  • matplotlib (De facto static plotting in Python)
  • pandas (Data analysis library : inspired pyparty ParticleManager API)
  • ilastik (Interactive Learning and Segmentation Tool)
  • Pillow (Python Image Library)

Coming Soon

  • More multi-particle types.
  • Better control of color shading of labels.
  • More examples.

Have a feature request, or want to report a bug? Please fill out a github issue with the appropriate label.

History

pyparty originally began at the George Washington University (2013) in an effort to generate test data for SEM and AFM images of gold nanoparticles on glass substrates. We really enjoyed scikit-image for image processing and sought to implement it in generating test data. We sought to provide an API for managing labeled particles from real images. Scikit-image draw and measure modules laid the groundwork to the core functionality that pyparty attempts to streamline.

I should also note that some of the inspiration came from the excellent Analyze Particles features in ImageJ.

About the Author

I'm a PhD student at GWU (check me out on researchgate, Linkedin or twitter) and former Enthought intern. I work in biomolecule sensing and plasmonics.

Acknowledgements

Thank you scikit-image team for their patience and assistance with us on the mailing list, and for putting together a great library for the community.

Thank you countless developers who have patiently answered hundreds of my questions on too many mailing lists and sites to list.

Thank you Zhaowen Liu for all of your help with this project, our other projects and for your unwaivering encouragement (and for the panda).