Data Structures

Bases: BaseModel2DTM

Stores optics group parameters for the imaging system on a microscope.

Currently utilizes the minimal set of parameters for calculating a contrast transfer function (CTF) for a given optics group. Other parameters for future use are included but currently unused.

Attributes:

• label (str) –

  Unique string (among other optics groups) for the optics group.

• pixel_size (float) –

  Pixel size in Angstrom.

• voltage (float) –

  Voltage in kV.

• spherical_aberration (float) –

  Spherical aberration in mm. Default is 2.7.

• amplitude_contrast_ratio (float) –

  Amplitude contrast ratio as a unitless percentage in [0, 1]. Default is 0.07.

• phase_shift (float) –

  Additional phase shift of the contrast transfer function in degrees. Default is 0.0 degrees.

• defocus_u (float) –

  Defocus (underfocus) along the major axis in Angstrom.

• defocus_v (float) –

  Defocus (underfocus) along the minor axis in Angstrom.

• astigmatism_angle (float) –

  Angle of defocus astigmatism relative to the X-axis in degrees.

• ctf_B_factor (float) –

  B-factor to apply in the contrast transfer function in A^2. Default is 0.0.

Methods:

• model_dump –

  Returns a dictionary of the model parameters.

mag_matrix_tensor: Tensor | None

Bases: _ParticleStackBase

Particle stack whose tabular data is loaded from a CSV file.

Particle images are extracted from the micrograph paths referenced in the CSV at run time. This is the original ParticleStack behavior.

Attributes:

• df_path (str) –

  Path to the CSV file containing the particle data.

load_df() -> None

export_results(allow_file_overwrite: bool = False) -> None

to_hdf5(hdf5_path: str, allow_file_overwrite: bool = False, include_image_stack: bool = False, include_local_stats: bool = False) -> ParticleStackHDF5

Bases: _ParticleStackBase

Particle stack stored entirely within a single HDF5 file.

The particle table, optional image stack, and optional per-particle local statistic maps are all held in one .h5 file. Two loading modes are supported — choose one. Mixing them raises errors:

• Load from referenced files: image_stack and local_stats are computed from the paths stored in the particle table. The HDF5 file stores only the particle table (image_stack_stored=False).
• Load from HDF5: image_stack and local_stats are read directly from the HDF5 datasets (image_stack_stored=True and/or local_stats_stored=True).

Any subset of the *_path statistic-map columns can be stored as local_stats -- not just correlation average/variance. Populate self.local_stats (e.g. via self.local_stats.update(self.get_local_stat_maps())) before calling to_hdf5(include_local_stats=True), and every entry present at that point is written, each to its own dataset under /local_stats named after its column (e.g. mip_path, correlation_average_path).

/ (root)
│  attrs: leopard_em_version, extracted_box_size, original_template_size,
│         image_stack_stored, local_stats_stored,
│         global_whitening_applied, local_whitening_applied,
│         global_normalization_applied, local_normalization_applied
├─ particles/
│      particle_id            (N,)   variable-length str  "{mic_stem}_{idx:05d}"
│      <column>               (N,)   float64 or variable-length str
│      ...
├─ image_stack                (N, box_h, box_w)             float32  [optional]
└─ local_stats/                                                      [optional]
       <column>                (N, valid_h, valid_w)         float32
       ...                                     -- one dataset per entry in
                                                   `local_stats` at write time,
                                                   e.g. `mip_path`,
                                                   `correlation_average_path`

Attributes:

• hdf5_path (str) –

  Path to the HDF5 file.

• allow_file_overwrite (bool) –

  Whether to permit overwriting an existing file, by default False.

• image_stack_stored (bool) –

  True when /image_stack is present in the HDF5 file.

• local_stats_stored (bool) –

  True when /local_stats group is present in the HDF5 file.

load_df() -> None

export_results(include_image_stack: bool = False, include_local_stats: bool = False) -> None

to_hdf5(include_image_stack: bool = False, include_local_stats: bool = False) -> None

from_hdf5(path: str, allow_file_overwrite: bool = True) -> ParticleStackHDF5