markjolah/Mappel

Maximum a posteriori Point Emitter Localization -- High-performance, parallel, robust, cross-platform localization for EMCCD and SCMOS microscopy.

MAPPEL

Mappel is an object-oriented image processing library for high-performance super-resolution localization of Gaussian point emitters in fluorescence microscopy applications.

• Mappel uses CMake and builds cross-platform for Linux and Windows 64-bit.
• Mappel provides object-oriented interfaces for C++, Python, and Matlab.
• Mappel uses OpenMP to parallelize operations over vectors of images or parameters
• Mappel is free-as-in-beer and free-as-in-speech! (GPL-v3)

Documentation

The Mappel Doxygen documentation can be build with the OPT_DOC CMake option and is also available on online:

• Mappel HTML Manual
• Mappel PDF Manual
• Mappel github repository

Background

Point emitter localization is a process of precisely estimating the sub-pixel location of a single point source emitters (molecules/proteins) at effective resolutions 10-50 times smaller than the fundamental diffraction limit for optical microscopes. Operationally, this is the process of going from blurry, noisy, pixelated images to a sub-pixel estimate of true emitter position as well as the uncertainty in that estimate. Figure 1 shows the point emitter localization process with realistic physical values for a typical super-resolution fluorescence microscope configuration.

Figure 1: Effective fitting resolution in typical applications

Applications

• Stochastic super-resolution reconstruction with PALM and dSTORM florescence microscopy techniques.
• Single particle tracking (SPT)
  • The Robust Particle Tracking (RPT) library uses Mappel for the localization phase of tracking.
• Nano-structure optical measurements and alignment.
• Accurate estimation of fluorophore emitter intensity over time.

Performance

Emitter localization applications, especially SPT and super-resolution imaging, can require millions of emitter estimations per dataset. This demand is only increasing with the drive towards larger EMCCD and SCMOS sensors and longer experiments at higher frame-rates. Speed becomes even more crucial for these applications when batch processing dozens of large data files.

• Mappel runs all image oriented computations in parallel using OpenMP making full use the system hardware concurrency.
• Mappel is fast. It can easily localize 10^4 emitters/sec/core on modern consumer hardware
• Small and medium-sized datasets using Mappel can work well on laptops allowing interactive Matlab applications like RPT to be used from nearly any machine.

Installation

Mappel uses the CMake build system, and is designed to be cross-compiled from linux to other platforms, primarily Win64, although future OSX support is planned.

Dependencies

Several standard numerical packages are required to build Mappel. Most distributions should have development versions of these packages which provide the include files and other necessary development files for the packages.

• Armadillo - A high-performance array library for C++.
• Boost
• BLAS
  • Requires support for 64-bit integers.
  • Netlib BLAS Reference
• LAPACK
  • Requires support for 64-bit integers.
  • Netlib LAPACK Reference

Note the OPT_BLAS_INT64 CMake option controls whether Armadillo uses BLAS and LAPACK libraries that use 64-bit integer indexing. Matlab uses 64-bit by default, so linking Mappel to Matlab MEX libraries requires this option enabled. Many linux systems only provide 32-bit integer versions of BLAS and Lapack, and the option can be disabled if Matlab support is not a concern and 64-bit support is difficult to provide.

External Projects

These packages are specialized CMake projects. If they are not currently installed on the development machines we use the AddExternalDependency.cmake which will automatically download, configure, build and install to the CMAKE_INSTALL_PREFIX, enabling their use through the normal CMake find_package() system.

• BacktraceException - A library to provide debugging output on exception calls. Important for Matlab debugging.
• ParallelRngManager - A simple manager for easily deploying a set of RNG parallelized over a set number of threads, using the TRNG parallel RNG library.
• PriorHessian - The PriorHessian library allows fast computation of log-likelihood and derivatives for composite priors.

Model classes

Mappel provides model objects that correspond to different fitting-modes (psf-models). Mappel's core is a C++ library libmappel.so that uses OpenMP to automatically parallelize localizations over multiple images. Mappel also provides detailed object-oriented interfaces for Python and Matlab, using the same concept of a Model class to represent each class of psf fitting models.

Computations available

• llh - log-likelihood (log of pdf)
• rllh - relative log-likelihood (log of pdf without constant terms)
• grad - derivative of log-likelihood (or equivalently of relative-llh)
• grad2 - 2nd-derivative of log-likelihood
• hessian - hessian of log-likelihood

Design Notes

Static Polymorphism

The Mappel library is designed using static polymorphism (templates), and as such avoids virtual functions for small-grained tasks, and instead uses templates, which allow many small functions to be inlined. This aggressive inlining by the compiler produces log-likelihood, gradient, and hessian functions that are nearly as fast as hand-coded functions.

License

• Copyright: 2013-2019
• Author: Mark J. Olah
• Email: (mjo@cs.unm DOT edu)
• LICENSE: GPL-v3 See LICENSE file.