cryomap#

cryocat.core.cryomap.bandpass(input_map, lp_fourier_pixels=None, lp_target_resolution=None, hp_fourier_pixels=None, hp_target_resolution=None, pixel_size=None, lp_gaussian=3, hp_gaussian=2, output_path=None)#

Apply a bandpass filter to an input map using specified low-pass and high-pass filter parameters.

Parameters:

input_mapstr or array_like: The input map to be filtered, either as a filename or as an array.
lp_fourier_pixelsint, optional: Number of pixels/voxels in Fourier space for the low-pass filter. Default is None.
lp_target_resolutionfloat, optional: Target resolution in Angstroms for the low-pass filter. Default is None.
hp_fourier_pixelsint, optional: Number of pixels/voxels in Fourier space for the high-pass filter. Default is None.
hp_target_resolutionfloat, optional: Target resolution in Angstroms for the high-pass filter. Default is None.
pixel_sizefloat, optional: Pixel/voxel size in Angstroms. Default is None.
lp_gaussianint, default=3: Width of the Gaussian falloff for the low-pass filter. Default is 3.
hp_gaussianint, default=2: Width of the Gaussian falloff for the high-pass filter. Default is 2.
output_pathstr, optional: Filename to save the filtered output. If not provided, the filtered map is not saved. Default is None.

Returns:

bandpass_filteredndarray: The bandpass-filtered map.

Notes

The function reads an input map, applies a bandpass filter by creating a mask in Fourier space that combines a low-pass and a high-pass filter, and then applies this mask to the Fourier transform of the input map. The result is transformed back to real space. If an output filename is provided, the result is saved.

cryocat.core.cryomap.binarize(input_map, threshold=0.5)#

Converts a given input map to a binary map based on a specified threshold.

Parameters:

input_maparray_like or str: The input map to binarize. Can be an array or a path to a file containing the map data.
thresholdfloat, default=0.5: The threshold value used for binarization. Values greater than this threshold will be set to 1, and values less than or equal to the threshold will be set to 0. Default is 0.5.

Returns:

binary_mapndarray: The binarized map as a numpy array of integers (0s and 1s).

Examples

>>> input_map = np.array([0.2, 0.6, 0.4, 0.8])
>>> binarize(input_map)
array([0, 1, 0, 1])

cryocat.core.cryomap.calculate_conjugates(vol, filter=None)#

This function calculates the complex conjugates of a volume and its square after applying a Fourier transform and an optional filter.

Parameters:

volndarray: The input volume to be transformed and filtered.
filterndarray, optional: The filter to be applied to the Fourier transform of the volume. If None, no filter is applied. Default is None.

Returns:

conj_targetndarray: The complex conjugate of the Fourier transform of the input volume after applying the filter.
conj_target_sqndarray: The complex conjugate of the square of the filtered volume after applying the Fourier transform.

Notes

The 0-frequency peak of the Fourier transform of the input volume is set to zero before calculating the complex conjugates.

cryocat.core.cryomap.calculate_flcf(vol1, mask, vol2=None, conj_target=None, conj_target_sq=None, filter=None)#

This function calculates the Fast Local Correlation Coefficient (FLCC) map between two volumes (3D arrays).

Parameters:

vol1ndarray: The first volume for which the FLCC map is to be calculated.
maskndarray: The mask to be applied on the volumes.
vol2ndarray, optional: The second volume for which the FLCC map is to be calculated. If not provided, conj_target and conj_target_sq must be provided.
conj_targetndarray, optional: The conjugate of the target volume. Required if vol2 is not provided.
conj_target_sqndarray, optional: The square of the conjugate of the target volume. Required if vol2 is not provided.
filterndarray, optional: The filter to be applied on the volumes.

Returns:

cc_mapndarray: The calculated FLCC map, clipped between 0.0 and 1.0.

Raises:

ValueError: If vol2 is not provided, both conj_target and conj_target_sq must be provided.

cryocat.core.cryomap.calculate_masked_fsc(half_map_a, half_map_b, pixel_size=None, mask=None, n_repeats=10, fourier_cutoff=None, output_path=None)#

Calculate phase-randomisation corrected FSC between two half-maps.

