Add basic facilities for 3D background irfs

.mailmap

@@ -1,7 +1,6 @@
 Maximilian Linhoff <[email protected]> <[email protected]>
 
-Michele Peresano <[email protected]> Michele Peresano <[email protected]>
-Michele Peresano <[email protected]> Michele Peresano <[email protected]>
+Michele Peresano <[email protected]> Michele Peresano <[email protected]>
 
 Thomas Vuillaume <[email protected]> vuillaut <[email protected]>
 Thomas Vuillaume <[email protected]> Thomas Vuillaume <[email protected]>

CHANGES.rst

@@ -1,3 +1,40 @@
+pyirf v0.11.0 (2024-05-14)
+==========================
+
+Bug Fixes
+---------
+
+- Fix ``pyirf.benchmarks.energy_bias_resolution_from_energy_dispersion``.
+  This function was not adapted to the now correct normalization of the
+  energy dispersion matrix, resulting in wrong results on the now correct
+  matrices. [`#268 <https://github.com/cta-observatory/pyirf/pull/268>`__]
+
+
+New Features
+------------
+
+- Adds an extrapolator for parametrized compontents utilizing blending over visible edges, resulting 
+  in a smooth extrapolation compared to the NearestSimplexExtrapolator. [`#253 <https://github.com/cta-observatory/pyirf/pull/253>`__]
+
+- Ignore warnings about invalid floating point operations when calculating `n_signal` and `n_signal_weigthed` because the relative sensitivty is frequently NaN. [`#264 <https://github.com/cta-observatory/pyirf/pull/264>`__]
+
+- Add basic combinatoric fill-value handling for RAD_MAX estimation. [`#282 <https://github.com/cta-observatory/pyirf/pull/282>`__]
+
+
+Maintenance
+-----------
+
+- Clarified some documentation. [`#266 <https://github.com/cta-observatory/pyirf/pull/266>`__]
+
+- Add support for astropy 6.0. [`#271 <https://github.com/cta-observatory/pyirf/pull/271>`__]
+
+- Added filling of CREF keyword (IRF axis order) in the output files [`#275 <https://github.com/cta-observatory/pyirf/pull/275>`__]
+
+
+
+Refactoring and Optimization
+----------------------------
+
 pyirf v0.10.1 (2023-09-15)
 ==========================
 

README.rst

@@ -29,3 +29,20 @@ please cite it by using the corresponding DOI:
 
 - latest : |doilatest|
 - all versions: `Please visit Zenodo <https://zenodo.org/record/5833284>`_ and select the correct version
+
+At this point, our latest publication is the `2023 ICRC proceeding <https://doi.org/10.22323/1.444.0618>`_, which you can
+cite using the following bibtex entry, especially if using functionalities from ``pyirf.interpolation``:
+
+.. code::
+
+   @inproceedings{pyirf-icrc-2023,
+     author = {Dominik, Rune Michael and Linhoff, Maximilian and Sitarek, Julian},
+     title = {Interpolation of Instrument Response Functions for the Cherenkov Telescope Array in the Context of pyirf},
+     usera = {for the CTA Consortium},
+     doi = {10.22323/1.444.0703},
+     booktitle = {Proceedings, 38th International Cosmic Ray Conference},
+     year=2023,
+     volume={444},
+     number={618},
+     location={Nagoya, Japan},
+   }

docs/changes/268.bugfix.rst → docs/changes/273.bugfix.rst

@@ -1,4 +1,4 @@
-Fix ``pyirf.benchmarks.energy_bias_resolution_from_energy_dispersion``.
+Fix ``pyirf.irfs.energy_dispersion.energy_dispersion_to_migration``.
 This function was not adapted to the now correct normalization of the
 energy dispersion matrix, resulting in wrong results on the now correct
-matrices.
+matrices.

docs/changes/276.feature.rst

@@ -0,0 +1 @@
+Add function to make 3d background for lon/lat coordinates.

docs/changes/281.feature.rst

@@ -0,0 +1,2 @@
+
+Add 3D effective area functions for lon/lat and theta/phi coordinates and some necessary utiliy functions.

docs/changes/289.maintenance.rst

@@ -0,0 +1,3 @@
+Make pyirf compatible with numpy 2.0.
+
+Replace deprecated ``logging.warn`` with ``logging.warning``.

docs/changes/290.api.rst

@@ -0,0 +1,3 @@
+Make it possible to pass multiple quantiles to ``pyirf.benchmarks.angular_resolution``, calculating all of them.
+
+The column name(s) in the output now include(s) the percentage value of the calculated quantile, e.g. ``angular_resolution_68``.

docs/conf.py

