MaxScoreOverRotations

class MaxScoreOverRotations(shape, offset=None, score_threshold=0, shm_handler=None, use_memmap=False, inversion_mapping=False, jax_mode=False, **kwargs)

Bases: AbstractAnalyzer

Determine the rotation maximizing the score over all possible translations.

Parameters:

shapetuple of int

Shape of array passed to MaxScoreOverRotations.__call__().

offsetBackendArray, optional

Coordinate origin considered during merging, zero by default.

score_thresholdfloat, optional

Minimum score to be considered, zero by default.

shm_handlermultiprocessing.managers.SharedMemoryManager, optional

Shared memory manager, defaults to memory not being shared.

use_memmapbool, optional

Memmap internal arrays, False by default.

thread_safe: bool, optional

Allow class to be modified by multiple processes, True by default.

inversion_mappingbool, optional

Do not use rotation matrix bytestrings for intermediate data handling. This is useful for GPU backend where analyzers are not shared across devices and every rotation is only observed once. It is generally safe to deactivate inversion mapping, but at a cost of performance.

Examples

The following achieves the minimal definition of a MaxScoreOverRotations instance

>>> import numpy as np
>>> from tme.analyzer import MaxScoreOverRotations
>>> analyzer = MaxScoreOverRotations(shape=(50, 50))

The following simulates a template matching run by creating random data for a range of rotations and sending it to analyzer via its __call__ method

>>> state = analyzer.init_state()
>>> for rotation_number in range(10):
>>>     scores = np.random.rand(50,50)
>>>     rotation = np.random.rand(scores.ndim, scores.ndim)
>>>     state = analyzer(state, scores=scores, rotation_matrix=rotation)

The aggregated scores can be extracted by invoking the result method of analyzer

>>> results = analyzer.result(state)

The results tuple contains (1) the maximum scores for each translation, (2) an offset which is relevant when merging results from split template matching using MaxScoreOverRotations.merge(), (3) the rotation used to obtain a score for a given translation, (4) a dictionary mapping indices used in (2) to rotation matrices (2).

We can extract the optimal_score, optimal_translation and optimal_rotation as follows

>>> optimal_score = results[0].max()
>>> optimal_translation = np.where(results[0] == results[0].max())
>>> optimal_rotation = results[2][optimal_translation]

The outlined procedure is a trivial method to identify high scoring peaks. Alternatively, PeakCaller offers a range of more elaborate approaches that can be used.

Attributes

MaxScoreOverRotations.shareable

Indicate whether the analyzer can be shared across processes.

Methods

MaxScoreOverRotations.__call__(state, ...)	Update the parameter store.
MaxScoreOverRotations.correct_background(state)	Applies flat-fielding correction to scores f as
MaxScoreOverRotations.init_state()	Initialize the analysis state.
MaxScoreOverRotations.merge(results[, ...])	Merge multiple instances of the current class.
MaxScoreOverRotations.result(state[, ...])	Finalize the analysis result with optional postprocessing.