Skip to content

Managers

leopard_em.pydantic_models.managers

Pydantic models for Leopard-EM program managers.

ConstrainedSearchManager

Bases: BaseModel2DTM

Model holding parameters necessary for running the constrained search program.

NOTE: The constrained search program should only be run on data from a single reference micrograph. That is, if you have data from two or more micrographs, that data from each micrograph needs processed separately. This restriction may be lifted in the future.

Attributes:

  • template_volume_path (str) –

    Path to the template volume MRC file.

  • center_vector (list[float]) –

    The centre vector of the template volume.

  • particle_stack_reference (ParticleStackCSV | ParticleStackHDF5) –

    Particle stack object containing particle data reference particles. Use ParticleStackCSV for a CSV-backed particle table or ParticleStackHDF5 for an HDF5-backed one. Both expose the same in-memory API.

  • particle_stack_constrained (ParticleStackCSV | ParticleStackHDF5) –

    Particle stack object containing particle data constrained particles.

  • defocus_refinement_config (DefocusSearchConfig) –

    Configuration for defocus refinement.

  • orientation_refinement_config (RefineOrientationConfig) –

    Configuration for orientation refinement.

  • preprocessing_filters (PreprocessingFilters) –

    Filters to apply to the particle images.

  • computational_config (ComputationalConfigRefine) –

    What computational resources to allocate for the program.

  • template_volume (ExcludedTensor) –

    The template volume tensor (excluded from serialization).

  • false_positives (float) –

    The number of false positives to allow per particle.

Methods:

  • TODO serialization/import methods –
  • __init__ –

    Initialize the constrained search manager.

  • make_backend_core_function_kwargs –

    Create the kwargs for the backend refine_template core function.

  • run_constrained_search –

    Run the constrained search program.

  • refine_result_to_dataframe –

    Build the refined particle DataFrame from a backend result (no I/O).

  • export_results –

    Build the refined DataFrame and write it (plus CSV parameter/ above-threshold siblings) to disk, matching the input particle_stack_reference's back-end by default (override with output_format).

make_backend_core_function_kwargs 

make_backend_core_function_kwargs(prefer_refined_angles: bool = True) -> dict[str, Any]

Create the kwargs for the backend constrained_template core function.

run_constrained_search(output_dataframe_path: str, false_positives: float = 0.005, orientation_batch_size: int = 64, output_format: Literal['csv', 'hdf5'] | None = None, allow_file_overwrite: bool = False) -> None

Run the constrained search program and export the resultant DataFrame.

Parameters:

  • output_dataframe_path (str) –

    Path to save the constrained search results.

  • false_positives (float, default: 0.005 ) –

    The number of false positives to allow per particle.

  • orientation_batch_size (int, default: 64 ) –

    Number of orientations to process at once. Defaults to 64.

  • output_format (Literal['csv', 'hdf5'] | None, default: None ) –

    Output back-end for the main refined table. Defaults to None, which matches the back-end of self.particle_stack_reference (CSV in, CSV out; HDF5 in, HDF5 out). Pass "csv" or "hdf5" to override. The accompanying "_parameters" and "_above_threshold" sibling tables are always written as CSV regardless of this setting.

  • allow_file_overwrite (bool, default: False ) –

    Whether to overwrite an existing file at output_dataframe_path. Defaults to False.

get_refine_result 

get_refine_result(backend_kwargs: dict, orientation_batch_size: int = 64) -> dict[str, np.ndarray]

Get refine template result.

Parameters:

  • backend_kwargs (dict) –

    Keyword arguments for the backend processing

  • orientation_batch_size (int, default: 64 ) –

    Number of orientations to process at once. Defaults to 64.

Returns:

  • dict[str, ndarray] –

    The result of the refine template program.

refine_result_to_dataframe 

refine_result_to_dataframe(result: dict[str, ndarray]) -> pd.DataFrame

Convert constrained search result to a DataFrame.

Parameters:

  • result (dict[str, ndarray]) –

    The result of the constrained search program.

