Skip to content

Utilities

leopard_em.utils

Utilities submodule for various data and pre- and post-processing tasks.

handle_correlation_mode 

handle_correlation_mode(cross_correlation: Tensor, out_shape: tuple[int, ...], mode: Literal['valid', 'same']) -> torch.Tensor

Handle cropping for cross correlation mode.

NOTE: 'full' mode is not implemented.

Parameters:

  • cross_correlation (Tensor) –

    The cross correlation result.

  • out_shape (tuple[int, ...]) –

    The desired shape of the output.

  • mode (Literal['valid', 'same']) –

    The mode of the cross correlation. Either 'valid' or 'same'. See numpy.correlate for more details.

calculate_ctf_filter_stack 

calculate_ctf_filter_stack(template_shape: tuple[int, int], optics_group: OpticsGroup, defocus_offsets: Tensor, pixel_size_offsets: Tensor) -> torch.Tensor

Calculate searched CTF filter values for a given shape and optics group.

Parameters:

  • template_shape (tuple[int, int]) –

    Desired output shape for the filter, in real space.

  • optics_group (OpticsGroup) –

    OpticsGroup object containing the optics defining the CTF parameters.

  • defocus_offsets (Tensor) –

    Tensor of defocus offsets to search over, in Angstroms.

  • pixel_size_offsets (Tensor) –

    Tensor of pixel size offsets to search over, in Angstroms.

