Projection Matching API

Projection Matcher

cryoPARES.projmatching.projMatcher.get_rotmat(degAngles, convention='ZYZ', device=None)

Parameters:

convention (str)

cryoPARES.projmatching.projMatcher.get_eulers(rotmats, convention='ZYZ', device=None)

Parameters:

convention (str)

class cryoPARES.projmatching.projMatcher.ProjectionMatcher(reference_vol, pixel_size=None, grid_distance_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, grid_step_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, max_resolution_A=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, top_k_poses_localref=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, verbose=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, correct_ctf=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, mask_radius_angs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>)

Bases: Module

Single concrete aligner (Fourier pipeline). This class folds together the previous abstract base + Fourier subclass.

Parameters:

• reference_vol (PathLike | str | Tensor | ndarray)

• pixel_size (float | None)

• grid_distance_degs (float | Tuple[float, float, float])

• grid_step_degs (float | Tuple[float, float, float])

• max_resolution_A (float | None)

• top_k_poses_localref (int)

• verbose (bool)

• correct_ctf (bool)

• mask_radius_angs (float | None)

__init__(reference_vol, pixel_size=None, grid_distance_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, grid_step_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, max_resolution_A=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, top_k_poses_localref=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, verbose=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, correct_ctf=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, mask_radius_angs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• reference_vol (PathLike | str | Tensor | ndarray)

• pixel_size (float | None)

• grid_distance_degs (float | Tuple[float, float, float])

• grid_step_degs (float | Tuple[float, float, float])

• max_resolution_A (float | None)

• top_k_poses_localref (int)

• verbose (bool)

• correct_ctf (bool)

• mask_radius_angs (float | None)

property device

correlateF(parts, projs)

Parameters:

• parts (Tensor)

• projs (Tensor)

property max_resoluton_freq_pixels

preprocess_particles(particles, data_rootdir, batch_size, n_cpus, halfset=None, subset_idxs=None)

Parameters:

particles (PathLike | str)

forward(imgs, ctfs, rotmats)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

align_star(particles, starFnameOut, data_rootdir=None, batch_size=256, device='cuda', n_cpus=1, halfset=None)

Align particles (input STAR file) to the reference. Writes a STAR with predicted poses/shifts if starFnameOut provided.

Return type:

ParticlesStarSet

Parameters:

• particles (PathLike | str)

• starFnameOut (PathLike | str)

• data_rootdir (str | None)

• halfset (Literal[1, 2] | None)

cryoPARES.projmatching.projMatcher.extract_ccor_max(corrs, max_shift_fraction)

cryoPARES.projmatching.projMatcher.align_star(reference_vol, particles_star_fname, out_fname, particles_dir, mask_radius_angs=None, grid_distance_degs=8.0, grid_step_degs=2.0, return_top_k_poses=1, filter_resolution_angst=None, num_dataworkers=1, batch_size=1024, use_cuda=True, verbose=True, float32_matmul_precision='high', gpu_id=None, n_first_particles=None, correct_ctf=True, halfmap_subset=None)

Parameters:

• reference_vol (str) – Path to the reference volume file (e.g., .mrc).

• particles_star_fname (str) – Input STAR file containing particle metadata.

• out_fname (str) – Path for the output STAR file with aligned particle poses.

• particles_dir (Optional[str]) – Root directory for particle image paths if they are relative in the STAR file.

• mask_radius_angs (Optional[float]) – Radius of the circular mask to apply to particles, in Angstroms.

• grid_distance_degs (float) – Angular search range around the initial orientation, in degrees.

• grid_step_degs (float) – Step size for the angular search grid, in degrees.

• return_top_k_poses (int) – Number of top-scoring poses to save for each particle.

• filter_resolution_angst (Optional[float]) – Low-pass filter the reference volume to this resolution (Angstroms) before matching.

• num_dataworkers (int) – Number of CPU workers for data loading

• batch_size (int) – Number of particles to process in each batch on each job.

• use_cuda (bool) – If True, use a CUDA-enabled GPU for processing.

• verbose (bool) – If True, print progress and informational messages.

• float32_matmul_precision (Literal['highest', 'high', 'medium']) – Precision for torch.set_float32_matmul_precision (‘highest’, ‘high’, ‘medium’).

• gpu_id (Optional[int]) – Specific GPU ID to use when use_cuda is True.

• n_first_particles (Optional[int]) – Process only the first N particles from the input STAR file.

• correct_ctf (bool) – If True, apply CTF correction during matching.

• halfmap_subset (Optional[Literal['1', '2']]) – Process only a specific random subset (‘1’ or ‘2’) of particles for half-map validation.

Returns:

particles: ParticlesStarSet

ProjectionMatcher Class

class cryoPARES.projmatching.projMatcher.ProjectionMatcher(reference_vol, pixel_size=None, grid_distance_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, grid_step_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, max_resolution_A=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, top_k_poses_localref=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, verbose=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, correct_ctf=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, mask_radius_angs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>)

Bases: Module

Single concrete aligner (Fourier pipeline). This class folds together the previous abstract base + Fourier subclass.

Parameters:

• reference_vol (PathLike | str | Tensor | ndarray)

• pixel_size (float | None)

• grid_distance_degs (float | Tuple[float, float, float])

• grid_step_degs (float | Tuple[float, float, float])

• max_resolution_A (float | None)

• top_k_poses_localref (int)

• verbose (bool)

• correct_ctf (bool)

• mask_radius_angs (float | None)

__init__(reference_vol, pixel_size=None, grid_distance_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, grid_step_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, max_resolution_A=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, top_k_poses_localref=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, verbose=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, correct_ctf=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, mask_radius_angs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• reference_vol (PathLike | str | Tensor | ndarray)

• pixel_size (float | None)

• grid_distance_degs (float | Tuple[float, float, float])

• grid_step_degs (float | Tuple[float, float, float])

• max_resolution_A (float | None)

• top_k_poses_localref (int)

• verbose (bool)

• correct_ctf (bool)

• mask_radius_angs (float | None)

property device

correlateF(parts, projs)

Parameters:

• parts (Tensor)

• projs (Tensor)

property max_resoluton_freq_pixels

preprocess_particles(particles, data_rootdir, batch_size, n_cpus, halfset=None, subset_idxs=None)

Parameters:

particles (PathLike | str)

forward(imgs, ctfs, rotmats)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

align_star(particles, starFnameOut, data_rootdir=None, batch_size=256, device='cuda', n_cpus=1, halfset=None)

Align particles (input STAR file) to the reference. Writes a STAR with predicted poses/shifts if starFnameOut provided.

Return type:

ParticlesStarSet

Parameters:

• particles (PathLike | str)

• starFnameOut (PathLike | str)

• data_rootdir (str | None)

• halfset (Literal[1, 2] | None)

Command-Line Interface

cryoPARES.projmatching.projmatching.create_shared_tensor(shape, dtype=torch.float32, ctx=None, lock=False)

Create a shared multiprocessing.Array for storing tensor data.

Parameters:

• shape (tuple[int]) – Desired tensor shape.

• dtype (torch.dtype) – PyTorch dtype (supports float32, float64, int64).

• ctx – Multiprocessing context (default: torch.multiprocessing).

• lock (bool) – If False, disables lock for performance (safe when workers write disjoint slices).

Returns:

A multiprocessing.Array and the shape tuple.

Return type:

(shared_array, shape)

cryoPARES.projmatching.projmatching.worker(worker_id, *args, **kwargs)

Wrapper to catch exceptions in workers and print tracebacks.

cryoPARES.projmatching.projmatching.projmatching_starfile(reference_vol, particles_star_fname, out_fname, particles_dir, mask_radius_angs=None, grid_distance_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, grid_step_degs=<cryoPARES.configManager.inject_defaults.CONFIG_PARAM object>, return_top_k_poses=1, filter_resolution_angst=None, n_jobs=1, num_dataworkers=1, batch_size=1024, use_cuda=True, verbose=False, float32_matmul_precision='high', gpu_id=None, n_first_particles=None, correct_ctf=True, halfmap_subset=None)

Aligns particles from a STAR file to a reference volume using projection matching.

This function can run in a single-process mode or be distributed across multiple jobs for parallel processing.

Parameters:

• reference_vol (str) – Path to reference 3D volume (.mrc file) for generating projection templates

• particles_star_fname (str) – Path to input STAR file with particle metadata

• out_fname (str) – Path for output STAR file with aligned particle poses

• particles_dir (Optional[str]) – Root directory for particle image paths. If provided, overrides paths in the .star file

• mask_radius_angs (Optional[float]) – Radius of circular mask in Angstroms applied to particle images

• grid_distance_degs (float) – Maximum angular distance in degrees for local refinement search. Grid ranges from -grid_distance_degs to +grid_distance_degs around predicted pose

• grid_step_degs (float) – Angular step size in degrees for grid search during local refinement

• return_top_k_poses (int) – Number of top matching poses to save per particle

• filter_resolution_angst (Optional[float]) – Low-pass filter resolution in Angstroms applied to reference volume before matching

• n_jobs (int) – Number of parallel worker processes for distributed projection matching

• num_dataworkers (int) – Number of CPU workers per PyTorch DataLoader for data loading

• batch_size (int) – Number of particles to process simultaneously per job

• use_cuda (bool) – Enable GPU acceleration. If False, runs on CPU only

• verbose (bool) – Enable verbose logging output

• float32_matmul_precision (Literal['highest', 'high', 'medium']) – PyTorch float32 matrix multiplication precision mode (“highest”, “high”, or “medium”)

• gpu_id (Optional[int]) – Specific GPU device ID to use (if multiple GPUs available)

• n_first_particles (Optional[int]) – Process only the first N particles from dataset (for testing or validation)

• correct_ctf (bool) – Apply CTF correction during projection matching

• halfmap_subset (Optional[Literal['1', '2']]) – Select half-map subset (1 or 2) for half-map validation

cryoPARES.projmatching.projmatching.main()

Main entry point: parse CLI args from docstrings and run projmatching_starfile().