Returns:

  • DataFrame –

    The refined particle data. Not written to disk; use export_results to do both in one call.

export_results 

export_results(output_dataframe_path: str, result: dict[str, ndarray], false_positives: float = 0.005, output_format: Literal['csv', 'hdf5'] | None = None, allow_file_overwrite: bool = False) -> ParticleStackCSV | ParticleStackHDF5

Build the refined DataFrame and write it, plus two CSV siblings, to disk.

Parameters:

  • output_dataframe_path (str) –

    Path to save the refined particle data.

  • result (dict[str, ndarray]) –

    The result of the constrained search program.

  • false_positives (float, default: 0.005 ) –

    The number of false positives to allow per particle.

  • output_format (Literal['csv', 'hdf5'] | None, default: None ) –

    Output back-end for the main refined table. Defaults to None, which matches the back-end of self.particle_stack_reference. Pass "csv" or "hdf5" to override.

  • allow_file_overwrite (bool, default: False ) –

    Whether to overwrite an existing file at output_dataframe_path. Defaults to False.

Returns:

FrameInspectionManager

Bases: PeakInspectionManager

Run peak inspection independently for each frame in a movie.

run_peak_inspection_per_frame 

run_peak_inspection_per_frame(correlation_batch_size: int = 32, prefer_refined_angles: bool = True, apply_projection_normalization: bool = True, template_tensor: Tensor | None = None, output_mode: Literal['cross_correlation', 'frc'] = 'cross_correlation', apply_template_dose_weighting: bool = False) -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]

Run peak inspection independently for every movie frame.

Composes the per-frame pipeline: load the movie/motion inputs, prepare the shared template and fixed whitening filters, build the frame-independent backend kwargs, then score and stack every frame.

Parameters:

  • correlation_batch_size (int, default: 32 ) –

    Number of orientation offsets processed per backend batch.

  • prefer_refined_angles (bool, default: True ) –

    If True, use refined Euler angles from the particle stack when available.

  • apply_projection_normalization (bool, default: True ) –

    Whether to normalize each projection before scoring.

  • template_tensor (Tensor | None, default: None ) –

    Optional template volume override.

  • output_mode (Literal['cross_correlation', 'frc'], default: 'cross_correlation' ) –

    Score mode (CC maps or FRC spectra).

  • apply_template_dose_weighting (bool, default: False ) –

    If True, apply cumulative dose filtering to the provided non-dose- weighted template separately for each frame interval.

Returns:

  • Tensor | tuple[Tensor, Tensor] –

    Stacked per-frame results: a (T, N, n_px, n_def, n_orient, H, W) CC tensor, or (stacked_frc, frequency_bins) in FRC mode.

run_and_save_peak_inspection_per_frame 

run_and_save_peak_inspection_per_frame(output_path: str | Path, correlation_batch_size: int = 32, prefer_refined_angles: bool = True, apply_projection_normalization: bool = True, template_tensor: Tensor | None = None, output_mode: Literal['cross_correlation', 'frc'] = 'cross_correlation', apply_template_dose_weighting: bool = False) -> Path

Run per-frame peak inspection and write a self-describing .npz file.

Parameters:

  • output_path (str | Path) –

    Destination path for the .npz file (suffix appended if missing).

  • correlation_batch_size (int, default: 32 ) –

    Number of orientation offsets processed per backend batch.

  • prefer_refined_angles (bool, default: True ) –

    If True, use refined Euler angles from the particle stack when available.

  • apply_projection_normalization (bool, default: True ) –

    Whether to normalize each projection before scoring.

  • template_tensor (Tensor | None, default: None ) –

    Optional template volume override.

  • output_mode (Literal['cross_correlation', 'frc'], default: 'cross_correlation' ) –

    Score mode (CC maps or FRC spectra).

  • apply_template_dose_weighting (bool, default: False ) –

    If True, apply cumulative dose filtering to the provided non-dose- weighted template separately for each frame interval.