Implements the masked-corrected FSC procedure of Chen et al. (2013, Ultramicroscopy 142:18-25): phases of the unmasked half-maps are randomised beyond fourier_cutoff, the mask is applied in real space after the inverse FFT, and the resulting noise-floor FSC is used to correct the masked FSC.

Parameters:

half_map_astr or ndarray: First half-map: file path or 3-D numpy array.
half_map_bstr or ndarray: Second half-map: file path or 3-D numpy array.
pixel_sizefloat, optional: Pixel size in Angstroms. When given, the x-axis is expressed as spatial frequency in 1/Å; otherwise the Fourier shell index is used.
maskstr or ndarray, optional: Real-space mask. A box-filling mask of ones is used when None.
n_repeatsint, optional: Number of phase-randomisation repeats (default 10). Set to 0 or None to skip phase-randomisation correction.
fourier_cutoffint, optional: Shell index beyond which phases are randomised. Determined from box size automatically when None (box//10 for box<100, box//15 for box<210, 15 otherwise).
output_pathstr, optional: File path for saving results. Extension selects format: .csv – comma-separated table; .xml – ChimeraX-compatible XML. The best available FSC column (corrected or uncorrected) is written.

Returns:

pandas.DataFrame: Columns: x, uncorrected_fsc and, when phase randomisation is performed, corrected_fsc and mean_phase_fsc.

Raises:

ValueError: If half-map shapes do not match, volumes are not cubic 3-D arrays, the mask shape differs from the half-maps, or an unsupported output extension is provided.

cryocat.core.cryomap.compute_ctf_1d(length, pixel_size, voltage, cs, defocus, amplitude, phaseshift, bfactor)#

This function computes the 1D Contrast Transfer Function (CTF) for a given set of parameters.

Parameters:

lengthint: The length of the 1D array for which the CTF is computed.
pixel_sizefloat: The size of the pixel in the image.
voltagefloat: The voltage used in the microscope.
csfloat: The spherical aberration coefficient.
defocusfloat: The defocus value.
amplitudefloat: The amplitude contrast.
phaseshiftfloat: The phase shift value.
bfactorfloat: The B-factor for the envelope function.

Returns:

ctfndarray: The computed 1D Contrast Transfer Function.

cryocat.core.cryomap.crop(input_map, new_size, output_file=None, crop_coord=None)#

This function crops a given input map to a new size. If no crop coordinates are provided, the function will crop from the center of the input map. If an output file is specified, the cropped volume will be written to this file.

Parameters:

input_mapstr or np.array: The input map to be cropped. If a string is provided, it is assumed to be the path to the input map file.
new_sizetuple or str: The desired size of the cropped volume. If a string is provided, it is assumed to be in the format ‘x,y,z’.
output_filestr, optional: The path to the output file where the cropped volume will be written. If not provided, the cropped volume will not be written to a file.
crop_coordtuple or str, optional: The coordinates from which to start cropping. If a string is provided, it is assumed to be in the format ‘x,y,z’. If not provided, the function will crop from the center of the input map.

Returns:

cropped_volumenp.array: The cropped volume.

Notes

see also: trim

cryocat.core.cryomap.deconvolve(input_volume, pixel_size_a, defocus, snr_falloff, deconv_strength, highpass_nyquist, phase_flipped=False, phaseshift=0, output_path=None)#

Deconvolution adapted from MATLAB script tom_deconv_tomo by D. Tegunov (dtegunov/tom_deconv). Example for usage: deconvolve(my_map, 3.42, 6, 1.1, 1, 0.02, false, 0)

Parameters:

input_volumenp.array or string: tomogram volume
pixel_size_afloat: pixel size in Angstroms
defocusfloat: defocus in micrometers, positive = underfocus
snr_fallofffloat: how fast does SNR fall off, i. e. higher values will downweight high frequencies; values like 1.0 or 1.2 seem reasonable
deconv_strengthfloat: how much will the signal be deconvoluted overall, i. e. a global scale for SNR; exponential scale: 1.0 is SNR = 1000 at zero frequency, 0.67 is SNR = 100, and so on
highpass_nyquistfloat: fraction of Nyquist frequency to be cut off on the lower end (since it will be boosted the most)
phase_flippedbool: whether the data are already phase-flipped. Default is False.
phaseshiftint: CTF phase shift in degrees (e. g. from a phase plate). Default is 0.
output_pathstr: Name of the output file for the deconvolved tomogram. Default is None (tomogram will be not written).

Returns:

deconvolved_mapnp.array: deconvolved tomogram

cryocat.core.cryomap.em2mrc(map_name, invert=False, overwrite=True, voxel_size=1.0, output_path=None)#

Convert a file in EM format to MRC format.

Parameters:

map_namestr: The name of the input map file to be converted.
invertbool, default=False: If True, the data will be inverted (multiplied by -1). Default is False.
overwritebool, default=True: If True, allows overwriting of the output file if it already exists. Default is True.
voxel_size: float, default=1.0: The size of the voxels to store in the header of the MRC files. Defaults to 1.0.
output_pathstr, optional: The name of the output MRC file. If None, the output name will be derived from map_name by replacing the last two characters with ‘mrc’.

Returns:

None: The function writes the converted data to the specified output file.

Raises:

ValueError: If input map_name is not a valid .em file path

cryocat.core.cryomap.extract_subvolume(volume, coordinates, subvolume_shape, enforce_shape=False, output_file=None)#

Extracts a subvolume from a given volume.

Parameters:

volumendarray: The 3D array from which to extract the subvolume.
coordinatestuple: The (x, y, z) coordinates of the center of the subvolume to extract.
subvolume_shapetuple: The (x, y, z) shape of the subvolume to extract.
enforce_shapebool, optional: If True, the final volume will have the same shape as the original volume and the voxels outside the region of interest will be set to the mean value of the original volume. Default is False.
output_filestr, optional: If provided, the extracted subvolume will be written to this file.

Returns:

subvolumendarray: The extracted subvolume.

Notes

The function first calculates the start and end indices for the volume and subvolume. Then it creates an empty subvolume with the same shape as the desired subvolume, filled with the mean value of the original volume. The values from the original volume are then copied into the subvolume. If an output file is provided, the subvolume is written to this file.

cryocat.core.cryomap.flip(input_map, axis='z', output_path=None)#

Function to flip a given input map along specified axis.

Parameters:

input_maparray_like: The input map to be flipped.
axisstr, optional: The axis along which to flip the input map. Default is “z”.
output_pathstr, optional: The name of the output file. If not provided, the function will return the flipped map.

Returns:

output_maparray_like: The flipped map.

Notes

The function reads the input map, flips it along the specified axis, and writes the output map to a file if an output name is provided.

cryocat.core.cryomap.get_cross_slices(input_map, slice_half_dim=None, slice_numbers=None, axis=None)#

This function generates cross slices across an axis from a given input map.

Parameters:

input_maparray_like: The input map from which to generate cross slices.
slice_half_dimint, optional: The half dimension of the slice. If None, the slice will cover the entire dimension of the input map.
slice_numbersarray_like, optional: The slice numbers to use. If None, the slice numbers will be calculated as the ceiling of half the shape of the input map.
axisarray_like, optional: The axis along which to generate the slices. If None, slices will be generated along all axes.

Returns:

cross_sliceslist: A list of cross slices generated from the input map.

Notes

The function first reads the input map and checks the axis and slice numbers. If the axis is not provided, it defaults to [0, 1, 2]. If the slice numbers are not provided, they are calculated as the ceiling of half the shape of the input map. The function then generates the cross slices along the specified axis and returns them as a list.

cryocat.core.cryomap.get_filter_radius(edge_size, fourier_pixels, target_resolution, pixel_size)#

Calculate the filter radius based on either direct Fourier pixel/voxel specification or target resolution.

Parameters:

edge_sizefloat: Size of the edge of the image/map in pixels/voxels.
fourier_pixelsint, optional: Number of pixels in the Fourier space. Default is None.
target_resolutionfloat, optional: Desired resolution to achieve. Default is None.
pixel_sizefloat, optional: Size of a pixel/voxel in the image/map. Default is None.

Returns:

int: Calculated radius in pixels/voxels for the filter.

Raises:

ValueError: If neither fourier_pixels nor both target_resolution and pixel_size are specified.

Notes

The function requires either a direct specification of the Fourier pixels or both the target resolution and pixel size to compute the filter radius.

cryocat.core.cryomap.get_start_end_indices(coord, volume_shape, subvolume_shape)#

This function calculates the start and end indices of a subvolume within a larger volume, given the center coordinate of the subvolume.

Parameters:

coordarray_like: The center coordinate of the subvolume.
volume_shapearray_like: The shape of the larger volume.
subvolume_shapearray_like: The shape of the subvolume.

Returns:

volume_start_clipndarray: The start indices of the subvolume within the larger volume, after being clipped to ensure they are within the volume.
volume_end_clipndarray: The end indices of the subvolume within the larger volume, after being clipped to ensure they are within the volume.
subvolume_startndarray: The start indices of the subvolume, relative to its own shape.
subvolume_endndarray: The end indices of the subvolume, relative to its own shape.

Notes

The function first calculates the start and end indices of the subvolume within the larger volume, without considering whether they are within the volume. It then clips these indices to ensure they are within the volume. Finally, it calculates the start and end indices of the subvolume, relative to its own shape.

cryocat.core.cryomap.highpass(input_map, fourier_pixels=None, target_resolution=None, pixel_size=None, gaussian=2, output_path=None)#

Apply a highpass filter to a given input map using Fourier transform methods.

Parameters:

input_mapstr or array_like: The input map filename or its numpy array.
fourier_pixelsint, optional: Number of pixels/voxels to use in the Fourier space. Default is None.
target_resolutionfloat, optional: The target resolution in Angstroms for the highpass filter. Default is None.
pixel_sizefloat, optional: The size of each pixel/voxel in the input map in Angstroms. Default is None.
gaussianint, default=2: The width of the Gaussian fall-off in pixels/voxels. Default is 2.
output_pathstr, optional: The filename to save the filtered output. If None, the filtered map is not saved. Default is None.

Returns:

filtered_mapndarray: The highpass filtered map as a numpy array.

Notes

The function reads an input map, calculates the necessary filter radius based on the provided parameters, applies a spherical highpass filter in Fourier space, and optionally saves the result to a file.

cryocat.core.cryomap.invert_contrast(input_map, output_path=None)#

Invert the contrast of an input volume map.

Parameters:

input_mapstr or numpy.ndarray: The path to the input volume map file or the volume map data itself.
output_pathstr, optional: The name of the output file where the inverted volume map will be saved. If not provided, the output will not be saved to a file.

Returns:

numpy.ndarray: The inverted volume map.

Notes

The contrast is inverted by multiplying the input map by -1. The data type of the output file will be set to single precision if the input map is of type float64; otherwise, it will retain the original data type.

cryocat.core.cryomap.lowpass(input_map, fourier_pixels=None, target_resolution=None, pixel_size=None, gaussian=3, output_path=None)#

Apply a lowpass filter to a given input map using Fourier transform methods.

Parameters:

input_mapstr or array_like: The input map to be filtered, either as a file path or as an array.
fourier_pixelsint, optional: Number of pixels/voxels in the Fourier space representation. Default is None.
target_resolutionfloat, optional: The target resolution in Angstroms for the filtering process. Default is None.
pixel_sizefloat, optional: The size of each pixel/voxel in the input map in Angstroms.
gaussianint, default=3: Width of the Gaussian falloff for the low-pass filter. Default is 3.
output_pathstr, optional: The file name to save the filtered map. If not provided, the map is not saved. Default is None.

Returns:

filtered_mapndarray: The filtered map as a numpy array.

Examples

>>> # For input map with box size 100 and pixel size 7.89
>>> filtered = lowpass('input_map.mrc', target_resolution=20, pixel_size=7.89)
The target resolution corresponds to 39 pixels.

>>> # For input map with box size 100 and pixel size 7.89
>>> filtered = lowpass('input_map.mrc', fourier_pixels=39, pixel_size=7.89)
The target resolution is 20.23 Angstroms.

cryocat.core.cryomap.mrc2em(map_name, invert=False, overwrite=True, output_path=None)#

Convert a file in MRC format to EM format.

map_namestr: The name of the input map file to be converted.
invertbool, default=False: If True, the data will be inverted (multiplied by -1). Default is False.
overwritebool, default=True: If True, allows overwriting of the output file if it already exists. Default is True.
output_pathstr, optional: The name of the output EM file. If None, the output name will be derived from map_name by replacing the last three characters with ‘em’.

Returns:

None: The function writes the converted data to the specified output file.

Raises:

ValueError: If the provided file name does not end with .em extension.

cryocat.core.cryomap.normalize(input_map)#

Normalize a given map by standardizing its values.

Parameters:

mapstr or numpy.ndarray: The input map to be normalized.

Returns:

numpy.ndarray: The normalized map with zero mean and unit variance.

Notes

This function reads the input map, computes its mean and standard deviation, and then normalizes the map by subtracting the mean and dividing by the standard deviation.

Examples

>>> normalized_map = normalize(my_map)

cryocat.core.cryomap.normalize_under_mask(ref, mask)#

A function to take a reference volume and a mask, and normalize the area under the mask to 0-mean and standard deviation of 1. Based on stopgap code by W.Wan

Parameters:

refnp.ndarray
masknp.ndarray

Returns:

norm_refnp.ndarray: The map with the area under the mask normalized.

cryocat.core.cryomap.pad(input_volume, new_size, fill_value=None)#

Pads an input volume to a new size.

This function reads an input volume, calculates the mean of the volume if no fill value is provided, and creates a new volume of the specified size filled with the mean or provided fill value. The original volume is then placed in the center of the new volume.

Parameters:

input_volumendarray: The input volume to be padded.
new_sizetuple: The desired size of the new volume. Must be a 3-element tuple.
fill_valuefloat, optional: The value to fill the new volume with. If None, the new volume is filled with the mean of the input volume.

Returns:

padded_volumendarray: The padded volume of the new size.

Notes

The original volume is placed in the center of the new volume. If the new size is not an integer multiple of the original size, the original volume is placed such that there is an equal number of padding voxels on either side of the volume in each dimension.

cryocat.core.cryomap.pixels2resolution(fourier_pixels, edge_size, pixel_size, print_out=True)#

Calculate the resolution in Angstroms based on Fourier pixel count, edge size, and pixel size.

Parameters:

fourier_pixelsint: Number of pixels in the Fourier space.
edge_sizefloat: Size of the edge of the image in pixels/voxels.
pixel_sizefloat: Size of one pixel/voxel in Angstroms.
print_outbool, default=True: Flag to determine whether to print the resolution. Default is True.

Returns:

float: The calculated resolution in Angstroms.

Examples

>>> pixels2resolution(100, 200, 1.5)
The target resolution is 3.0 Angstroms.
3.0

cryocat.core.cryomap.place_object(input_object, motl, volume_shape=None, volume=None, feature_to_color='object_id')#

Places an object or a list of objects into a volume based on the given motion list (motl).

Parameters:

input_objectstr or list: The object or list of objects to be placed. If a string is provided, it is assumed to be a path to the object file.
motlobject: The motion list containing the rotations and coordinates for placing the objects.
volume_shapetuple, optional: The shape of the volume in which the objects are to be placed. If not provided, the volume parameter must be provided.
volumestr, optional: The volume in which the objects are to be placed. If not provided, the volume_shape parameter must be provided.
feature_to_colorstr, default=”object_id”: The feature in the motion list dataframe to use for coloring the objects.

Returns:

object_containerndarray: The volume with the objects placed.

Notes

The objects are rotated according to the rotations in the motl list and placed at the coordinates in the motl list. The objects are colored according to the feature_to_color parameter. If the input_object is a list, each object in the list is placed according to the corresponding rotation and coordinate in the motl list. If the input_object is a single object, it is placed at each rotation and coordinate in the motl list.

cryocat.core.cryomap.read(input_map, transpose=True, data_type=None)#

Reads a map file (from the file or numpy array) and returns the data as a numpy array.

Parameters:

input_mapstr or numpy.ndarray: The input map file name or a numpy array containing the map data. The accepted formats are MRC and EM.
transposebool, optional: Whether to transpose the data. Default is True.
data_typenumpy.dtype, optional: The desired data type of the returned array. If None, the data type is not modified.

Returns:

numpy.ndarray: The map data as a numpy array.

Raises:

ValueError: If the input map file name does not have a valid extension. If the input map file is not a valid path or numpy array.

Notes

This function supports reading map files with the following extensions: .mrc, .rec, .st, .ali, .em.

If the input_map is a string, the function will attempt to open the file and read the data. If the input_map is a numpy array, it will be directly used as the map data.

If transpose is True, the data will be transposed using the transpose(2, 1, 0) method.

If data_type is not None, the data will be cast to the specified data type using the astype method.

Examples

>>> data = read("map.mrc")
>>> data = read("map.em", transpose=False, data_type=np.float32)
>>> data = read(np.random.rand(10, 10, 10))

cryocat.core.cryomap.read_hdf5(hdf5_name, dataset_name='predictions', print_datasets=False)#

Read a dataset from an HDF5 file.

Parameters:

hdf5_namestr: The name of the HDF5 file to read from.
dataset_namestr, defaults=’predictions’: The name of the dataset to read from the HDF5 file. Default is ‘predictions’.
print_datasetsbool, default=False: If True, prints the names of available datasets in the HDF5 file. Default is False.

Returns:

numpy.ndarray: The data from the specified dataset as a NumPy array.

Raises:

FileNotFoundError: If the specified HDF5 file does not exist.
KeyError: If the specified dataset name does not exist in the HDF5 file.

cryocat.core.cryomap.recenter(map, new_center)#

Recenter a given map around a new center.

Parameters:

mapstr or ndarray: The input map to be recentered. If a string is passed, that is assumed to be the path to the map file.
new_centerndarray: The new center coordinates for the map, with relation to the coordinate frame of the map (eg. box size).

Returns:

trans_structndarray: The recentered map.

Notes

The function creates a transformation matrix, calculates the shift required to move the center of the map to the new center, applies the transformation to the map, and returns the recentered map.

cryocat.core.cryomap.resolution2pixels(resolution, edge_size, pixel_size, print_out=True)#

Calculate the number of Fourier pixels/voxels corresponding to a given resolution for a specific edge size and pixel size.

Parameters:

resolutionfloat: The target resolution to convert to Fourier pixels/voxels.
edge_sizefloat: The size of the edge in pixels/voxels.
pixel_sizefloat: The size of one pixel/voxel in Angstroms.
print_outbool, default=True: Flag to determine whether to print the resolution. Default is True.

Returns:

int: The number of pixels/voxels corresponding to the given resolution.

Notes

This is the value one should use for low-pass and high-pass filters in STOPGAP, GAPSTOP(TM), and novaSTA.

cryocat.core.cryomap.rotate(input_map, rotation=None, rotation_angles=None, coord_space='zxz', transpose_rotation=False, degrees=True, spline_order=3, output_path=None)#

Rotate a 3D input map using a specified rotation matrix or rotation angles.

Parameters:

input_mapstr or numpy.ndarray: The input 3D map to be rotated.
rotationRotation, optional: A rotation object representing the rotation to be applied. If provided, rotation_angles (if provided) will not be considered. Default is None.
rotation_anglesarray_like, optional: Angles for rotation in the specified coordinate space. If provided, they will be considered only if rotation is not be specified. Default is None.
coord_spacestr, default=’zxz’: The coordinate space for the rotation angles. Default is ‘zxz’.
transpose_rotationbool, default=False: If True, the transpose of the rotation matrix will be used. Default is False.
degreesbool, default=True: If True, the rotation angles are interpreted as degrees. Default is True.
spline_orderint, default=3: The order of the spline used for interpolation. Default is 3.
output_pathstr, optional: If specified, the rotated structure will be written to this file. Default is None.

Returns:

rot_structnumpy.ndarray: The rotated 3D map.

Raises:

ValueError: If neither rotation nor rotation_angles is specified.

cryocat.core.cryomap.scale(input_map, scaling_factor, output_path=None)#

Scales an input map by a given scaling factor.

Parameters:

input_mapstr or np.ndarray: The input map to be scaled passed as a numpy.ndarray or as the path to its file.
scaling_factorfloat: The factor by which to scale the input map (a value grater than one indicates upscaling, between 0 and downscaling). If the scaling factor is greater than 1, anti-aliasing is turned off.
output_pathstr, optional: The name of the output file to which to write the scaled map. If not provided, the scaled map will not be saved.

Returns:

scaled_mapndarray: The scaled map. If the dtype of the scaled map is float64, it is cast to float32 before being returned.

Notes

The function reads the input map, applies a scaling transformation using bicubic interpolation, and optionally saves the result to a specified output file. The output map is converted to float32 if the original scaled map is of type float64.

cryocat.core.cryomap.shift(map, delta)#

Shifts the input map by a given delta.

Parameters:

mapndarray: The input map to be shifted. It should be a 3D array.
deltafloat: The amount by which to shift the map.

Returns:

shifted_mapndarray: The shifted map. It is a 3D array of the same shape as the input map.

Notes

This function uses the Fourier shift theorem to perform the shift, which involves a Fourier transform, a multiplication by a phase shift factor, and an inverse Fourier transform.

cryocat.core.cryomap.shift2(input_map, delta, output_path=None)#

Shifts an input map by a specified delta.

Parameters:

input_mapstr or np.ndarray: The input map to be shifted. If a string is provided, it is assumed to be a filename from which to read the map.
deltaarray_like: The shift to apply to the input map. Must be of length 3.
output_pathstr, optional: If provided, the shifted map will be written to a file with this name. The data type of the output will be np.single.

Returns:

shifted_mapnp.ndarray: The input map, shifted by the specified delta.

Notes

The shift is applied using an affine transformation with a matrix that is the identity except for the last column, which is set to the negative of the delta. The mode of the affine transformation is “grid-wrap”.

cryocat.core.cryomap.symmetrize_volume(vol, symmetry)#: Symmetrize the input volume based on the specified symmetry.

cryocat.core.cryomap.trim(input_map, trim_start, trim_end, output_path=None)#

Trims a 3D map to a specified range.

Parameters:

input_mapndarray: The 3D map to be trimmed.
trim_startarray_like: The starting coordinates for the trim. Must be a 3-element array-like object.
trim_endarray_like: The ending coordinates for the trim. Must be a 3-element array-like object.
output_pathstr, optional: If provided, the trimmed map will be written to a file with this name. The file will be written in single precision float format.

Returns:

output_mapndarray: The trimmed 3D map.

Notes

The trim_start and trim_end parameters are inclusive. That is, the output_map will include the voxels at these coordinates. If either trim_start or trim_end is beyond the bounds of input_map, it will be adjusted to fit within the bounds. see also: crop

cryocat.core.cryomap.write(data_to_write, file_name, transpose=True, data_type=None, voxel_size=1.0, overwrite=True)#

Write data to a specified file in a given format.

Parameters:

data_to_writenumpy.ndarray: The data array to be written to the file. It can be of any shape and type.
file_namestr: The name of the file to which the data will be written. The file extension must be one of the following: ‘.mrc’, ‘.rec’, or ‘.em’.
transposebool, default=True: If True (default), the data will be transposed before writing. The transposition will change the order of the axes to (2, 1, 0). Default is True.
data_typetype, optional: If specified, the data will be cast to this type before writing. If None (default), the original data type will be used.
voxel_size: float, default=1.0: The size of the voxels to store in the header of the MRC files. Note that .em files do not store such in the header and this value is therefore ignored. Defaults to 1.0.
overwritebool, default=True: If True (default), existing files will be overwritten. If False, an error will be raised if the file already exists. Default is True.

Raises:

ValueError: If the provided file name does not end with one of the allowed extensions (‘.mrc’, ‘.rec’, or ‘.em’).

Notes

The function will convert the data to float32 if the original data type is float64 before writing to the file.

cryocat.core.cryomap.write_hdf5(map_name, labels=None, weight=None, output_path=None)#

Write data to an HDF5 file.

Parameters:

map_namestr: The name of the input file containing the data to be written.
labelsstr, optional: The name of the input file containing the labels to be written. If provided, the labels will be stored in the HDF5 file. Default is None.
weightstr, optional: The name of the input file containing the weights to be written. If provided, the weights will be stored in the HDF5 file. Default is None.
output_pathstr, optional: The name of the output HDF5 file. If not provided, the output file will be named by replacing the last three characters of map_name with ‘hdf5’. Default is None.

Returns:

None: This function does not return any value. It writes the data, labels, and weights to the specified HDF5 file.

Raises:

ValueError: If the provided file name does not end with .em or .mrc extension.