Results

Bases: BaseModel2DTM

Correlation table data structure storing possible detections along a 2DTM search.

Attributes:

• correlation_threshold (float) –

  Pre-defined threshold a cross-correlation value must surpass to be included in the correlation table.

• num_observations (int) –

  Total number of detections in the correlation table (number of search indices which surpassed the correlation threshold).

• defocus_offsets (list[float]) –

  List of defocus offsets (in Angstroms) used in the search.

• phi_theta_angles (list[tuple[float, float]]) –

  List out-of-plane rotation angles (in degrees, Euler angles phi and theta, in ZYZ convention) used in the search.

• psi_angles (list[float]) –

  List of in-plane rotation angles (in degrees, Euler angle psi, in ZYZ convention) used in the search.

• search_index (list[int]) –

  Global search index defining defocus offset, phi/theta angles, and psi angle for each detection. Calculated as i * (n_j * n_k) + j * n_k + k, where i is the index of the defocus offset, j is the index of the phi/theta angles, and k is the index of the psi angle. Length will be equal to num_observations.

• x (list[int]) –

  List of x-coordinates (in pixels) of the detections in the micrograph.

• y (list[int]) –

  List of y-coordinates (in pixels) of the detections in the micrograph.

• correlation_value (list[float]) –

  List of cross-correlation values for each detection.

• correlation_mean (list[float]) –

  List of mean cross-correlation values for each detection, calculated across all search indices for the same x/y coordinates.

• correlation_variance (list[float]) –

  List of variance of cross-correlation values for each detection, calculated across all search indices for the same x/y coordinates.

Methods:

• to_dataframe –
• from_dataframe –
• to_hdf5 –
• from_hdf5 –
• from_match_template_results –

to_dataframe() -> pd.DataFrame

from_dataframe(df: DataFrame) -> CorrelationTable

to_hdf5(file_path: str) -> None

/metadata              (attrs: correlation_threshold, num_observations)
/search_space/
    defocus_offsets    float32 1-D
    phi_theta_angles   float32 (n, 2)
    psi_angles         float32 1-D
/detections/
    search_index       int32 1-D
    x                  int32 1-D
    y                  int32 1-D
    correlation_value  float32 1-D
    correlation_mean   float32 1-D
    correlation_variance float32 1-D

from_hdf5(file_path: str) -> CorrelationTable

from_match_template_results(processed_correlation_table: dict, defocus_values: Tensor, euler_angles: Tensor, correlation_average: Tensor, correlation_variance_map: Tensor) -> CorrelationTable

Bases: _MatchTemplateResultBase

Bundles all result tensors and metadata into a single HDF5 file.

/  (root)
│  attrs: leopard_em_version, total_projections,
│         total_orientations, total_defocus
└─ tensors/
       mip                  float32, shape (H, W), gzip-4 (if compress=True)
       scaled_mip           float32, shape (H, W), gzip-4
       correlation_average  float32, shape (H, W), gzip-4
       correlation_variance float32, shape (H, W), gzip-4
       orientation_psi      float32, shape (H, W), gzip-4
       orientation_theta    float32, shape (H, W), gzip-4
       orientation_phi      float32, shape (H, W), gzip-4
       relative_defocus     float32, shape (H, W), gzip-4

Attributes:

• hdf5_path (str) –

  Path to the HDF5 output file.

• allow_file_overwrite (bool) –

  Whether to allow overwriting an existing file. Default is False.

• compress (bool) –

  Whether to apply gzip-4 compression to tensor datasets. Default is True. Disable for faster writes at the cost of larger files.

Methods:

• validate_hdf5_path –

  Validates write permissions and overwrite policy for hdf5_path.

• to_hdf5 –

  Writes tensors and metadata to hdf5_path.

• from_hdf5 –

  Class method that loads an instance from an existing HDF5 file.

validate_hdf5_path() -> Self

export_results() -> None

to_hdf5() -> None

from_hdf5(path: str | PathLike, allow_file_overwrite: bool = True, compress: bool = True) -> MatchTemplateResultHDF5

Bases: _MatchTemplateResultBase

Stores each result tensor in a separate MRC file.

Attributes:

• allow_file_overwrite (bool) –

  Whether to allow overwriting of existing files. Default is False.

• mip_path (str) –

  Output path for the maximum intensity projection MRC file.

• scaled_mip_path (str) –

  Output path for the scaled MIP MRC file.

• correlation_average_path (str) –

  Output path for the correlation average MRC file.

• correlation_variance_path (str) –

  Output path for the correlation variance MRC file.

• orientation_psi_path (str) –

  Output path for the orientation psi MRC file.

• orientation_theta_path (str) –

  Output path for the orientation theta MRC file.

• orientation_phi_path (str) –

  Output path for the orientation phi MRC file.

• relative_defocus_path (str) –

  Output path for the relative defocus MRC file.

Methods:

• validate_paths –

  Validates write permissions and overwrite policy for all eight paths.

• load_tensors_from_paths –

  Reads MRC files from the held paths into memory.

• export_results –

  Writes the held tensors to their respective MRC paths.

validate_paths() -> Self

load_tensors_from_paths() -> None

export_results() -> None