Tutorial 4: Peak Matching

Peak matching relies on mlgidMATCH package. First, create the mlgidBASE class instance, run detection and fitting:

from mlgidbase import mlgidBASE
filename = r'../../example/BA2PbI4.h5'
analysis = mlgidBASE(filename=filename)
analysis.run_detection()
analysis.run_fitting()

2026-05-26 13:55:54.582894482 [W:onnxruntime:Default, device_discovery.cc:283 GetGpuDevices] Failed to detect devices under "/sys/class/drm/card0": device_discovery.cc:93 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor"

INFO - Loading model

INFO - Saved detected peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0

INFO - Saved fitted peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0

CIF preprocessing

Before usage, a preprocessing of CIF files should be done (see full documentation):

import warnings
warnings.filterwarnings("ignore")

from mlgidmatch.preprocess.cif_preprocess import CifPattern
from pygidsim.experiment import ExpParameters

# path to the folder with CIF files
folder_path = '../../example/cifs/'

params = ExpParameters(q_xy_max=5, # maximum q_xy value (Å⁻¹)
                       q_z_max=5,  # maximum q_z value (Å⁻¹)
                       en=24000)   # X-ray beam energy (eV)

cif_prepr = CifPattern(
    params=params,
    folder_path=folder_path,
    create_all=True
)

This step needs to be performed only once for a given set of CIF files. The CifPattern instance is then used during the matching stage. It can also be saved and reused across different samples to avoid repeated preprocessing:

import pickle

with open('../../example/prepr_cifs.pickle', 'wb') as file:
    pickle.dump(cif_prepr, file)

Then run matching:

Minimal Code Example

analysis.run_matching(
    cif_prepr = r'../../example/prepr_cifs.pickle',
    peaks_type='segments',
    )

INFO - Saved matched peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0

Parameters

entry (str) — Data file entry to process. Defaults to None (process all entries). OPTIONAL
frame_num (int or List[int]) — Frame number(s) within each entry to process. Defaults to None (all frames). OPTIONAL
cif_prepr (CifPattern or str) — Preprocessed CIFs object (CifPattern) or path to a PICKLE file. REQUIRED
peaks_type (str) — Type of peaks used for matching: 'segments' (2D) or 'rings' (1D). Defaults to 'peaks'. REQUIRED
probability_threshold (float) — Matching threshold for peaks (0–1). Defaults to 0.5. OPTIONAL
intensity_threshold (float) — Minimum intensity of fitted peaks to be considered for matching. OPTIONAL
device (str) — Computation device ('cpu' or 'cuda'). Defaults to None (automatic detection). OPTIONAL

Description

You can process a single entry or all entries in the file by setting entry=None. The frame_num parameter accepts either a single integer or a list of frame indices.

The cif_prepr argument should be a CifPattern instance or a path to a saved PICKLE file. It can be set only once for the mlgidBASE instance to avoid the repeating the

The peaks_type parameter defines the type of data to match: either rings (1D matching) or segments (2D matching).

probability_threshold (0–1) controls how strict the matching is, while intensity_threshold ignores fitted peaks with low intensity. The computation device can be specified via device or automatically detected.

analysis.run_matching(
    cif_prepr = r'../../example/prepr_cifs.pickle',
    peaks_type='segments',
    probability_threshold=0.1,
    intensity_threshold=0,
    device='cuda',
)

INFO - cif_prepr is already set. The previous cif_prepr is to be used

INFO - Saved matched peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0

analysis.run_matching(
    cif_prepr = r'../../example/prepr_cifs.pickle',
    peaks_type='rings',
    probability_threshold=0.9,
    intensity_threshold=0,
)

INFO - cif_prepr is already set. The previous cif_prepr is to be used

INFO - No solutions for (../../example/BA2PbI4.h5, entry: entry_0000, frame: 0) was found. Try to decrease threshold

The results can be visualized using silx view or loaded from the saved file, as shown in Tutorial 8.