Features - Download - User Manual

This user guide contains the information on how to install, configure and run the Absolute Integrator STEM analysis code. Absolute integrator is continually being improved based on user feedback so please check the support page for update notifications and changelogs.

User Manual Quick Links:

Installation - Configuration - Running - Results

Installation

(return to top)

Absolute Integrator Componant Files

As Absolute Integrator is being activley developed and improved small updates may be distributed frequently. To facilitate this it is built from several modules each of which can be updated seperatly. The table below outlines the files that you should have in your installation, their purpose and the most current version. Before running Absolute Integrator for the first time users should check all these files are present in the same folder along with the image file to be processed.

File	Purpose	Current Version	Release Date
AbsoluteIntegrator_Core_1_2	Performs the majority of the analysis and communicates to the other modules.	1.2	1st October 2013
AbsoluteIntegrator_Wrapper_1_2	User interface for variable set-up of the analysis variables.	1.2	1st October 2013
Integrator_license_check	Checks the current license state.	1.0	12th September 2013
convolve2*	Performs a fast 2D convolution used in the background subtraction step.	-	11th April 2011
File_Opener_1_5_3	Opens image files of various types and passes image data to "AbsoluteIntegrator_Core".	1.5.3	12th September 2013
Ranger_Core_2_2	Performs the peak-finding.	2.2	13th September 2013
Ranger_license_check	Checks the current license state.	1.0	12th September 2013
ReadDM3*	Allows "File_Opener" to handle Gatan .dm3 files.	-	19th March 2010
serReader*	Allows "File_Opener" to handle Titan .ser files.	-	6th August 2009
weightedEllipticalGaussianFit	Perfomrs the experimental eccentricity fitting calculation	-	20th March 2013

In addition to the above the Matlab Image-processing, Statistics and Curve-fitting Toolboxes are required to use Absolute Integrator.

Example Installation

The image below shows a typical installation of Absolute Integrator (ordered alphabetically). All the componant files as well as the image to be processed must be in the same folder as each other.

Configuration

(return to top)

Setting the Analysis Variables

The Absolute Integrator wrapper file sets up all the input variables needed to process the image to the user’s specification. Before running the code each of the variables should be verified. Once verified however these will only need modifying rather than entireley resetting each time.

The following table defines the action of each input variable.

Show / hide variable definitions

Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes
manual_best_size	Gives the user the ability to over-ride the peak-finding feature seperation determination and specify a fixed value	0	0 for automaic, 1 to manually over-ride	If set to 1, then the value must also be specified (odd number).
best_size	The feature-spacing when using manual over-ride	Sample dependent, see notes	Must be an odd number	Should be the nearest odd number to the feature separation in pixels.
removeZeroSpot	Allows the user to include a high-pass filtering as part of the peak-finding	0	0 for off, otherwise percentage radial limit to filter.	When high-pass filtering is reqired a value of 2% is often sufficient.
refinePositions	Allows the user to select to run an additional 2D Gaussian feature position refinement if necessary	0	0 for off, 1 for on	-
show_progress	Allows the user to show or hide peak-finding progress windows	1	0 for hidden, 1 to show	-
display_results	Allows the user to show a large figure showing the determined feature locations	1	0 for hidden, 1 to show	-
Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes
latticeParameter	Used in the image magnification calibration	Sample dependent	Positive, non-zero	Units of nm. Variable is unused if a manual pixel size is specified.
calibrationPlanes	Specifies the h,k,l indices of the diffractogram spots that are used in the calibration	Sample dependent	Must contain three positive integers in the form [ h k l ]	-
faradayCurrentImaging	Specifies the probe current used for HAADF imaging	1	Positive non-zero number	Units must be the same as one another, generally pA. The ratio of these is used in the analysis so setting both to unity is also acceptable.
faradayCurrentDetector	Specifies the current used for detector mapping	1	Positive non-zero number
Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes
upsamplingFactor	Upsamples the HAADF image for smoother integration region edges	2	Positive integers only	Large upsampling values will significantly increase image processing time.
autoRadius	Allows the user to over-ride the integration radius upper-limit	1	1 for automatic, 0 for manual	If manual mode is selected then the radius must also be specified.
manualRadius	The upper-limit to integration radius when specified manually	Sample dependent	Positive number	Units of pixels.
subtractBackground	Allows the user to select wether to subtract background intensity in the experimental image or not	1	1 for yes, 0 for no	-
fitLocalBackground	Allows the user to select whther background subtraction should attempt to be locally varying	1 or 0, see notes	1 for yes, 0 for no	If vacuum or support is visible around whole sample, use 1. If sample extends off image edge use 0.
backfillIterations	Specifies the upper limit to the number of background recreation iterations when using locally varying background subtraction	250	Positive integers	Background recreation iteration can be terminated before this number during execution so is better to choose a large number here.
Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes
loadSimulation	Allows the user to specify if a simulation is being loaded	-	0 for experimental, 1 for simulation	If set to 1 no detector map will be loaded but diffractogram calibration may still be used if desired.
simulationTiling	Allows the user to tile the simulation this many times in both x and y before analysis	1	Positive integers	-
manualPixelWidth	Allows the user to avoid the diffractogram calibration if the pixel size is know from simulation	0 for off (use diffractogram calibration), otherwise simulation dependednt	Positive number	Units of nm.
addRandomOffset	Allows the user to add a random direction, zero mean, Gaussian distributed error to the image feature coordinates with this standard deviation	0	Non-negative number	Advanced users only.
addNoiseTargetSNR	Allows the user to deliberatly degrade the SNR of images, usually simulations	Zero for off, otherwise target SNR	Non-negative numbers	Advanced users only.
Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes
weightDetector	Experimental compensation of detector asymmetry	0	0 for off, 1 for on	BETA feature - still in testing.
innerAngle	Detector inner angle for detector map calibration	Detector / camera-length specific	Positive, non-zer number	Units of mrad.
TDSexponent	Fitting variable for detector asymmetry compensation	Sample Z dependent	Positive, non-zero numbers	BETA feature - still in testing.
analyseAzimuthalSensitivity	Allows the user to analyse the azimuthal variation in detector sensitivity	0	0 for off, 1 for on	BETA feature - still in testing.
calculateEllipticity	Allows the user to calculate the eccentricity of all atomic columns in the image	0	0 for off, 1 for on	BETA feature - still in testing. Can take over an hour for larger images.
offsetDetector	Allows the user to introduce a deliberate optical misalignemnt of the annular detector in the y and x directions respectively	[ 0 0 ]	Non-negative numbers	BETA feature - still in testing. Units of percentage inner angle.
Variable	Purpose	Default / Recommended Value	Input Restrictions	Notes

