Class Averaging Architecture¶

ASPIRE now contains a broad collection of configurable and extensible components which can be combined to create class averaging solutions tailored to different datasets. The architecture was designed to both be modular and encourage experimentation. Lower level components are aggregated into a high level interface by ClassAvgSource instances. Starting there this document will descend into each contributing component.

ClassAvgSource¶

ClassAvgSource is the fully customizable base class which links together components into a cohesive source to be used with other ASPIRE components. A power user can instantiate an instance of each required component and assign them here for complete control.

classDiagram class ClassAvgSource{ src: ImageSource classifier: Class2D class_selector: ClassSelector averager: Averager2D +images() } ClassAvgSource o-- ImageSource ClassAvgSource o-- Class2D ClassAvgSource o-- ClassSelector ClassAvgSource o-- Averager2D class ImageSource{ +images() } class Class2D{ +classify() } class ClassSelector{ +select() } class Averager2D{ +average() }

While that allows for full customization, two helper classes are provided that supply defaults as a jumping off point. Both of these helper sources only require an input Source to be instantiated. They can still be fully customized, but they are intended to start with sensible defaults, so users only need to instantiate the specific components they wish to configure.

classDiagram ClassAvgSource <|-- DebugClassAvgSource ClassAvgSource <|-- DefaultClassAvgSource class DebugClassAvgSource{ src: ImageSource classifier: RIRClass2D class_selector: TopClassSelector averager: BFRAverager2D +images() } class DefaultClassAvgSource{ version="0.11.0" src: ImageSource classifier: RIRClass2D class_selector: NeighborVarianceWithRepulsionClassSelector averager: BFSRAverager2D +images() }

DebugClassAvgSource is designed for use in testing, documentation, and development because it defaults to the simplest components while also maintaining the original input source index ordering. That is, the first 10 class averages from DebugClassAvgSource should correspond with the first 10 source images without requiring any index mappings etc.

DefaultClassAvgSource applies the most sensible defaults available in the current ASPIRE release. DefaultClassAvgSource takes a version string, such as 0.11.0 which will return a specific configuration. This version should allow users to perform a similar experiment across releases as ASPIRE implements improved methods. When a version is not provided, DefaultClassAvgSource defaults to the latest version available.

Classifiers¶

Classifiers take an image Source and attempts to classify into class_indices that identify images with similar viewing angles up to reflection. All Class2D instances are expected to implement a classify method which returns (class_indices, class_refl, class_distances). The three returned variables are expected to be 2D Numpy arrays in a neighbor network format having shape (src.n, n_nbors). So to retrieve the set of input source indices for the first class’s neighbors, we would want class_indices[0,:]. The first index class_indices[0,0] in the set is the index of the reference image used for classification. In this case class_indices[0,0]=0. The actual underlying image would be input_src.images[0], or more generally input_src.images[class_indices[c,0]] for some class c.

No further class selection or ordering occurs during classification. Those methods are broken out into other components.

Currently ASPIRE has a single classification algorithm known as RIRClass2D. This algorithm uses multiple applications of PCA in conjunction with bispectrum analysis to identify nearest neighbors in a rotationally invariant feature space.

classDiagram class Class2D{ +classify() } Class2D <|-- RIRClass2D

Class Selectors¶

Class Selectors consume the output of Class2D and attempt to order and/or filter classes down to a selection. Selecting the “best” classes in cryo-EM problems is still an area of active research. Some common methods are provided, along with an extensible base interface.

Generally, Class Selection comes in two flavors depending on what information is required to perform the selection.

Local Class Selectors¶

For “Local” class selection, we will attempt to use only the information returned from Class2D. In the case of RIRClass2D this would primarily be a network of distances as measured in the compressed feature space.

This approach has two main advantages. First, we already have this information computed as part of classification. Second, it allows us to register and stack a relatively small subset of the “best” classes. Because registration and alignment are computationally expensive this can reduce pipeline run times by an order of magnitude.

classDiagram class ClassSelector{ +select() } ClassSelector <|-- TopClassSelector ClassSelector <|-- RandomClassSelector ClassSelector <|-- NeighborVarianceClassSelector ClassSelector <|-- DistanceClassSelector ClassSelector o-- GreedyClassRepulsionMixin

Global Class Selectors¶

Global Class Selection techniques first compute the entire collection of registered and aligned class averages, then compute some quality measure on all classes.

Many classic experiments computed variance of each class averaged image, sorting to express highest variance. Sometimes this is referred to as contrast. Often times the classes were selected to avoid classes with views already seen. This can be accomplished now by using the VarianceImageQualityFunction in a GlobalWithRepulsionClassSelector.

An SNR based approach is also provided, and a bandpass method should be implemented in a future release. Again, these components are fully customizable and the base interfaces were designed with algorithm developers in mind.