Returns:

  • Path –

    The path the result was written to (with .npz suffix).

MatchTemplateManager

Bases: BaseModel2DTM

Model holding parameters necessary for running full orientation 2DTM.

Attributes:

  • micrograph_path (str) –

    Path to the micrograph .mrc file.

  • template_volume_path (str) –

    Path to the template volume .mrc file.

  • micrograph (ExcludedTensor) –

    Image to run template matching on. Not serialized.

  • template_volume (ExcludedTensor) –

    Template volume to match against. Not serialized.

  • optics_group (OpticsGroup) –

    Optics group parameters for the imaging system on the microscope.

  • defocus_search_config (DefocusSearchConfig) –

    Parameters for searching over defocus values.

  • orientation_search_config (OrientationSearchConfig) –

    Parameters for searching over orientation angles.

  • preprocessing_filters (PreprocessingFilters) –

    Configurations for the preprocessing filters to apply during correlation.

  • match_template_result (MatchTemplateResultMRC | MatchTemplateResultHDF5) –

    Result of the match template program. Use MatchTemplateResultMRC to write individual MRC files or MatchTemplateResultHDF5 to bundle all tensors into a single HDF5 file.

  • computational_config (ComputationalConfigMatch) –

    Parameters for controlling computational resources.

Methods:

  • validate_micrograph_path –

    Ensure the micrograph file exists.

  • validate_template_volume_path –

    Ensure the template volume file exists.

  • __init__ –

    Constructor which also loads the micrograph and template volume from disk. The 'preload_mrc_files' parameter controls whether to read the MRC files immediately upon initialization.

  • make_backend_core_function_kwargs –

    Generates the keyword arguments for backend 'core_match_template' call from held parameters. Does the necessary pre-processing steps to filter the image and template.

  • run_match_template –

    Runs the base match template program in PyTorch.

  • results_to_dataframe –

    half_template_width_pos_shift: bool = True, exclude_columns: Optional[list] = None, locate_peaks_kwargs: Optional[dict] = None,

  • ) -> pd.DataFrame –

    Converts the basic extracted peak info DataFrame (from the result object) to a DataFrame with additional information about reference files, microscope parameters, etc.

  • save_config –

    Save this Pydantic model config to disk.

validate_micrograph_path 

validate_micrograph_path(v) -> str

Ensure the micrograph file exists.

validate_template_volume_path 

validate_template_volume_path(v) -> str

Ensure the template volume file exists.

make_backend_core_function_kwargs 

make_backend_core_function_kwargs() -> dict[str, Any]

Generates the keyword arguments for backend call from held parameters.

run_match_template 

run_match_template(orientation_batch_size: int = 16, do_result_export: bool = True, compute_correlation_table: bool = False) -> None

Runs the base match template in pytorch.

Parameters:

  • orientation_batch_size (int, default: 16 ) –

    The number of projections to process in a single batch. Default is 1.

  • do_result_export (bool, default: True ) –

    If True, call the MatchTemplateResult.export_results method to save the results to disk directly after running the match template. Default is True.

  • compute_correlation_table (bool, default: False ) –

    If True, track cross-correlation values which surpass the correlation table threshold during the search. If False, the CorrelationTable will be empty. Incurs a small runtime overhead when enabled. Default is False.

Returns:

  • None –

run_match_template_distributed 

run_match_template_distributed(world_size: int, rank: int, local_rank: int, orientation_batch_size: int = 16, do_result_export: bool = True, compute_correlation_table: bool = False) -> None

Runs the base match template in a distributed, multi-node environment.

Parameters:

  • world_size (int) –

    The total number of processes in the distributed job.

  • rank (int) –

    The global rank of this process.

  • local_rank (int) –

    The local rank of this process (used to assign GPU).

  • orientation_batch_size (int, default: 16 ) –

    The number of projections to process in a single batch. Default is 1.

  • do_result_export (bool, default: True ) –

    If True, call the MatchTemplateResult.export_results method to save the results to disk directly after running the match template. Default is True.

  • compute_correlation_table (bool, default: False ) –

    If True, track cross-correlation values which surpass the correlation table threshold during the search. If False, the CorrelationTable will be empty. Incurs a small runtime overhead when enabled. Default is False.

