tiltstack#

class cryocat.core.tiltstack.TiltStack(tilt_stack, input_order='xyz', output_order='xyz')#

Bases: object

correct_order(new_data=None)#

Corrects the order of the data and ensures it is of the correct type.

Parameters:

new_dataarray-like, optional: The new data to be corrected. If None, the method will use the instance’s data. Default is None.

Returns:

array: The corrected data, which is either the new data with the correct type and order, or the instance’s data if no new data is provided.

Notes

The method checks if the data type of the provided or instance data matches the expected data type. If not, it converts the data to the expected type. Additionally, if the current order of the data does not match the desired output order, the data is transposed to the correct order.

write_out(output_file, new_data=None)#

Writes data to a specified output file.

Parameters:

output_filestr: The path to the output file where data will be written.
new_dataoptional: The data to write to the output file. If not provided, the method will use the instance’s data. Default is None.

Returns:

None

Notes

This method uses the cryomap.write function to perform the actual writing of data.

cryocat.core.tiltstack.bin(tilt_stack, binning_factor, output_file=None, input_order='xyz', output_order='xyz')#

Binning of a tilt stack using local mean downscaling.

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be binned.
binning_factorint: The factor by which to downscale the tilt stack.
output_filestr, optional: The file path to save the binned tilt stack. If None, the output will not be saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack binned data in the specified output order.

Notes

This function utilizes local mean downscaling to reduce the size of the tilt stack by the specified binning factor. The output can be saved to a file if an output file path is provided.

cryocat.core.tiltstack.calculate_total_dose_batch(tomo_list, prior_dose_file_format, dose_per_image, output_file_format)#

Calculate the total dose for a batch of tilt series and save the results to output files.

Parameters:

tomo_liststr or array-like: A list of tilt series to be processed.
prior_dose_file_formatstr: The file format string for the prior dose files, which should include a placeholder for the tilt series identifier.
dose_per_imagefloat: The dose value to be applied per image in the tilt series.
output_file_formatstr: The file format string for the output files, which should include a placeholder for the tilt series identifier.

Returns:

None: The function saves the total dose results to files specified by the output_file_format.

Notes

The function uses the ioutils module to load the tilt series list and replace patterns in file names. The total dose is calculated using the calculate_total_dose function and results are saved using numpy.savetxt.

cryocat.core.tiltstack.crop(tilt_stack, new_width=None, new_height=None, output_file=None, input_order='xyz', output_order='xyz')#

Crop a tilt stack to a specified width and height, and optionally save the result to a file.

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be cropped specified either as a path or array-like data.
new_widthint, optional: The desired width of the cropped output. If None, the original width is used. Defaults to None.
new_heightint, optional: The desired height of the cropped output. If None, the original height is used. Defaults to None.
output_filestr, optional: The file path where the cropped tilt stack will be saved. If None, the output is not saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack data in the desired order.

Notes

The cropping is performed around the center of the original tilt stack. The function modifies the tilt stack in place and saves the cropped data if an output file is specified.

cryocat.core.tiltstack.deconvolve(tilt_stack, pixel_size_a, defocus, defocus_file_type='gctf', snr_falloff=1.2, deconv_strength=1.0, highpass_nyquist=0.02, phase_flipped=False, phaseshift=0.0, output_file=None, input_order='xyz', output_order='xyz')#

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

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be deconvolved.
pixel_size_afloat: Pixel size in Angstroms.
defocusfloat, int, str or array-like: Defocus in micrometers, positive = underfocus, or file from CTF estimation.
defocus_file_typestr, default=’gctf’: In case the defocus is specified as a file, the type of the file has to be specified (ctffind4, gctf, warp).
snr_fallofffloat, default=1.2: How fast does SNR fall off, i. e. higher values will downweight high frequencies; values like 1.0 or 1.2 seem reasonable. Defaults to 1.2.
deconv_strengthfloat, default=1.0: 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. Defaults to 1.0.
highpass_nyquistfloat, default=0.02: Fraction of Nyquist frequency to be cut off on the lower end (since it will be boosted the most). Defaults to 0.02.
phase_flippedbool, default=False: Whether the data are already phase-flipped. Defaults to False.
phaseshiftfloat, default=0: CTF phase shift in degrees (e. g. from a phase plate). Defaults to 0.
output_filestr, optional: Name of the output file for the deconvolved stack. Defaults to None (tilt stack will be not written). Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

deconvolved_stacknumpy.ndarray: Deconvolved tilt stack data.

cryocat.core.tiltstack.dose_filter(tilt_stack, pixel_size, total_dose, output_file=None, input_order='xyz', output_order='xyz')#

Apply a dose filter to a tilt stack of images.

Parameters:

tilt_stackstr or array-like: The input tilt stack data containing the images to be filtered.
pixel_sizefloat: The size of a pixel in the same units as the tilt stack in Angstroms.
total_dosestr or array_like: The total dose for each tilt image in the stack specified either by a file path or directly as an array.
output_filestr, optional: The file path to save the filtered tilt stack. If None, the output will not be saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack data with the dose filter applied.

Notes

This function calculates a frequency array based on the pixel size and applies a dose filter to each image in the tilt stack. The filtered images are then saved to the specified output file if provided.

cryocat.core.tiltstack.dose_filter_single_image(image, dose, freq_array)#

Filter a single image based on dose and frequency array using Fourier transform.

Parameters:

imagendarray: The input image to be filtered, represented as a 2D array.
dosefloat: The dose value used to calculate the exposure-dependent amplitude attenuator.
freq_arrayndarray: The frequency array corresponding to the image, used in the calculation of the attenuator.

Returns:

numpy.ndarray: The filtered image, represented as a 2D array, with the same shape as the input image.

Notes

This function applies a frequency-dependent attenuation based on the dose, using parameters derived from the Grant and Grigorieff paper. The Fourier transform is utilized to perform the filtering in the frequency domain.

cryocat.core.tiltstack.equalize_histogram(tilt_stack, eh_method='contrast_stretching', output_file=None, input_order='xyz', output_order='xyz')#

Equalizes the histogram of a tilt stack using specified methods.

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be processed.
eh_methodstr, default=’contrast_stretching’: The method used for histogram equalization. Options are: - ‘contrast_stretching’: Applies contrast stretching. - ‘equalization’: Applies standard histogram equalization. - ‘adaptive_eq’: Applies adaptive histogram equalization. Defaults to ‘contrast_stretching’.
output_filestr, optional: The file path where the output data will be saved. If None, the data will not be saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack data with equalized histograms.

Raises:

ValueError: If an unknown histogram equalization method is specified.

cryocat.core.tiltstack.flip_along_axes(tilt_stack, axes, output_file=None, input_order='xyz', output_order='xyz')#

Flip the tilt stack along specified axes and optionally save the result to a file.

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be flipped along one or more axes.
axeslist of str: The axes along which to flip the tilt stack. Acceptable values are ‘x’, ‘y’, and ‘z’.
output_filestr, optional: The file path to save the flipped tilt stack. If None, the result is not saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: The flipped tilt stack data in the specified output order.

Raises:

ValueError: If the axes contains different values than ‘x’,’y’,’z’.

Notes

The flipping correspond to IMOD’s ‘clip’ function with options flipx, flipy, flipz. If multiple axes are specified it correspond to concatenation of those IMOD operations. For example, axes=[‘x’,’y’] will correspond to calling clip flipx input.mrc output_x.mrc and subsequently clip flipy ouput_x.mrc output_y.mrc. This is not equivalent to the result of calling clip flipxy input.mrc output.mrc!

cryocat.core.tiltstack.merge(file_path_pattern, output_file=None, output_order='xyz')#

Merge multiple files matching a given pattern into a single stack.

Parameters:

file_path_patternstr: A pattern for file paths to match files that will be merged. This can include wildcards, i.e. tilt.mrc* will load all files from given folder that start with tilt.mrc followed by numbering such as tilt.mrc001, tilt.mrc2 etc.
output_filestr, optional: The path to the output file where the merged stack will be saved. If None, the stack will not be saved to a file. Defaults to None.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

TiltStack: A TiltStack object containing the merged data in the specified output order.

Notes

This function retrieves all files matching the specified pattern, sorts them, and then merges their contents into a single stack. The resulting stack is saved to the specified output file if provided. Since the data are always loaded first (having always ‘zyx’ order), the input_order is irrelevant and thus not required.

Examples

>>> merged_stack = merge("data/*.mrc", output_file="merged_output.mrc", output_order="xyz")

cryocat.core.tiltstack.remove_tilts(tilt_stack, idx_to_remove, numbered_from_1=True, output_file=None, input_order='xyz', output_order='xyz')#

Remove specified tilts from a tilt stack and optionally save the result to a file.

Parameters:

tilt_stackstr or array-like: The input tilt stack data from which tilts will be removed.
idx_to_removearray-like: Indices of the tilts to remove. If numbered_from_1 is True, the indices are 1-based.
numbered_from_1bool, defaults=True: If True, the indices in idx_to_remove are considered to be 1-based. Defaults to True.
output_filestr, optional: The file path where the modified tilt stack will be saved. If None, the result is not saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack data with the specified tilts removed. If the tilts to be cleaned correspond to all the tilts (apart from those already cleaned), the numpy 3D array with the original tilt stack data is returned.

Notes

This function modifies the tilt stack in place and can save the result to a specified output file.

cryocat.core.tiltstack.sort_tilts_by_angle(tilt_stack, input_tilts, output_file=None, input_order='xyz', output_order='xyz')#

Sorts a stack of tilts by their angles and optionally writes the sorted data to a file.

Parameters:

tilt_stackstr or array-like: The input tilt stack data to be sorted specified either as a path or array-like data.
input_tiltsstr or array-like: The file path to the input tilt angles. See ioutils.tlt_load function for more info.
output_filestr, optional: The file path where the sorted tilt data will be saved. If None, the data will not be saved. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

numpy.ndarray: Numpy 3D array with tilt stack data in the desired order.

Notes

The function loads tilt angles from the specified input file, sorts the tilt stack based on these angles, and writes the sorted data to the specified output file if provided. The input and output orders can be specified to accommodate different needs.

cryocat.core.tiltstack.split_stack_even_odd(tilt_stack, output_file_prefix=None, input_order='xyz', output_order='xyz')#

Splits a given tilt stack into even and odd stacks.

Parameters:

tilt_stackstr or array-like: The input tilt stack data specified by its filename (including the path) or as 3d numpy array.
output_file_prefixstr, optional: The prefix for the output filenames. If provided, the function will save the even and odd stacks as files with this prefix followed by ‘_even.mrc’ and ‘_odd.mrc’, respectively. Defaults to None.
input_orderstr, default=’xyz’: The order of the input data dimensions. Relevant only if tilt_stack in numpy.ndarray. Defaults to ‘xyz’.
output_orderstr, default=’xyz’: The order of the output data dimensions. It does not influence order for writing the stack out, just of the returned array. Defaults to ‘xyz’.

Returns:

tuple of numpy.ndarray: A tuple containing two arrays: the first array contains the even indexed tilts, and the second array contains the odd indexed tilts, both reordered according to output_order.