To implementing concrete GlobalClassSelector instances, leverage the subcomponents described below.

classDiagram ClassSelector <|-- GlobalClassSelector class GlobalClassSelector{ averager: Averager2D function: ImageQuaityFunction heap_size: int } GlobalClassSelector *-- ImageQualityFunction GlobalClassSelector ..> Heap GlobalClassSelector <|-- GlobalWithRepulsionClassSelector class ImageQualityFunction{ -_function +__call__() } ImageQualityFunction o-- WeightedImageQualityMixin ImageQualityFunction <|-- BandedSNRImageQualityFunction ImageQualityFunction <|-- VarianceImageQualityFunction ImageQualityFunction <|-- BandpassImageQualityFunction_TBD class WeightedImageQualityMixin{ -_weight_function } WeightedImageQualityMixin <|-- RampWeightedImageQualityMixin WeightedImageQualityMixin <|-- BumpWeightedImageQualityMixin GlobalClassSelector <|-- RampWeightedVarianceImageQualityFunction RampWeightedImageQualityMixin <|-- RampWeightedVarianceImageQualityFunction GlobalClassSelector <|-- BumpWeightedVarianceImageQualityFunction BumpWeightedImageQualityMixin <|-- BumpWeightedVarianceImageQualityFunction

Class Repulsion¶

Class Repulsion are techniques used to avoid classes based on some criterion. Currently we provide GreedyClassRepulsionMixin, but this mix-in class can be mimicked to implement alternate schemes.

GreedyClassRepulsionMixin is based on the following intuition. Assume the selection has in fact ordered the classes so that the “best” classes occur first. It follows that the “best” expression of a viewing angle locus will be the first seen. Now assume the classifier returns classes with closest viewing angles (up to reflections). Then the classes formed by neighbors of the current expression are inferior. The aggressiveness of the neighbor repulsion count is tunable.

In practice, GreedyClassRepulsionMixin is a mix-in designed to be mixed into any other ClassSelector. Note, that repulsion can (and will) dramatically reduce the population of class averages returned.

Image Quality Functions¶

The ImageQualityFunction interface provides a consistent way to bring your own function to measure the quality of a single aligned and registered class average. This function should operate on a single Image, with conversions and broadcasting being handled behind the scenes.

An example would be VarianceImageQualityFunction which computes and returns variance.

Another advantage of using the class is that it exposes and manages a grid cache, which is handy to avoid recomputing the same grid for every image when using spatial methods.

WeightedImageQualityMixin¶

WeightedImageQualityMixin is designed to mix with subclasses of ImageQualityFunction, extending them with a weighted image mask applied prior to the image quality function call.

Two concrete examples are provided BumpWeightedVarianceImageQualityFunction and RampWeightedVarianceImageQualityFunction which apply the respective weight functions prior to the variance calculation.

Again, WeightedImageQualityMixin exposes and manages a grid cache, this time for grid weights.

Averagers¶

Averagers consume from a Source and return averaged images defined by class network arguments class_indices and class_refl. You may find the terms averaging and stacking used interchangeably in this context, so know that averaging does not always imply arithmetic mean.

Some averaging techniques, those subclassing AligningAverager2D have distinct alignment and averaging stages. Others such as expectation-maximization (EM) may perform these internally and provide only an opaque averages stage.

classDiagram class Averager2D{ basis: Basis src: ImageSource +average() } Averager2D ..> ImageStacker Averager2D <|-- AligningAverager2D class AligningAverager2D{ align() } ImageSource *-- Averager2D Averager2D <|-- AligningAverager2D Averager2D <|-- EMAverager2D_TBD Averager2D <|-- FTKAverager2D_TBD AligningAverager2D <|-- BFRAverager2D BFRAverager2D <|-- BFSRAverager2D AligningAverager2D <|-- ReddyChetterjiAverager2D ReddyChetterjiAverager2D <|-- BFSReddyChetterjiAverager2D

Each AligningAverager2D can be configured to use a custom ImageStacker if desired.

ImageStacker¶

ImageStacker provides an interface for the common task of stacking images. Implementations for common stacking methods are provided and should work for both Image and (1D) coefficient stacks. Users experimenting with advanced stacking are responsible for selecting an ImageStacker method appropriate for their data.

Note that the ASPIRE default is naturally MeanImageStacker.

classDiagram class ImageStacker{ stack() } class SigmaRejectionImageStacker{ sigma } class WinsorizedImageStacker{ percentile } ImageStacker <|-- MeanImageStacker ImageStacker <|-- MedianImageStacker ImageStacker <|-- SigmaRejectionImageStacker SigmaRejectionImageStacker .. Gaussian SigmaRejectionImageStacker .. FWHM ImageStacker <|-- WinsorizedImageStacker