Raises:

  • RuntimeError –

    If the distributed process group has not been initialized.

Returns:

  • None –

results_to_dataframe 

results_to_dataframe(half_template_width_pos_shift: bool = True, exclude_columns: list | None = None, locate_peaks_kwargs: dict | None = None) -> pd.DataFrame

Converts the match template results to a DataFrame with additional info.

Data included in this dataframe should be sufficient to do cross-correlation on the extracted peaks, that is, all the microscope parameters, defocus parameters, etc. are included in the dataframe. Run-specific filter information is not included in this dataframe; use the YAML configuration file to replicate a match_template run.

Parameters:

  • half_template_width_pos_shift (bool, default: True ) –

    If True, columns for the image peak position are shifted by half a template width to correspond to the center of the particle. This should be done when the position of a peak corresponds to the top-left corner of the template rather than the center. Default is True. This should generally be left as True unless you know what you are doing.

  • exclude_columns (list, default: None ) –

    List of columns to exclude from the DataFrame. Default is None and no columns are excluded.

  • locate_peaks_kwargs (dict, default: None ) –

    Keyword arguments to pass to the 'MatchTemplateResult.locate_peaks' method. Default is None and no additional keyword arguments are passed.

Returns:

  • DataFrame –

    DataFrame containing the match template results.

save_config 

save_config(path: str, mode: Literal['yaml', 'json'] = 'yaml') -> None

Save this Pydandic model to disk. Wrapper around the serialization methods.

Parameters:

  • path (str) –

    Path to save the configuration file.

  • mode (Literal['yaml', 'json'], default: 'yaml' ) –

    Serialization format to use. Default is 'yaml'.

Returns:

  • None –

Raises:

  • ValueError –

    If an invalid serialization mode is provided.

OptimizeTemplateManager

Bases: BaseModel2DTM

Model holding parameters necessary for running the optimize template program.

Attributes:

  • particle_stack (ParticleStackCSV | ParticleStackHDF5) –

    Particle stack object containing particle data. Use ParticleStackCSV for a CSV-backed particle table or ParticleStackHDF5 for an HDF5-backed one. Both expose the same in-memory API.

  • pixel_size_coarse_search (PixelSizeSearchConfig) –

    Configuration for pixel size coarse search.

  • pixel_size_fine_search (PixelSizeSearchConfig) –

    Configuration for pixel size fine search.

  • preprocessing_filters (PreprocessingFilters) –

    Filters to apply to the particle images.

  • computational_config (ComputationalConfigRefine) –

    What computational resources to allocate for the program.

  • simulator (Simulator) –

    The simulator object.

  • apply_global_filtering (bool) –

    If True, apply filtering to the full micrograph before particle extraction. If False, filter are calculated and applied to the cropped particle images. Default is True.

Methods:

make_backend_core_function_kwargs 

make_backend_core_function_kwargs(prefer_refined_angles: bool = True) -> dict[str, Any]

Create the kwargs for the backend refine_template core function.

Parameters:

  • prefer_refined_angles (bool, default: True ) –

    Whether to use refined angles or not. Defaults to True.

run_optimize_template 

run_optimize_template(output_text_path: str, write_individual_csv: bool = False, min_snr: float | None = None, best_n: int | None = None, consecutive_threshold: int = 2) -> None

Run the refine template program and saves the resultant DataFrame to csv.

Parameters:

  • output_text_path (str) –

    Path to save the optimized template pixel size.

  • write_individual_csv (bool, default: False ) –

    Whether to write individual CSV files for each pixel size evaluated. Defaults to False.

  • min_snr (float | None, default: None ) –

    Minimum SNR threshold to filter particles. If provided, all particles with SNR above this threshold are used. Defaults to None.

  • best_n (int | None, default: None ) –

    Number of best particles to use for SNR calculation. Defaults to None. If both min_snr and best_n are provided, applies both filters: first min_snr threshold, then limits to best_n particles. If neither is provided, uses min_snr=8 as default.

  • consecutive_threshold (int, default: 2 ) –

    Number of consecutive iterations with decreasing SNR to stop the search. Defaults to 2.