Running Absolute Integrator

(return to top)

Once the above parameters have been selected in the Absolute Integrator Wrapper file simply press run (or F5).

The restoration then proceeds in the folloing stages which are described in turn below:

The detector image is read in to the workspace by the'File_Opener' module.
The detector sensitivity histogram will be displayed for vacuum and active-area threshold selection.
The HAADF image is read in to the workspace.
Diffractogram Calibration of the HAADF image.

1 - Detector File Reading

If a .dm3 or .ser file was selected the greyscale image will be extracted from the file by the appropriate file converter.

2 - Sensitivity Threshold Selection

The annular detector will be displayed, along with a histogram of the recorded counts at every pixel. The user must select two thresholds using the crosshairs mouse cursor; first the upper limit (right edge) of the first histogram peak corresponding to the image vacuum pixels, and second the lower limit (left edge) of the second histogram peak corresponding to the active region of the detector. Incorrect clicks can be undone by pressing the 'Backspace' button; once happy press 'Enter' to accept.

Typical Absolute Integrator Installation

After pressign 'Enter' the histogram will be updated with two solid black lines that represent the threshold vlaues that were selected, as well as with two dashed black lines that represent the average intensities of the vacuum and detector respectively. The three histogram segments will be colour coded to reflect this division as will the detector map image. The detector sensitivity is now calibrated.

3 - HAADF Image File Reading

4 - Diffractogram Image-Magnification Calibration

For the magnification calibration the experimental image will be displayed alongside the central part of its Fourier transform.

Using the crosshair mouse cursor the user must select two diffractogram spots that correspond to the indices configured in the Wrapper file. If two unique spots cannot be reliably identified then it is acceptable, but not preffered, to accept a spot and its conjugate. Incorrect clicks can be undone by pressing the 'Backspace' button; once happy press 'Enter' to accept the selections.

$Absolute Integrator Diffractogram Calibration$

After pressing 'Enter' the lengths selected on the diffractogram will be highlighted and a scale marker will be added to the experimental image. Magnification calibration is then complete.

5 - HAADF Image Peak-finding

Peak-finding is performed on the experimental image to determine the locations of the atomic columns. The user can modify the suggested results by manually clicking any missing peaks or removing any surplus ones. A full description of the peak-finding module can be found here.

6 - HAADF Image Segmentation and Integration

The peak-finding results are used to determine the appropriate regions for integration. Following integration the scattering cross-sections are calcualted and illustrated back in the same areas as the integration regions.

Additionally two histograms are shown illustrating the areas (in square pixels) of the integration regions used (to inspect for consistency), and also showing the spread of the calcualted scattering cross-sections.

Absolute Integrator Results

(return to top)

After completion the workspace will be cleared.

* MatLab function files available from MatLab Central.

"convolve2.m" was developed by David Young.

"ReadDM3" was developed by Fred Sigworth and Liguo Wang at Yale University.

"serReader.m" was developed by Peter Ercius at the National Center for Electron Microscopy (NCEM).