resolved merge conflitcts

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Set update schedule for GitHub Actions
+
+version: 2
+updates:
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-minor", "version-update:semver-patch"]

.github/workflows/documentation.yml

@@ -16,12 +16,12 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.8'
 
@@ -35,7 +35,7 @@ jobs:
         run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
 
       - name: Cache dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ${{ steps.pip-cache.outputs.dir }}
           key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -55,7 +55,7 @@ jobs:
           cp _assets/gh-pages-redirect.html _build/index.html
 
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./doc/sphinx/_build

.github/workflows/python_publish.yml

@@ -11,9 +11,9 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.x'
       - name: Install dependencies

.github/workflows/pythonpackage.yml

@@ -18,9 +18,9 @@ jobs:
         python-version: ["3.8", "3.9", "3.10"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

.gitignore

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

CHANGELOG.txt

@@ -25,6 +25,61 @@ v23.2.1
   event generation from MC, resulting in a great performance increase when
   generating many trials with many events.
 
+- The core.pdf.MultiDimGridPDF class has been adapted to the new Python
+  interface of photospline that supports numpy arrays. The determination of the
+  spline table's basis function indices has been separated from the spline table
+  evaluation which provides an accelerated PDF evaluation.
+
+- The core.dataset.Dataset.get_aux_data method got the new optional argument
+  "default" to specify a default return value if the auxiliary data is not
+  defined for that dataset.
+
+- The core.signal_generator.MCMultiDatasetSignalGenerator get the new optional
+  constructor argument "valid_event_field_ranges_dict_list=None" to specify
+  valid event field ranges, e.g. for the declination. If generated signal events
+  do not match these valid event field ranges, those signal events will be
+  redrawn.
+
+- The i3.signal_generation.PointLikeSourceI3SignalGenerationMethod class uses
+  the new rotation function core.utils.coords.rotate_signal_events_on_sphere
+  to preserve the position angle and great circle distance between the event's
+  true and reco directions.
+
+- Corrected the calculation of the number of signal events to be generated for
+  each individual dataset in the
+  core.signal_generator.MultiDatasetSignalGenerator class.
+
+- Operations for "unstable" events in the
+  core.llhratio.ZeroSigH0SingleDatasetTCLLHRatio.calculate_log_lambda_and_grads
+  method are only performed if there are actually such events.
+
+- Added argument "iprint" to the constructor of the
+  core.minimizer.LBFGSMinimizerImpl class to be able to print out more minimizer
+  internal statistics.
+
+- Added keyword argument "minimizer_rss" to method
+  core.analysis.Analysis.do_trial and subsequent methods, like
+  core.analysis.Analysis.do_trial_with_given_pseudo_data.
+
+  It is now possible to specify a separate RandomStateService (RSS) for the
+  minimizer. This will make sure that trial pseudo data generation is not
+  influenced by the minimizer when generating new initial fit parameter values
+  after the minimizer failed.
+
+- Changed keyword argument name "rss" of method core.analysis.Analysis.unblind
+  to "minimizer_rss" to be consistent with the new "minimizer_rss" keyword
+  argument of core.analysis.Analysis.do_trial.
+
+- Added background generation method class
+  core.background_generation.CompositeMCDataSamplingBkgGenMethod.
+
+  This new background generation method samples background events from a
+  monte-carlo sample and has the ability to calculate different background
+  component rates for each trial after the monte-carlo events were already
+  scrambled. This is useful in cases where a background component is
+  non-isotropic, i.e. depends on the position in the sky. An example would be a
+  background component from the galactic plane.
+
 v23.2.0
 =======
 - Complete overhaul of SkyLLH for more generic handling of parameters
@@ -86,7 +141,7 @@ v23.2.0
 
     - core.event_selection.SpatialBoxEventSelectionMethod:
 
-        Improved calculation of right-ascention difference. Thus, speed-up in
+        Improved calculation of right-ascension difference. Thus, speed-up in
         trial generation when using this event selection method.
 
 - core.scrambling.DataScrambler.scramble_data method also takes Dataset instance
@@ -100,7 +155,7 @@ v23.1.1
 =======
 - bugfix of core.pdf.MultiDimGridPDFSet
 - bugfix of core.pdf.MappedMultiDimGridPDFSet
-- removal of depricated proptery core.pdf.PDFSet.pdf_axes
+- removal of deprecated property core.pdf.PDFSet.pdf_axes
 
 v23.1.0
 =======

README.md

@@ -3,16 +3,26 @@
 [![Tests](https://github.com/icecube/skyllh/actions/workflows/pythonpackage.yml/badge.svg)](#)
 [![Docs](https://github.com/icecube/skyllh/actions/workflows/documentation.yml/badge.svg)](https://icecube.github.io/skyllh/)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/licenses/GPL-3.0)
+[![PyPI - Version](https://img.shields.io/pypi/v/skyllh)](https://pypi.org/project/skyllh/)
+[![conda-forge](https://anaconda.org/conda-forge/skyllh/badges/version.svg)](https://anaconda.org/conda-forge/skyllh)
 
 [[Full documentation]](https://icecube.github.io/skyllh/).
 
-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 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
 
-The latest `skyllh` release can be installed from [PyPI](https://pypi.org/project/skyllh/) repository:
+The latest `skyllh` release can be installed from
+[PyPI](https://pypi.org/project/skyllh/) repository:
 ```bash
 pip install skyllh
 ```
@@ -22,17 +32,20 @@ The current development version can be installed using pip:
 pip install git+https://github.com/icecube/skyllh.git#egg=skyllh
 ```
 
-Optionally, the editable package version with a specified reference can be installed by:
+Optionally, the editable package version with a specified reference can be
+installed by:
 ```bash
 pip install -e git+https://github.com/icecube/skyllh.git@[ref]#egg=skyllh
 ```
 where
 - `-e` is an editable flag
-- `[ref]` is an optional argument containing a specific commit hash, branch name or tag
+- `[ref]` is an optional argument containing a specific commit hash, branch name
+  or tag
 
 ## Cloning from GitHub
 
-The `skyllh` (and an optional private [i3skyllh](#i3skyllh)) package can be installed by cloning the GitHub repository and adding it to the Python path:
+The `skyllh` (and an optional private [i3skyllh](#i3skyllh)) package can be
+installed by cloning the GitHub repository and adding it to the Python path:
 
 ```python
 import sys
@@ -45,11 +58,55 @@ sys.path.insert(0, '/path/to/i3skyllh')  # optional
 
 Several publications about the SkyLLH software are available:
 
+- IceCube Collaboration, C. Bellenghi, M. Karl, M. Wolf, et al. PoS ICRC2023 (2023) 1061
+  [DOI](https://doi.org/10.22323/1.444.1061)
 - IceCube Collaboration, T. Kontrimas, M. Wolf, et al. PoS ICRC2021 (2022) 1073
   [DOI](http://doi.org/10.22323/1.395.1073)
 - IceCube Collaboration, M. Wolf, et al. PoS ICRC2019 (2020) 1035
   [DOI](https://doi.org/10.22323/1.358.1035)
 
+# Developer Guidelines
+
+These guidelines should help new developers of SkyLLH to join the development
+process easily.
+
+## Code style
+
+- The code follows PEP8 coding style guidelines as close as possible.
+
+- Code lines are maximum 80 characters wide.
+
+- 4 spaces are used as one indentation level.
+
+## Branching
+
+- When implementing a new feature / change, first an issue must be created
+  describing the new feature / change. Then a branch must be created referring
+  to this issue. We recommend the branch name `fix<ISSUE_NUMBER>`, where
+  `<ISSUE_NUMBER>` is the number of the created issue for this feature / change.
+
+- In cases when SkyLLH needs to be updated because of a change in the i3skyllh
+  package (see below), we recommend the branch name `i3skyllh_<ISSUE_NUMBER>`,
+  where `<ISSUE_NUMBER>` is the number of the issue created in the i3skyllh
+  repository. That way the *analysis unit tests* workflow will be able to find
+  the correct skyllh branch corresponding to the i3skyllh change automatically.
+
+## Releases and Versioning
+
+- Release version numbers follow the format `v<YY>.<MAJOR>.<MINOR>`, where
+  `<YY>` is the current year, `<MAJOR>` and `<MINOR>` are the major and minor
+  version numbers of type integer. Example: `v23.2.0`.
+
+- Release candidates follow the same format as releases, but have the additional
+  suffix `.rc<NUMBER>`,  where `<NUMBER>` is an integer starting with 1.
+  Example: `v23.2.0.rc1`
+
+- Before creating the release on github, the version number needs to be updated
+  in the Sphinx documentation: `doc/sphinx/conf.py`.
+
 # i3skyllh
 
-The [`i3skyllh`](https://github.com/icecube/i3skyllh) package provides complementary pre-defined common analyses and datasets for the [IceCube Neutrino Observatory](https://icecube.wisc.edu) detector in a private [repository](https://github.com/icecube/i3skyllh).
+The [`i3skyllh`](https://github.com/icecube/i3skyllh) package provides
+complementary pre-defined common analyses and datasets for the
+[IceCube Neutrino Observatory](https://icecube.wisc.edu) detector in a private
+[repository](https://github.com/icecube/i3skyllh).

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/conf.py

@@ -30,7 +30,7 @@
 author = u'The IceCube Collaboration'
 
 # The short X.Y version
-version = u'23.2.0'
+version = u'24.1.0'
 # The full version, including alpha/beta/rc tags
 release = u''
 

doc/sphinx/faq/index.rst

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