Notebook

Object Hunt Script¶

In [1]:

%run NBCONFIG.ipynb

Populating the interactive namespace from numpy and matplotlib

Introduction¶

pyparty installs a script called objecthunt. The purpose of objecthunt is to separate color-labeled objects from an image, and output common statistics, plots and perform common pyparty operations. This is best shown by example, so consider the pyparty test image, test_labeled:

In [2]:

from pyparty.data import test_labeled

REZ = (1000, 1024)
IMAGE = test_labeled(REZ)
imshow(IMAGE);

objecthunt will automate a series of common pyparty Canvas and Multicanvas operations including:

Pie, Histograms and multiplots of the groups of particles
Particle counts, statistics
- Includes attributes stats such as min, max and mean circularity of each group.
Image conversions, Gray, Binary etc.. deconstructed by species.

All the various outputs will be discussed later in the Configuration section

Getting started¶

First, test that objecthunt is installed properly by typing:

objecthunt - h

This should output a argparser help message.

usage: objecthunt <image> <outdir> --options Measure and separate objects in image based on color. positional arguments: image Path to image out directory Path to outdirectory optional arguments: -h, --help show this help message and exit -c, --config Path to config file. Defaults to "./_configobjhunt.py" -p, --params Overwrite configuration parameters manually (e.g. objecthunt <image> <outdir> -p ignore=black -f, --force Overwrite outdirectory if it exists. WARNING: this will remove entire directory tree! --dpi Plotting resolution (dots per inch) -v, --verbosity Set screen logging. If no argument, defaults to info -t, --trace Show traceback on errors

The only positional arguments are an image and an out directory. The default configuration is found in the config file in the pyparty/scripts/objecthunt folder view it here.

At this point, I have saved the cropped test_image above into my home directory. Let's check out the output with the default configuration:

objecthunt ~/test_image.png ~/foo_out -p ignore=black

Where we set a parameter, ignore to black as the test image has a black background. Alternatively, this could have been set directly in the config file. Any run parameter can be overwritten at the command line.

Results¶

First, notice there are several folders output by the script:

MultiCanvas: Plots/stats of multicanvas methods like multi-histogram and pie chart (see below)
Net_Canvas: Plots/stats of single Canvas of all particles
- For example, the percent image coverage is a canvas stat.
** Canvas_by_Canvas**: Plots/stats of individual particle subgroups.

Examples of these outputs are shown below:

In [3]:

from IPython.display import Image
Image('../scriptimg_1.png')

Out[3]:

Notices that 4 generic species, patch1-4 have been assigned. In the configuration section below, we show how to assign names to each group. The majority of statistics is in the summary.txt output. Here is an excerpt that shows the MultiCanvas, Net Canvas and Patch 1 Canvas, as well as statistics of each:

MultiCanvas (0xaefd9bc) 171: patch1 - Canvas (0xaef8e0c) : 1024 X 1000 : 96 particles patch2 - Canvas (0xaefd6bc) : 1024 X 1000 : 16 particles patch3 - Canvas (0xaefd98c) : 1024 X 1000 : 40 particles patch4 - Canvas (0xaefd77c) : 1024 X 1000 : 19 particles ### Net Canvas ### ------------------ Canvas (0xafd7cbc): background --> (1024 X 1000) : file/colorstring/url particles --> 171 particles : 1 types xygrid[435] --> (29p X 15p) : (34.5 X 68.2) [pix/tile] Image Resolution: (1024, 1000) Particle coverage: 19.57% area (min, max, mean): (437.00 - 3319.00, 1172.11) circularity (min, max, mean): (0.30 - 1.00, 0.80) equivalent_diameter (min, max, mean): (23.59 - 65.01, 37.28) ### patch1 ### -------------- Canvas (0xd1409ec): background --> (1024 X 1000) : file/colorstring/url particles --> 96 particles : 1 types xygrid[435] --> (29p X 15p) : (34.5 X 68.2) [pix/tile] Image Resolution: (1024, 1000) Particle coverage: 6.59% area (min, max, mean): (437.00 - 1125.00, 703.38) circularity (min, max, mean): (0.94 - 1.00, 0.97) equivalent_diameter (min, max, mean): (23.59 - 37.85, 29.77)

Configuration¶

There are several configurable parameters, mostly having to do with plotting styles, and which analysis to do and which not to. Hopefully, the variable names are self-explantory. Here are just a few examples:

multidir Directory name of where to output multicanvas plots (pie, hist etc..)
multihist = 'hist.png' : multihistkwds = {}
- Name of multicanvas piechart and any valid keywords (e.g. bins=50)
ignore = 'white'
- Background color to ignore in images

For plots and directories, setting value to None (e.g. multihist=None) will remove that part of the analysis. For example, setting canvasdir = None will avoid the canvas-by-canvas analysis entiely!

Another key parameter is the mapper, which allows the user to specify group names and colors of objects. For our example images, the mapper would be set as follows:

mapper = [
    ('singles','red'),
    ('doubles',(0,1,0)),
    ('trimers', 'gold' ),
    ('clusters', 'magenta')
    ]

Where the colors are specified as any valid pyparty color style. The script will guess the closest color from the one specified, so exact colors are not required! The order of the names in the mapper persists in the plots! Here is an example of the pie and multishow when the above mapper is used in the config file:

In [4]:

Image('../scriptimg_2.png')

Out[4]:

If you are having trouble guessing the nearest colors, I'd recommend either using a hexcode or you can use pyparty.unique() to see all the colors in the image. Internally, pyparty will convert the image to rgb using any2rgb function, so let's look at the unique values after converting:

In [5]:

from pyparty.tools.arraytools import unique
from pyparty.utils import any2rgb

unique( any2rgb(IMAGE) )

WARNING:pyparty.utils:4-channel RGBA recieved; ignoring A channel

Out[5]:

[array([ 0.,  0.,  0.]),
 array([ 1.,  0.,  0.]),
 array([ 0.,  1.,  0.]),
 array([ 1.,  1.,  0.]),
 array([ 1.,  0.,  1.])]

These corresponds to black, red, green, yellow and magenta, respectively.

Creating your own configuration file¶

Creating your own configuration file is simple. Merely import _configobjhunt.DefaultParameters and overwrite default parameters to your liking view defaults here. Just be sure you name your new class Parameters.

So for example, a configuration file that changes all of the particle group names to rappers and sets the background color of the image to white would be created as:

from pyparty.scripts.objectmodeling import DefaultParameters class Parameters(DefaultParameters): """ Creating a new Parameters class; we will rename mapper attributes to rappers, and ignore white pixels as background. """ ignore = 'white' mapper = [ ('50cent','yellow'), ('kendrick', (1,0,0)), ('dre', 'pink' ), ('reds', 'red') ] ...

Then to use this configuration, it's as simple as:

objecthunt <image> <outdir> -c path/to/configfile.py

Script Workflow¶

This section is mainly aimed at those looking to script with pyparty, or change/improve the objecthunt script.

Caveats¶

A couple things to keep in mind about this script:

Images with more than 10 separate colors, by default, will not be analyzed. This is due to the inherent slowness of MultiCanvas.from_labeled(), and the restraint will be soon once this step is sped up.