optimize_pixel_size 

optimize_pixel_size(all_results_path: str, output_text_path: str | None = None, write_individual_csv: bool = False, min_snr: float | None = None, best_n: int | None = None, consecutive_threshold: int = 2) -> float

Optimize the pixel size of the template volume.

Parameters:

  • all_results_path (str) –

    Path to the file for logging all iterations

  • output_text_path (str | None, default: None ) –

    Path to the output text file for saving individual results. Defaults to None.

  • write_individual_csv (bool, default: False ) –

    Whether to write individual CSV files for each pixel size evaluated. Defaults to False.

  • min_snr (float | None, default: None ) –

    Minimum SNR threshold to filter particles. Defaults to None.

  • best_n (int | None, default: None ) –

    Number of best particles to use for SNR calculation. Defaults to None.

  • consecutive_threshold (int, default: 2 ) –

    Number of consecutive iterations with decreasing SNR to stop the search. Defaults to 2.

Returns:

  • float –

    The optimal pixel size.

evaluate_template_px 

evaluate_template_px(px: float, output_text_path: str | None = None, write_individual_csv: bool = False, min_snr: float | None = None, best_n: int | None = None) -> float

Evaluate the template pixel size.

Parameters:

  • px (float) –

    The pixel size to evaluate.

  • output_text_path (str | None, default: None ) –

    Path to the output text file. If provided, saves result to CSV. Defaults to None.

  • write_individual_csv (bool, default: False ) –

    Whether to write individual CSV files for each pixel size evaluated. Defaults to False.

  • min_snr (float | None, default: None ) –

    Minimum SNR threshold to filter particles. Defaults to None.

  • best_n (int | None, default: None ) –

    Number of best particles to use for SNR calculation. Defaults to None.

Returns:

  • float –

    The mean SNR of the template.

get_correlation_result 

get_correlation_result(backend_kwargs: dict, orientation_batch_size: int = 64) -> dict[str, np.ndarray]

Get correlation result.

Parameters:

  • backend_kwargs (dict) –

    Keyword arguments for the backend processing

  • orientation_batch_size (int, default: 64 ) –

    Number of orientations to process at once. Defaults to 64.

Returns:

  • dict[str, ndarray] –

    The result of the refine template program.

results_to_snr 

results_to_snr(result: dict[str, ndarray], min_snr: float | None = None, best_n: int | None = None) -> float

Convert optimize template result to mean SNR.

Parameters:

  • result (dict[str, ndarray]) –

    The result of the optimize template program.

  • min_snr (float | None, default: None ) –

    Minimum SNR threshold to filter particles. If provided, all particles with SNR above this threshold are used. Defaults to None.

  • best_n (int | None, default: None ) –

    Number of best particles to use for SNR calculation. Defaults to None. If both min_snr and best_n are provided, applies both filters: first min_snr threshold, then limits to best_n particles.

Returns:

  • float –

    The mean SNR of the template.

refine_result_to_dataframe 

refine_result_to_dataframe(output_dataframe_path: str, result: dict[str, ndarray], prefer_refined_angles: bool = True) -> None

Convert refine template result to a dataframe and write it to CSV.

NOTE: This always writes CSV, regardless of the input particle_stack's back-end. It is only used to dump intermediate, per-pixel-size diagnostic results during the pixel size search.

Parameters:

  • output_dataframe_path (str) –

    Path to save the refined particle data.

  • result (dict[str, ndarray]) –

    The result of the refine template program.

  • prefer_refined_angles (bool, default: True ) –

    Whether to use the refined angles or not. Defaults to True.

PeakInspectionManager

Bases: RefineTemplateManager

