Added high zenith performance for MAGIC+LST1 and MAGIC

docs/source/.gitignore

@@ -0,0 +1,2 @@
+*.pdf
+*.png

docs/source/api/index.rst

@@ -39,14 +39,79 @@ Package resources
 =================
 
 The package comes shipped with a set of package resources which are available
-after installation,
-
-- a configuration file ``config.yml``,
-  which can be obtained with the :ref:`iact-estimator-cfg` command
-- a `~astropy.table.QTable` containing the low zenith (0 to 30 degrees)
-  performance (``from iact_estimator import LOW_ZENITH_PERFORMANCE``)
-- a `~astropy.table.QTable` zenith (0 to 30 degrees)
-  performance (``from iact_estimator import MID_ZENITH_PERFORMANCE``)
+after installation.
+
+Configuration File
+------------------
+
+A default configuration file ``config.yml`` can be obtained with the
+:ref:`iact-estimator-cfg` command.
+
+Performance Data Tables
+-----------------------
+
+All performance data are stored as `~astropy.table.QTable` objects and can be
+imported directly:
+
+MAGIC-only Performance
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from iact_estimator import (
+        LOW_ZENITH_PERFORMANCE,      # 0-30° zenith
+        MID_ZENITH_PERFORMANCE,      # 30-45° zenith
+        HIGH_ZENITH_PERFORMANCE,     # ~60° zenith
+    )
+
+MAGIC+LST1 Performance
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from iact_estimator import (
+        MAGIC_LST1_LOW_ZENITH_PERFORMANCE,   # 0-30° zenith
+        MAGIC_LST1_MID_ZENITH_PERFORMANCE,   # 30-45° zenith
+        MAGIC_LST1_HIGH_ZENITH_PERFORMANCE,  # ~60° zenith (MC-based)
+    )
+
+Each table contains the following columns:
+
+- ``min_energy``: Lower energy bin edge (GeV)
+- ``max_energy``: Upper energy bin edge (GeV)
+- ``gamma_rate``: Rate of gamma-ray events (1/min)
+- ``background_rate``: Rate of background events (1/min)
+
+Data Sources and References
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table:: Performance Data Provenance
+   :header-rows: 1
+   :widths: 30 20 50
+
+   * - Dataset
+     - Zenith
+     - Source
+   * - MAGIC Low/Mid
+     - 0-45°
+     - Aleksić et al. 2016, Astroparticle Physics, 72, 76
+   * - MAGIC High
+     - 55-62°
+     - Crab observations (2016-2018), 2.5 hours
+   * - MAGIC+LST1 Low
+     - 0-30°
+     - Monte Carlo simulations, validated with data
+   * - MAGIC+LST1 Mid
+     - 30-45°
+     - Abe et al. 2023, A&A, 670, A145
+   * - MAGIC+LST1 High
+     - ~59°
+     - Monte Carlo simulations (conservative background)
+
+.. note::
+   When using MAGIC+LST1 high zenith performance data, please note that it is
+   based on Monte Carlo simulations. Background rates above 1 TeV have been
+   increased by 40% to provide conservative estimates.
 
 API description
 ===============

docs/source/changes/41.added.rst

@@ -0,0 +1 @@
+Added high zenith performance for MAGIC+LST1 and MAGIC telescopes.

docs/source/index.rst

@@ -37,44 +37,54 @@ Eq. 17 definition from [2]_.
 The currently available performance data publicly shipped with the package is
 summarized by this table:
 
-==========  ===============  ============  ============  ==========
-Istrument   Zenith range ID  Zenith range  Energy range  References
-==========  ===============  ============  ============  ==========
-MAGIC       low              0 to 30 deg   40GeV-16TeV   [1]_
-MAGIC       mid              30 to 45 deg  40GeV-16TeV   [1]_
-==========  ===============  ============  ============  ==========
+=================  ===============  ============  ==============  ==========
+Instrument         Zenith range ID  Zenith range  Energy range    References
+=================  ===============  ============  ==============  ==========
+MAGIC              low              0 to 30 deg   40 GeV-16 TeV   [1]_
+MAGIC              mid              30 to 45 deg  40 GeV-16 TeV   [1]_
+MAGIC              high             ~60 deg       250 GeV-16 TeV  [4]_
+MAGIC+LST1         low              0 to 30 deg   40 GeV-16 TeV   [5]_
+MAGIC+LST1         mid              30 to 45 deg  80 GeV-16 TeV   [3]_
+MAGIC+LST1         high             ~60 deg       250 GeV-16 TeV  [5]_
+=================  ===============  ============  ==============  ==========
+
+.. note::
+   MAGIC+LST1 high zenith performance is based on Monte Carlo simulations with
+   conservative background estimates. Please refer to :ref:`userguide` for
+   detailed caveats when using this dataset.
 
 Current caveats
 ---------------
 
-- the tool is operating on estimated energy doing simple
-  comparisons with differential in estimated energy rates seen for the
-  Crab Nebula; for softer sources the differences in energy migration
-  will result in different performance than the ones produced by this tool
-
-- the treatment of extended sources is very approximate, only the
-  increase in background is taken into account (without energy
-  dependence of Point Spread Function); for extended sources with extension >~ 0.4 deg the
-  dependence on the offset from the centre of the camera will further
-  worsen the performance w.r.t. one produced by this tool
-
-- significances are given for each differential energy bin
-  separately, but to detect a source one normally applies a cut that
-  keeps a broad range of energies inside resulting in better integral
-  sensitivity than differential one; also, optimization of cuts for a
-  broad energy range usually results in somewhat
-  better sensitivity than what one can get by simply integrating
-  the used here signal in
-  differential energy bins; as a very crude approximation for detection
-  capability we calculate here also a sum of significances of all the
-  points in Spectral Energy Distribution
-  divided by the sqrt of the number of those points
+.. warning::
+   Please refer to the :ref:`userguide` for comprehensive information about
+   caveats and limitations. Key points include:
+
+- The tool operates on **estimated energy** by comparing with differential rates
+  from Crab Nebula observations; for sources with soft spectra, energy migration
+  effects may result in different performance
+
+- The treatment of **extended sources** is approximate, accounting only for
+  increased background (without energy-dependent PSF); for sources with
+  extension > 0.4°, camera offset effects will further reduce performance
+
+- Significances are given for **differential energy bins**; in practice, broader
+  energy cuts and optimized analysis yield better integral sensitivity than
+  simple integration of differential bins
+
+- The **combined significance** is a crude approximation of detection capability
+
+- **High zenith** observations have higher energy thresholds and specific
+  limitations (see userguide)
 
 References
 ----------
 
-.. [1] Aleksic, J., et al., 2016, Astroparticle Physics, 72, 76
-.. [2] Li & Ma 1983, ApJ, 272, 317
+.. [1] Aleksić, J., et al., 2016, Astroparticle Physics, 72, 76
+.. [2] Li, T.-P. & Ma, Y.-Q., 1983, ApJ, 272, 317
+.. [3] Abe, H., et al., 2023, A&A, 670, A145
+.. [4] MAGIC Crab observations at 55-62° zenith (2016-2018), Dataset: `Dr. J. van Scherpenberg PhD Thesis <https://nbn-resolving.org/urn:nbn:de:bvb:91-diss-20250606-1775491-0-4>`_
+.. [5] MAGIC+LST1 Monte Carlo simulations (conservative estimates for high zenith)
 
 .. toctree::
    :maxdepth: 2