{
 "cells": [
  {
   "metadata": {
    "collapsed": true
   },
   "cell_type": "markdown",
   "source": "# Tutorial 3: Peak Fitting",
   "id": "ca138800a4b85768"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-26T16:10:34.487403729Z",
     "start_time": "2026-03-26T16:10:34.484636830Z"
    }
   },
   "cell_type": "markdown",
   "source": [
    "Peak fitting relies on [`pygidFIT`](https://github.com/mlgid-project/pygidFIT) package.\n",
    "First, create the mlgidBASE class instance and run detection:\n"
   ],
   "id": "a0a77b4c1f7cde9a"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-26T16:12:08.105808338Z",
     "start_time": "2026-03-26T16:12:04.975044458Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from mlgidbase import mlgidBASE\n",
    "filename = '../../example/BA2PbI4.h5'\n",
    "analysis = mlgidBASE(filename=filename)\n",
    "analysis.run_detection()"
   ],
   "id": "c73ca44626e694eb",
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO - Loading model\n",
      "INFO - Using the GPU for inference\n",
      "INFO - Saved detected peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0\n"
     ]
    }
   ],
   "execution_count": 4
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-26T16:11:32.133821148Z",
     "start_time": "2026-03-26T16:11:32.121583596Z"
    }
   },
   "cell_type": "markdown",
   "source": [
    "Then run fitting:\n",
    "\n",
    "---\n",
    "#### **Minimal Code Example**"
   ],
   "id": "8f2264f3d99bd58e"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-26T16:12:10.038706588Z",
     "start_time": "2026-03-26T16:12:08.107192327Z"
    }
   },
   "cell_type": "code",
   "source": "analysis.run_fitting()",
   "id": "fc07a1ab577d3f95",
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO - Saved fitted peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0\n"
     ]
    }
   ],
   "execution_count": 5
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "### Parameters\n",
    "\n",
    "- `entry` (str) — Data file entry to process. Defaults to `None` (all entries). OPTIONAL\n",
    "- `frame_num` (int/List[int]) — Frame number in each entry for detection / list of frames. Defaults to `None` (all frames).\n",
    "- `clustering_distance_peaks` (float) — Distance threshold for clustering peaks. Defaults to `10`.\n",
    "- `clustering_distance_rings` (float) — Distance threshold for clustering rings. Defaults to `10`.\n",
    "- `clustering_extend` (float) — Cluster extension factor. Defaults to `2`.\n",
    "- `theta_fixed` (bool) - Whether to fix Gaussian tilt angle to 0° (azimuthal direction) during fitting. Defaults to `True`\n",
    "- `crit_angle` (float) — Critical angle used in fitting. Defaults to `0`.\n",
    "- `use_pool` (bool) — Enable multiprocessing. Defaults to `False`.\n",
    "- `debug` (bool) — Enable debug output. Defaults to `False`."
   ],
   "id": "e5b742d120ed3a9a"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "### Decription\n",
    "The user can specify a single entry or process all entries in the file by setting `entry=None`. The `frame_num` parameter accepts either a single `int` or a `list` of frame indices to process.\n",
    "\n",
    "Clustering is controlled by a distance threshold that defines how close detected boxes need to be to form a cluster. The `clustering_extend` parameter adds extra pixels to the cluster size and can be useful for broad peaks.\n",
    "\n",
    "In many cases, peaks are azimuthally oriented. However, in GID geometry, peaks can also appear along truncation rods (i.e., along \\(q_z\\)). In this case, the tilt angle `theta` of the 2D Gaussian should be included in the fit. To enable this, set `theta_fixed=False`.\n",
    "\n",
    "The `crit_angle` parameter (in degrees) can be used to account for the sample horizon. The region below this angle will be masked.\n",
    "\n",
    "For time series, peak pooling can be enabled with `use_pool=True`. This reuses fitted parameters from previous frames as initial guesses and can speed up the fitting.\n",
    "\n",
    "To visualize and print fitting details, set `debug=True`."
   ],
   "id": "8a672a6759d7d25e"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-27T08:56:47.043164369Z",
     "start_time": "2026-03-27T08:56:46.125632468Z"
    }
   },
   "cell_type": "code",
   "source": [
    "analysis = mlgidBASE(filename=filename)\n",
    "analysis.run_fitting(\n",
    "    entry='entry_0000',\n",
    "    frame_num=0,\n",
    "    clustering_distance_peaks=10,\n",
    "    clustering_distance_rings=10,\n",
    "    clustering_extend=2,\n",
    "    crit_angle=1,\n",
    "    theta_fixed=False,\n",
    "    use_pool=True,\n",
    "    debug=False,\n",
    ")"
   ],
   "id": "c9a5ff75c0ea5a8c",
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO - Saved fitted peaks to file: ../../example/BA2PbI4.h5, entry: entry_0000, frame: 0\n"
     ]
    }
   ],
   "execution_count": 6
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2026-03-27T10:38:32.684911970Z",
     "start_time": "2026-03-27T10:38:32.648827690Z"
    }
   },
   "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": "e6035fa741ee7e06"
  },
  {
   "metadata": {},
   "cell_type": "code",
   "outputs": [],
   "execution_count": null,
   "source": "",
   "id": "bab152be9a3e0023"
  }
 ],
 "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
}