Updated the docs

.gitignore

@@ -136,5 +136,10 @@ dmypy.json
 profile.json
 profile.html
 
+# Latex compilation files
+*.aux
+*.bbl
+*.blg
+
 # Local temporary data repositories
 .repository

README.md

@@ -8,6 +8,9 @@
 
 The SkyLLH framework is an open-source Python3-based package licensed under the GPLv3 license. It provides a modular framework for implementing custom likelihood functions and executing log-likelihood ratio hypothesis tests. The idea is to provide a class structure tied to the mathematical objects of the likelihood functions, rather than to entire abstract likelihood models.
 
+The math formalism used in SkyLLH is described in the
+[[math formalism document]](https://github.com/icecube/skyllh/blob/master/doc/user_manual.pdf).
+
 # Installation
 
 ## Using pip

doc/sphinx/concepts/config.ipynb

@@ -1,24 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%load_ext autoreload\n",
-    "%autoreload 2"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import numpy as np"
-   ]
-  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -29,7 +10,9 @@
   },
   {
    "cell_type": "raw",
-   "metadata": {},
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
    "source": [
     "An analysis requires a (local) configuration. Such a configuration defines for\n",
     "instance the internal units used for the calculations, or defines the project's\n",
@@ -57,7 +40,9 @@
   },
   {
    "cell_type": "raw",
-   "metadata": {},
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
    "source": [
     "The configuration instance will be passed to the \n",
     ":py:class:`skyllh.core.analysis.Analysis` class and all other classes that need\n",

doc/sphinx/faq/index.rst

@@ -0,0 +1,10 @@
+.. _faq_index:
+
+******************************
+Frequently Ask Questions (FAQ)
+******************************
+
+.. toctree::
+    :maxdepth: 3
+
+    signal_generator

doc/sphinx/faq/signal_generator.ipynb

@@ -0,0 +1,78 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Signal Generator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## How can I change the flux model of my sources (for my signal events)?"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
+   "source": [
+    "When SkyLLH generates pseudo data for an analysis, it will generate background\n",
+    "and signal events. It might be desired to change the flux model of the sources \n",
+    "to generate signal events following a different flux model as originally choosen\n",
+    "when the analysis was created.\n",
+    "\n",
+    "The most general procedure to change the flux model(s) of the source(s) of \n",
+    "(only) the signal generator is to create a new signal generator with a \n",
+    ":py:class:`~skyllh.core.source_hypo_grouping.SourceHypoGroupManager` instance \n",
+    "that includes the sources with the changed flux model.\n",
+    "\n",
+    "The new signal generator instance should then be set to the\n",
+    ":py:attr:`~skyllh.core.analysis.Analysis._sig_generator` attribute of the\n",
+    ":py:class:`~skyllh.core.analysis.Analysis` class. However, if the analysis \n",
+    "signal generator relies on signal generators for each individual dataset, such\n",
+    "dataset signal generators need to be re-created as well and set to the\n",
+    ":py:attr:`~skyllh.core.analysis.Analysis._sig_generator_list` attribute of the\n",
+    ":py:class:`~skyllh.core.analysis.Analysis` class.\n",
+    "\n",
+    ".. note::\n",
+    "\n",
+    "    If the flux model(s) of the source(s) should be set for the analysis itself,\n",
+    "    i.e. also for the detector signal yield calculation, which is used to weigh\n",
+    "    the datasets of a multi-dataset analysis, the \n",
+    "    :py:meth:`~skyllh.core.analysis.Analysis.change_shg_mgr` method should be\n",
+    "    called with the new \n",
+    "    :py:class:`~skyllh.core.source_hypo_grouping.SourceHypoGroupManager` \n",
+    "    instance. This method will call the ``change_shg_mgr`` method of all \n",
+    "    analysis components.\n",
+    "    \n",
+    "    A re-creation of the signal generator instances is then not required.\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "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.12"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/sphinx/index.rst

@@ -20,6 +20,7 @@ mathematical likelihood function.
     installation
     concepts/index
     tutorials/index
+    faq/index
     examples/index
     reference/skyllh
     notes

doc/user_manual.tex

@@ -15,6 +15,9 @@
 \newcommand{\psk}{\vec{p}_{\mathrm{s}_k}}
 \newcommand{\hatps}{\vec{\hat{p}}_{\mathrm{s}}}
 \newcommand{\xs}{\vec{x}_{\mathrm{s}}}
+\newcommand{\xsastro}{\vec{x}_{\mathrm{s,astro}}}
+\newcommand{\xslocal}{\vec{x}_{\mathrm{s,local}}}
+\newcommand{\tobs}{t_{\mathrm{obs}}}
 
 \newcommand{\dPhisdE}{\frac{\mathrm{d}\Phi_{\mathrm{s}}}{\mathrm{d}E}}
 
@@ -777,29 +780,29 @@ \section{Detector Signal Yield}
 The detector signal yield, $\mathcal{Y}_{\mathrm{s}_{j,k}}(\psk)$,
 is the mean number of expected signal events in the detector from a given
 source $k$ in a given data sample $j$. For a differential source flux,
-$\mathrm{d}\Phi_{\mathrm{s}}/(\mathrm{d}A\mathrm{d}\Omega\mathrm{d}E\mathrm{d}t)$,
+$\mathrm{d}^4\Phi_{\mathrm{s}}/(\mathrm{d}A\mathrm{d}\Omega\mathrm{d}E\mathrm{d}t)$,
 it is the integral of the product of the detector effective area and this
 differential flux over the solid-angle, energy, and time of the source:
 \begin{equation}
- \mathcal{Y}_{\mathrm{s}_{j,k}}(\psk) \equiv \int_{\Omega_{\mathrm{s}_k}} \mathrm{d}\Omega \int_0^\infty \mathrm{d}E \int_{t_{\mathrm{start}_j}}^{t_{\mathrm{end}_j}}\mathrm{d}t A_{\mathrm{eff}_j}(E,t|\psk) \frac{\mathrm{d}\Phi_{\mathrm{s}}(E,t|\psk)}{\mathrm{d}A\mathrm{d}\Omega\mathrm{d}E\mathrm{d}t}
+ \mathcal{Y}_{\mathrm{s}_{j,k}}(\psk) \equiv \int_{\Omega_{\mathrm{s}_k}} \mathrm{d}\Omega \int_0^\infty \mathrm{d}E \int_{t_{\mathrm{start}_j}}^{t_{\mathrm{end}_j}}\mathrm{d}t A_{\mathrm{eff}_j}(E,t|\psk) \frac{\mathrm{d}^4\Phi_{\mathrm{s}}(E,t|\psk)}{\mathrm{d}A\mathrm{d}\Omega\mathrm{d}E\mathrm{d}t}
 \label{eq:Ysj}
 \end{equation}
 
-In the most-general case, the source position $\xs$ consists of celestrial
-coordinates right-ascension and declination, which might be a function of the
-observation time $t_{\mathrm{obs}}$ for very long data taking periods in the
-order of several tens of years, i.e. due to the movement of the solar system
-w.r.t. the source:
-$\xs = \{\alpha_{\mathrm{s}}(t_{\mathrm{obs}}),\delta_{\mathrm{s}}(t_{\mathrm{obs}})\}$.
-
+In the most-general case, the astrophysical source position $\xsastro$ consists
+of celestrial coordinates right-ascension and declination, which are a function
+of the observation time, $t_{\mathrm{obs}}$, for very long data taking periods
+in the order of several tens of years, due to the movement of the solar system
+w.r.t. the astrophysical source:
+$\xsastro(t_{\mathrm{obs}}) = \{\alpha_{\mathrm{s}}(t_{\mathrm{obs}}),\delta_{\mathrm{s}}(t_{\mathrm{obs}})\}$.
 
 The time-dependent effective area $A_{\mathrm{eff}_j}(E,t|\psk)$ must account
 for the detector off-time intervals within the data sample $j$. In cases, where
-the effective area is constant within a data sample, it can be written as
+the effective area has no time dependence within a data sample, it can be
+written as
 \begin{equation}
- A_{\mathrm{eff}_j}(E,t|\psk) \equiv A_{\mathrm{eff}_j}(E|\psk) T_{\mathrm{live}}(t)
+ A_{\mathrm{eff}_j}(E,t|\psk) \equiv A_{\mathrm{eff}_j}(E|\psk) T_{\mathrm{live}}(t),
 \end{equation}
-with $T_{\mathrm{live}}(t)$ is the detector live-time function as given by
+where $T_{\mathrm{live}}(t)$ is the detector live-time function as given by
 equation (\ref{eq:Tlive}).
 
 \subsection{Effective Area}
@@ -811,15 +814,29 @@ \subsection{Effective Area}
 of the simulation events.
 In IceCube simulation the Monte-Carlo weights have the unit GeV~cm$^2$~sr.
 Using the Monte-Carlo weight, $w_{m,j}$, of the $m$th event of data sample $j$,
-that corresponds to a signal event, i.e. an event that has similar properties as
-a signal event (\emph{e.g.} same true direction), the effective area is given by
-the sum of the weights of those events, divided by the
-solid angle and the energy range $\Delta E$ of the summed selected events:
+of the set $M$ of Monte-Carlo events that correspond to signal events, i.e.
+events that have similar properties as the signal events (\emph{e.g.} same true
+direction), the effective area is simply given by the sum of the Monte-Carlo
+weights of those events, divided by the solid angle $\Omega_M$ and the energy
+range $\Delta E_M$ of the summed selected signal-like events:
+\begin{equation}
+ A_{\mathrm{eff}_j}(E|\psk) = \frac{1}{\Omega_M \Delta E_M} \sum_{m=1}^{M} w_{m,j}
+\end{equation}
+The selection of the $M$ signal-like Monte-Carlo events depends on the detector
+local source position, $\xslocal$, within the detector (specified through the
+local horizontal coordinate system with coordinates given in altitude (or zenith)
+and azimuth). The local source position can be calculated via a coordinate
+transformation function, $f_{\mathrm{eq}\rightarrow\mathrm{horiz}}$, that
+transforms the astrophysical source position $\xsastro$ in equatorial
+coordinates right-ascension and declination into the local horizontal
+coordinates, given a detector location on Earth, $\vec{x}_{\mathrm{detector}}$,
+and an observation time $\tobs$:
 \begin{equation}
- A_{\mathrm{eff}_j}(E) = \frac{\sum_{m=1}^{M} w_{m,j}}{\Omega \Delta E}
+  \xslocal = f_{\mathrm{eq}\rightarrow\mathrm{horiz}}(\xsastro|\vec{x}_{\mathrm{detector}}, \tobs)
 \end{equation}
 
 
+
 \section{The Concept of Source Hypothesis Groups}
 
 The analyses in SkyLLH rely heavily on the calculation of detector signal