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-07-22 15:56:34.795374244 [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

---------------------------------------------------------------------------
InvalidProtobuf                           Traceback (most recent call last)
File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/mlgidbase/mlgiddetect_functions.py:68, in load_inference(analysis)
     67 try:
---> 68     analysis.imp_detect = Inference(analysis.config_detect)
     69 except:

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/mlgiddetect/inference/inference.py:32, in Inference.__init__(self, config)
     31     sess_options.intra_op_num_threads = 1
---> 32 self.sess = rt.InferenceSession(model_path, providers=preferred_providers, sess_options=sess_options)

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/onnxruntime/capi/onnxruntime_inference_collection.py:528, in InferenceSession.__init__(self, path_or_bytes, sess_options, providers, provider_options, **kwargs)
    527 try:
--> 528     self._create_inference_session(providers, provider_options, disabled_optimizers)
    529 except (ValueError, RuntimeError) as e:

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/onnxruntime/capi/onnxruntime_inference_collection.py:623, in InferenceSession._create_inference_session(self, providers, provider_options, disabled_optimizers)
    622 if self._model_path:
--> 623     sess = C.InferenceSession(session_options, self._model_path, True, self._read_config_from_model)
    624 else:

InvalidProtobuf: [ONNXRuntimeError] : 7 : INVALID_PROTOBUF : Load model from /home/docs/.local/share/mlgiddetect/dino.onnx failed:Protobuf parsing failed.

During handling of the above exception, another exception occurred:

ValueError                                Traceback (most recent call last)
Cell In[1], line 4
      1 from mlgidbase import mlgidBASE
      2 filename = r'../../example/BA2PbI4.h5'
      3 analysis = mlgidBASE(filename=filename)
----> 4 analysis.run_detection()
      5 analysis.run_fitting()

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/mlgidbase/main.py:194, in mlgidBASE.run_detection(self, entry, frame_num, config_detect, model_type)
    179 def run_detection(self, entry=None, frame_num=None, config_detect=None, model_type=None):
    180     """
    181     Run peak detection on the dataset.
    182 
   (...)    192         Type of detection model to use (e.g., 'faster_rcnn', 'dino').
    193     """
--> 194     _run_detection(self, entry, frame_num, config_detect, model_type)

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/mlgidbase/mlgiddetect_functions.py:48, in _run_detection(analysis, entry, frame_num, config_detect, model_type)
     43 # if model_type is not None:
     44 #     if analysis.config_detect.MODEL_TYPE != model_type:
     45 #         analysis.config_detect.MODEL_TYPE = model_type
     46 #         analysis.imp_detect = None
     47 if analysis.imp_detect is None:
---> 48     load_inference(analysis)
     50 if not analysis.from_nexus:
     51     if frame_num != 1 and not frame_num is None:

File ~/checkouts/readthedocs.org/user_builds/mlgidbase/envs/latest/lib/python3.11/site-packages/mlgidbase/mlgiddetect_functions.py:70, in load_inference(analysis)
     68     analysis.imp_detect = Inference(analysis.config_detect)
     69 except:
---> 70     raise ValueError("Detection failed. Couldn't load the model.")

ValueError: Detection failed. Couldn't load the model.

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',
    )

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 'segments'. 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',
)

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

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