Run refine-template search without best-peak reduction.

This manager reuses the refine-template backend setup, but returns full local score tensors for inspection rather than only the argmax result.

get_peak_inspection_result 

get_peak_inspection_result(backend_kwargs: dict[str, Any], correlation_batch_size: int = 32, apply_projection_normalization: bool = True, output_mode: Literal['cross_correlation', 'frc'] = 'cross_correlation') -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]

Run the inspect backend and return scores for all local hypotheses.

Parameters:

  • backend_kwargs (dict[str, Any]) –

    Backend inputs from :meth:make_backend_core_function_kwargs.

  • correlation_batch_size (int, default: 32 ) –

    Number of orientation offsets processed per backend batch.

  • apply_projection_normalization (bool, default: True ) –

    Whether to normalize each projection before scoring.

  • output_mode (Literal['cross_correlation', 'frc'], default: 'cross_correlation' ) –

    Score mode. "cross_correlation" returns local CC maps; "frc" returns local FRC spectra.

Returns:

  • Tensor | tuple[Tensor, Tensor] –
    • "cross_correlation": tensor with shape (N, n_px, n_defocus, n_orient, H, W).
    • "frc": (frc_tensor, frequency_bins) where frc_tensor has shape (N, n_px, n_defocus, n_orient, n_freq) and frequency_bins has shape (n_freq,).

run_peak_inspection 

run_peak_inspection(correlation_batch_size: int = 32, prefer_refined_angles: bool = True, apply_projection_normalization: bool = True, template_tensor: Tensor | None = None, output_mode: Literal['cross_correlation', 'frc'] = 'cross_correlation') -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]

Run peak inspection using configured data and optional template override.

Parameters:

  • correlation_batch_size (int, default: 32 ) –

    Number of orientation offsets processed per backend batch.

  • prefer_refined_angles (bool, default: True ) –

    If True, use refined Euler angles from the particle stack when available.

  • apply_projection_normalization (bool, default: True ) –

    Whether to normalize each projection before scoring.

  • template_tensor (Tensor | None, default: None ) –

    Optional template volume override.

  • output_mode (Literal['cross_correlation', 'frc'], default: 'cross_correlation' ) –

    Score mode. "cross_correlation" returns local CC maps; "frc" returns local FRC spectra.

Returns:

  • Tensor | tuple[Tensor, Tensor] –

    Inspect output tensor (CC mode) or (frc_tensor, frequency_bins) tuple (FRC mode).

run_and_save_peak_inspection 

run_and_save_peak_inspection(output_path: str | Path, correlation_batch_size: int = 32, prefer_refined_angles: bool = True, apply_projection_normalization: bool = True, template_tensor: Tensor | None = None, output_mode: Literal['cross_correlation', 'frc'] = 'cross_correlation') -> Path

Run peak inspection and write the score tensor to a .npz file.

Parameters:

  • output_path (str | Path) –

    Destination path for the .npz file (suffix appended if missing).

  • correlation_batch_size (int, default: 32 ) –

    Number of orientation offsets processed per backend batch.

  • prefer_refined_angles (bool, default: True ) –

    If True, use refined Euler angles from the particle stack when available.

  • apply_projection_normalization (bool, default: True ) –

    Whether to normalize each projection before scoring.

  • template_tensor (Tensor | None, default: None ) –

    Optional template volume override.

  • output_mode (Literal['cross_correlation', 'frc'], default: 'cross_correlation' ) –

    Score mode. "cross_correlation" saves local CC maps; "frc" saves local FRC spectra plus the frequency bins.

Returns:

  • Path –

    The path the result was written to (with .npz suffix).

RefineTemplateManager

Bases: BaseModel2DTM

Model holding parameters necessary for running the refine template program.

