{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0c7fbc7d",
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ee28d8c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "452ac3ce",
   "metadata": {},
   "source": [
    "# Parameter Definition"
   ]
  },
  {
   "cell_type": "raw",
   "id": "23cf3a4b",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Parameters are fundamental parts of a likelihood function. Two types of parameters exist: *fixed parameters* and *floating parameters*.\n",
    "\n",
    "SkyLLH provides the class :py:class:`~skyllh.core.parameters.Parameter` for defining a parameter. The ``Parameter`` class can represent a fixed parameter or a floating parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "84bb97d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "from skyllh.core.parameters import Parameter"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "4aa38262",
   "metadata": {},
   "source": [
    "Creating a fixed parameter\n",
    "---"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "05ea8128",
   "metadata": {},
   "source": [
    "A fixed parameter has a name and an initial value. Its `isfixed` property is set to `True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "1ca1c10d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: a = 2.1 [fixed]\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "param_a = Parameter(name='a', initial=2.1)\n",
    "print(param_a)\n",
    "print(param_a.isfixed)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "8ee3caed",
   "metadata": {},
   "source": [
    "Changing the value of a fixed parameter\n",
    "---"
   ]
  },
  {
   "cell_type": "raw",
   "id": "3a596000",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Sometimes it is neccessary to change the value of a fixed parameter. This can be done using the :py:meth:`~skyllh.core.parameters.Parameter.change_fixed_value` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "c44eb063",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: a = 3.3 [fixed]\n"
     ]
    }
   ],
   "source": [
    "param_a.change_fixed_value(3.3)\n",
    "print(param_a)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "9c014787",
   "metadata": {},
   "source": [
    "Creating a floating parameter\n",
    "---"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "1a1d2233",
   "metadata": {},
   "source": [
    "A floating parameter has a name, an initial value, and a value range from `valmin` to `valmax`. Its `isfixed` property is set to `False`.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "fd0c5677",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: b = 6.3 [floating] {\n",
      "    initial: 6.3\n",
      "    range: (4, 7.3)\n",
      "}\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "param_b = Parameter(name='b', initial=6.3, valmin=4.0, valmax=7.3)\n",
    "print(param_b)\n",
    "print(param_b.isfixed)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "372136e3",
   "metadata": {},
   "source": [
    "Converting fixed and floating parameters\n",
    "---"
   ]
  },
  {
   "cell_type": "raw",
   "id": "6fa4021b",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Fixed parameters can be made floating parameters and vise-versa. For making a fixed parameter floating one can use the :py:meth:`~skyllh.core.parameters.Parameter.make_floating` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8971a4cc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: a = 3.3 [floating] {\n",
      "    initial: 3.3\n",
      "    range: (0, 4)\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "# Converting a fixed parameter into a floating parameter.\n",
    "param_a.make_floating(initial=3.3, valmin=0, valmax=4)\n",
    "print(param_a)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "eaf7659c",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "For converting a floating parameter into a fixed parameter one can use the :py:meth:`~skyllh.core.parameters.Parameter.make_fixed` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "4f8937e2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: b = 42.3 [fixed]\n"
     ]
    }
   ],
   "source": [
    "# Converting a floating parameter into a fixed parameter.\n",
    "param_b.make_fixed(initial=42.3)\n",
    "print(param_b)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "14c1f859",
   "metadata": {},
   "source": [
    "Comparing parameters\n",
    "---"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "1a0bbbd4",
   "metadata": {},
   "source": [
    "Two parameters can be compared to each other. They are equal if they represent the same parameter, i.e. the same name, initial value, and value range if they are floating parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "c56a9337",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "param_c = Parameter(name='b', initial=42.3)\n",
    "print(param_c == param_b)\n",
    "print(param_c is param_b)\n",
    "print(param_c == param_a)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "7baeace5",
   "metadata": {},
   "source": [
    "Creating a linear grid from a floating parameter\n",
    "---"
   ]
  },
  {
   "cell_type": "raw",
   "id": "5bc65287",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Sometimes it useful to create an equal-distanced grid of values from a floating parameter. The :py:class:`~skyllh.core.parameters.Parameter` class has the method :py:meth:`~skyllh.core.parameters.Parameter.as_linear_grid` to create a :py:class:`~skyllh.core.parameters.ParameterGrid` instance representing a grid of values with equal distances. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "fcd28e13",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a = [0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.  1.1 1.2 1.3 1.4 1.5 1.6 1.7\n",
      " 1.8 1.9 2.  2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 3.  3.1 3.2 3.3 3.4 3.5\n",
      " 3.6 3.7 3.8 3.9 4. ], decimals = 1\n"
     ]
    }
   ],
   "source": [
    "param_grid_a = param_a.as_linear_grid(delta=0.1)\n",
    "print(param_grid_a)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f95e23ba",
   "metadata": {},
   "source": [
    "Parameter Sets\n",
    "---"
   ]
  },
  {
   "cell_type": "raw",
   "id": "6bb9e044",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "For an analysis a set of parameters are usually required. The set of parameters for the likelihood function might depend on the particlar source in case of a multi-source analysis.\n",
    "\n",
    "Each analysis needs to define a global set of parameters. SkyLLH provides the :py:class:`~skyllh.core.parameters.ParameterSet` class to define a set of parameters. How these parameters are then mapped to the individual sources is defined via the *source parameter mapper*."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "9fc97436",
   "metadata": {},
   "source": [
    "As example we are creating a set of two Parameters, $n_{\\mathrm{s}}$, and $\\gamma$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "dca5bff6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Parameter: ns = 100 [floating] {\n",
      "    initial: 100\n",
      "    range: (0, 1000)\n",
      "}\n",
      "Parameter: gamma = 2 [floating] {\n",
      "    initial: 2\n",
      "    range: (1, 4)\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "param_ns = Parameter('ns', 100, valmin=0, valmax=1000)\n",
    "param_gamma = Parameter('gamma', 2, valmin=1, valmax=4.)\n",
    "print(param_ns)\n",
    "print(param_gamma)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "74243d30",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ParameterSet: 2 parameters (2 floating, 0 fixed) {\n",
      "    Parameter: ns = 100 [floating] {\n",
      "        initial: 100\n",
      "        range: (0, 1000)\n",
      "    }\n",
      "    Parameter: gamma = 2 [floating] {\n",
      "        initial: 2\n",
      "        range: (1, 4)\n",
      "    }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "from skyllh.core.parameters import ParameterSet\n",
    "paramset = ParameterSet((param_ns, param_gamma))\n",
    "print(paramset)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "d03240f5",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. _sec:ParameterToModelMapping:"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "e4d11628",
   "metadata": {},
   "source": [
    "Parameter to Model mapping\n",
    "--"
   ]
  },
  {
   "cell_type": "raw",
   "id": "306be6d3",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "After a global set of parameters is defined, those parameters need to get mapped to individual models, e.g. sources, of the analysis. SkyLLH provides the :py:class:`~skyllh.core.parameters.ParameterModelMapper` class to provide this functionality."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "7357a9d8",
   "metadata": {},
   "source": [
    "As example we consider the following mapping of parameters to models and sources:"
   ]
  },
  {
   "cell_type": "raw",
   "id": "23a8c0c1",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "+--------------+-----+--------+--------+\n",
    "| Parameter >  | ns  | gamma1 | gamma2 |\n",
    "+--------------+-----+--------+--------+\n",
    "| Model/Source |                       |\n",
    "+==============+=====+========+========+\n",
    "| detector     | ns  | ---    | ---    |\n",
    "+--------------+-----+--------+--------+\n",
    "| source1      | --- | gamma  | ---    |\n",
    "+--------------+-----+--------+--------+\n",
    "| source2      | --- | ---    | gamma  |\n",
    "+--------------+-----+--------+--------+"
   ]
  },
  {
   "cell_type": "raw",
   "id": "ed80f417",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "SkyLLH provides two main base models: :py:class:`~skyllh.core.model.DetectorModel` and :py:class:`~skyllh.core.model.SourceModel`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "291cd40a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from skyllh.core.model import DetectorModel\n",
    "from skyllh.core.source_model import SourceModel\n",
    "from skyllh.core.parameters import ParameterModelMapper"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "11dfec3c",
   "metadata": {},
   "source": [
    "We define the models and sources to which we want to map parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "efce19d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "detector = DetectorModel('IceCube')\n",
    "source1 = SourceModel('source1')\n",
    "source2 = SourceModel('source2')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "a61d6084",
   "metadata": {},
   "source": [
    "Now we define the parameters, which we want to map to the models and sources:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "c40c67f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "param_ns = Parameter('ns', 10, valmin=0, valmax=1000)\n",
    "param_gamma1 = Parameter('gamma1', 2.5, valmin=1, valmax=4)\n",
    "param_gamma2 = Parameter('gamma2', 3.3, valmin=1, valmax=4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "c0d59c37",
   "metadata": {},
   "source": [
    "After creating the models and parameters we can create the `ParameterModelMapper` for the set of models."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "adfa6943",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ParameterModelMapper: 0 global parameters, 3 models (2 sources)\n"
     ]
    }
   ],
   "source": [
    "pmm = ParameterModelMapper(models=(detector,source1,source2))\n",
    "print(pmm)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f351e77f",
   "metadata": {},
   "source": [
    "Finally we can define the parameter mapping of each parameter to the models:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "1d1cad2d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ParameterModelMapper: 3 global parameters, 3 models (2 sources)\n",
      "    Parameters:        \n",
      "        ns [floating (0 <= 10 <= 1000)]\n",
      "            in models:\n",
      "            - IceCube: ns\n",
      "                    \n",
      "        gamma1 [floating (1 <= 2.5 <= 4)]\n",
      "            in models:\n",
      "            - source1: gamma\n",
      "                    \n",
      "        gamma2 [floating (1 <= 3.3 <= 4)]\n",
      "            in models:\n",
      "            - source2: gamma\n",
      "            \n"
     ]
    }
   ],
   "source": [
    "(pmm.map_param(param_ns, models=(detector,), model_param_names='ns')\n",
    "    .map_param(param_gamma1, models=(source1,), model_param_names='gamma')\n",
    "    .map_param(param_gamma2, models=(source2,), model_param_names='gamma')\n",
    ")\n",
    "print(pmm)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "c49c165f",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The :py:meth:`~skyllh.core.parameters.ParameterModelMapper.create_src_params_recarray` method of the :py:class:`~skyllh.core.parameters.ParameterModelMapper` class can create a numpy record array with the local source parameters of all or selected sources: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "8623b261",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([(1, 1.1, 2), (2, 2.2, 3)],\n",
       "      dtype=[(':model_idx', '<i4'), ('gamma', '<f8'), ('gamma:gpidx', '<i4')])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pmm.create_src_params_recarray(gflp_values=np.array([11, 1.1, 2.2]), sources=None)"
   ]
  },
  {
   "cell_type": "raw",
   "id": "8aa8cca9",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "A dictionary with a model's local parameters and values can be created via the :py:meth:`~skyllh.core.parameters.ParameterModelMapper.create_model_params_dict` method. It takes a model argument, which can either be a ``str`` with the model's name, the actual :py:class:`~skyllh.core.model.Model` instance, or an ``int`` instance specifying the model index within the :py:class:`~skyllh.core.parameters.ParameterModelMapper`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "f5c94f5c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'ns': 11.0}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pmm.create_model_params_dict(gflp_values=np.array([11, 1.1, 2.2]), model='IceCube')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "86fcb788",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'gamma': 1.1}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pmm.create_model_params_dict(gflp_values=np.array([11, 1.1, 2.2]), model=source1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "4c2ab4dc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'gamma': 2.2}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pmm.create_model_params_dict(gflp_values=np.array([11, 1.1, 2.2]), model=2)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}