CryoLike Python API

• cryolike.file_conversions
  • cryolike.file_conversions.make_templates_from_inputs_api
    • make_templates_from_inputs()
  • cryolike.file_conversions.particle_stacks_wrappers
    • convert_particle_stacks_from_cryosparc_job_directory()
    • convert_particle_stacks_from_indexed_cryosparc_file()
    • convert_particle_stacks_from_indexed_star_file()
    • convert_particle_stacks_from_paired_star_and_mrc_files()
  • cryolike.file_conversions.particle_stacks_converter
    • ParticleStackConverter
• cryolike.grids
  • cryolike.grids.cartesian_grid
    • CartesianGrid2D
    • CartesianGrid3D
  • cryolike.grids.polar_grid
    • ArbitraryPolarQuadrature
    • PolarGrid
  • cryolike.grids.sphere_grid
    • CartesianShell
    • SphereGrid
    • SphereShell
  • cryolike.grids.volume
    • Volume
• cryolike.likelihoods
  • cryolike.likelihoods.interface
    • compute_cross_correlation_complete()
    • compute_optimal_pose()
    • compute_optimal_displacement_and_rotation()
    • compute_optimal_displacement()
    • compute_optimal_rotation()
  • cryolike.likelihoods.iteration
    • CrossCorrelationYieldType
    • template_first_comparator()
    • aggregate_ill()
  • cryolike.likelihoods.kernels
    • compute_cross_correlation()
    • compute_image_norms()
    • compute_template_norms()
    • ill_kernel()
• cryolike.metadata
  • cryolike.metadata.lens_descriptor
    • LensDescriptor
  • cryolike.metadata.image_descriptor
    • ImageDescriptor
  • cryolike.metadata.viewing_angles
    • ViewingAngles
• cryolike.microscopy
  • cryolike.microscopy.ctf
    • CTF
• cryolike.stacks
  • cryolike.stacks.image
    • Images
  • cryolike.stacks.template
    • Templates
• cryolike.util
  • cryolike.util.atomic_model
    • AtomicModel
  • cryolike.util.device_handling
    • check_nufft_installed()
    • get_device()
  • cryolike.util.enums
    • AtomShape
    • Basis
    • CrossCorrelationReturnType
    • InputFileType
    • NormType
    • Precision
    • QuadratureType
    • SamplingStrategy
  • cryolike.util.post_process_output
  • cryolike.util.types

cryolike.plot

cryolike.run_likelihood

cryolike.run_likelihood.configure_displacement(max_displacement_pixels: float = 8.0, n_displacements_x: int = -1, n_displacements_y: int = -1) → Callable[[Templates], None]

Sets up an object (callback) that sets the grid of displacements to search for each template file before processing.

Parameters:

• max_displacement_pixels (float, optional) – Maximum number of pixels to displace in either x or y dimension for search. Defaults to 8.0. Note that the full range will be from -(this value) to +(this value).

• n_displacements_x (int, optional) – Number of displacements to search in the x-direction. Defaults to -1.

• n_displacements_y (int, optional) – Number of displacements to search in the y-direction. Defaults to -1.

Returns:

A callback that ensures the displacement search

grid is correctly set.

Return type:

displacement_configurator_T

cryolike.run_likelihood.configure_likelihood_files(folder_templates: str, folder_particles: str, folder_output: str = '', n_stacks: int = 1, i_template: int = 0, return_likelihood_optimal_pose_physical: bool = False) → LikelihoodFileManager

Sets up an object that is responsible for ensuring name consistency for files input to or output by the run_likelihood wrappers.

Parameters:

• folder_templates (str) – Root of the folder where template files can be found

• folder_particles (str) – Root of the folder where image stack files can be found

• folder_output (str, optional) – Root of the folder to use for output. Defaults to ‘’.

• n_stacks (int, optional) – Maximum number of image stacks to process. Defaults to 1.

• i_template (int, optional) – Index of the template file within the templates directory. Defaults to 0.

• return_likelihood_optimal_pose_physical (bool, optional) – Whether to additionally compute the likelihood of the optimal pose in physical-space representation. Not currently implemented. Defaults to False.

Returns:

An object that provides consistent file name handling.

Return type:

LikelihoodFileManager

cryolike.run_likelihood.run_likelihood_full_cross_correlation(file_config: LikelihoodFileManager, params_input: str | ImageDescriptor, displacer: Callable[[Templates], None], template_index: int = 0, n_stacks: int = 1, skip_exist: bool = False, n_templates_per_batch: int | None = None, n_images_per_batch: int | None = None, discover_batch_size: bool = False)

Function to run cross-correlation likelihood of a template stack against potentially several image stacks meeting the same name convention. It is mostly a convenience wrapper around the user-facing functions in cryolike.likelihoods.interface, as it automates calling the likelihood computation against multiple input files. Note that the API currently provided by this function is quite likely to change, as it is only a convenience wrapper.

This version will write a single file per image stack, containing a 4-tensor showing the cross-correlation likelihood between each image and template pair at each displacement and rotation.

Parameters:

• file_config (LikelihoodFileManager) – A file manager obtained by calling configure_likelihood_files, which handles consistent naming on the file system

• params_input (str | ImageDescriptor) – An ImageDescriptor or a path to where one has been saved on the file system

• displacer (displacement_configurator_T) – The result of calling configure_displacement (technically a callback)

