WMI User Guide

Program Components & Installation

WMI consists of 6 MATLAB® files, described below. It doesn't matter where they are located as long as they are in the same folder as each other. The filenames below are for the most updated versions (which are included in the download file).

Weapon_of_mass_Integration_01_00.p -- This is the analysis program itself.

WMI_Launcher_01_00.m -- Used to launch the program, this file is where you select the program parameters you wish to use.

Composite_Stitch_01_01.p -- Used to create a composite image by extracting individual nanoparticles from (multiple) images(s), if that option is selected.

fmgaussfit_WMI.m -- Used for fitting each nanoparticle with a rotated 2D Gaussian. The original file was developed by Nathan Orloff, and slightly modified here.

ReadDM3.m -- Used for importing Digital Micrograph® .dm3 files into MATLAB®. Developed by Fred Sigworth.

serReader.m -- Used for importing TIA (FEI) .ser files into MATLAB®. Developed by Peter Ercius.

The current version of WMI requirements are:

MATLAB® (2014b or newer. It might work with some older versions, but I can't promise.)

MATLAB® Toolboxes: Curve Fitting, Image Processing, Signal Processing, Statistics, Symbolic Math

I intend to reduce some of the toolbox dependencies through rewriting certain portions of the code; likely Symbolic Math & Signal Processing.  The others are unlikely to go away.

Analysis Parameters

The WMI Launcher file contains a list of user-settable variables that inform the program of the kind of analyses you want to perform and the parameters with which to perform the analysis. It is good practice to save a version of this file (with the selected parameters) with your data, so that you will always know what parameters were used to perform the analysis. The use of a launcher file like this is an idea I pulled from Lewys Jones.

Data Input & Preparation

Variable  --  Description

runstitch  --  Tells the program whether or not to extract the nanoparticles from a folder of images into a single composite "stitched" image. 0 = no, 1 = yes. (Default = 0) 

fillhole  --  Tells the program whether to fill any zero-intensity pixels in your image with the lowest non-zero background value. This is typically only used for stitched images. If your image has none, as a single-micrograph should, then this function obviously won't have any effect. 0 = no, 1 = yes. (Default = 1) 

numheadrow  --  Number of header rows in the nanoparticle location file. Must be an integer. 

numheadcol  --  Number of header columns in the nanoparticle location file. Must be an integer. 

runfilt  --  Tells the program whether to filter the image prior to fitting the nanoparticles, which can help with noisy images. It must be notes that the *raw*, unfiltered image is always used for intensity analysis, regardless of this option. 0 = no, 1 = yes. (Default = 1) 

gfsize  --  Size of the Gaussian filter, in pixels (see above). This values depends on the size of your nanoparticles, but a few pixels (2-3) is usually a reasonable value for small particles. 

gfsigma  --  Sigma of the Gaussian filter, in pixels (see above). This value also depends on the size of your nanoparticles. 1 is often a reasonable value. 

Input Parameters for Analysis

Variable  --  Description

np_size  --  Initial estimate of the diameter of your nanoparticles, in pixels. The program uses this value to determine a suitable number of radial expansion iterations and such. 

pxscale  --  The nanometers-per-pixel scale of your images. The program currently assumes all your images are the same scale. 

runint  --  Tells the program whether to perform the intensity integration analysis for each nanoparticle. 0 = no, 1 = yes. (Default = 1) 

runphys  --  Tells the program whether to perform the physical size analysis for each nanoparticle. 0 = no, 1 = yes (Default = 1) 

icutrad  --  Initial cut-off radius for the intensity integration, in pixels. Make sure this value is sufficiently smaller than the nanoparticle size (Default = 2 or 3). 

bkgwidth  --  The width of the annulus to use for the background value determination, in pixels. Typically only a few pixels. (Default = 2) 

ficfilt  --  The order of the median filter applied to the intensity change data used to determine the integration cut-off radius. Must be an integer. (Default = 3) 

threshlim  --  The threshold of fractional (0-1) intensity change used as the criterion for determining the integration cut-off radius. May need to be tailored according to your data. The program gives you the chance to adjust this value during the analysis. (Default = 0.1) 

numincthresh  --  The number of sequential integration increments of intensity change that must fall below the above threshold in order to trigger the cut-off radius. Must be 1, 2, or 3. (Default = 3) 

N  --  The initial N for FW(1/N)M to use for determining the physical diameter (e.g., N = 2 for FWHM). The program gives you the chance to adjust this value during the analysis. (Default = 2) 

Running WMI

To run WMI, adjust the parameters in the Launcher file to your satisfaction and then click the "Run" button (or F5).

A dialog will appear asking you to select the image to be analyzed. WMI accepts images of most any common file type, as well as .dm3 (Digital Micrograph®) and .ser (TIA) files. For quantitative intensity analysis, only lossless file types (.dm3, .ser, .tif) should be used. A drop-down in this dialog can be used to sort through the files in a folder.

After selecting an image file, it will ask you to select the corresponding nanoparticle location file. This is a text file containing the coordinates (in pixel units; fractional pixels are accepted) of the nanoparticle centers in the image. The centering does not need to be perfect, but it should be close. Future versions of WMI will contain particle identification baked in, but I haven't been satisfied with it, yet, particularly for low-signal-to-noise images.

In the meantime, I suggest using something like the Find Foci plugin for ImageJ/FIJI or just manually identifying them in ImageJ yourself (with the multi-select tool). A quick guide to that process is included [HERE].

If you chose to do a composite/stitched image, instead of asking you for a pair of files, the dialog will ask you to select a folder. This folder should contain the images and their corresponding nanoparticle files. They should be named such that the two groups of files should be in the same order (e.g., "Image_01, Image_02, ..." and "NPCenters_01, NPCenters_02, ..."). Selection of a folder will pop up a progress bar as each nanoparticle and a region around it is extracted and tiled into a single composite image. The image intensity values are not altered by this process.

Upon selection of the files, the image will be read in and displayed. The program will then begin fitting each nanoparticle with a 2D rotated Gaussian. This serves two purposes: to refine the location of each nanoparticle and to measure a physical size. If the fitting fails for a given nanoparticle, as sometimes happens when the signal-to-noise is very low, and the fit's center deviates too far from the initial center, this erroneous value will be thrown out and the original center used instead. This also helps prevent a nearby nanoparticle from accidentally being fitted instead. This fitting procedure is by far the most time-consuming part of the program, everything else zips right along.

Once this fitting is complete, if you opted to perform the physical measurement (runphys = 1) a blue circle will be overlaid on each nanoparticle. The circle's diameter corresponds to the average FW(1/N)M of the fit. A dialog pop-up will let you select a different value of N -- the overlaid circles update to reflect the change -- until you are satisfied. Once you are satisfied with the value, select okay or press enter without changing the value.

Because despite ones best efforts, occasionally things go awry, especially for low-SNR cases, and a nanoparticle may be showing a fit that is wildly wrong. To fix this, the program now gives you the change to manually refine the fit. To tweak a nanoparticle, click on/near it. A window will be displayed showing a close-up of that nanoparticle, a close-up of the fitted Gaussian, and a plot.

The diameter of the overlaid blue circle on each close-up is the average of the FW(1/N)M determined from the fit. The two lines on each close-up correspond to the orthogonal X (red) and Y (blue) slices through the image (solid lines) and fit (dashed lines), which are plotted on the right. The vertical dotted lines on the plot are the current bounds of the blue circle. To change them, click on the plot where you want to move them to. The lines and the blue circle will be updated. You can reselect them as much as you want. When satisfied, press Enter. This will return you to the refinement screen, where you may select another nanoparticle to refine. Once you are satisfied with the physical sizes, press Enter.

If you opted to perform the intensity integration (runint = 1), the program will pop up a progress bar while it performs the integration. This should be quick.

For each nanoparticle, WMI :

1. Integrates the intensities of the pixels enclosed by a circle of a given radius (starting with icutrad).

2. Determines a background intensity value from the average intensity value of the pixels enclosed within an annulus of set width (bkgwidth) beginning just outside the circle of (1).

3. Subtracts the value of (2) from each pixel in (1) to determine the integrated intensity of the nanoparticle alone (i.e., and not the support it is sitting on).

4. Iterates (1) through (3), increasing the radius of (1) by 1 pixel each time. This process is repeated until the integration bounds of (1) extend a distance well past the nanoparticle.

The optimal integration bounds value is determined by when the additional intensity that increasing the radius by another pixel would add to the total falls below a fraction of the total intensity, determined by threshlim. The variable numincthresh is how many times this must occur sequentially for the cut-off to be triggered.

Once complete, the micrograph will be displayed again, but this time the yellow circles correspond to the integration bounds. At this point the program will let you adjust the threshhold fraction, in case you want to try values other than the initial one you entered, and the overlaid circles update to reflect any change. Once satisfied, click okay or press Enter without changing the value

Now WMI will give you a chance to manually refine the integration bounds of any nanoparticles. As above, just click on or near the nanoparticle you wish to refine and the refinement window will be displayed.

The refinement window contains six sections, labeled in the above figure. (1) is a close-up of the nanoparticle you selected. The solid yellow line circle is the integration bound, the dashed yellow line is the outer edge of the background annulus, and the blue circle is the physical diameter. (2) is the integrated intensity fraction change, used to calculated the cut-off. The dotted curve is the raw intensity change while the blue solid line has been median-filtered to reduce the impact of sharp swings that can occur at low radii. (3) is the background-corrected integrated intensity of the nanoparticle. (4) is the mean background intensity of the annulus, (5) is the mean raw (not background-corrected) integrated intensity, and (6) is the mean intensity of each one-pixel iteration ring. (2-6) are all plotted as a function of iteration, and the dotted vertical lines indicate the current position of the integration cut-off radius. To adjust the cut-off radius, click on any of the five plots where you want the new position to be. All six elements will update to reflect the change. You may make as many changes as you wish. When satisfied, press Enter and you will be returned to the main image. If you would like to tweak another nanoparticle, select it in the same manner as you did the first. Once you are satisfied, press Enter. This will bring up the output options.

Output

Upon completion of the analysis, a dialog window will appear giving you three options for exporting the results:

Table & Figures -- A table with the analysis results will be exported as a .csv file. Additionally, 1-3 images will be exported, depending on the analysis options chosen. If only the physical size measurement was performed, a figure of the source image with each nanoparticle labeled and its physical diameters overlays will be exported. Similarly if the intensity integration was performed. If both analyses were performed, then a third image with both overlays will be exported.

Table Only -- Only the results table will be exported

Nothing -- No table or figures will be saved.

In the table, each row corresponds to a nanoparticle (with a unique ID, corresponding to its label on the image). The columns contain the corresponding measurement for each nanoparticle, depending on which were performed: physical radius, integration radius, and integrated intensity.

Selecting one of the first two export options will bring up a save dialog to choose the name and destination of the exports. The chosen name is used for both table and figures, with a different descriptor being appended to each file name:

".txt" -- The results table

"_physrad.png" -- Labeled image with physical size overlays

"_intrad.png" -- Labeled image with integration boundary overlays

"_bothrad.png" -- Labeled image with both overlays

Regardless of which option is selected, all MATLAB® variables and data structures created by the program will be cleared except for a summary table (nctable) that contains the final analysis results.