Skip to content

analysis

Submodule for analyzing results during the template matching pipeline.

MatchTemplatePeaks

Bases: NamedTuple

Helper class for return value of extract_peaks_and_statistics.

Source code in src/leopard_em/analysis/match_template_peaks.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class MatchTemplatePeaks(NamedTuple):
    """Helper class for return value of extract_peaks_and_statistics."""

    pos_y: torch.Tensor
    pos_x: torch.Tensor
    mip: torch.Tensor
    scaled_mip: torch.Tensor
    psi: torch.Tensor
    theta: torch.Tensor
    phi: torch.Tensor
    relative_defocus: torch.Tensor
    correlation_mean: torch.Tensor
    correlation_variance: torch.Tensor
    total_correlations: int

extract_peaks_and_statistics_p_value(mip, scaled_mip, best_psi, best_theta, best_phi, best_defocus, correlation_average, correlation_variance, total_correlation_positions, p_value_cutoff=0.01, mask_radius=5.0)

Returns peak locations, stats, etc. using the pvalue metric.

Parameters:

Name Type Description Default
mip Tensor

Maximum intensity projection of the match template results.

 required
scaled_mip Tensor

Scaled maximum intensity projection of the match template results.

 required
best_psi Tensor

Best psi angles for each pixel.

 required
best_theta Tensor

Best theta angles for each pixel.

 required
best_phi Tensor

Best phi angles for each pixel.

 required
best_defocus Tensor

Best relative defocus values for each pixel.

 required
correlation_average Tensor

Average correlation value for each pixel.

 required
correlation_variance Tensor

Variance of the correlation values for each pixel.

 required
total_correlation_positions int

Total number of correlation positions calculated during template matching. Must be provided if z_score_cutoff is not provided (needed for the noise model).

 required
p_value_cutoff float

P-value cutoff value for peak detection. Default is 0.01.

 0.01
mask_radius float

Radius for the mask used to filter peaks. Default is 5.0.

 5.0

Returns:

Type Description
MatchTemplatePeaks

A named tuple containing the peak locations, statistics, and other relevant data.
Source code in src/leopard_em/analysis/pvalue_metric.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
def extract_peaks_and_statistics_p_value(
    mip: torch.Tensor,
    scaled_mip: torch.Tensor,
    best_psi: torch.Tensor,
    best_theta: torch.Tensor,
    best_phi: torch.Tensor,
    best_defocus: torch.Tensor,
    correlation_average: torch.Tensor,
    correlation_variance: torch.Tensor,
    total_correlation_positions: int,
    p_value_cutoff: float = 0.01,
    mask_radius: float = 5.0,
) -> MatchTemplatePeaks:
    """Returns peak locations, stats, etc. using the pvalue metric.

    Parameters
    ----------
    mip : torch.Tensor
        Maximum intensity projection of the match template results.
    scaled_mip : torch.Tensor
        Scaled maximum intensity projection of the match template results.
    best_psi : torch.Tensor
        Best psi angles for each pixel.
    best_theta : torch.Tensor
        Best theta angles for each pixel.
    best_phi : torch.Tensor
        Best phi angles for each pixel.
    best_defocus : torch.Tensor
        Best relative defocus values for each pixel.
    correlation_average : torch.Tensor
        Average correlation value for each pixel.
    correlation_variance : torch.Tensor
        Variance of the correlation values for each pixel.
    total_correlation_positions : int
        Total number of correlation positions calculated during template matching. Must
        be provided if `z_score_cutoff` is not provided (needed for the noise model).
    p_value_cutoff : float, optional
        P-value cutoff value for peak detection. Default is 0.01.
    mask_radius : float, optional
        Radius for the mask used to filter peaks. Default is 5.0.

    Returns
    -------
    MatchTemplatePeaks
        A named tuple containing the peak locations, statistics, and other relevant
        data.
    """
    pos_y, pos_x = find_peaks_from_pvalue(
        mip=mip,
        scaled_mip=scaled_mip,
        p_value_cutoff=p_value_cutoff,
        mask_radius=mask_radius,
    )

    # Raise warning if no peaks are found
    if len(pos_y) == 0:
        warnings.warn("No peaks found using p-value metric.", stacklevel=2)

    # Extract peak heights, orientations, etc. from other maps
    return MatchTemplatePeaks(
        pos_y=pos_y,
        pos_x=pos_x,
        mip=mip[pos_y, pos_x],
        scaled_mip=scaled_mip[pos_y, pos_x],
        psi=best_psi[pos_y, pos_x],
        theta=best_theta[pos_y, pos_x],
        phi=best_phi[pos_y, pos_x],
        relative_defocus=best_defocus[pos_y, pos_x],
        correlation_mean=correlation_average[pos_y, pos_x],
        correlation_variance=correlation_variance[pos_y, pos_x],
        total_correlations=total_correlation_positions,
    )