Attributes:

  • template_volume_path (str) –

    Path to the template volume MRC file.

  • particle_stack (ParticleStackCSV | ParticleStackHDF5) –

    Particle stack object containing particle data. Use ParticleStackCSV for a CSV-backed particle table or ParticleStackHDF5 for an HDF5-backed one. Both expose the same in-memory API.

  • defocus_refinement_config (DefocusSearchConfig) –

    Configuration for defocus refinement.

  • pixel_size_refinement_config (PixelSizeSearchConfig) –

    Configuration for pixel size refinement.

  • orientation_refinement_config (RefineOrientationConfig) –

    Configuration for orientation refinement.

  • preprocessing_filters (PreprocessingFilters) –

    Filters to apply to the particle images.

  • computational_config (ComputationalConfigRefine) –

    What computational resources to allocate for the program.

  • apply_global_filtering (bool) –

    If True, apply filtering to the full micrograph before particle extraction. If False, filter are calculated and applied to the cropped particle images. Default is True.

  • template_volume (ExcludedTensor) –

    The template volume tensor (excluded from serialization).

  • movie_config (MovieConfig) –

    Configuration for the movie.

Methods:

  • TODO serialization/import methods –
  • __init__ –

    Initialize the refine template manager.

  • make_backend_core_function_kwargs –

    Create the kwargs for the backend refine_template core function.

  • run_refine_template –

    Run the refine template program.

  • refine_result_to_dataframe –

    -> pd.DataFrame Build the refined particle DataFrame from a backend result (no I/O).

  • export_results –

    Build the refined DataFrame and write it to disk, matching the input particle_stack's back-end by default (override with output_format).

make_backend_core_function_kwargs 

make_backend_core_function_kwargs(prefer_refined_angles: bool = True, template_tensor: Tensor | None = None) -> dict[str, Any]

Create the kwargs for the backend refine_template core function.

Parameters:

  • prefer_refined_angles (bool, default: True ) –

    Whether to use the refined angles from the particle stack. Defaults to True.

  • template_tensor (Tensor | None, default: None ) –

    Optional template volume override. If None, the configured template volume/path is used.

make_differentiable_backend_kwargs 

make_differentiable_backend_kwargs(image_stack: Tensor, mean_stack: Tensor, std_stack: Tensor, particle_indices: list[Index], template_tensor: Tensor | None = None, prefer_refined_angles: bool = True, images_are_particles: bool = False) -> dict[str, Any]

Create the kwargs for the backend differentiable refine core function.

Parameters:

  • image_stack (Tensor) –

    Pre-loaded image stack tensor.

  • mean_stack (Tensor) –

    Pre-loaded mean stack tensor.

  • std_stack (Tensor) –

    Pre-loaded std stack tensor.

  • particle_indices (list[Index]) –

    The particle indices to process.

  • template_tensor (Tensor | None, default: None ) –

    Pre-loaded template tensor. If None, will be loaded from the template volume path. Defaults to None.

  • prefer_refined_angles (bool, default: True ) –

    Whether to use the refined angles from the particle stack. Defaults to True.

  • images_are_particles (bool, default: False ) –

    Whether the images are particles or not. Defaults to False.

run_refine_template 

run_refine_template(output_dataframe_path: str, correlation_batch_size: int = 32, output_format: Literal['csv', 'hdf5'] | None = None, allow_file_overwrite: bool = False) -> None

Run the refine template program and export the resultant DataFrame.

Parameters:

  • output_dataframe_path (str) –

    Path to save the refined particle data.

  • correlation_batch_size (int, default: 32 ) –

    Number of cross-correlations to process in one batch, defaults to 32.

  • output_format (Literal['csv', 'hdf5'] | None, default: None ) –

    Output back-end to write. Defaults to None, which matches the back-end of self.particle_stack (CSV in, CSV out; HDF5 in, HDF5 out). Pass "csv" or "hdf5" to override.

  • allow_file_overwrite (bool, default: False ) –

    Whether to overwrite an existing file at output_dataframe_path. Defaults to False.

run_differentiable_refine 

