autoemx.runners.collect_particle_statistics module

Created on Thu Oct 9 10:14:12 2025

@author: Andrea

autoemx.runners.collect_particle_statistics.collect_particle_statistics(samples: List[Dict[str, Any]], n_par_target: int, microscope_ID: str = 'PhenomXL', microscope_type: str = 'SEM', detector_type: str = 'BSD', sample_halfwidth: float = 2.9, sample_substrate_type: str = 'Ctape', sample_substrate_shape: str = 'circle', sample_substrate_width_mm: float = 12, working_distance: float = 5, is_manual_navigation: bool = False, is_auto_substrate_detection: bool = False, auto_adjust_brightness_contrast: bool = True, contrast: float = 4.3877, brightness: float = 0.4504, saved_images_extension: str = 'png', save_raw_images: bool = False, powder_meas_cfg_kwargs: Dict[str, Any] | None = None, output_filename_suffix: str = '', development_mode: bool = False, verbose: bool = True, results_dir: str | None = None, on_sample_done: Callable[[str, BaseException | None], None] | None = None) → None[source]

Particle size statistics of a list of powder samples, measured at the electron microscope.

For each sample, particles are detected in frames scanned over the sample until n_par_target particles are found in each size band (see EM_Particle_Finder.get_particle_stats). The statistics are stored in the sample ledger (ledger.json) and saved as particle sizes, statistics and histogram files in the sample folder.

Parameters:

  • samples (list of dict) –

    List of sample definitions. Each dictionary must contain:

    • ’ID’ (str): Sample identifier (SampleConfig.ID).

    • ’pos’ (tuple of float): (x, y) stage coordinates in mm (SampleConfig.center_pos).

  • n_par_target (int) – Target number of particles to analyse, in each size band.

  • microscope_ID (str, optional) – Identifier for the microscope hardware. Must correspond to a calibration folder in ./XSp_calibs/Microscopes/<ID> (MicroscopeConfig.ID). Default is ‘PhenomXL’.

  • microscope_type (str, optional) – Type of microscope. Allowed: ‘SEM’ (implemented), ‘STEM’ (not implemented). Default is ‘SEM’ (MicroscopeConfig.type).

  • detector_type (str, optional) – Default : BSD

  • sample_halfwidth (float, optional) – Half-width of the sample area in mm for mapping/acquisition. Default is 3.0 (SampleConfig.half_width_mm).

  • sample_substrate_type (str, optional) – Type of sample substrate. Allowed: ‘Ctape’, ‘None’. Default is ‘Ctape’ (SampleSubstrateConfig.type).

  • sample_substrate_shape (str, optional) – Shape of the substrate. Allowed: ‘circle’, ‘square’. Default is ‘circle’ (SampleSubstrateConfig.shape).

  • sample_substrate_width_mm (float, optional) – Lateral dimension of substrate holder in mm (SampleSubstrateConfig.stub_w_mm).

  • working_distance (float, optional) – Working distance in mm for acquisition. If None, taken from microscope driver. Default is 5.0 (MeasurementConfig.working_distance).

  • is_manual_navigation (bool, optional) – If True, navigation to sample positions is manual. Default is False (MeasurementConfig.is_manual_navigation).

  • is_auto_substrate_detection (bool, optional) – If True, substrate elements are detected automatically. Implemented only for ‘Ctape’ substrates. Default is False (SampleSubstrateConfig.auto_detection).

  • auto_adjust_brightness_contrast (bool, optional) – If True, brightness/contrast are set automatically. Default is True (MicroscopeConfig.is_auto_BC).

  • contrast (float, optional) – Manual contrast setting (required if auto_adjust_brightness_contrast is False). Default is 4.3877 (MicroscopeConfig.contrast).

  • brightness (float, optional) – Manual brightness setting (required if auto_adjust_brightness_contrast is False). Default is 0.4504 (MicroscopeConfig.brightness).

  • saved_images_extension (str, optional) – File extension for saved SEM images. Allowed: ‘png’, ‘tif’, ‘jpg’, ‘webp’. ‘png’ and ‘tif’ are both lossless (8-bit), ‘png’ smaller; avoid ‘jpg’ for images to reanalyse. Default is taken from defaults (MeasurementConfig.saved_images_extension).

  • save_raw_images (bool, optional) – If True, also save raw (unannotated) SEM images alongside annotated frames. Default is False (saves only annotated images, lightweight output). Default is taken from defaults (MeasurementConfig.save_raw_images).

  • powder_meas_cfg_kwargs (dict, optional) – Additional keyword arguments for PowderMeasurementConfig.

  • output_filename_suffix (str, optional) – String appended to output filenames. Default is ‘’.

  • development_mode (bool, optional) – If True, enables development/debug features. Default is False.

  • verbose (bool, optional) – If True, print verbose output. Default is True.

  • results_dir (str, optional) – Directory where results are saved. Default is None.

  • on_sample_done (callable, optional) –

    Called after each sample with its ID and None if it was measured successfully, or the exception that made it fail (the batch then continues with the next sample). Signature:

    on_sample_done(sample_id: str, error: Optional[BaseException])

Returns:

Results are saved in the folder of each sample.

Return type:

None