Skip to content

utils

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

handle_correlation_mode(cross_correlation, out_shape, mode)

Handle cropping for cross correlation mode.

NOTE: 'full' mode is not implemented.

Parameters:

Name Type Description Default
cross_correlation Tensor

The cross correlation result.

 required
out_shape tuple[int, ...]

The desired shape of the output.

 required
mode Literal['valid', 'same']

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

 required
Source code in src/leopard_em/utils/cross_correlation.py 
 8
 9
10
11
12
13
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
40
def handle_correlation_mode(
    cross_correlation: torch.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 : torch.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](https://numpy.org/doc/stable/reference/generated/
        numpy.convolve.html#numpy.convolve)
        for more details.
    """
    # Crop the result to the valid bounds
    if mode == "valid":
        slices = [slice(0, _out_s) for _out_s in out_shape]
        cross_correlation = cross_correlation[slices]
    elif mode == "same":
        pass
    elif mode == "full":
        raise NotImplementedError("Full mode not supported")
    else:
        raise ValueError(f"Invalid mode: {mode}")

    return cross_correlation

load_mrc_image(file_path)

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

Parameters:

Name Type Description Default
file_path str | PathLike | Path

Path to the MRC file.

 required

Returns:

Type Description
Tensor

The MRC image as a tensor.

Raises:

Type Description
ValueError

If the MRC file is not two-dimensional.
Source code in src/leopard_em/utils/data_io.py 
 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
def load_mrc_image(file_path: str | os.PathLike | Path) -> torch.Tensor:
    """Helper function for loading an two-dimensional MRC image into a tensor.

    Parameters
    ----------
    file_path : str | os.PathLike | Path
        Path to the MRC file.

    Returns
    -------
    torch.Tensor
        The MRC image as a tensor.

    Raises
    ------
    ValueError
        If the MRC file is not two-dimensional.
    """
    tensor = read_mrc_to_tensor(file_path)

    # Check that tensor is 2D, squeezing if necessary
    tensor = tensor.squeeze()
    if len(tensor.shape) != 2:
        raise ValueError(f"MRC file is not two-dimensional. Got shape: {tensor.shape}")

    return tensor

load_mrc_volume(file_path)

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

Parameters:

Name Type Description Default
file_path str | PathLike | Path

Path to the MRC file.

 required

Returns:

Type Description
Tensor

The MRC volume as a tensor.

Raises:

Type Description
ValueError

If the MRC file is not three-dimensional.
Source code in src/leopard_em/utils/data_io.py 
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
def load_mrc_volume(file_path: str | os.PathLike | Path) -> torch.Tensor:
    """Helper function for loading an three-dimensional MRC volume into a tensor.

    Parameters
    ----------
    file_path : str | os.PathLike | Path
        Path to the MRC file.

    Returns
    -------
    torch.Tensor
        The MRC volume as a tensor.

    Raises
    ------
    ValueError
        If the MRC file is not three-dimensional.
    """
    tensor = read_mrc_to_tensor(file_path)

    # Check that tensor is 3D, squeezing if necessary
    tensor = tensor.squeeze()
    if len(tensor.shape) != 3:
        raise ValueError(
            f"MRC file is not three-dimensional. Got shape: {tensor.shape}"
        )

    return tensor

load_template_tensor(template_volume=None, template_volume_path=None)

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:

Name Type Description Default
template_volume Optional[Union[Tensor, Any]]

The template volume object, by default None

 None
template_volume_path Optional[Union[str, PathLike, Path]]

Path to the template volume file, by default None

 None

Returns:

Type Description
Tensor

The template volume as a torch.Tensor

Raises:

Type Description
ValueError

If both template_volume and template_volume_path are None
Source code in src/leopard_em/utils/data_io.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def load_template_tensor(
    template_volume: Optional[Union[torch.Tensor, Any]] = None,
    template_volume_path: Optional[Union[str, os.PathLike, Path]] = 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[torch.Tensor, Any]], optional
        The template volume object, by default None
    template_volume_path : Optional[Union[str, os.PathLike, Path]], optional
        Path to the template volume file, by default None

    Returns
    -------
    torch.Tensor
        The template volume as a torch.Tensor

    Raises
    ------
    ValueError
        If both template_volume and template_volume_path are None
    """
    if template_volume is None:
        if template_volume_path is None:
            raise ValueError("template_volume or template_volume_path must be provided")
        template_volume = load_mrc_volume(template_volume_path)

    if not isinstance(template_volume, torch.Tensor):
        template = torch.from_numpy(template_volume)
    else:
        template = template_volume

    return template

read_mrc_to_numpy(mrc_path)

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

Attributes:

Name Type Description
mrc_path str | PathLike | Path

Path to the MRC file.

Returns:

Type Description
ndarray

The MRC data as a numpy array, copied.
Source code in src/leopard_em/utils/data_io.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
def read_mrc_to_numpy(mrc_path: str | os.PathLike | Path) -> np.ndarray:
    """Reads an MRC file and returns the data as a numpy array.

    Attributes
    ----------
    mrc_path : str | os.PathLike | Path
        Path to the MRC file.

    Returns
    -------
    np.ndarray
        The MRC data as a numpy array, copied.
    """
    with mrcfile.open(mrc_path) as mrc:
        return mrc.data.copy()

read_mrc_to_tensor(mrc_path)

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

Attributes:

Name Type Description
mrc_path str | PathLike | Path

Path to the MRC file.

Returns:

Type Description
Tensor

The MRC data as a tensor, copied.
Source code in src/leopard_em/utils/data_io.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def read_mrc_to_tensor(mrc_path: str | os.PathLike | Path) -> torch.Tensor:
    """Reads an MRC file and returns the data as a torch tensor.

    Attributes
    ----------
    mrc_path : str | os.PathLike | Path
        Path to the MRC file.

    Returns
    -------
    torch.Tensor
        The MRC data as a tensor, copied.
    """
    return torch.tensor(read_mrc_to_numpy(mrc_path))

write_mrc_from_numpy(data, mrc_path, mrc_header=None, overwrite=False)

Writes a numpy array to an MRC file.

NOTE: Writing header information is not currently implemented.

Attributes:

Name Type Description
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.
Source code in src/leopard_em/utils/data_io.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def write_mrc_from_numpy(
    data: np.ndarray,
    mrc_path: str | os.PathLike | Path,
    mrc_header: Optional[dict] = None,
    overwrite: bool = False,
) -> None:
    """Writes a numpy array to an MRC file.

    NOTE: Writing header information is not currently implemented.

    Attributes
    ----------
    data : np.ndarray
        The data to write to the MRC file.
    mrc_path : str | os.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.
    """
    if mrc_header is not None:
        raise NotImplementedError("Setting header info is not yet implemented.")

    with mrcfile.new(mrc_path, overwrite=overwrite) as mrc:
        mrc.set_data(data)

write_mrc_from_tensor(data, mrc_path, mrc_header=None, overwrite=False)

Writes a tensor array to an MRC file.

NOTE: Not currently implemented.

Attributes:

Name Type Description
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.
Source code in src/leopard_em/utils/data_io.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def write_mrc_from_tensor(
    data: torch.Tensor,
    mrc_path: str | os.PathLike | Path,
    mrc_header: Optional[dict] = None,
    overwrite: bool = False,
) -> None:
    """Writes a tensor array to an MRC file.

    NOTE: Not currently implemented.

    Attributes
    ----------
    data : np.ndarray
        The data to write to the MRC file.
    mrc_path : str | os.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_numpy(data.numpy(), mrc_path, mrc_header, overwrite)