run_differentiable_refine(output_dataframe_path: str, image_stack: Tensor, mean_stack: Tensor, std_stack: Tensor, particle_indices: list[Index], template_tensor: Tensor | None = None, correlation_batch_size: int = 32, images_are_particles: bool = False, output_format: Literal['csv', 'hdf5'] | None = None, allow_file_overwrite: bool = False) -> None

Run the differentiable refine template program and export the DataFrame.

Parameters:

  • output_dataframe_path (str) –

    Path to save the refined particle data.

  • image_stack (Tensor) –

    Pre-loaded image stack tensor.

  • mean_stack (Tensor) –

    Pre-loaded mean stack tensor.

  • std_stack (Tensor) –

    Pre-loaded std stack tensor.

  • particle_indices (list[Index]) –

    The particle indices to process.

  • template_tensor (Tensor | None, default: None ) –

    Pre-loaded template tensor. If None, will be loaded from the template volume path. Defaults to None.

  • correlation_batch_size (int, default: 32 ) –

    Number of cross-correlations to process in one batch, defaults to 32.

  • images_are_particles (bool, default: False ) –

    Whether the images are particles or not. Defaults to False.

  • output_format (Literal['csv', 'hdf5'] | None, default: None ) –

    Output back-end to write. Defaults to None, which matches the back-end of self.particle_stack (CSV in, CSV out; HDF5 in, HDF5 out). Pass "csv" or "hdf5" to override.

  • allow_file_overwrite (bool, default: False ) –

    Whether to overwrite an existing file at output_dataframe_path. Defaults to False.

get_refine_result 

get_refine_result(backend_kwargs: dict, correlation_batch_size: int = 32, use_differentiable: bool = False) -> dict[str, np.ndarray | torch.Tensor]

Get refine template result.

Parameters:

  • backend_kwargs (dict) –

    Keyword arguments for the backend processing

  • correlation_batch_size (int, default: 32 ) –

    Number of orientations to process at once. Defaults to 32.

  • use_differentiable (bool, default: False ) –

    If True, use differentiable refine. If False, use regular refine. Defaults to False.

Returns:

  • dict[str, ndarray | Tensor] –

    The result of the refine template program. Returns torch.Tensor for differentiable refine, np.ndarray for regular refine.

refine_result_to_dataframe 

refine_result_to_dataframe(result: dict[str, ndarray | Tensor], prefer_refined_angles: bool = True) -> pd.DataFrame

Convert refine template result to a DataFrame.

Parameters:

  • result (dict[str, ndarray | Tensor]) –

    The result of the refine template program. Can contain either np.ndarray (regular refine) or torch.Tensor (differentiable refine).

  • prefer_refined_angles (bool, default: True ) –

    Whether to use the refined angles or not. Defaults to True.

Returns:

  • DataFrame –

    The refined particle data. Not written to disk; use export_results to do both in one call.

export_results 

export_results(output_dataframe_path: str, result: dict[str, ndarray | Tensor], prefer_refined_angles: bool = True, output_format: Literal['csv', 'hdf5'] | None = None, allow_file_overwrite: bool = False) -> ParticleStackCSV | ParticleStackHDF5

Build the refined DataFrame and write it to disk.

Parameters:

  • output_dataframe_path (str) –

    Path to save the refined particle data.

  • result (dict[str, ndarray | Tensor]) –

    The result of the refine template program. Can contain either np.ndarray (regular refine) or torch.Tensor (differentiable refine).

  • prefer_refined_angles (bool, default: True ) –

    Whether to use the refined angles or not. Defaults to True.

  • output_format (Literal['csv', 'hdf5'] | None, default: None ) –

    Output back-end to write. Defaults to None, which matches the back-end of self.particle_stack (CSV in, CSV out; HDF5 in, HDF5 out). Pass "csv" or "hdf5" to override.

  • allow_file_overwrite (bool, default: False ) –

    Whether to overwrite an existing file at output_dataframe_path. Defaults to False.

Returns:

  • ParticleStackCSV | ParticleStackHDF5 –

    The refined particle stack, already written to output_dataframe_path. Reuse directly instead of re-reading from disk if feeding into another program.