• template_index (int, optional) – The index of the template file, among similarly-named template files, to use for comparison. Defaults to 0. Note that this refers to a particular file among similarly-named files; it does not refer to an individual template within a template stack (stored in a single file).

• n_stacks (int, optional) – How many image stacks to process. Defaults to 1.

• skip_exist (bool, optional) – Whether to skip processing of any image stack which appears (from existing file names) to have been processed already. Defaults to False.

• n_templates_per_batch (int, optional) – The number of templates to try to compare at once in memory. Higher numbers should result in more efficient computation, particularly on GPUs, but may need to be reduced if out-of-memory errors occur. If set to None (the default), requires discover_batch_size to be set, and will be initially set to the full template count.

• n_images_per_batch (int, optional) – The number of images to try to compare at once in memory. Higher numbers should result in more efficient computation, particularly on GPUs, but may need to be reduced if out-of-memory errors occur. If set to None (the default), requires discover_batch_size to be set, and will be initially guessed as 1/8 of the total images for the first iteration.

• discover_batch_size (bool, optional) – Whether to attempt to compute an optimal number of templates and images per batch. Defaults to False. If False, explicit template and image batch sizes will be used (and any resulting out-of-memory errors will cause processing failure). If set True, image and template batch sizes will be adjusted for subsequent image stacks with the same template, starting with the values of the n_templates_per_batch and n_images_per_batch parameters (which are taken as hints rather than hard requirements). OOM errors will be caught, and errors will only be generated if the system still runs out of memory with a single image and template per batch. Otherwise, the logic will first adjust the template batch size to the value that gives the smallest total number of template batches without running out of memory. Once this value is found, the image batch size will be adjusted by halves between a hard ceiling (a batch size that resulted in OOM) and a hard floor (the largest known-working batch size), with adjustment stopping once these parameters would no longer decrease the total number of image batches.

cryolike.run_likelihood.run_likelihood_optimal_pose(file_config: LikelihoodFileManager, params_input: str | ImageDescriptor, displacer: Callable[[Templates], None], template_index: int = 0, n_stacks: int = 1, skip_exist: bool = False, n_templates_per_batch: int | None = None, n_images_per_batch: int | None = None, discover_batch_size: bool = False, return_likelihood_optimal_pose_fourier: bool = False, return_likelihood_integrated_pose_fourier: bool = False)

Function to run cross-correlation likelihood of a template stack against potentially several image stacks meeting the same name convention. It is mostly a convenience wrapper around the user-facing functions in cryolike.likelihoods.interface, as it automates calling the likelihood computation against multiple input files. Note that the API currently provided by this function is quite likely to change, as it is only a convenience wrapper.

This version will write files containing the optimal x- and y-displacement of each template-image pair, as well as the optimal rotation for each pair. Additionally, if return_likelihood_optimal_pose_fourier is set, a file will be written containing the per-image log likelihood of the optimal pose; and if return_likelihood_integrated_pose_fourier is set, a file will be written containing the per-image integrated log likelihood over all poses.

Parameters:

• file_config (LikelihoodFileManager) – A file manager obtained by calling configure_likelihood_files, which handles consistent naming on the file system

• params_input (str | ImageDescriptor) – An ImageDescriptor or a path to where one has been saved on the file system

• displacer (displacement_configurator_T) – The result of calling configure_displacement (technically a callback)

• template_index (int, optional) – The index of the template file, among similarly-named template files, to use for comparison. Defaults to 0. Note that this refers to a particular file among similarly-named files; it does not refer to an individual template within a template stack (stored in a single file).

• n_stacks (int, optional) – How many image stacks to process. Defaults to 1.

• skip_exist (bool, optional) – Whether to skip processing of any image stack which appears (from existing file names) to have been processed already. Defaults to False.

• n_templates_per_batch (int, optional) – The number of templates to try to compare at once in memory. Higher numbers should result in more efficient computation, particularly on GPUs, but may need to be reduced if out-of-memory errors occur. If set to None (the default), requires discover_batch_size to be set, and will be initially set to the full template count.

• n_images_per_batch (int, optional) – The number of images to try to compare at once in memory. Higher numbers should result in more efficient computation, particularly on GPUs, but may need to be reduced if out-of-memory errors occur. If set to None (the default), requires discover_batch_size to be set, and will be initially guessed as 1/8 of the total images for the first iteration.

• discover_batch_size (bool, optional) – Whether to attempt to compute an optimal number of templates and images per batch. Defaults to False. If False, explicit template and image batch sizes will be used (and any resulting out-of-memory errors will cause processing failure). If set True, image and template batch sizes will be adjusted for subsequent image stacks with the same template, starting with the values of the n_templates_per_batch and n_images_per_batch parameters (which are taken as hints rather than hard requirements). OOM errors will be caught, and errors will only be generated if the system still runs out of memory with a single image and template per batch. Otherwise, the logic will first adjust the template batch size to the value that gives the smallest total number of template batches without running out of memory. Once this value is found, the image batch size will be adjusted by halves between a hard ceiling (a batch size that resulted in OOM) and a hard floor (the largest known-working batch size), with adjustment stopping once these parameters would no longer decrease the total number of image batches.

• return_likelihood_optimal_pose_fourier (bool, optional) – Whether to return the optimal Fourier pose (as opposed to the optimal rotation and displacement per-template). Defaults to False.

• return_likelihood_integrated_pose_fourier (bool, optional) – Whether to output the integrated log likelihood (in Fourier space) for each image. Defaults to False.