@@ -84,8 +84,7 @@
 html_theme = "sphinx_rtd_theme"
 
 html_theme_options = {
-    'canonical_url': 'https://cta-observatory.github.io/pyirf',
-    'display_version': True,
+    'canonical_url': 'https://pyirf.readthedocs.io/',
 }
 
 intersphinx_mapping = {

examples/comparison_with_EventDisplay.ipynb

@@ -528,7 +528,7 @@
     "\n",
     "plt.errorbar(\n",
     "    0.5 * (ang_res['reco_energy_low'] + ang_res['reco_energy_high']).to_value(u.TeV),\n",
-    "    ang_res['angular_resolution'].to_value(u.deg),\n",
+    "    ang_res['angular_resolution_68'].to_value(u.deg),\n",
     "    xerr=0.5 * (ang_res['reco_energy_high'] - ang_res['reco_energy_low']).to_value(u.TeV),\n",
     "    ls='',\n",
     "    label='pyirf'\n",

pyirf/benchmarks/angular_resolution.py

@@ -1,3 +1,4 @@
+from collections.abc import Sequence
 import numpy as np
 from astropy.table import QTable
 from scipy.stats import norm
@@ -10,7 +11,8 @@
 
 
 def angular_resolution(
-    events, energy_bins,
+    events,
+    energy_bins,
     energy_type="true",
     quantile=ONE_SIGMA_QUANTILE,
 ):
@@ -20,6 +22,8 @@ def angular_resolution(
     This implementation corresponds to the 68% containment of the angular
     distance distribution.
 
+    Passing a list of quantiles results in all the quantiles being calculated.
+
     Parameters
     ----------
     events : astropy.table.QTable
@@ -29,8 +33,8 @@ def angular_resolution(
     energy_type: str
         Either "true" or "reco" energy.
         Default is "true".
-    quantile : float
-        Which quantile to use for the angular resolution,
+    quantile : list(float)
+        Which quantile(s) to use for the angular resolution,
         by default, the containment of the 1-sigma region
         of the normal distribution (~68%) is used.
 
@@ -52,8 +56,13 @@ def angular_resolution(
     result[f"{energy_key}_center"] = 0.5 * (energy_bins[:-1] + energy_bins[1:])
     result["n_events"] = 0
 
-    key = "angular_resolution"
-    result[key] = u.Quantity(np.nan, table["theta"].unit)
+    if not isinstance(quantile, Sequence):
+        quantile = [quantile]
+
+    keys = [f"angular_resolution_{value * 100:.0f}" for value in quantile]
+
+    for key in keys:
+        result[key] = u.Quantity(np.nan, table["theta"].unit)
 
     # if we get an empty input (no selected events available)
     # we return the table filled with NaNs
@@ -63,6 +72,9 @@ def angular_resolution(
     # use groupby operations to calculate the percentile in each bin
     by_bin = table[valid].group_by(bin_index[valid])
     for bin_idx, group in zip(by_bin.groups.keys, by_bin.groups):
-        result[key][bin_idx] = np.nanquantile(group["theta"], quantile)
         result["n_events"][bin_idx] = len(group)
+        quantile_values = np.nanquantile(group["theta"], quantile)
+        for key, value in zip(keys, quantile_values):
+            result[key][bin_idx] = value
+
     return result

pyirf/benchmarks/energy_bias_resolution.py

@@ -4,6 +4,7 @@
 import astropy.units as u
 
 from ..binning import calculate_bin_indices, UNDERFLOW_INDEX, OVERFLOW_INDEX
+from ..compat import COPY_IF_NEEDED
 
 
 NORM_LOWER_SIGMA, NORM_UPPER_SIGMA = norm(0, 1).cdf([-1, 1])
@@ -83,8 +84,10 @@ def energy_bias_resolution(
     """
 
     # create a table to make use of groupby operations
-    table = QTable(events[["true_energy", "reco_energy"]], copy=False)
-    table["rel_error"] = (events["reco_energy"] / events["true_energy"]).to_value(u.one) - 1
+    table = QTable(events[["true_energy", "reco_energy"]], copy=COPY_IF_NEEDED)
+    table["rel_error"] = (events["reco_energy"] / events["true_energy"]).to_value(
+        u.one
+    ) - 1
 
     energy_key = f"{energy_type}_energy"
 
@@ -102,7 +105,6 @@ def energy_bias_resolution(
         # we return the table filled with NaNs
         return result
 
-
     # use groupby operations to calculate the percentile in each bin
     bin_index, valid = calculate_bin_indices(table[energy_key], energy_bins)
     by_bin = table.group_by(bin_index)
@@ -115,6 +117,7 @@ def energy_bias_resolution(
         result["resolution"][bin_idx] = resolution_function(group["rel_error"])
     return result
 
+
 def energy_bias_resolution_from_energy_dispersion(
     energy_dispersion,
     migration_bins,
@@ -147,7 +150,7 @@ def energy_bias_resolution_from_energy_dispersion(
             low, median, high = np.interp(
                 [NORM_LOWER_SIGMA, MEDIAN, NORM_UPPER_SIGMA],
                 cdf[energy_bin, :, fov_bin],
-                migration_bins[1:] # cdf is defined at upper bin edge
+                migration_bins[1:],  # cdf is defined at upper bin edge
             )
             bias[energy_bin, fov_bin] = median - 1
             resolution[energy_bin, fov_bin] = 0.5 * (high - low)

pyirf/benchmarks/tests/test_angular_resolution.py

@@ -8,17 +8,17 @@
 def test_empty_angular_resolution():
     from pyirf.benchmarks import angular_resolution
 
-    events = QTable({
-        'true_energy': [] * u.TeV,
-        'theta': [] * u.deg,
-    })
-
-    table = angular_resolution(
-        events,
-        [1, 10, 100] * u.TeV
+    events = QTable(
+        {
+            "true_energy": [] * u.TeV,
+            "theta": [] * u.deg,
+        }
     )
 
-    assert np.all(np.isnan(table["angular_resolution"]))
+    table = angular_resolution(events, [1, 10, 100] * u.TeV)
+
+    assert np.all(np.isnan(table["angular_resolution_68"]))
+
 
 @pytest.mark.parametrize("unit", (u.deg, u.rad))
 def test_angular_resolution(unit):
@@ -32,28 +32,32 @@ def test_angular_resolution(unit):
 
     true_resolution = np.append(np.full(N, TRUE_RES_1), np.full(N, TRUE_RES_2))
 
-
     rng = np.random.default_rng(0)
 
-    events = QTable({
-        'true_energy': np.concatenate([
-            [0.5], # below bin 1 to test with underflow
-            np.full(N - 1, 5.0),
-            np.full(N - 1, 50.0),
-            [500], # above bin 2 to test with overflow
-        ]) * u.TeV,
-        'theta': np.abs(rng.normal(0, true_resolution)) * u.deg
-    })
+    events = QTable(
+        {
+            "true_energy": np.concatenate(
+                [
+                    [0.5],  # below bin 1 to test with underflow
+                    np.full(N - 1, 5.0),
+                    np.full(N - 1, 50.0),
+                    [500],  # above bin 2 to test with overflow
+                ]
+            )
+            * u.TeV,
+            "theta": np.abs(rng.normal(0, true_resolution)) * u.deg,
+        }
+    )
 
-    events['theta'] = events['theta'].to(unit)
+    events["theta"] = events["theta"].to(unit)
 
     # add nans to test if nans are ignored
     events["true_energy"].value[N // 2] = np.nan
     events["true_energy"].value[(2 * N) // 2] = np.nan
 
     bins = [1, 10, 100] * u.TeV
     table = angular_resolution(events, bins)
-    ang_res = table['angular_resolution'].to(u.deg)
+    ang_res = table["angular_resolution_68"].to(u.deg)
     assert len(ang_res) == 2
     assert u.isclose(ang_res[0], TRUE_RES_1 * u.deg, rtol=0.05)
     assert u.isclose(ang_res[1], TRUE_RES_2 * u.deg, rtol=0.05)
@@ -64,9 +68,26 @@ def test_angular_resolution(unit):
     # 2 sigma coverage interval
     quantile = norm(0, 1).cdf(2) - norm(0, 1).cdf(-2)
     table = angular_resolution(events, bins, quantile=quantile)
-    ang_res = table['angular_resolution'].to(u.deg)
-
+    ang_res = table["angular_resolution_95"].to(u.deg)
     assert len(ang_res) == 2
-
     assert u.isclose(ang_res[0], 2 * TRUE_RES_1 * u.deg, rtol=0.05)
     assert u.isclose(ang_res[1], 2 * TRUE_RES_2 * u.deg, rtol=0.05)
+
+    # 25%, 50%, 90% coverage interval
+    table = angular_resolution(events, bins, quantile=[0.25, 0.5, 0.9])
+    cov_25 = table["angular_resolution_25"].to(u.deg)
+    assert len(cov_25) == 2
+    assert u.isclose(
+        cov_25[0], norm(0, TRUE_RES_1).interval(0.25)[1] * u.deg, rtol=0.05
+    )
+    assert u.isclose(
+        cov_25[1], norm(0, TRUE_RES_2).interval(0.25)[1] * u.deg, rtol=0.05
+    )
+
+    cov_50 = table["angular_resolution_50"].to(u.deg)
+    assert u.isclose(cov_50[0], norm(0, TRUE_RES_1).interval(0.5)[1] * u.deg, rtol=0.05)
+    assert u.isclose(cov_50[1], norm(0, TRUE_RES_2).interval(0.5)[1] * u.deg, rtol=0.05)
+
+    cov_90 = table["angular_resolution_90"].to(u.deg)
+    assert u.isclose(cov_90[0], norm(0, TRUE_RES_1).interval(0.9)[1] * u.deg, rtol=0.05)
+    assert u.isclose(cov_90[1], norm(0, TRUE_RES_2).interval(0.9)[1] * u.deg, rtol=0.05)