extract_peaks_and_statistics_zscore(mip, scaled_mip, best_psi, best_theta, best_phi, best_defocus, correlation_average, correlation_variance, total_correlation_positions, false_positives=1.0, z_score_cutoff=None, mask_radius=5.0)

Returns peak locations, heights, and pose stats from match template results.

Parameters:

Name Type Description Default
mip Tensor

Maximum intensity projection of the match template results.

 required
scaled_mip Tensor

Scaled maximum intensity projection of the match template results.

 required
best_psi Tensor

Best psi angles for each pixel.

 required
best_theta Tensor

Best theta angles for each pixel.

 required
best_phi Tensor

Best phi angles for each pixel.

 required
best_defocus Tensor

Best relative defocus values for each pixel.

 required
correlation_average Tensor

Average correlation value for each pixel.

 required
correlation_variance Tensor

Variance of the correlation values for each pixel.

 required
total_correlation_positions int

Total number of correlation positions calculated during template matching. Must be provided if z_score_cutoff is not provided (needed for the noise model).

 required
false_positives float

Number of false positives to allow in the image (over all pixels). Default is 1.0 which corresponds to a single false-positive.

 1.0
z_score_cutoff float

Z-score cutoff value for peak detection. If not provided, it is calculated using the Gaussian noise model. Default is None.

 None
mask_radius float

Radius of the mask to apply around the peak, in units of pixels. Default is 5.0.

 5.0

Returns:

Type Description
MatchTemplatePeaks

Named tuple containing the peak locations, heights, and pose statistics.
Source code in src/leopard_em/analysis/zscore_metric.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def extract_peaks_and_statistics_zscore(
    mip: torch.Tensor,
    scaled_mip: torch.Tensor,
    best_psi: torch.Tensor,
    best_theta: torch.Tensor,
    best_phi: torch.Tensor,
    best_defocus: torch.Tensor,
    correlation_average: torch.Tensor,
    correlation_variance: torch.Tensor,
    total_correlation_positions: int,
    false_positives: float = 1.0,
    z_score_cutoff: Optional[float] = None,
    mask_radius: float = 5.0,
) -> MatchTemplatePeaks:
    """Returns peak locations, heights, and pose stats from match template results.

    Parameters
    ----------
    mip : torch.Tensor
        Maximum intensity projection of the match template results.
    scaled_mip : torch.Tensor
        Scaled maximum intensity projection of the match template results.
    best_psi : torch.Tensor
        Best psi angles for each pixel.
    best_theta : torch.Tensor
        Best theta angles for each pixel.
    best_phi : torch.Tensor
        Best phi angles for each pixel.
    best_defocus : torch.Tensor
        Best relative defocus values for each pixel.
    correlation_average : torch.Tensor
        Average correlation value for each pixel.
    correlation_variance : torch.Tensor
        Variance of the correlation values for each pixel.
    total_correlation_positions : int
        Total number of correlation positions calculated during template matching. Must
        be provided if `z_score_cutoff` is not provided (needed for the noise model).
    false_positives : float, optional
        Number of false positives to allow in the image (over all pixels). Default is
        1.0 which corresponds to a single false-positive.
    z_score_cutoff : float, optional
        Z-score cutoff value for peak detection. If not provided, it is calculated using
        the Gaussian noise model. Default is None.
    mask_radius : float, optional
        Radius of the mask to apply around the peak, in units of pixels. Default is 5.0.

    Returns
    -------
    MatchTemplatePeaks
        Named tuple containing the peak locations, heights, and pose statistics.
    """
    if z_score_cutoff is None:
        z_score_cutoff = gaussian_noise_zscore_cutoff(
            num_ccg=mip.numel() * total_correlation_positions,
            false_positives=false_positives,
        )

    # Find the peak locations only in the scaled MIP
    pos_y, pos_x = find_peaks_from_zscore(scaled_mip, z_score_cutoff, mask_radius)

    # Raise warning if no peaks are found
    if len(pos_y) == 0:
        warnings.warn("No peaks found using z-score metric.", stacklevel=2)

    # Extract peak heights, orientations, etc. from other maps
    return MatchTemplatePeaks(
        pos_y=pos_y,
        pos_x=pos_x,
        mip=mip[pos_y, pos_x],
        scaled_mip=scaled_mip[pos_y, pos_x],
        psi=best_psi[pos_y, pos_x],
        theta=best_theta[pos_y, pos_x],
        phi=best_phi[pos_y, pos_x],
        relative_defocus=best_defocus[pos_y, pos_x],
        correlation_mean=correlation_average[pos_y, pos_x],
        correlation_variance=correlation_variance[pos_y, pos_x],
        total_correlations=total_correlation_positions,
    )

