MaxScoreOverRotations

class MaxScoreOverRotations(shape, scores=None, rotations=None, offset=None, score_threshold=0, shm_handler=None, use_memmap=False, thread_safe=True, only_unique_rotations=False, **kwargs)

Bases: object

Determine the rotation maximizing the score over all possible translations.

Parameters:

shapetuple of int

Shape of array passed to MaxScoreOverRotations.__call__().

scoresBackendArray, optional

Array mapping translations to scores.

rotationsBackendArray, optional

Array mapping translations to rotation indices.

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.

only_unique_rotationsbool, optional

Whether each rotation will be shown only once, False by default.

Attributes:

scoresBackendArray

Mapping of translations to scores.

rotationsBackendArray

Mmapping of translations to rotation indices.

rotation_mappingDict

Mapping of rotations to rotation indices.

offsetBackendArray, optional

Coordinate origin considered during merging, zero by default

Examples

The following achieves the minimal definition of a MaxScoreOverRotations instance

>>> 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

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

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

>>> results = tuple(analyzer)

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 rotation matrices to the indices used in (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_index = results[2][optimal_translation]
>>> for key, value in results[3].items():
>>>     if value != optimal_rotation_index:
>>>         continue
>>>     optimal_rotation = np.frombuffer(key, rotation.dtype)
>>>     optimal_rotation = optimal_rotation.reshape(scores.ndim, scores.ndim)

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.is_shareable

Boolean indicating whether class instance can be shared across processes.

Methods

MaxScoreOverRotations.__call__(scores, ...)	Update the parameter store.
MaxScoreOverRotations.merge(param_stores, ...)	Merge multiple instances of the current class.