Rebasing from upstream (#7)

* Create initial documentation

* Added tests for functions in Particle Analysis

Added testing functions for the following functions:

-ParticleAnalysis()
-store_image()
-store_maps()
-store_spectrum()
-get_composition()

* Added files for travis

Added travis yml file and requirements file for travis builds.

* Added test for particle list loading

* Update requirements.txt

Changed hyperspy dependency.

* Update requirements.txt

Updated PyQt5 requirements

* Update requirements.txt

* Syntax corrections

Corrected import syntax

* Revert "Syntax corrections"

This reverts commit 600e2bf.

* Updated import syntax

* Update .travis.yml

Added installation in virtual env

* Changed path to parameters file

* Updated the example notebook

* Improve Find Zone-axis procedure and bug fixes

Update find_zoneaxis and particleanalysis in order to more reliably find zone axes from noisy data.

Bug fixed in reading old segmentation parameters.

* Add kernel size for local thresholding

Added option to change the kernel size for local thresholding (was previously set to default 21 pixels).

* Changed max limits in SegUI

Changed the max values for the spin boxes in SegUI. They should now scale with the image size rather than being fixed to 99.

* Added Local Otsu

Added Local Otsu to thresholding options.

* Added (Local + Global) Otsu Threshold

Added Threshold Option that combines the result of the Local and Global Otsu Thresholds.

* Fixed uint8 bug

Fixed bug that would incorrectly scale integer images. Now converts to float before scaling.

* Update find_zoneaxis.py

* Updated requirements for uploading to PyPI

* Update README.md

* Update setup.py

Include check for PyQT5 import to avoid clash with pyqt package in conda.

* Update setup.py

* Updates for building a wheel

Updated file requirements in setup.py nad MANIFEST.in for correctly building.

* Update setup.py

Bug fix

* Update setup.py

* Add radial profile

Added function to plot a radial profile of signals from a particle.

Also added the option of defining the number of bins in the histogram plotters.

* Create requirements.txt

* Update to radial profile plotting

* Fix list issue and add radius marker.

- Finally fixed the issue to do with adding particles to previously created particle lists.
- Added a radius marker to the radial profiles.

* Update Particle Analysis to include zone axis determination

* Set theme jekyll-theme-architect

* Added tests for functions in Particle Analysis

Added testing functions for the following functions:

-ParticleAnalysis()
-store_image()
-store_maps()
-store_spectrum()
-get_composition()

* Added files for travis

Added travis yml file and requirements file for travis builds.

* Added test for particle list loading

* Update requirements.txt

Changed hyperspy dependency.

* Update requirements.txt

Updated PyQt5 requirements

* Update requirements.txt

* Syntax corrections

Corrected import syntax

* Revert "Syntax corrections"

This reverts commit 600e2bf.

* Updated import syntax

* Update .travis.yml

Added installation in virtual env

* Changed path to parameters file

* Updated the example notebook

* Improve Find Zone-axis procedure and bug fixes

Update find_zoneaxis and particleanalysis in order to more reliably find zone axes from noisy data.

Bug fixed in reading old segmentation parameters.

* Add kernel size for local thresholding

Added option to change the kernel size for local thresholding (was previously set to default 21 pixels).

* Changed max limits in SegUI

Changed the max values for the spin boxes in SegUI. They should now scale with the image size rather than being fixed to 99.

* Added Local Otsu

Added Local Otsu to thresholding options.

* Added (Local + Global) Otsu Threshold

Added Threshold Option that combines the result of the Local and Global Otsu Thresholds.

* Fixed uint8 bug

Fixed bug that would incorrectly scale integer images. Now converts to float before scaling.

* Update find_zoneaxis.py

* Updated requirements for uploading to PyPI

* Update README.md

* Update setup.py

Include check for PyQT5 import to avoid clash with pyqt package in conda.

* Update setup.py

* Updates for building a wheel

Updated file requirements in setup.py nad MANIFEST.in for correctly building.

* Update setup.py

Bug fix

* Update setup.py

* Add radial profile

Added function to plot a radial profile of signals from a particle.

Also added the option of defining the number of bins in the histogram plotters.

* Create requirements.txt

* Update to radial profile plotting

* Fix list issue and add radius marker.

- Finally fixed the issue to do with adding particles to previously created particle lists.
- Added a radius marker to the radial profiles.

* Update Particle Analysis to include zone axis determination

* Set theme jekyll-theme-architect

* Add initial documentation source files

* Update .travis.yml

* Update .travis.yml

* Update .travis.yml

* Update .travis.yml

* Update .travis.yml

* Update README.md

* Revamped particle properties and added new properties

Revamped particle properties so that properties are held as a dictionary rather than as separate class members.

Added eccentricity, major and minor axes and equivalent circular diameter to properties.

Added new plot function to particle list that plots a histogram of any particle property.

* Minor corrections

Updated diameter equation and modified property names.

* Fix tests

* Update .travis.yml

* Update doc strings

* Documentation Update

Updated documentation to include page on segmentation.

* Add particle intensity

Added total particle intensity measure.

* Add Particle Analysis Documentation

Author: TomSlater

.travis.yml

@@ -6,6 +6,20 @@ python:
 install:
   - pip install -r requirements.txt
   - pip install -e .
+  - pip install sphinx
+  - pip install sphinx_rtd_theme
 
 script:
   - pytest
+  - cd docs
+  - make html
+  - touch _build/html/.nojekyll
+
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN  # Set in travis-ci.org dashboard, marked secure
+  keep-history: true
+  on:
+    branch: master
+  local_dir: docs/_build/html/

ParticleSpy/ParticleAnalysis.py

@@ -25,10 +25,10 @@ def ParticleAnalysis(acquisition,parameters,particles=None,mask=np.zeros((1))):
     acquisition: Hyperpsy signal object or list of hyperspy signal objects.
         Hyperpsy signal object containing a nanoparticle image or a list of signal
          objects that contains an image at position 0 and other datasets following.
-    process_param: Dictionary of parameters
+    parameters: Dictionary of parameters
         The parameters can be input manually in to a dictionary or can be generated
         using param_generator().
-    particle_list: List
+    particles: list
         List of already analysed particles that the output can be appended
         to.
     mask: Numpy array
@@ -37,7 +37,7 @@ def ParticleAnalysis(acquisition,parameters,particles=None,mask=np.zeros((1))):
         
     Returns
     -------
-    list: List of Particle objects.
+    Particle_list object
     """
 
     if particles==None:
@@ -80,13 +80,28 @@ def ParticleAnalysis(acquisition,parameters,particles=None,mask=np.zeros((1))):
         area_units = image.axes_manager[0].units+"^2"
         p.set_area(cal_area,area_units)
 
+        #Set diam measures
+        cal_circdiam = 2*(cal_area**0.5)/np.pi
+        diam_units = image.axes_manager[0].units
+        p.set_circdiam(cal_circdiam,diam_units)
+        
+        cal_axes_lengths = (region.major_axis_length*image.axes_manager[0].scale,region.minor_axis_length*image.axes_manager[0].scale)
+        #Note: the above only works for square pixels
+        p.set_axes_lengths(cal_axes_lengths,diam_units)
+        
         #Set shape measures
         peri = image.axes_manager[0].scale*perimeter(maskp,neighbourhood=4)
-        circularity = 4*3.14159265*p.area/(peri**2)
+        circularity = 4*3.14159265*p.properties['area']['value']/(peri**2)
         p.set_circularity(circularity)
+        eccentricity = region.eccentricity
+        p.set_eccentricity(eccentricity)
+        
+        #Set total image intensity
+        intensity = (image*mask).sum()
+        p.set_intensity(intensity)
 
         #Set zoneaxis
-        im_smooth = filters.gaussian(p_im,1)
+        im_smooth = filters.gaussian(np.uint16(p_im),1)
         im_zone = np.zeros_like(im_smooth)
         im_zone[im_smooth>0] = im_smooth[im_smooth>0] - im_smooth[im_smooth>0].mean()
         im_zone[im_zone<0] = 0

ParticleSpy/SegUI.py

@@ -262,6 +262,9 @@ def main(haadf):
     return(ex)
 
 def SegUI(image):
+    """
+    Function to launch the Segmentation User Interface.
+    """
     app = QApplication(sys.argv)
     app.aboutToQuit.connect(app.deleteLater)
 

ParticleSpy/find_zoneaxis.py

@@ -24,7 +24,7 @@ def find_zoneaxis(im):
         
     Returns
     -------
-    string: Zone axis of material in image (eg. '011')
+    str : Zone axis of material in image (eg. '011')
     """
 
     #Get FFT of particle image

ParticleSpy/ptcl_class.py

@@ -9,18 +9,54 @@
 from ParticleSpy.particle_save import save_plist
 
 class Particle(object):
-    """A segmented particle object."""
+    """A segmented particle object.
+    
+    Attributes
+    ----------
+    properties : dict
+        Dictionary of particle properties created by the ParticleAnalysis() function.
+    origin : str
+        Origin of particle data, e.g. filename or acquisition number.
+    zone : str
+        Zone axis of particle.
+    mask : array
+        Boolean array corresponding to the particle pixels on the original image.
+    image : Hyperspy signal object
+        Image of particle.
+    maps : dict
+        Dictionary containing elemental maps of the particle.
+    spectrum : Hyperspy signal object
+        Spectrum obtained from the particle.
+    composition : dict
+        Dictionary of composition values for the particle.
+    
+    """
+    
+    def __init__(self):
+        self.properties = {}
 
     def set_origin(self, origin):
         """A container for the origin of data (filename, acquisition number etc.)"""
         self.origin = origin
 
     def set_area(self, area, units):
-        self.area = area
-        self.area_units = units
+        self.properties['area'] = {'value':area,'units':units}
+        
+    def set_circdiam(self, circdiam, units):
+        self.properties['equivalent circular diameter'] = {'value':circdiam,'units':units}
+        
+    def set_axes_lengths(self,axeslengths,units):
+        self.properties['major axis length'] = {'value':axeslengths[0],'units':units}
+        self.properties['minor axis length'] = {'value':axeslengths[1],'units':units}
 
     def set_circularity(self, circularity):
-        self.circularity = circularity
+        self.properties['circularity'] = {'value':circularity,'units':None}
+        
+    def set_eccentricity(self,eccentricity):
+        self.properties['eccentricity'] = {'value':eccentricity,'units':None}
+        
+    def set_intensity(self,intensity):
+        self.properties['intensity'] = {'value':intensity,'units':None}
 
     def set_zone(self, zone):
         self.zone = zone
@@ -64,10 +100,10 @@ def plot_area(self,bins=20):
         areas = []
 
         for p in self.list:
-            areas.append(p.area)
+            areas.append(p.properties['area']['value'])
 
         plt.hist(areas,bins=bins)
-        plt.xlabel("Area ("+self.list[0].area_units+")")
+        plt.xlabel("Area ("+self.list[0].properties['area']['units']+")")
         plt.ylabel("No. of particles")
 
     def plot_circularity(self,bins=20):
@@ -78,8 +114,33 @@ def plot_circularity(self,bins=20):
         circularities = []
 
         for p in self.list:
-            circularities.append(p.circularity)
+            circularities.append(p.properties['circularity']['value'])
 
         plt.hist(circularities,bins=bins)
         plt.xlabel("Circularity")
+        plt.ylabel("No. of particles")
+        
+    def plot(self,prop='area',bins=20):
+        """
+        Displays a histogram of the chosen particle property.
+        
+        Parameters
+        ----------
+        prop : str
+            The name of the property to plot as a histogram.
+        bins : int
+            The number of bins in the histogram.
+        
+        """
+        
+        property_list = []
+        
+        for p in self.list:
+            property_list.append(p.properties[prop]['value'])
+            
+        plt.hist(property_list,bins=bins)
+        if self.list[0].properties[prop]['units'] == None:
+            plt.xlabel(prop.capitalize())
+        else:
+            plt.xlabel(prop.capitalize()+" ("+self.list[0].properties[prop]['units']+")")
         plt.ylabel("No. of particles")

ParticleSpy/radial_profile.py

@@ -7,7 +7,22 @@
 import numpy as np
 import matplotlib.pyplot as plt
 
-def radial_profile(particle,signals,plot=True, mark_radius=False, radius=1):
+def radial_profile(particle,signals,plot=True, mark_radius=False):
+    """
+    Function to calculate and plot a radial profile of a signal from an individual 
+    particle.
+    
+    Parameters
+    ----------
+    particle : ParticleSpy particle object
+        The particle object.
+    signals : list
+        List of signals to plot, either 'Image' or element name, e.g. 'Ag'.
+    plot : bool
+        True if plotting, False otherwise.
+    mark_radius : bool
+        If true, mark the particle radius on the profile plot.
+    """
 
     dist_count_dic = {}
     for sig in signals:
@@ -20,7 +35,7 @@ def radial_profile(particle,signals,plot=True, mark_radius=False, radius=1):
     units = particle.image.axes_manager[0].units
 
     if plot==True:
-        plot_profile(dist_count_dic,scale,units, mark_radius=mark_radius, radius=radius)
+        plot_profile(dist_count_dic,scale,units, mark_radius=mark_radius, radius=particle.properties['equivalent circular diameter']['value']/2)
     return(dist_count_dic)
 
 '''def sum_profiles(profiles):
@@ -85,14 +100,23 @@ def getkey(item):
 
     return distance_unique, count_unique
 
-def plot_profile(dist_count_dic, scale, units, mark_radius=False, radius=1, save=False, dir_save=None):
-    '''
-    DisNorm: check if the distance from particle centre 
-            is normalised by the particle size
-    '''
+def plot_profile(dist_count_dic, scale, units, mark_radius=False, radius=1.0, save=False, dir_save=None):
+    """
+    Function to plot a radial profile of particle signals.
     
-    '''if DisNorm == True:
-        plt.xlim([0,100])'''
+    Parameters
+    ----------
+    dist_count_dic : dict
+        Dictionary containing the distances and counts of the profile.
+    scale : float
+    units : str
+    mark_radius : bool
+        If true, mark the particle radius on the profile plot.
+    radius : float
+    save : bool
+    dir_save : str
+        Default : None
+    """
 
     plt.xlabel('Distance from particle centre ('+units+')')
     plt.ylabel('Normalised intensity (counts)')

ParticleSpy/tests/test_particle_analysis.py

@@ -85,9 +85,9 @@ def test_particleanalysis():
 
     p = p_list.list[0]
 
-    nptest.assert_almost_equal(p.area,20069.0)
-    assert p.area_units == 'nm^2'
-    nptest.assert_almost_equal(p.circularity,0.9095832157785668)
+    nptest.assert_almost_equal(p.properties['area']['value'],20069.0)
+    assert p.properties['area']['units'] == 'nm^2'
+    nptest.assert_almost_equal(p.properties['circularity']['value'],0.9095832157785668)
     assert p.zone == None
     nptest.assert_allclose(p.mask,mask)
     nptest.assert_allclose(p.image.data,image.data[16:184,16:184])

ParticleSpy/tests/test_particle_io.py

@@ -12,8 +12,8 @@ def test_load_particles():
     image = gen_test.generate_test_image(hspy=True)
     mask = gen_test.generate_test_image(hspy=False)
 
-    nptest.assert_almost_equal(p.area,20069.0)
-    assert p.area_units == 'nm^2'
-    nptest.assert_almost_equal(p.circularity,0.9095832157785668)
+    nptest.assert_almost_equal(p.properties['area']['value'],20069.0)
+    assert p.properties['area']['units'] == 'nm^2'
+    nptest.assert_almost_equal(p.properties['circularity']['value'],0.9095832157785668)
     nptest.assert_allclose(p.mask,mask)
     nptest.assert_allclose(p.image.data,image.data[16:184,16:184])

README.md

@@ -1,4 +1,6 @@
 # ParticleSpy
 Package for analysing particles in electron microscopy data sets.
 
-The package can be installed from PyPI using pip install ParticleSpy.
+The package can be installed from PyPI using pip install ParticleSpy.
+
+Documentation can be found at https://epsic-dls.github.io/ParticleSpy/index.html.

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)