gaussian_noise_zscore_cutoff(num_ccg, false_positives=1.0)

Determines the z-score cutoff based on Gaussian noise model and number of pixels.

NOTE: This procedure assumes that the z-scores (normalized maximum intensity projections) are distributed according to a standard normal distribution. Here, this model is used to find the cutoff value such that there is at most 'false_positives' number of false positives in all of the pixels.

Parameters:

Name Type Description Default
num_ccg int

Total number of cross-correlograms calculated during template matching. Product of the number of pixels, number of defocus values, and number of orientations.

 required
false_positives float

Number of false positives to allow in the image (over all pixels). Default is 1.0 which corresponds to a single false-positive.

 1.0

Returns:

Type Description
float

Z-score cutoff.
Source code in src/leopard_em/analysis/zscore_metric.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def gaussian_noise_zscore_cutoff(num_ccg: int, false_positives: float = 1.0) -> float:
    """Determines the z-score cutoff based on Gaussian noise model and number of pixels.

    NOTE: This procedure assumes that the z-scores (normalized maximum intensity
    projections) are distributed according to a standard normal distribution. Here,
    this model is used to find the cutoff value such that there is at most
    'false_positives' number of false positives in all of the pixels.

    Parameters
    ----------
    num_ccg : int
        Total number of cross-correlograms calculated during template matching. Product
        of the number of pixels, number of defocus values, and number of orientations.
    false_positives : float, optional
        Number of false positives to allow in the image (over all pixels). Default is
        1.0 which corresponds to a single false-positive.

    Returns
    -------
    float
        Z-score cutoff.
    """
    tmp = erfcinv(2.0 * false_positives / num_ccg)
    tmp *= np.sqrt(2.0)

    return float(tmp)

match_template_peaks_to_dataframe(peaks)

Convert MatchTemplatePeaks object to a pandas DataFrame.

Source code in src/leopard_em/analysis/match_template_peaks.py 
30
31
32
def match_template_peaks_to_dataframe(peaks: MatchTemplatePeaks) -> pd.DataFrame:
    """Convert MatchTemplatePeaks object to a pandas DataFrame."""
    return pd.DataFrame(peaks._asdict())

match_template_peaks_to_dict(peaks)

Convert MatchTemplatePeaks object to a dictionary.

Source code in src/leopard_em/analysis/match_template_peaks.py 
25
26
27
def match_template_peaks_to_dict(peaks: MatchTemplatePeaks) -> dict:
    """Convert MatchTemplatePeaks object to a dictionary."""
    return peaks._asdict()