Returns:

  • Tensor –

    Tensor of CTF filter values for the specified shape and optics group. Will have shape (num_pixel_sizes, num_defocus_offsets, h, w // 2 + 1)

load_mrc_image 

load_mrc_image(file_path: str | PathLike | Path) -> torch.Tensor

Helper function for loading an two-dimensional MRC image into a tensor.

Parameters:

  • file_path (str | PathLike | Path) –

    Path to the MRC file.

Returns:

  • Tensor –

    The MRC image as a tensor, converted to float32 for FFT compatibility.

Raises:

  • ValueError –

    If the MRC file is not two-dimensional.

load_mrc_volume 

load_mrc_volume(file_path: str | PathLike | Path) -> torch.Tensor

Helper function for loading an three-dimensional MRC volume into a tensor.

Parameters:

  • file_path (str | PathLike | Path) –

    Path to the MRC file.

Returns:

  • Tensor –

    The MRC volume as a tensor, converted to float32 for FFT compatibility.

Raises:

  • ValueError –

    If the MRC file is not three-dimensional.

load_template_tensor 

load_template_tensor(template_volume: Tensor | Any | None = None, template_volume_path: str | PathLike | Path | None = None) -> torch.Tensor

Load and convert template volume to a torch.Tensor.

This function ensures that the template volume is a torch.Tensor. If template_volume is None, it loads the volume from template_volume_path. If template_volume is not a torch.Tensor, it converts it to one.

Parameters:

  • template_volume (Optional[Union[Tensor, Any]], default: None ) –

    The template volume object, by default None

  • template_volume_path (Optional[Union[str, PathLike, Path]], default: None ) –

    Path to the template volume file, by default None

Returns:

  • Tensor –

    The template volume as a torch.Tensor

Raises:

  • ValueError –

    If both template_volume and template_volume_path are None

read_mrc_to_numpy 

read_mrc_to_numpy(mrc_path: str | PathLike | Path) -> np.ndarray

Reads an MRC file and returns the data as a numpy array.

Attributes:

  • mrc_path (str | PathLike | Path) –

    Path to the MRC file.

Returns:

  • ndarray –

    The MRC data as a numpy array, copied.

read_mrc_to_tensor 

read_mrc_to_tensor(mrc_path: str | PathLike | Path) -> torch.Tensor

Reads an MRC file and returns the data as a torch tensor.

Attributes:

  • mrc_path (str | PathLike | Path) –

    Path to the MRC file.

Returns:

  • Tensor –

    The MRC data as a tensor, copied and converted to float32 if needed.

write_mrc_from_numpy 

write_mrc_from_numpy(data: ndarray, mrc_path: str | PathLike | Path, mrc_header: dict | None = None, overwrite: bool = False) -> None

Writes a numpy array to an MRC file.

NOTE: Writing header information is not currently implemented.

Attributes:

  • data (ndarray) –

    The data to write to the MRC file.

  • mrc_path (str | PathLike | Path) –

    Path to the MRC file.

  • mrc_header (Optional[dict]) –

    Dictionary containing header information. Default is None.

  • overwrite (bool) –

    Overwrite argument passed to mrcfile.new. Default is False.

write_mrc_from_tensor 

write_mrc_from_tensor(data: Tensor, mrc_path: str | PathLike | Path, mrc_header: dict | None = None, overwrite: bool = False) -> None

Writes a tensor array to an MRC file.

NOTE: Not currently implemented.

Attributes:

  • data (ndarray) –

    The data to write to the MRC file.

  • mrc_path (str | PathLike | Path) –

    Path to the MRC file.

  • mrc_header (Optional[dict]) –

    Dictionary containing header information. Default is None.

  • overwrite (bool) –

    Overwrite argument passed to mrcfile.new. Default is False.

volume_to_rfft_fourier_slice 

volume_to_rfft_fourier_slice(volume: Tensor) -> torch.Tensor

Prepares a 3D volume for Fourier slice extraction.

Parameters:

  • volume (Tensor) –

    The input volume.

Returns:

  • Tensor –

    The prepared volume in Fourier space ready for slice extraction.

preprocess_image 

preprocess_image(image_rfft: Tensor, cumulative_fourier_filters: Tensor, bandpass_filter: Tensor, full_image_shape: tuple[int, int], extracted_box_shape: tuple[int, int]) -> torch.Tensor

Preprocess and normalize image FFTs with computed normalization factors.

Parameters:

  • image_rfft (Tensor) –

    The real Fourier-transformed image (unshifted).

  • cumulative_fourier_filters (Tensor) –

    The cumulative Fourier filters. Multiplication of the whitening filter, phase randomization filter, bandpass filter, and arbitrary curve filter.

  • bandpass_filter (Tensor) –

    The bandpass filter used for the image. Used for dimensionality normalization.

  • full_image_shape (tuple[int, int]) –

    The shape of the full image.

  • extracted_box_shape (tuple[int, int]) –

    The shape of the extracted box.

Returns:

  • Tensor –

    Preprocessed and normalized image in Fourier space.

cs_to_pixel_size 

cs_to_pixel_size(cs_vals: Tensor, nominal_pixel_size: float, nominal_cs: float = 2.7) -> torch.Tensor

Convert Cs values to pixel sizes.

Parameters:

  • cs_vals (Tensor) –

    The Cs (spherical aberration) values.

  • nominal_pixel_size (float) –

    The nominal pixel size.

  • nominal_cs (float, default: 2.7 ) –

    The nominal Cs value, by default 2.7.

Returns:

  • Tensor –

    The pixel sizes.

get_cs_range 

get_cs_range(pixel_size: float, pixel_size_offsets: Tensor, cs: float = 2.7) -> torch.Tensor

Get the Cs values for a range of pixel sizes.

Parameters:

  • pixel_size (float) –

    The nominal pixel size.

  • pixel_size_offsets (Tensor) –

    The pixel size offsets.

  • cs (float, default: 2.7 ) –

    The Cs (spherical aberration) value, by default 2.7.

Returns:

  • Tensor –

    The Cs values for the range of pixel sizes.

get_search_tensors 

get_search_tensors(min_val: float, max_val: float, step_size: float, skip_enforce_zero: bool = False) -> torch.Tensor

Get the search tensors (pixel or defocus) for a given range and step size.

Parameters:

  • min_val (float) –

    The minimum value.

  • max_val (float) –

    The maximum value.

  • step_size (float) –

    The step size.

  • skip_enforce_zero (bool, default: False ) –

    Whether to skip enforcing a zero value, by default False.

Returns:

  • Tensor –

    The search tensors.