{
 "cells": [
  {
   "metadata": {
    "collapsed": true
   },
   "cell_type": "markdown",
   "source": "# Tutorial 4: Peak Matching",
   "id": "f5cb1b9aae5dc28a"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "Peak matching relies on [`mlgidMATCH`](https://github.com/mlgid-project/mlgidMATCH) package.\n",
    "First, create the mlgidBASE class instance, run detection and fitting:\n"
   ],
   "id": "29f2da8360bba2d6"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "from mlgidbase import mlgidBASE\n",
    "filename = r'../../example/BA2PbI4.h5'\n",
    "analysis = mlgidBASE(filename=filename)\n",
    "analysis.run_detection()\n",
    "analysis.run_fitting()"
   ],
   "id": "5992f5db681110a7",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-27T09:04:41.101917699Z",
     "start_time": "2026-03-27T09:04:41.093337533Z"
    }
   },
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "### CIF preprocessing\n",
    "Before usage, a preprocessing of CIF files should be done (see full [documentation](https://github.com/mlgid-project/mlgidMATCH)):"
   ],
   "id": "36c6dfa976c56121"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "from mlgidmatch.preprocess.cif_preprocess import CifPattern\n",
    "from pygidsim.experiment import ExpParameters\n",
    "\n",
    "# path to the folder with CIF files\n",
    "folder_path = '../../example/cifs/'\n",
    "\n",
    "params = ExpParameters(q_xy_max=5, # maximum q_xy value (Å⁻¹)\n",
    "                       q_z_max=5,  # maximum q_z value (Å⁻¹)\n",
    "                       en=24000)   # X-ray beam energy (eV)\n",
    "\n",
    "cif_prepr = CifPattern(\n",
    "    params=params,\n",
    "    folder_path=folder_path,\n",
    "    create_all=True\n",
    ")"
   ],
   "id": "8f35955a67ecd5db",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "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:",
   "id": "f526320734c9ac4"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "import pickle\n",
    "\n",
    "with open('../../example/prepr_cifs.pickle', 'wb') as file:\n",
    "    pickle.dump(cif_prepr, file)"
   ],
   "id": "cb361565de91485f",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "Then run matching:\n",
    "\n",
    "---\n",
    "#### **Minimal Code Example**"
   ],
   "id": "7ce48f0f6e3bb7da"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "analysis.run_matching(\n",
    "    cif_prepr = r'../../example/prepr_cifs.pickle',\n",
    "    peaks_type='segments',\n",
    "    )"
   ],
   "id": "2753641d1f49fe20",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "### Parameters\n",
    "\n",
    "- `entry` (str) — Data file entry to process. Defaults to `None` (process all entries). OPTIONAL\n",
    "- `frame_num` (int or List[int]) — Frame number(s) within each entry to process. Defaults to `None` (all frames). OPTIONAL\n",
    "- `cif_prepr` (CifPattern or str) — Preprocessed CIFs object (`CifPattern`) or path to a PICKLE file. REQUIRED\n",
    "- `peaks_type` (str) — Type of peaks used for matching: `'segments'` (2D) or `'rings'` (1D). Defaults to `'peaks'`. REQUIRED\n",
    "- `probability_threshold` (float) — Matching threshold for peaks (0–1). Defaults to `0.5`. OPTIONAL\n",
    "- `intensity_threshold` (float) — Minimum intensity of fitted peaks to be considered for matching. OPTIONAL\n",
    "- `device` (str) — Computation device (`'cpu'` or `'cuda'`). Defaults to `None` (automatic detection). OPTIONAL\n",
    "\n",
    "---\n"
   ],
   "id": "c3993005fc8969d5"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "### Description\n",
    "\n",
    "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.\n",
    "\n",
    "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\n",
    "\n",
    "The `peaks_type` parameter defines the type of data to match: either rings (1D matching) or segments (2D matching).\n",
    "\n",
    "`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."
   ],
   "id": "471eec4d4c4c060c"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "analysis.run_matching(\n",
    "    cif_prepr = r'../../example/prepr_cifs.pickle',\n",
    "    peaks_type='segments',\n",
    "    probability_threshold=0.1,\n",
    "    intensity_threshold=0,\n",
    "    device='cuda',\n",
    ")"
   ],
   "id": "b2c4191918dabc86",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": [
    "analysis.run_matching(\n",
    "    cif_prepr = r'../../example/prepr_cifs.pickle',\n",
    "    peaks_type='rings',\n",
    "    probability_threshold=0.9,\n",
    "    intensity_threshold=0,\n",
    ")"
   ],
   "id": "bab6e597a3a9bb40",
   "outputs": [],
   "execution_count": null
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "The results can be visualized using `silx view` or loaded from the saved file, as shown in [Tutorial 8](tutorial_08_get_data.ipynb).",
   "id": "7c78005652589ef7"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "source": "",
   "id": "1efea1530818af56",
   "outputs": [],
   "execution_count": null
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}