yamanmy/partycool

particle size analysis software for all microscopy images

Partycool

Particle Size Analysis Package for Scanning Electron Microscopy Images

Partycool is a package used to analyze nanoparticles size in details directly from electron microscopy images!

To use it just import the partycool package and upload your SEM image and you will get a partycool summary and interactive plots showing the size feautures of your particles.

This is a very handy tools for scientists working with nanoparticles in different field of chemistry , physiscs and biology. Knowing the precise size and size distribution of the sample is crucial for nanomaterials application in optoelectroics, clean energy, biomedicine and much more.

Lets walk together through the step that will bring from your electron microscopy image to the size analysis of your particles.

Contributers: Muammer Yaman, Ximin Hu, Margherita Taddei, Yangwei Shi

Release date: 2020-03-16

Organization of the project

The project has the following structure:

partycool/
  |- README.md
  |- partycool/
     |- __init__.py
     |- partycool.py
     |- tests/
        |- __init__.py
        |- test_partycool.py
        |- partycool.py           
     |- trial/  
        |- *.ipynb
  |- doc/
     |- technology_review.pdf
     |- partycool.docx
     |- Presentation.pptx
  |- example_images/
     |- README.md
     |- watershed_trail/
     |- cut_images/ 
        |- zoom/         
     |- train/
        |- darkfield/
        |- optic/
        |- sem/
        |- afm/
  |- example/
     |- user_case.ipynb
     |- infonanoparticle.html
  |- .travis.yml
  |- environment.yml
  |- LICENSE
  |- setup.py
  |- requirements.txt

The module code is inside partycool/partycool.py and contains all the functions necessary to pass from your input image to the size analysis output. Information about the functions are shown below.

Module code

We place the module code in a file called partycool.py in the directory called partycool. The module code can be implemented by typing in your jupyter notebook import partycool. All the library used to create the functions inside partycool.py are listed in __init__.py. In the module code all functions are defined in lines that precede the lines that use that function. This helps readability of the code, because you know that if you see some name, the definition of that name will appear earlier in the file, either as a function/variable definition, or as an import from some other module or package. The boundary_detection function is used to to distinguish the scale bar background with particle backgroundand uses the OpenCV threshold operatio to distinguish the scale bar background with particle background in the SEM image. The corner_detection function is used to find the length of each pixel in nm. It uses the dilated_image function to find the brighter feautures corrisponding to the particle via the gaussian filter of OpenCV. The image is then treated with the img_pread function that gives out the dilated and boundary cutted image.

Then, the contour_capture function captures the contours from the given imgage and gives the average perimeters of the particles through peri_avg function. The shape_radar function unify the result from contour_capture to the filtered image and gives as an output the image showing the size distribution of the particles. Monomers are shown in white, dimers in red and polymers in green.

The partycool_summary gives as output the final dataframe containing all the size analysis of the particles in the input image. The partycool_plots gives the size analysis information in form of interactive plots using histograms and pie plot from Plotly.

At the end, we define the watershed function that will be used to distinguish close nanoparticles into monomers, dimers or polymers

Preview of app

• Categories of nanoparticles

• Statistics distribution

Major dependencies

• Python >= 3.6
  • OpenCV
  • Skimage
  • Plotly

How to install & import

pip install partycool

from partycool import *

Project Data

The data used to the develop the code are SEM images of gold nanoparticles on protein substrate taken from the Ginger Lab at the University of Washington. In the example_images repository we provide a good collection of SEM, TEM, AFM, opticaland dark field images that can be used by the user.

Testing

All the function in the partycool code were tested using nosetests. The testing files are found the tests repository and each function is tested with the test_partycool.py using assert statements.

.......
----------------------------------------------------------------------
Ran 7 tests in 64.733s

OK

Continuous integration

Travis CI is deployed for continuous integration, code style checked through flake8

Licensing

Our code is open to public utilization but to protect it we used the MIT license. You can read the conditions of the license in the LICENSE file.

partycool's Issues

Missing design documents

I didn't find any design documents in the .doc directory. Make sure you place them in there.

For the component and functional spec... The functional spec is essentially the use cases. I like to write use cases by first creating a number of "user stories" that describe the specific user types, e.g.

Alice is an experimentalist who will be using the tool to analyze her data.  She has limited programming experience but is an expert user of tools like Excel and instrumentation control software.

Then, for each user type, enumerate the specific use cases, e.g.,

* Alice will use this software to load her raw EIS data into the database.
* Alice will use raw EIS data in the database to create a Nyquist plot.
* Alice will use the user interface to select multiple Nyquist plots to show simultaneously.

I realize these might not match your software, but I just wanted to put in some examples.

For the component specification, use the use cases and things mentioned in them to create components. E.g., in the above there are two top level components that come up right away:

1. A database
2. A user interface
   But there are likely many more and some that are sub-components of the above. For each component, you can use the following template to create a component 'card' in the form:

* Name
* What it does
* Inputs (with type information)
* Outputs (with type information)
* How it interacts with other components

Unit tests and continuous integration

I looked through the branches and didn't find any unit tests or a .travis.yml to setup continuous integration. Make sure you have a tests directory in your project module directory that contains the .py files with unit tests.

Make sure you have a full complement of unit tests and are using continuous integration. You can use the template from the repository I demoed: https://github.com/dacb/codebase_conda

Make sure to put badges in your README.md in the repo root.

Cruft in repo

I see some cruft in your repo, e.g. in the doc directory, there is a .DS_Store that got committed. This is an OS specific file and should be in the repo. You can delete it with git rm followed by the path and then add the .DS_Store to your .gitignore.

Do a scan of the repo and look for other stuff like that.

Repository structure

Refer to the repository structure slides found here:

• https://github.com/UWDIRECT/UWDIRECT.github.io/raw/master/Wi20_content/SEDS/L9.Project_Structure.pdf
  and/or this repo:
• https://github.com/dacb/codebase_conda
  for the general structure of your repository. Your doc directory should contain the tech review, component and functional specs, etc.
  In the root of the repo I see jupyter notebooks and .py files.