+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+
+"""
+Core units classes and functions.
+"""
+
+
+import inspect
+import operator
+import textwrap
+import warnings
+
+import numpy as np
+
+from astropy.utils.decorators import lazyproperty
+from astropy.utils.exceptions import AstropyWarning
+from astropy.utils.misc import isiterable
+
+from . import format as unit_format
+from .utils import (
+ is_effectively_unity,
+ resolve_fractions,
+ sanitize_power,
+ sanitize_scale,
+ validate_power,
+)
+
+__all__ = [
+ "UnitsError",
+ "UnitsWarning",
+ "UnitConversionError",
+ "UnitTypeError",
+ "UnitBase",
+ "NamedUnit",
+ "IrreducibleUnit",
+ "Unit",
+ "CompositeUnit",
+ "PrefixUnit",
+ "UnrecognizedUnit",
+ "def_unit",
+ "get_current_unit_registry",
+ "set_enabled_units",
+ "add_enabled_units",
+ "set_enabled_equivalencies",
+ "add_enabled_equivalencies",
+ "set_enabled_aliases",
+ "add_enabled_aliases",
+ "dimensionless_unscaled",
+ "one",
+]
+
+UNITY = 1.0
+
+
+def _flatten_units_collection(items):
+ """
+ Given a list of sequences, modules or dictionaries of units, or
+ single units, return a flat set of all the units found.
+ """
+ if not isinstance(items, list):
+ items = [items]
+
+ result = set()
+ for item in items:
+ if isinstance(item, UnitBase):
+ result.add(item)
+ else:
+ if isinstance(item, dict):
+ units = item.values()
+ elif inspect.ismodule(item):
+ units = vars(item).values()
+ elif isiterable(item):
+ units = item
+ else:
+ continue
+
+ for unit in units:
+ if isinstance(unit, UnitBase):
+ result.add(unit)
+
+ return result
+
+
+def _normalize_equivalencies(equivalencies):
+ """Normalizes equivalencies ensuring each is a 4-tuple.
+
+ The resulting tuple is of the form::
+
+ (from_unit, to_unit, forward_func, backward_func)
+
+ Parameters
+ ----------
+ equivalencies : list of equivalency pairs
+
+ Raises
+ ------
+ ValueError if an equivalency cannot be interpreted
+ """
+ if equivalencies is None:
+ return []
+
+ normalized = []
+
+ for i, equiv in enumerate(equivalencies):
+ if len(equiv) == 2:
+ funit, tunit = equiv
+ a = b = lambda x: x
+ elif len(equiv) == 3:
+ funit, tunit, a = equiv
+ b = a
+ elif len(equiv) == 4:
+ funit, tunit, a, b = equiv
+ else:
+ raise ValueError(f"Invalid equivalence entry {i}: {equiv!r}")
+ if not (
+ funit is Unit(funit)
+ and (tunit is None or tunit is Unit(tunit))
+ and callable(a)
+ and callable(b)
+ ):
+ raise ValueError(f"Invalid equivalence entry {i}: {equiv!r}")
+ normalized.append((funit, tunit, a, b))
+
+ return normalized
+
+
+class _UnitRegistry:
+ """
+ Manages a registry of the enabled units.
+ """
+
+ def __init__(self, init=[], equivalencies=[], aliases={}):
+ if isinstance(init, _UnitRegistry):
+ # If passed another registry we don't need to rebuild everything.
+ # but because these are mutable types we don't want to create
+ # conflicts so everything needs to be copied.
+ self._equivalencies = init._equivalencies.copy()
+ self._aliases = init._aliases.copy()
+ self._all_units = init._all_units.copy()
+ self._registry = init._registry.copy()
+ self._non_prefix_units = init._non_prefix_units.copy()
+ # The physical type is a dictionary containing sets as values.
+ # All of these must be copied otherwise we could alter the old
+ # registry.
+ self._by_physical_type = {
+ k: v.copy() for k, v in init._by_physical_type.items()
+ }
+
+ else:
+ self._reset_units()
+ self._reset_equivalencies()
+ self._reset_aliases()
+ self.add_enabled_units(init)
+ self.add_enabled_equivalencies(equivalencies)
+ self.add_enabled_aliases(aliases)
+
+ def _reset_units(self):
+ self._all_units = set()
+ self._non_prefix_units = set()
+ self._registry = {}
+ self._by_physical_type = {}
+
+ def _reset_equivalencies(self):
+ self._equivalencies = set()
+
+ def _reset_aliases(self):
+ self._aliases = {}
+
+ @property
+ def registry(self):
+ return self._registry
+
+ @property
+ def all_units(self):
+ return self._all_units
+
+ @property
+ def non_prefix_units(self):
+ return self._non_prefix_units
+
+ def set_enabled_units(self, units):
+ """
+ Sets the units enabled in the unit registry.
+
+ These units are searched when using
+ `UnitBase.find_equivalent_units`, for example.
+
+ Parameters
+ ----------
+ units : list of sequence, dict, or module
+ This is a list of things in which units may be found
+ (sequences, dicts or modules), or units themselves. The
+ entire set will be "enabled" for searching through by
+ methods like `UnitBase.find_equivalent_units` and
+ `UnitBase.compose`.
+ """
+ self._reset_units()
+ return self.add_enabled_units(units)
+
+ def add_enabled_units(self, units):
+ """
+ Adds to the set of units enabled in the unit registry.
+
+ These units are searched when using
+ `UnitBase.find_equivalent_units`, for example.
+
+ Parameters
+ ----------
+ units : list of sequence, dict, or module
+ This is a list of things in which units may be found
+ (sequences, dicts or modules), or units themselves. The
+ entire set will be added to the "enabled" set for
+ searching through by methods like
+ `UnitBase.find_equivalent_units` and `UnitBase.compose`.
+ """
+ units = _flatten_units_collection(units)
+
+ for unit in units:
+ # Loop through all of the names first, to ensure all of them
+ # are new, then add them all as a single "transaction" below.
+ for st in unit._names:
+ if st in self._registry and unit != self._registry[st]:
+ raise ValueError(
+ f"Object with name {st!r} already exists in namespace. "
+ "Filter the set of units to avoid name clashes before "
+ "enabling them."
+ )
+
+ for st in unit._names:
+ self._registry[st] = unit
+
+ self._all_units.add(unit)
+ if not isinstance(unit, PrefixUnit):
+ self._non_prefix_units.add(unit)
+
+ hash = unit._get_physical_type_id()
+ self._by_physical_type.setdefault(hash, set()).add(unit)
+
+ def get_units_with_physical_type(self, unit):
+ """
+ Get all units in the registry with the same physical type as
+ the given unit.
+
+ Parameters
+ ----------
+ unit : UnitBase instance
+ """
+ return self._by_physical_type.get(unit._get_physical_type_id(), set())
+
+ @property
+ def equivalencies(self):
+ return list(self._equivalencies)
+
+ def set_enabled_equivalencies(self, equivalencies):
+ """
+ Sets the equivalencies enabled in the unit registry.
+
+ These equivalencies are used if no explicit equivalencies are given,
+ both in unit conversion and in finding equivalent units.
+
+ This is meant in particular for allowing angles to be dimensionless.
+ Use with care.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ List of equivalent pairs, e.g., as returned by
+ `~astropy.units.equivalencies.dimensionless_angles`.
+ """
+ self._reset_equivalencies()
+ return self.add_enabled_equivalencies(equivalencies)
+
+ def add_enabled_equivalencies(self, equivalencies):
+ """
+ Adds to the set of equivalencies enabled in the unit registry.
+
+ These equivalencies are used if no explicit equivalencies are given,
+ both in unit conversion and in finding equivalent units.
+
+ This is meant in particular for allowing angles to be dimensionless.
+ Use with care.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ List of equivalent pairs, e.g., as returned by
+ `~astropy.units.equivalencies.dimensionless_angles`.
+ """
+ # pre-normalize list to help catch mistakes
+ equivalencies = _normalize_equivalencies(equivalencies)
+ self._equivalencies |= set(equivalencies)
+
+ @property
+ def aliases(self):
+ return self._aliases
+
+ def set_enabled_aliases(self, aliases):
+ """
+ Set aliases for units.
+
+ Parameters
+ ----------
+ aliases : dict of str, Unit
+ The aliases to set. The keys must be the string aliases, and values
+ must be the `astropy.units.Unit` that the alias will be mapped to.
+
+ Raises
+ ------
+ ValueError
+ If the alias already defines a different unit.
+
+ """
+ self._reset_aliases()
+ self.add_enabled_aliases(aliases)
+
+ def add_enabled_aliases(self, aliases):
+ """
+ Add aliases for units.
+
+ Parameters
+ ----------
+ aliases : dict of str, Unit
+ The aliases to add. The keys must be the string aliases, and values
+ must be the `astropy.units.Unit` that the alias will be mapped to.
+
+ Raises
+ ------
+ ValueError
+ If the alias already defines a different unit.
+
+ """
+ for alias, unit in aliases.items():
+ if alias in self._registry and unit != self._registry[alias]:
+ raise ValueError(
+ f"{alias} already means {self._registry[alias]}, so "
+ f"cannot be used as an alias for {unit}."
+ )
+ if alias in self._aliases and unit != self._aliases[alias]:
+ raise ValueError(
+ f"{alias} already is an alias for {self._aliases[alias]}, so "
+ f"cannot be used as an alias for {unit}."
+ )
+
+ for alias, unit in aliases.items():
+ if alias not in self._registry and alias not in self._aliases:
+ self._aliases[alias] = unit
+
+
+class _UnitContext:
+ def __init__(self, init=[], equivalencies=[]):
+ _unit_registries.append(_UnitRegistry(init=init, equivalencies=equivalencies))
+
+ def __enter__(self):
+ pass
+
+ def __exit__(self, type, value, tb):
+ _unit_registries.pop()
+
+
+_unit_registries = [_UnitRegistry()]
+
+
+def get_current_unit_registry():
+ return _unit_registries[-1]
+
+
+def set_enabled_units(units):
+ """
+ Sets the units enabled in the unit registry.
+
+ These units are searched when using
+ `UnitBase.find_equivalent_units`, for example.
+
+ This may be used either permanently, or as a context manager using
+ the ``with`` statement (see example below).
+
+ Parameters
+ ----------
+ units : list of sequence, dict, or module
+ This is a list of things in which units may be found
+ (sequences, dicts or modules), or units themselves. The
+ entire set will be "enabled" for searching through by methods
+ like `UnitBase.find_equivalent_units` and `UnitBase.compose`.
+
+ Examples
+ --------
+ >>> from astropy import units as u
+ >>> with u.set_enabled_units([u.pc]):
+ ... u.m.find_equivalent_units()
+ ...
+ Primary name | Unit definition | Aliases
+ [
+ pc | 3.08568e+16 m | parsec ,
+ ]
+ >>> u.m.find_equivalent_units()
+ Primary name | Unit definition | Aliases
+ [
+ AU | 1.49598e+11 m | au, astronomical_unit ,
+ Angstrom | 1e-10 m | AA, angstrom ,
+ cm | 0.01 m | centimeter ,
+ earthRad | 6.3781e+06 m | R_earth, Rearth ,
+ jupiterRad | 7.1492e+07 m | R_jup, Rjup, R_jupiter, Rjupiter ,
+ lsec | 2.99792e+08 m | lightsecond ,
+ lyr | 9.46073e+15 m | lightyear ,
+ m | irreducible | meter ,
+ micron | 1e-06 m | ,
+ pc | 3.08568e+16 m | parsec ,
+ solRad | 6.957e+08 m | R_sun, Rsun ,
+ ]
+ """
+ # get a context with a new registry, using equivalencies of the current one
+ context = _UnitContext(equivalencies=get_current_unit_registry().equivalencies)
+ # in this new current registry, enable the units requested
+ get_current_unit_registry().set_enabled_units(units)
+ return context
+
+
+def add_enabled_units(units):
+ """
+ Adds to the set of units enabled in the unit registry.
+
+ These units are searched when using
+ `UnitBase.find_equivalent_units`, for example.
+
+ This may be used either permanently, or as a context manager using
+ the ``with`` statement (see example below).
+
+ Parameters
+ ----------
+ units : list of sequence, dict, or module
+ This is a list of things in which units may be found
+ (sequences, dicts or modules), or units themselves. The
+ entire set will be added to the "enabled" set for searching
+ through by methods like `UnitBase.find_equivalent_units` and
+ `UnitBase.compose`.
+
+ Examples
+ --------
+ >>> from astropy import units as u
+ >>> from astropy.units import imperial
+ >>> with u.add_enabled_units(imperial):
+ ... u.m.find_equivalent_units()
+ ...
+ Primary name | Unit definition | Aliases
+ [
+ AU | 1.49598e+11 m | au, astronomical_unit ,
+ Angstrom | 1e-10 m | AA, angstrom ,
+ cm | 0.01 m | centimeter ,
+ earthRad | 6.3781e+06 m | R_earth, Rearth ,
+ ft | 0.3048 m | foot ,
+ fur | 201.168 m | furlong ,
+ inch | 0.0254 m | ,
+ jupiterRad | 7.1492e+07 m | R_jup, Rjup, R_jupiter, Rjupiter ,
+ lsec | 2.99792e+08 m | lightsecond ,
+ lyr | 9.46073e+15 m | lightyear ,
+ m | irreducible | meter ,
+ mi | 1609.34 m | mile ,
+ micron | 1e-06 m | ,
+ mil | 2.54e-05 m | thou ,
+ nmi | 1852 m | nauticalmile, NM ,
+ pc | 3.08568e+16 m | parsec ,
+ solRad | 6.957e+08 m | R_sun, Rsun ,
+ yd | 0.9144 m | yard ,
+ ]
+ """
+ # get a context with a new registry, which is a copy of the current one
+ context = _UnitContext(get_current_unit_registry())
+ # in this new current registry, enable the further units requested
+ get_current_unit_registry().add_enabled_units(units)
+ return context
+
+
+def set_enabled_equivalencies(equivalencies):
+ """
+ Sets the equivalencies enabled in the unit registry.
+
+ These equivalencies are used if no explicit equivalencies are given,
+ both in unit conversion and in finding equivalent units.
+
+ This is meant in particular for allowing angles to be dimensionless.
+ Use with care.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ list of equivalent pairs, e.g., as returned by
+ `~astropy.units.equivalencies.dimensionless_angles`.
+
+ Examples
+ --------
+ Exponentiation normally requires dimensionless quantities. To avoid
+ problems with complex phases::
+
+ >>> from astropy import units as u
+ >>> with u.set_enabled_equivalencies(u.dimensionless_angles()):
+ ... phase = 0.5 * u.cycle
+ ... np.exp(1j*phase) # doctest: +FLOAT_CMP
+ <Quantity -1.+1.2246468e-16j>
+ """
+ # get a context with a new registry, using all units of the current one
+ context = _UnitContext(get_current_unit_registry())
+ # in this new current registry, enable the equivalencies requested
+ get_current_unit_registry().set_enabled_equivalencies(equivalencies)
+ return context
+
+
+def add_enabled_equivalencies(equivalencies):
+ """
+ Adds to the equivalencies enabled in the unit registry.
+
+ These equivalencies are used if no explicit equivalencies are given,
+ both in unit conversion and in finding equivalent units.
+
+ This is meant in particular for allowing angles to be dimensionless.
+ Since no equivalencies are enabled by default, generally it is recommended
+ to use `set_enabled_equivalencies`.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ list of equivalent pairs, e.g., as returned by
+ `~astropy.units.equivalencies.dimensionless_angles`.
+ """
+ # get a context with a new registry, which is a copy of the current one
+ context = _UnitContext(get_current_unit_registry())
+ # in this new current registry, enable the further equivalencies requested
+ get_current_unit_registry().add_enabled_equivalencies(equivalencies)
+ return context
+
+
+def set_enabled_aliases(aliases):
+ """
+ Set aliases for units.
+
+ This is useful for handling alternate spellings for units, or
+ misspelled units in files one is trying to read.
+
+ Parameters
+ ----------
+ aliases : dict of str, Unit
+ The aliases to set. The keys must be the string aliases, and values
+ must be the `astropy.units.Unit` that the alias will be mapped to.
+
+ Raises
+ ------
+ ValueError
+ If the alias already defines a different unit.
+
+ Examples
+ --------
+ To temporarily allow for a misspelled 'Angstroem' unit::
+
+ >>> from astropy import units as u
+ >>> with u.set_enabled_aliases({'Angstroem': u.Angstrom}):
+ ... print(u.Unit("Angstroem", parse_strict="raise") == u.Angstrom)
+ True
+
+ """
+ # get a context with a new registry, which is a copy of the current one
+ context = _UnitContext(get_current_unit_registry())
+ # in this new current registry, enable the further equivalencies requested
+ get_current_unit_registry().set_enabled_aliases(aliases)
+ return context
+
+
+def add_enabled_aliases(aliases):
+ """
+ Add aliases for units.
+
+ This is useful for handling alternate spellings for units, or
+ misspelled units in files one is trying to read.
+
+ Since no aliases are enabled by default, generally it is recommended
+ to use `set_enabled_aliases`.
+
+ Parameters
+ ----------
+ aliases : dict of str, Unit
+ The aliases to add. The keys must be the string aliases, and values
+ must be the `astropy.units.Unit` that the alias will be mapped to.
+
+ Raises
+ ------
+ ValueError
+ If the alias already defines a different unit.
+
+ Examples
+ --------
+ To temporarily allow for a misspelled 'Angstroem' unit::
+
+ >>> from astropy import units as u
+ >>> with u.add_enabled_aliases({'Angstroem': u.Angstrom}):
+ ... print(u.Unit("Angstroem", parse_strict="raise") == u.Angstrom)
+ True
+
+ """
+ # get a context with a new registry, which is a copy of the current one
+ context = _UnitContext(get_current_unit_registry())
+ # in this new current registry, enable the further equivalencies requested
+ get_current_unit_registry().add_enabled_aliases(aliases)
+ return context
+
+
+class UnitsError(Exception):
+ """
+ The base class for unit-specific exceptions.
+ """
+
+
+class UnitScaleError(UnitsError, ValueError):
+ """
+ Used to catch the errors involving scaled units,
+ which are not recognized by FITS format.
+ """
+
+ pass
+
+
+class UnitConversionError(UnitsError, ValueError):
+ """
+ Used specifically for errors related to converting between units or
+ interpreting units in terms of other units.
+ """
+
+
+class UnitTypeError(UnitsError, TypeError):
+ """
+ Used specifically for errors in setting to units not allowed by a class.
+
+ E.g., would be raised if the unit of an `~astropy.coordinates.Angle`
+ instances were set to a non-angular unit.
+ """
+
+
+class UnitsWarning(AstropyWarning):
+ """
+ The base class for unit-specific warnings.
+ """
+
+
+class UnitBase:
+ """
+ Abstract base class for units.
+
+ Most of the arithmetic operations on units are defined in this
+ base class.
+
+ Should not be instantiated by users directly.
+ """
+
+ # Make sure that __rmul__ of units gets called over the __mul__ of Numpy
+ # arrays to avoid element-wise multiplication.
+ __array_priority__ = 1000
+
+ _hash = None
+ _type_id = None
+
+ def __deepcopy__(self, memo):
+ # This may look odd, but the units conversion will be very
+ # broken after deep-copying if we don't guarantee that a given
+ # physical unit corresponds to only one instance
+ return self
+
+ def _repr_latex_(self):
+ """
+ Generate latex representation of unit name. This is used by
+ the IPython notebook to print a unit with a nice layout.
+
+ Returns
+ -------
+ Latex string
+ """
+ return unit_format.Latex.to_string(self)
+
+ def __bytes__(self):
+ """Return string representation for unit."""
+ return unit_format.Generic.to_string(self).encode("unicode_escape")
+
+ def __str__(self):
+ """Return string representation for unit."""
+ return unit_format.Generic.to_string(self)
+
+ def __repr__(self):
+ string = unit_format.Generic.to_string(self)
+
+ return f'Unit("{string}")'
+
+ def _get_physical_type_id(self):
+ """
+ Returns an identifier that uniquely identifies the physical
+ type of this unit. It is comprised of the bases and powers of
+ this unit, without the scale. Since it is hashable, it is
+ useful as a dictionary key.
+ """
+ if self._type_id is None:
+ unit = self.decompose()
+ self._type_id = tuple(zip((base.name for base in unit.bases), unit.powers))
+
+ return self._type_id
+
+ @property
+ def names(self):
+ """
+ Returns all of the names associated with this unit.
+ """
+ raise AttributeError(
+ "Can not get names from unnamed units. Perhaps you meant to_string()?"
+ )
+
+ @property
+ def name(self):
+ """
+ Returns the canonical (short) name associated with this unit.
+ """
+ raise AttributeError(
+ "Can not get names from unnamed units. Perhaps you meant to_string()?"
+ )
+
+ @property
+ def aliases(self):
+ """
+ Returns the alias (long) names for this unit.
+ """
+ raise AttributeError(
+ "Can not get aliases from unnamed units. Perhaps you meant to_string()?"
+ )
+
+ @property
+ def scale(self):
+ """
+ Return the scale of the unit.
+ """
+ return 1.0
+
+ @property
+ def bases(self):
+ """
+ Return the bases of the unit.
+ """
+ return [self]
+
+ @property
+ def powers(self):
+ """
+ Return the powers of the unit.
+ """
+ return [1]
+
+ def to_string(self, format=unit_format.Generic, **kwargs):
+ r"""Output the unit in the given format as a string.
+
+ Parameters
+ ----------
+ format : `astropy.units.format.Base` instance or str
+ The name of a format or a formatter object. If not
+ provided, defaults to the generic format.
+
+ **kwargs
+ Further options forwarded to the formatter. Currently
+ recognized is ``fraction``, which can take the following values:
+
+ - `False` : display unit bases with negative powers as they are;
+ - 'inline' or `True` : use a single-line fraction;
+ - 'multiline' : use a multiline fraction (available for the
+ 'latex', 'console' and 'unicode' formats only).
+
+ Raises
+ ------
+ TypeError
+ If ``format`` is of the wrong type.
+ ValueError
+ If ``format`` or ``fraction`` are not recognized.
+
+ Examples
+ --------
+ >>> import astropy.units as u
+ >>> kms = u.Unit('km / s')
+ >>> kms.to_string() # Generic uses fraction='inline' by default
+ 'km / s'
+ >>> kms.to_string('latex') # Latex uses fraction='multiline' by default
+ '$\\mathrm{\\frac{km}{s}}$'
+ >>> print(kms.to_string('unicode', fraction=False))
+ km s⁻¹
+ >>> print(kms.to_string('unicode', fraction='inline'))
+ km / s
+ >>> print(kms.to_string('unicode', fraction='multiline'))
+ km
+ ──
+ s
+ """
+ f = unit_format.get_format(format)
+ return f.to_string(self, **kwargs)
+
+ def __format__(self, format_spec):
+ """Try to format units using a formatter."""
+ try:
+ return self.to_string(format=format_spec)
+ except ValueError:
+ return format(str(self), format_spec)
+
+ @staticmethod
+ def _normalize_equivalencies(equivalencies):
+ """Normalizes equivalencies, ensuring each is a 4-tuple.
+
+ The resulting tuple is of the form::
+
+ (from_unit, to_unit, forward_func, backward_func)
+
+ Parameters
+ ----------
+ equivalencies : list of equivalency pairs, or None
+
+ Returns
+ -------
+ A normalized list, including possible global defaults set by, e.g.,
+ `set_enabled_equivalencies`, except when `equivalencies`=`None`,
+ in which case the returned list is always empty.
+
+ Raises
+ ------
+ ValueError if an equivalency cannot be interpreted
+ """
+ normalized = _normalize_equivalencies(equivalencies)
+ if equivalencies is not None:
+ normalized += get_current_unit_registry().equivalencies
+
+ return normalized
+
+ def __pow__(self, p):
+ p = validate_power(p)
+ return CompositeUnit(1, [self], [p], _error_check=False)
+
+ def __truediv__(self, m):
+ if isinstance(m, (bytes, str)):
+ m = Unit(m)
+
+ if isinstance(m, UnitBase):
+ if m.is_unity():
+ return self
+ return CompositeUnit(1, [self, m], [1, -1], _error_check=False)
+
+ try:
+ # Cannot handle this as Unit, re-try as Quantity
+ from .quantity import Quantity
+
+ return Quantity(1, self) / m
+ except TypeError:
+ return NotImplemented
+
+ def __rtruediv__(self, m):
+ if isinstance(m, (bytes, str)):
+ return Unit(m) / self
+
+ try:
+ # Cannot handle this as Unit. Here, m cannot be a Quantity,
+ # so we make it into one, fasttracking when it does not have a
+ # unit, for the common case of <array> / <unit>.
+ from .quantity import Quantity
+
+ if hasattr(m, "unit"):
+ result = Quantity(m)
+ result /= self
+ return result
+ else:
+ return Quantity(m, self ** (-1))
+ except TypeError:
+ return NotImplemented
+
+ def __mul__(self, m):
+ if isinstance(m, (bytes, str)):
+ m = Unit(m)
+
+ if isinstance(m, UnitBase):
+ if m.is_unity():
+ return self
+ elif self.is_unity():
+ return m
+ return CompositeUnit(1, [self, m], [1, 1], _error_check=False)
+
+ # Cannot handle this as Unit, re-try as Quantity.
+ try:
+ from .quantity import Quantity
+
+ return Quantity(1, unit=self) * m
+ except TypeError:
+ return NotImplemented
+
+ def __rmul__(self, m):
+ if isinstance(m, (bytes, str)):
+ return Unit(m) * self
+
+ # Cannot handle this as Unit. Here, m cannot be a Quantity,
+ # so we make it into one, fasttracking when it does not have a unit
+ # for the common case of <array> * <unit>.
+ try:
+ from .quantity import Quantity
+
+ if hasattr(m, "unit"):
+ result = Quantity(m)
+ result *= self
+ return result
+ else:
+ return Quantity(m, unit=self)
+ except TypeError:
+ return NotImplemented
+
+ def __rlshift__(self, m):
+ try:
+ from .quantity import Quantity
+
+ return Quantity(m, self, copy=False, subok=True)
+ except Exception:
+ return NotImplemented
+
+ def __rrshift__(self, m):
+ warnings.warn(
+ ">> is not implemented. Did you mean to convert "
+ f"to a Quantity with unit {m} using '<<'?",
+ AstropyWarning,
+ )
+ return NotImplemented
+
+ def __hash__(self):
+ if self._hash is None:
+ parts = (
+ [str(self.scale)]
+ + [x.name for x in self.bases]
+ + [str(x) for x in self.powers]
+ )
+ self._hash = hash(tuple(parts))
+ return self._hash
+
+ def __getstate__(self):
+ # If we get pickled, we should *not* store the memoized members since
+ # hashes of strings vary between sessions.
+ state = self.__dict__.copy()
+ state.pop("_hash", None)
+ state.pop("_type_id", None)
+ return state
+
+ def __eq__(self, other):
+ if self is other:
+ return True
+
+ try:
+ other = Unit(other, parse_strict="silent")
+ except (ValueError, UnitsError, TypeError):
+ return NotImplemented
+
+ # Other is unit-like, but the test below requires it is a UnitBase
+ # instance; if it is not, give up (so that other can try).
+ if not isinstance(other, UnitBase):
+ return NotImplemented
+
+ try:
+ return is_effectively_unity(self._to(other))
+ except UnitsError:
+ return False
+
+ def __ne__(self, other):
+ return not (self == other)
+
+ def __le__(self, other):
+ scale = self._to(Unit(other))
+ return scale <= 1.0 or is_effectively_unity(scale)
+
+ def __ge__(self, other):
+ scale = self._to(Unit(other))
+ return scale >= 1.0 or is_effectively_unity(scale)
+
+ def __lt__(self, other):
+ return not (self >= other)
+
+ def __gt__(self, other):
+ return not (self <= other)
+
+ def __neg__(self):
+ return self * -1.0
+
+ def is_equivalent(self, other, equivalencies=[]):
+ """
+ Returns `True` if this unit is equivalent to ``other``.
+
+ Parameters
+ ----------
+ other : `~astropy.units.Unit`, str, or tuple
+ The unit to convert to. If a tuple of units is specified, this
+ method returns true if the unit matches any of those in the tuple.
+
+ equivalencies : list of tuple
+ A list of equivalence pairs to try if the units are not
+ directly convertible. See :ref:`astropy:unit_equivalencies`.
+ This list is in addition to possible global defaults set by, e.g.,
+ `set_enabled_equivalencies`.
+ Use `None` to turn off all equivalencies.
+
+ Returns
+ -------
+ bool
+ """
+ equivalencies = self._normalize_equivalencies(equivalencies)
+
+ if isinstance(other, tuple):
+ return any(self.is_equivalent(u, equivalencies) for u in other)
+
+ other = Unit(other, parse_strict="silent")
+
+ return self._is_equivalent(other, equivalencies)
+
+ def _is_equivalent(self, other, equivalencies=[]):
+ """Returns `True` if this unit is equivalent to `other`.
+ See `is_equivalent`, except that a proper Unit object should be
+ given (i.e., no string) and that the equivalency list should be
+ normalized using `_normalize_equivalencies`.
+ """
+ if isinstance(other, UnrecognizedUnit):
+ return False
+
+ if self._get_physical_type_id() == other._get_physical_type_id():
+ return True
+ elif len(equivalencies):
+ unit = self.decompose()
+ other = other.decompose()
+ for a, b, forward, backward in equivalencies:
+ if b is None:
+ # after canceling, is what's left convertible
+ # to dimensionless (according to the equivalency)?
+ try:
+ (other / unit).decompose([a])
+ return True
+ except Exception:
+ pass
+ elif (a._is_equivalent(unit) and b._is_equivalent(other)) or (
+ b._is_equivalent(unit) and a._is_equivalent(other)
+ ):
+ return True
+
+ return False
+
+ def _apply_equivalencies(self, unit, other, equivalencies):
+ """
+ Internal function (used from `_get_converter`) to apply
+ equivalence pairs.
+ """
+
+ def make_converter(scale1, func, scale2):
+ def convert(v):
+ return func(_condition_arg(v) / scale1) * scale2
+
+ return convert
+
+ for funit, tunit, a, b in equivalencies:
+ if tunit is None:
+ ratio = other.decompose() / unit.decompose()
+ try:
+ ratio_in_funit = ratio.decompose([funit])
+ return make_converter(ratio_in_funit.scale, a, 1.0)
+ except UnitsError:
+ pass
+ else:
+ try:
+ scale1 = funit._to(unit)
+ scale2 = tunit._to(other)
+ return make_converter(scale1, a, scale2)
+ except UnitsError:
+ pass
+ try:
+ scale1 = tunit._to(unit)
+ scale2 = funit._to(other)
+ return make_converter(scale1, b, scale2)
+ except UnitsError:
+ pass
+
+ def get_err_str(unit):
+ unit_str = unit.to_string("unscaled")
+ physical_type = unit.physical_type
+ if physical_type != "unknown":
+ unit_str = f"'{unit_str}' ({physical_type})"
+ else:
+ unit_str = f"'{unit_str}'"
+ return unit_str
+
+ unit_str = get_err_str(unit)
+ other_str = get_err_str(other)
+
+ raise UnitConversionError(f"{unit_str} and {other_str} are not convertible")
+
+ def _get_converter(self, other, equivalencies=[]):
+ """Get a converter for values in ``self`` to ``other``.
+
+ If no conversion is necessary, returns ``unit_scale_converter``
+ (which is used as a check in quantity helpers).
+
+ """
+ # First see if it is just a scaling.
+ try:
+ scale = self._to(other)
+ except UnitsError:
+ pass
+ else:
+ if scale == 1.0:
+ return unit_scale_converter
+ else:
+ return lambda val: scale * _condition_arg(val)
+
+ # if that doesn't work, maybe we can do it with equivalencies?
+ try:
+ return self._apply_equivalencies(
+ self, other, self._normalize_equivalencies(equivalencies)
+ )
+ except UnitsError as exc:
+ # Last hope: maybe other knows how to do it?
+ # We assume the equivalencies have the unit itself as first item.
+ # TODO: maybe better for other to have a `_back_converter` method?
+ if hasattr(other, "equivalencies"):
+ for funit, tunit, a, b in other.equivalencies:
+ if other is funit:
+ try:
+ converter = self._get_converter(tunit, equivalencies)
+ except Exception:
+ pass
+ else:
+ return lambda v: b(converter(v))
+
+ raise exc
+
+ def _to(self, other):
+ """
+ Returns the scale to the specified unit.
+
+ See `to`, except that a Unit object should be given (i.e., no
+ string), and that all defaults are used, i.e., no
+ equivalencies and value=1.
+ """
+ # There are many cases where we just want to ensure a Quantity is
+ # of a particular unit, without checking whether it's already in
+ # a particular unit. If we're being asked to convert from a unit
+ # to itself, we can short-circuit all of this.
+ if self is other:
+ return 1.0
+
+ # Don't presume decomposition is possible; e.g.,
+ # conversion to function units is through equivalencies.
+ if isinstance(other, UnitBase):
+ self_decomposed = self.decompose()
+ other_decomposed = other.decompose()
+
+ # Check quickly whether equivalent. This is faster than
+ # `is_equivalent`, because it doesn't generate the entire
+ # physical type list of both units. In other words it "fails
+ # fast".
+ if self_decomposed.powers == other_decomposed.powers and all(
+ self_base is other_base
+ for (self_base, other_base) in zip(
+ self_decomposed.bases, other_decomposed.bases
+ )
+ ):
+ return self_decomposed.scale / other_decomposed.scale
+
+ raise UnitConversionError(f"'{self!r}' is not a scaled version of '{other!r}'")
+
+ def to(self, other, value=UNITY, equivalencies=[]):
+ """
+ Return the converted values in the specified unit.
+
+ Parameters
+ ----------
+ other : unit-like
+ The unit to convert to.
+
+ value : int, float, or scalar array-like, optional
+ Value(s) in the current unit to be converted to the
+ specified unit. If not provided, defaults to 1.0
+
+ equivalencies : list of tuple
+ A list of equivalence pairs to try if the units are not
+ directly convertible. See :ref:`astropy:unit_equivalencies`.
+ This list is in addition to possible global defaults set by, e.g.,
+ `set_enabled_equivalencies`.
+ Use `None` to turn off all equivalencies.
+
+ Returns
+ -------
+ values : scalar or array
+ Converted value(s). Input value sequences are returned as
+ numpy arrays.
+
+ Raises
+ ------
+ UnitsError
+ If units are inconsistent
+ """
+ if other is self and value is UNITY:
+ return UNITY
+ else:
+ return self._get_converter(Unit(other), equivalencies)(value)
+
+ def in_units(self, other, value=1.0, equivalencies=[]):
+ """
+ Alias for `to` for backward compatibility with pynbody.
+ """
+ return self.to(other, value=value, equivalencies=equivalencies)
+
+ def decompose(self, bases=set()):
+ """
+ Return a unit object composed of only irreducible units.
+
+ Parameters
+ ----------
+ bases : sequence of UnitBase, optional
+ The bases to decompose into. When not provided,
+ decomposes down to any irreducible units. When provided,
+ the decomposed result will only contain the given units.
+ This will raises a `UnitsError` if it's not possible
+ to do so.
+
+ Returns
+ -------
+ unit : `~astropy.units.CompositeUnit`
+ New object containing only irreducible unit objects.
+ """
+ raise NotImplementedError()
+
+ def _compose(
+ self, equivalencies=[], namespace=[], max_depth=2, depth=0, cached_results=None
+ ):
+ def is_final_result(unit):
+ # Returns True if this result contains only the expected
+ # units
+ return all(base in namespace for base in unit.bases)
+
+ unit = self.decompose()
+ key = hash(unit)
+
+ cached = cached_results.get(key)
+ if cached is not None:
+ if isinstance(cached, Exception):
+ raise cached
+ return cached
+
+ # Prevent too many levels of recursion
+ # And special case for dimensionless unit
+ if depth >= max_depth:
+ cached_results[key] = [unit]
+ return [unit]
+
+ # Make a list including all of the equivalent units
+ units = [unit]
+ for funit, tunit, a, b in equivalencies:
+ if tunit is not None:
+ if self._is_equivalent(funit):
+ scale = funit.decompose().scale / unit.scale
+ units.append(Unit(a(1.0 / scale) * tunit).decompose())
+ elif self._is_equivalent(tunit):
+ scale = tunit.decompose().scale / unit.scale
+ units.append(Unit(b(1.0 / scale) * funit).decompose())
+ else:
+ if self._is_equivalent(funit):
+ units.append(Unit(unit.scale))
+
+ # Store partial results
+ partial_results = []
+ # Store final results that reduce to a single unit or pair of
+ # units
+ if len(unit.bases) == 0:
+ final_results = [{unit}, set()]
+ else:
+ final_results = [set(), set()]
+
+ for tunit in namespace:
+ tunit_decomposed = tunit.decompose()
+ for u in units:
+ # If the unit is a base unit, look for an exact match
+ # to one of the bases of the target unit. If found,
+ # factor by the same power as the target unit's base.
+ # This allows us to factor out fractional powers
+ # without needing to do an exhaustive search.
+ if len(tunit_decomposed.bases) == 1:
+ for base, power in zip(u.bases, u.powers):
+ if tunit_decomposed._is_equivalent(base):
+ tunit = tunit**power
+ tunit_decomposed = tunit_decomposed**power
+ break
+
+ composed = (u / tunit_decomposed).decompose()
+ factored = composed * tunit
+ len_bases = len(composed.bases)
+ if is_final_result(factored) and len_bases <= 1:
+ final_results[len_bases].add(factored)
+ else:
+ partial_results.append((len_bases, composed, tunit))
+
+ # Do we have any minimal results?
+ for final_result in final_results:
+ if len(final_result):
+ results = final_results[0].union(final_results[1])
+ cached_results[key] = results
+ return results
+
+ partial_results.sort(key=operator.itemgetter(0))
+
+ # ...we have to recurse and try to further compose
+ results = []
+ for len_bases, composed, tunit in partial_results:
+ try:
+ composed_list = composed._compose(
+ equivalencies=equivalencies,
+ namespace=namespace,
+ max_depth=max_depth,
+ depth=depth + 1,
+ cached_results=cached_results,
+ )
+ except UnitsError:
+ composed_list = []
+ for subcomposed in composed_list:
+ results.append((len(subcomposed.bases), subcomposed, tunit))
+
+ if len(results):
+ results.sort(key=operator.itemgetter(0))
+
+ min_length = results[0][0]
+ subresults = set()
+ for len_bases, composed, tunit in results:
+ if len_bases > min_length:
+ break
+
+ factored = composed * tunit
+ if is_final_result(factored):
+ subresults.add(factored)
+
+ if len(subresults):
+ cached_results[key] = subresults
+ return subresults
+
+ if not is_final_result(self):
+ result = UnitsError(
+ f"Cannot represent unit {self} in terms of the given units"
+ )
+ cached_results[key] = result
+ raise result
+
+ cached_results[key] = [self]
+ return [self]
+
+ def compose(
+ self, equivalencies=[], units=None, max_depth=2, include_prefix_units=None
+ ):
+ """
+ Return the simplest possible composite unit(s) that represent
+ the given unit. Since there may be multiple equally simple
+ compositions of the unit, a list of units is always returned.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ A list of equivalence pairs to also list. See
+ :ref:`astropy:unit_equivalencies`.
+ This list is in addition to possible global defaults set by, e.g.,
+ `set_enabled_equivalencies`.
+ Use `None` to turn off all equivalencies.
+
+ units : set of `~astropy.units.Unit`, optional
+ If not provided, any known units may be used to compose
+ into. Otherwise, ``units`` is a dict, module or sequence
+ containing the units to compose into.
+
+ max_depth : int, optional
+ The maximum recursion depth to use when composing into
+ composite units.
+
+ include_prefix_units : bool, optional
+ When `True`, include prefixed units in the result.
+ Default is `True` if a sequence is passed in to ``units``,
+ `False` otherwise.
+
+ Returns
+ -------
+ units : list of `CompositeUnit`
+ A list of candidate compositions. These will all be
+ equally simple, but it may not be possible to
+ automatically determine which of the candidates are
+ better.
+ """
+ # if units parameter is specified and is a sequence (list|tuple),
+ # include_prefix_units is turned on by default. Ex: units=[u.kpc]
+ if include_prefix_units is None:
+ include_prefix_units = isinstance(units, (list, tuple))
+
+ # Pre-normalize the equivalencies list
+ equivalencies = self._normalize_equivalencies(equivalencies)
+
+ # The namespace of units to compose into should be filtered to
+ # only include units with bases in common with self, otherwise
+ # they can't possibly provide useful results. Having too many
+ # destination units greatly increases the search space.
+
+ def has_bases_in_common(a, b):
+ if len(a.bases) == 0 and len(b.bases) == 0:
+ return True
+ for ab in a.bases:
+ for bb in b.bases:
+ if ab == bb:
+ return True
+ return False
+
+ def has_bases_in_common_with_equiv(unit, other):
+ if has_bases_in_common(unit, other):
+ return True
+ for funit, tunit, a, b in equivalencies:
+ if tunit is not None:
+ if unit._is_equivalent(funit):
+ if has_bases_in_common(tunit.decompose(), other):
+ return True
+ elif unit._is_equivalent(tunit):
+ if has_bases_in_common(funit.decompose(), other):
+ return True
+ else:
+ if unit._is_equivalent(funit):
+ if has_bases_in_common(dimensionless_unscaled, other):
+ return True
+ return False
+
+ def filter_units(units):
+ filtered_namespace = set()
+ for tunit in units:
+ if (
+ isinstance(tunit, UnitBase)
+ and (include_prefix_units or not isinstance(tunit, PrefixUnit))
+ and has_bases_in_common_with_equiv(decomposed, tunit.decompose())
+ ):
+ filtered_namespace.add(tunit)
+ return filtered_namespace
+
+ decomposed = self.decompose()
+
+ if units is None:
+ units = filter_units(self._get_units_with_same_physical_type(equivalencies))
+ if len(units) == 0:
+ units = get_current_unit_registry().non_prefix_units
+ elif isinstance(units, dict):
+ units = set(filter_units(units.values()))
+ elif inspect.ismodule(units):
+ units = filter_units(vars(units).values())
+ else:
+ units = filter_units(_flatten_units_collection(units))
+
+ def sort_results(results):
+ if not len(results):
+ return []
+
+ # Sort the results so the simplest ones appear first.
+ # Simplest is defined as "the minimum sum of absolute
+ # powers" (i.e. the fewest bases), and preference should
+ # be given to results where the sum of powers is positive
+ # and the scale is exactly equal to 1.0
+ results = list(results)
+ results.sort(key=lambda x: np.abs(x.scale))
+ results.sort(key=lambda x: np.sum(np.abs(x.powers)))
+ results.sort(key=lambda x: np.sum(x.powers) < 0.0)
+ results.sort(key=lambda x: not is_effectively_unity(x.scale))
+
+ last_result = results[0]
+ filtered = [last_result]
+ for result in results[1:]:
+ if str(result) != str(last_result):
+ filtered.append(result)
+ last_result = result
+
+ return filtered
+
+ return sort_results(
+ self._compose(
+ equivalencies=equivalencies,
+ namespace=units,
+ max_depth=max_depth,
+ depth=0,
+ cached_results={},
+ )
+ )
+
+ def to_system(self, system):
+ """
+ Converts this unit into ones belonging to the given system.
+ Since more than one result may be possible, a list is always
+ returned.
+
+ Parameters
+ ----------
+ system : module
+ The module that defines the unit system. Commonly used
+ ones include `astropy.units.si` and `astropy.units.cgs`.
+
+ To use your own module it must contain unit objects and a
+ sequence member named ``bases`` containing the base units of
+ the system.
+
+ Returns
+ -------
+ units : list of `CompositeUnit`
+ The list is ranked so that units containing only the base
+ units of that system will appear first.
+ """
+ bases = set(system.bases)
+
+ def score(compose):
+ # In case that compose._bases has no elements we return
+ # 'np.inf' as 'score value'. It does not really matter which
+ # number we would return. This case occurs for instance for
+ # dimensionless quantities:
+ compose_bases = compose.bases
+ if len(compose_bases) == 0:
+ return np.inf
+ else:
+ sum = 0
+ for base in compose_bases:
+ if base in bases:
+ sum += 1
+
+ return sum / float(len(compose_bases))
+
+ x = self.decompose(bases=bases)
+ composed = x.compose(units=system)
+ composed = sorted(composed, key=score, reverse=True)
+ return composed
+
+ @lazyproperty
+ def si(self):
+ """
+ Returns a copy of the current `Unit` instance in SI units.
+ """
+ from . import si
+
+ return self.to_system(si)[0]
+
+ @lazyproperty
+ def cgs(self):
+ """
+ Returns a copy of the current `Unit` instance with CGS units.
+ """
+ from . import cgs
+
+ return self.to_system(cgs)[0]
+
+ @property
+ def physical_type(self):
+ """
+ Physical type(s) dimensionally compatible with the unit.
+
+ Returns
+ -------
+ `~astropy.units.physical.PhysicalType`
+ A representation of the physical type(s) of a unit.
+
+ Examples
+ --------
+ >>> from astropy import units as u
+ >>> u.m.physical_type
+ PhysicalType('length')
+ >>> (u.m ** 2 / u.s).physical_type
+ PhysicalType({'diffusivity', 'kinematic viscosity'})
+
+ Physical types can be compared to other physical types
+ (recommended in packages) or to strings.
+
+ >>> area = (u.m ** 2).physical_type
+ >>> area == u.m.physical_type ** 2
+ True
+ >>> area == "area"
+ True
+
+ `~astropy.units.physical.PhysicalType` objects can be used for
+ dimensional analysis.
+
+ >>> number_density = u.m.physical_type ** -3
+ >>> velocity = (u.m / u.s).physical_type
+ >>> number_density * velocity
+ PhysicalType('particle flux')
+ """
+ from . import physical
+
+ return physical.get_physical_type(self)
+
+ def _get_units_with_same_physical_type(self, equivalencies=[]):
+ """
+ Return a list of registered units with the same physical type
+ as this unit.
+
+ This function is used by Quantity to add its built-in
+ conversions to equivalent units.
+
+ This is a private method, since end users should be encouraged
+ to use the more powerful `compose` and `find_equivalent_units`
+ methods (which use this under the hood).
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ A list of equivalence pairs to also pull options from.
+ See :ref:`astropy:unit_equivalencies`. It must already be
+ normalized using `_normalize_equivalencies`.
+ """
+ unit_registry = get_current_unit_registry()
+ units = set(unit_registry.get_units_with_physical_type(self))
+ for funit, tunit, a, b in equivalencies:
+ if tunit is not None:
+ if self.is_equivalent(funit) and tunit not in units:
+ units.update(unit_registry.get_units_with_physical_type(tunit))
+ if self._is_equivalent(tunit) and funit not in units:
+ units.update(unit_registry.get_units_with_physical_type(funit))
+ else:
+ if self.is_equivalent(funit):
+ units.add(dimensionless_unscaled)
+ return units
+
+ class EquivalentUnitsList(list):
+ """
+ A class to handle pretty-printing the result of
+ `find_equivalent_units`.
+ """
+
+ HEADING_NAMES = ("Primary name", "Unit definition", "Aliases")
+ ROW_LEN = 3 # len(HEADING_NAMES), but hard-code since it is constant
+ NO_EQUIV_UNITS_MSG = "There are no equivalent units"
+
+ def __repr__(self):
+ if len(self) == 0:
+ return self.NO_EQUIV_UNITS_MSG
+ else:
+ lines = self._process_equivalent_units(self)
+ lines.insert(0, self.HEADING_NAMES)
+ widths = [0] * self.ROW_LEN
+ for line in lines:
+ for i, col in enumerate(line):
+ widths[i] = max(widths[i], len(col))
+
+ f = " {{0:<{}s}} | {{1:<{}s}} | {{2:<{}s}}".format(*widths)
+ lines = [f.format(*line) for line in lines]
+ lines = lines[0:1] + ["["] + [f"{x} ," for x in lines[1:]] + ["]"]
+ return "\n".join(lines)
+
+ def _repr_html_(self):
+ """
+ Outputs a HTML table representation within Jupyter notebooks.
+ """
+ if len(self) == 0:
+ return f"<p>{self.NO_EQUIV_UNITS_MSG}</p>"
+ else:
+ # HTML tags to use to compose the table in HTML
+ blank_table = '<table style="width:50%">{}</table>'
+ blank_row_container = "<tr>{}</tr>"
+ heading_row_content = "<th>{}</th>" * self.ROW_LEN
+ data_row_content = "<td>{}</td>" * self.ROW_LEN
+
+ # The HTML will be rendered & the table is simple, so don't
+ # bother to include newlines & indentation for the HTML code.
+ heading_row = blank_row_container.format(
+ heading_row_content.format(*self.HEADING_NAMES)
+ )
+ data_rows = self._process_equivalent_units(self)
+ all_rows = heading_row
+ for row in data_rows:
+ html_row = blank_row_container.format(data_row_content.format(*row))
+ all_rows += html_row
+ return blank_table.format(all_rows)
+
+ @staticmethod
+ def _process_equivalent_units(equiv_units_data):
+ """
+ Extract attributes, and sort, the equivalent units pre-formatting.
+ """
+ processed_equiv_units = []
+ for u in equiv_units_data:
+ irred = u.decompose().to_string()
+ if irred == u.name:
+ irred = "irreducible"
+ processed_equiv_units.append((u.name, irred, ", ".join(u.aliases)))
+ processed_equiv_units.sort()
+ return processed_equiv_units
+
+ def find_equivalent_units(
+ self, equivalencies=[], units=None, include_prefix_units=False
+ ):
+ """
+ Return a list of all the units that are the same type as ``self``.
+
+ Parameters
+ ----------
+ equivalencies : list of tuple
+ A list of equivalence pairs to also list. See
+ :ref:`astropy:unit_equivalencies`.
+ Any list given, including an empty one, supersedes global defaults
+ that may be in effect (as set by `set_enabled_equivalencies`)
+
+ units : set of `~astropy.units.Unit`, optional
+ If not provided, all defined units will be searched for
+ equivalencies. Otherwise, may be a dict, module or
+ sequence containing the units to search for equivalencies.
+
+ include_prefix_units : bool, optional
+ When `True`, include prefixed units in the result.
+ Default is `False`.
+
+ Returns
+ -------
+ units : list of `UnitBase`
+ A list of unit objects that match ``u``. A subclass of
+ `list` (``EquivalentUnitsList``) is returned that
+ pretty-prints the list of units when output.
+ """
+ results = self.compose(
+ equivalencies=equivalencies,
+ units=units,
+ max_depth=1,
+ include_prefix_units=include_prefix_units,
+ )
+ results = {
+ x.bases[0] for x in results if len(x.bases) == 1 and x.powers[0] == 1
+ }
+ return self.EquivalentUnitsList(results)
+
+ def is_unity(self):
+ """
+ Returns `True` if the unit is unscaled and dimensionless.
+ """
+ return False
+
+
+class NamedUnit(UnitBase):
+ """
+ The base class of units that have a name.
+
+ Parameters
+ ----------
+ st : str, list of str, 2-tuple
+ The name of the unit. If a list of strings, the first element
+ is the canonical (short) name, and the rest of the elements
+ are aliases. If a tuple of lists, the first element is a list
+ of short names, and the second element is a list of long
+ names; all but the first short name are considered "aliases".
+ Each name *should* be a valid Python identifier to make it
+ easy to access, but this is not required.
+
+ namespace : dict, optional
+ When provided, inject the unit, and all of its aliases, in the
+ given namespace dictionary. If a unit by the same name is
+ already in the namespace, a ValueError is raised.
+
+ doc : str, optional
+ A docstring describing the unit.
+
+ format : dict, optional
+ A mapping to format-specific representations of this unit.
+ For example, for the ``Ohm`` unit, it might be nice to have it
+ displayed as ``\\Omega`` by the ``latex`` formatter. In that
+ case, `format` argument should be set to::
+
+ {'latex': r'\\Omega'}
+
+ Raises
+ ------
+ ValueError
+ If any of the given unit names are already in the registry.
+
+ ValueError
+ If any of the given unit names are not valid Python tokens.
+ """
+
+ def __init__(self, st, doc=None, format=None, namespace=None):
+ UnitBase.__init__(self)
+
+ if isinstance(st, (bytes, str)):
+ self._names = [st]
+ self._short_names = [st]
+ self._long_names = []
+ elif isinstance(st, tuple):
+ if not len(st) == 2:
+ raise ValueError("st must be string, list or 2-tuple")
+ self._names = st[0] + [n for n in st[1] if n not in st[0]]
+ if not len(self._names):
+ raise ValueError("must provide at least one name")
+ self._short_names = st[0][:]
+ self._long_names = st[1][:]
+ else:
+ if len(st) == 0:
+ raise ValueError("st list must have at least one entry")
+ self._names = st[:]
+ self._short_names = [st[0]]
+ self._long_names = st[1:]
+
+ if format is None:
+ format = {}
+ self._format = format
+
+ if doc is None:
+ doc = self._generate_doc()
+ else:
+ doc = textwrap.dedent(doc)
+ doc = textwrap.fill(doc)
+
+ self.__doc__ = doc
+
+ self._inject(namespace)
+
+ def _generate_doc(self):
+ """
+ Generate a docstring for the unit if the user didn't supply
+ one. This is only used from the constructor and may be
+ overridden in subclasses.
+ """
+ names = self.names
+ if len(self.names) > 1:
+ return f"{names[1]} ({names[0]})"
+ else:
+ return names[0]
+
+ def get_format_name(self, format):
+ """
+ Get a name for this unit that is specific to a particular
+ format.
+
+ Uses the dictionary passed into the `format` kwarg in the
+ constructor.
+
+ Parameters
+ ----------
+ format : str
+ The name of the format
+
+ Returns
+ -------
+ name : str
+ The name of the unit for the given format.
+ """
+ return self._format.get(format, self.name)
+
+ @property
+ def names(self):
+ """
+ Returns all of the names associated with this unit.
+ """
+ return self._names
+
+ @property
+ def name(self):
+ """
+ Returns the canonical (short) name associated with this unit.
+ """
+ return self._names[0]
+
+ @property
+ def aliases(self):
+ """
+ Returns the alias (long) names for this unit.
+ """
+ return self._names[1:]
+
+ @property
+ def short_names(self):
+ """
+ Returns all of the short names associated with this unit.
+ """
+ return self._short_names
+
+ @property
+ def long_names(self):
+ """
+ Returns all of the long names associated with this unit.
+ """
+ return self._long_names
+
+ def _inject(self, namespace=None):
+ """
+ Injects the unit, and all of its aliases, in the given
+ namespace dictionary.
+ """
+ if namespace is None:
+ return
+
+ # Loop through all of the names first, to ensure all of them
+ # are new, then add them all as a single "transaction" below.
+ for name in self._names:
+ if name in namespace and self != namespace[name]:
+ raise ValueError(
+ f"Object with name {name!r} already exists in "
+ f"given namespace ({namespace[name]!r})."
+ )
+
+ for name in self._names:
+ namespace[name] = self
+
+
+def _recreate_irreducible_unit(cls, names, registered):
+ """
+ This is used to reconstruct units when passed around by
+ multiprocessing.
+ """
+ registry = get_current_unit_registry().registry
+ if names[0] in registry:
+ # If in local registry return that object.
+ return registry[names[0]]
+ else:
+ # otherwise, recreate the unit.
+ unit = cls(names)
+ if registered:
+ # If not in local registry but registered in origin registry,
+ # enable unit in local registry.
+ get_current_unit_registry().add_enabled_units([unit])
+
+ return unit
+
+
+class IrreducibleUnit(NamedUnit):
+ """
+ Irreducible units are the units that all other units are defined
+ in terms of.
+
+ Examples are meters, seconds, kilograms, amperes, etc. There is
+ only once instance of such a unit per type.
+ """
+
+ def __reduce__(self):
+ # When IrreducibleUnit objects are passed to other processes
+ # over multiprocessing, they need to be recreated to be the
+ # ones already in the subprocesses' namespace, not new
+ # objects, or they will be considered "unconvertible".
+ # Therefore, we have a custom pickler/unpickler that
+ # understands how to recreate the Unit on the other side.
+ registry = get_current_unit_registry().registry
+ return (
+ _recreate_irreducible_unit,
+ (self.__class__, list(self.names), self.name in registry),
+ self.__getstate__(),
+ )
+
+ @property
+ def represents(self):
+ """The unit that this named unit represents.
+
+ For an irreducible unit, that is always itself.
+ """
+ return self
+
+ def decompose(self, bases=set()):
+ if len(bases) and self not in bases:
+ for base in bases:
+ try:
+ scale = self._to(base)
+ except UnitsError:
+ pass
+ else:
+ if is_effectively_unity(scale):
+ return base
+ else:
+ return CompositeUnit(scale, [base], [1], _error_check=False)
+
+ raise UnitConversionError(
+ f"Unit {self} can not be decomposed into the requested bases"
+ )
+
+ return self
+
+
+class UnrecognizedUnit(IrreducibleUnit):
+ """
+ A unit that did not parse correctly. This allows for
+ round-tripping it as a string, but no unit operations actually work
+ on it.
+
+ Parameters
+ ----------
+ st : str
+ The name of the unit.
+ """
+
+ # For UnrecognizedUnits, we want to use "standard" Python
+ # pickling, not the special case that is used for
+ # IrreducibleUnits.
+ __reduce__ = object.__reduce__
+
+ def __repr__(self):
+ return f"UnrecognizedUnit({self})"
+
+ def __bytes__(self):
+ return self.name.encode("ascii", "replace")
+
+ def __str__(self):
+ return self.name
+
+ def to_string(self, format=None):
+ return self.name
+
+ def _unrecognized_operator(self, *args, **kwargs):
+ raise ValueError(
+ f"The unit {self.name!r} is unrecognized, so all arithmetic operations "
+ "with it are invalid."
+ )
+
+ __pow__ = __truediv__ = __rtruediv__ = __mul__ = __rmul__ = _unrecognized_operator
+ __lt__ = __gt__ = __le__ = __ge__ = __neg__ = _unrecognized_operator
+
+ def __eq__(self, other):
+ try:
+ other = Unit(other, parse_strict="silent")
+ except (ValueError, UnitsError, TypeError):
+ return NotImplemented
+
+ return isinstance(other, type(self)) and self.name == other.name
+
+ def __ne__(self, other):
+ return not (self == other)
+
+ def is_equivalent(self, other, equivalencies=None):
+ self._normalize_equivalencies(equivalencies)
+ return self == other
+
+ def _get_converter(self, other, equivalencies=None):
+ self._normalize_equivalencies(equivalencies)
+ raise ValueError(
+ f"The unit {self.name!r} is unrecognized. It can not be converted "
+ "to other units."
+ )
+
+ def get_format_name(self, format):
+ return self.name
+
+ def is_unity(self):
+ return False
+
+
+class _UnitMetaClass(type):
+ """
+ This metaclass exists because the Unit constructor should
+ sometimes return instances that already exist. This "overrides"
+ the constructor before the new instance is actually created, so we
+ can return an existing one.
+ """
+
+ def __call__(
+ self,
+ s="",
+ represents=None,
+ format=None,
+ namespace=None,
+ doc=None,
+ parse_strict="raise",
+ ):
+ # Short-circuit if we're already a unit
+ if hasattr(s, "_get_physical_type_id"):
+ return s
+
+ # turn possible Quantity input for s or represents into a Unit
+ from .quantity import Quantity
+
+ if isinstance(represents, Quantity):
+ if is_effectively_unity(represents.value):
+ represents = represents.unit
+ else:
+ represents = CompositeUnit(
+ represents.value * represents.unit.scale,
+ bases=represents.unit.bases,
+ powers=represents.unit.powers,
+ _error_check=False,
+ )
+
+ if isinstance(s, Quantity):
+ if is_effectively_unity(s.value):
+ s = s.unit
+ else:
+ s = CompositeUnit(
+ s.value * s.unit.scale,
+ bases=s.unit.bases,
+ powers=s.unit.powers,
+ _error_check=False,
+ )
+
+ # now decide what we really need to do; define derived Unit?
+ if isinstance(represents, UnitBase):
+ # This has the effect of calling the real __new__ and
+ # __init__ on the Unit class.
+ return super().__call__(
+ s, represents, format=format, namespace=namespace, doc=doc
+ )
+
+ # or interpret a Quantity (now became unit), string or number?
+ if isinstance(s, UnitBase):
+ return s
+
+ elif isinstance(s, (bytes, str)):
+ if len(s.strip()) == 0:
+ # Return the NULL unit
+ return dimensionless_unscaled
+
+ if format is None:
+ format = unit_format.Generic
+
+ f = unit_format.get_format(format)
+ if isinstance(s, bytes):
+ s = s.decode("ascii")
+
+ try:
+ return f.parse(s)
+ except NotImplementedError:
+ raise
+ except Exception as e:
+ if parse_strict == "silent":
+ pass
+ else:
+ # Deliberately not issubclass here. Subclasses
+ # should use their name.
+ if f is not unit_format.Generic:
+ format_clause = f.name + " "
+ else:
+ format_clause = ""
+ msg = (
+ f"'{s}' did not parse as {format_clause}unit: {str(e)} "
+ "If this is meant to be a custom unit, "
+ "define it with 'u.def_unit'. To have it "
+ "recognized inside a file reader or other code, "
+ "enable it with 'u.add_enabled_units'. "
+ "For details, see "
+ "https://docs.astropy.org/en/latest/units/combining_and_defining.html"
+ )
+ if parse_strict == "raise":
+ raise ValueError(msg)
+ elif parse_strict == "warn":
+ warnings.warn(msg, UnitsWarning)
+ else:
+ raise ValueError(
+ "'parse_strict' must be 'warn', 'raise' or 'silent'"
+ )
+ return UnrecognizedUnit(s)
+
+ elif isinstance(s, (int, float, np.floating, np.integer)):
+ return CompositeUnit(s, [], [], _error_check=False)
+
+ elif isinstance(s, tuple):
+ from .structured import StructuredUnit
+
+ return StructuredUnit(s)
+
+ elif s is None:
+ raise TypeError("None is not a valid Unit")
+
+ else:
+ raise TypeError(f"{s} can not be converted to a Unit")
+
+
+class Unit(NamedUnit, metaclass=_UnitMetaClass):
+ """
+ The main unit class.
+
+ There are a number of different ways to construct a Unit, but
+ always returns a `UnitBase` instance. If the arguments refer to
+ an already-existing unit, that existing unit instance is returned,
+ rather than a new one.
+
+ - From a string::
+
+ Unit(s, format=None, parse_strict='silent')
+
+ Construct from a string representing a (possibly compound) unit.
+
+ The optional `format` keyword argument specifies the format the
+ string is in, by default ``"generic"``. For a description of
+ the available formats, see `astropy.units.format`.
+
+ The optional ``parse_strict`` keyword controls what happens when an
+ unrecognized unit string is passed in. It may be one of the following:
+
+ - ``'raise'``: (default) raise a ValueError exception.
+
+ - ``'warn'``: emit a Warning, and return an
+ `UnrecognizedUnit` instance.
+
+ - ``'silent'``: return an `UnrecognizedUnit` instance.
+
+ - From a number::
+
+ Unit(number)
+
+ Creates a dimensionless unit.
+
+ - From a `UnitBase` instance::
+
+ Unit(unit)
+
+ Returns the given unit unchanged.
+
+ - From no arguments::
+
+ Unit()
+
+ Returns the dimensionless unit.
+
+ - The last form, which creates a new `Unit` is described in detail
+ below.
+
+ See also: https://docs.astropy.org/en/stable/units/
+
+ Parameters
+ ----------
+ st : str or list of str
+ The name of the unit. If a list, the first element is the
+ canonical (short) name, and the rest of the elements are
+ aliases.
+
+ represents : UnitBase instance
+ The unit that this named unit represents.
+
+ doc : str, optional
+ A docstring describing the unit.
+
+ format : dict, optional
+ A mapping to format-specific representations of this unit.
+ For example, for the ``Ohm`` unit, it might be nice to have it
+ displayed as ``\\Omega`` by the ``latex`` formatter. In that
+ case, `format` argument should be set to::
+
+ {'latex': r'\\Omega'}
+
+ namespace : dict, optional
+ When provided, inject the unit (and all of its aliases) into
+ the given namespace.
+
+ Raises
+ ------
+ ValueError
+ If any of the given unit names are already in the registry.
+
+ ValueError
+ If any of the given unit names are not valid Python tokens.
+ """
+
+ def __init__(self, st, represents=None, doc=None, format=None, namespace=None):
+ represents = Unit(represents)
+ self._represents = represents
+
+ NamedUnit.__init__(self, st, namespace=namespace, doc=doc, format=format)
+
+ @property
+ def represents(self):
+ """The unit that this named unit represents."""
+ return self._represents
+
+ def decompose(self, bases=set()):
+ return self._represents.decompose(bases=bases)
+
+ def is_unity(self):
+ return self._represents.is_unity()
+
+ def __hash__(self):
+ if self._hash is None:
+ self._hash = hash((self.name, self._represents))
+ return self._hash
+
+ @classmethod
+ def _from_physical_type_id(cls, physical_type_id):
+ # get string bases and powers from the ID tuple
+ bases = [cls(base) for base, _ in physical_type_id]
+ powers = [power for _, power in physical_type_id]
+
+ if len(physical_type_id) == 1 and powers[0] == 1:
+ unit = bases[0]
+ else:
+ unit = CompositeUnit(1, bases, powers, _error_check=False)
+
+ return unit
+
+
+class PrefixUnit(Unit):
+ """
+ A unit that is simply a SI-prefixed version of another unit.
+
+ For example, ``mm`` is a `PrefixUnit` of ``.001 * m``.
+
+ The constructor is the same as for `Unit`.
+ """
+
+
+class CompositeUnit(UnitBase):
+ """
+ Create a composite unit using expressions of previously defined
+ units.
+
+ Direct use of this class is not recommended. Instead use the
+ factory function `Unit` and arithmetic operators to compose
+ units.
+
+ Parameters
+ ----------
+ scale : number
+ A scaling factor for the unit.
+
+ bases : sequence of `UnitBase`
+ A sequence of units this unit is composed of.
+
+ powers : sequence of numbers
+ A sequence of powers (in parallel with ``bases``) for each
+ of the base units.
+ """
+
+ _decomposed_cache = None
+
+ def __init__(
+ self,
+ scale,
+ bases,
+ powers,
+ decompose=False,
+ decompose_bases=set(),
+ _error_check=True,
+ ):
+ # There are many cases internal to astropy.units where we
+ # already know that all the bases are Unit objects, and the
+ # powers have been validated. In those cases, we can skip the
+ # error checking for performance reasons. When the private
+ # kwarg `_error_check` is False, the error checking is turned
+ # off.
+ if _error_check:
+ for base in bases:
+ if not isinstance(base, UnitBase):
+ raise TypeError("bases must be sequence of UnitBase instances")
+ powers = [validate_power(p) for p in powers]
+
+ if not decompose and len(bases) == 1 and powers[0] >= 0:
+ # Short-cut; with one unit there's nothing to expand and gather,
+ # as that has happened already when creating the unit. But do only
+ # positive powers, since for negative powers we need to re-sort.
+ unit = bases[0]
+ power = powers[0]
+ if power == 1:
+ scale *= unit.scale
+ self._bases = unit.bases
+ self._powers = unit.powers
+ elif power == 0:
+ self._bases = []
+ self._powers = []
+ else:
+ scale *= unit.scale**power
+ self._bases = unit.bases
+ self._powers = [
+ sanitize_power(operator.mul(*resolve_fractions(p, power)))
+ for p in unit.powers
+ ]
+
+ self._scale = sanitize_scale(scale)
+ else:
+ # Regular case: use inputs as preliminary scale, bases, and powers,
+ # then "expand and gather" identical bases, sanitize the scale, &c.
+ self._scale = scale
+ self._bases = bases
+ self._powers = powers
+ self._expand_and_gather(decompose=decompose, bases=decompose_bases)
+
+ def __repr__(self):
+ if len(self._bases):
+ return super().__repr__()
+ else:
+ if self._scale != 1.0:
+ return f"Unit(dimensionless with a scale of {self._scale})"
+ else:
+ return "Unit(dimensionless)"
+
+ @property
+ def scale(self):
+ """
+ Return the scale of the composite unit.
+ """
+ return self._scale
+
+ @property
+ def bases(self):
+ """
+ Return the bases of the composite unit.
+ """
+ return self._bases
+
+ @property
+ def powers(self):
+ """
+ Return the powers of the composite unit.
+ """
+ return self._powers
+
+ def _expand_and_gather(self, decompose=False, bases=set()):
+ def add_unit(unit, power, scale):
+ if bases and unit not in bases:
+ for base in bases:
+ try:
+ scale *= unit._to(base) ** power
+ except UnitsError:
+ pass
+ else:
+ unit = base
+ break
+
+ if unit in new_parts:
+ a, b = resolve_fractions(new_parts[unit], power)
+ new_parts[unit] = a + b
+ else:
+ new_parts[unit] = power
+ return scale
+
+ new_parts = {}
+ scale = self._scale
+
+ for b, p in zip(self._bases, self._powers):
+ if decompose and b not in bases:
+ b = b.decompose(bases=bases)
+
+ if isinstance(b, CompositeUnit):
+ scale *= b._scale**p
+ for b_sub, p_sub in zip(b._bases, b._powers):
+ a, b = resolve_fractions(p_sub, p)
+ scale = add_unit(b_sub, a * b, scale)
+ else:
+ scale = add_unit(b, p, scale)
+
+ new_parts = [x for x in new_parts.items() if x[1] != 0]
+ new_parts.sort(key=lambda x: (-x[1], getattr(x[0], "name", "")))
+
+ self._bases = [x[0] for x in new_parts]
+ self._powers = [sanitize_power(x[1]) for x in new_parts]
+ self._scale = sanitize_scale(scale)
+
+ def __copy__(self):
+ """
+ For compatibility with python copy module.
+ """
+ return CompositeUnit(self._scale, self._bases[:], self._powers[:])
+
+ def decompose(self, bases=set()):
+ if len(bases) == 0 and self._decomposed_cache is not None:
+ return self._decomposed_cache
+
+ for base in self.bases:
+ if not isinstance(base, IrreducibleUnit) or (
+ len(bases) and base not in bases
+ ):
+ break
+ else:
+ if len(bases) == 0:
+ self._decomposed_cache = self
+ return self
+
+ x = CompositeUnit(
+ self.scale, self.bases, self.powers, decompose=True, decompose_bases=bases
+ )
+ if len(bases) == 0:
+ self._decomposed_cache = x
+ return x
+
+ def is_unity(self):
+ unit = self.decompose()
+ return len(unit.bases) == 0 and unit.scale == 1.0
+
+
+si_prefixes = [
+ (["Q"], ["quetta"], 1e30),
+ (["R"], ["ronna"], 1e27),
+ (["Y"], ["yotta"], 1e24),
+ (["Z"], ["zetta"], 1e21),
+ (["E"], ["exa"], 1e18),
+ (["P"], ["peta"], 1e15),
+ (["T"], ["tera"], 1e12),
+ (["G"], ["giga"], 1e9),
+ (["M"], ["mega"], 1e6),
+ (["k"], ["kilo"], 1e3),
+ (["h"], ["hecto"], 1e2),
+ (["da"], ["deka", "deca"], 1e1),
+ (["d"], ["deci"], 1e-1),
+ (["c"], ["centi"], 1e-2),
+ (["m"], ["milli"], 1e-3),
+ (["u"], ["micro"], 1e-6),
+ (["n"], ["nano"], 1e-9),
+ (["p"], ["pico"], 1e-12),
+ (["f"], ["femto"], 1e-15),
+ (["a"], ["atto"], 1e-18),
+ (["z"], ["zepto"], 1e-21),
+ (["y"], ["yocto"], 1e-24),
+ (["r"], ["ronto"], 1e-27),
+ (["q"], ["quecto"], 1e-30),
+]
+
+
+binary_prefixes = [
+ (["Ki"], ["kibi"], 2**10),
+ (["Mi"], ["mebi"], 2**20),
+ (["Gi"], ["gibi"], 2**30),
+ (["Ti"], ["tebi"], 2**40),
+ (["Pi"], ["pebi"], 2**50),
+ (["Ei"], ["exbi"], 2**60),
+]
+
+
+def _add_prefixes(u, excludes=[], namespace=None, prefixes=False):
+ """
+ Set up all of the standard metric prefixes for a unit. This
+ function should not be used directly, but instead use the
+ `prefixes` kwarg on `def_unit`.
+
+ Parameters
+ ----------
+ excludes : list of str, optional
+ Any prefixes to exclude from creation to avoid namespace
+ collisions.
+
+ namespace : dict, optional
+ When provided, inject the unit (and all of its aliases) into
+ the given namespace dictionary.
+
+ prefixes : list, optional
+ When provided, it is a list of prefix definitions of the form:
+
+ (short_names, long_tables, factor)
+ """
+ if prefixes is True:
+ prefixes = si_prefixes
+ elif prefixes is False:
+ prefixes = []
+
+ for short, full, factor in prefixes:
+ names = []
+ format = {}
+ for prefix in short:
+ if prefix in excludes:
+ continue
+
+ for alias in u.short_names:
+ names.append(prefix + alias)
+
+ # This is a hack to use Greek mu as a prefix
+ # for some formatters.
+ if prefix == "u":
+ format["latex"] = r"\mu " + u.get_format_name("latex")
+ format["unicode"] = "\N{MICRO SIGN}" + u.get_format_name("unicode")
+
+ for key, val in u._format.items():
+ format.setdefault(key, prefix + val)
+
+ for prefix in full:
+ if prefix in excludes:
+ continue
+
+ for alias in u.long_names:
+ names.append(prefix + alias)
+
+ if len(names):
+ PrefixUnit(
+ names,
+ CompositeUnit(factor, [u], [1], _error_check=False),
+ namespace=namespace,
+ format=format,
+ )
+
+
+def def_unit(
+ s,
+ represents=None,
+ doc=None,
+ format=None,
+ prefixes=False,
+ exclude_prefixes=[],
+ namespace=None,
+):
+ """
+ Factory function for defining new units.
+
+ Parameters
+ ----------
+ s : str or list of str
+ The name of the unit. If a list, the first element is the
+ canonical (short) name, and the rest of the elements are
+ aliases.
+
+ represents : UnitBase instance, optional
+ The unit that this named unit represents. If not provided,
+ a new `IrreducibleUnit` is created.
+
+ doc : str, optional
+ A docstring describing the unit.
+
+ format : dict, optional
+ A mapping to format-specific representations of this unit.
+ For example, for the ``Ohm`` unit, it might be nice to
+ have it displayed as ``\\Omega`` by the ``latex``
+ formatter. In that case, `format` argument should be set
+ to::
+
+ {'latex': r'\\Omega'}
+
+ prefixes : bool or list, optional
+ When `True`, generate all of the SI prefixed versions of the
+ unit as well. For example, for a given unit ``m``, will
+ generate ``mm``, ``cm``, ``km``, etc. When a list, it is a list of
+ prefix definitions of the form:
+
+ (short_names, long_tables, factor)
+
+ Default is `False`. This function always returns the base
+ unit object, even if multiple scaled versions of the unit were
+ created.
+
+ exclude_prefixes : list of str, optional
+ If any of the SI prefixes need to be excluded, they may be
+ listed here. For example, ``Pa`` can be interpreted either as
+ "petaannum" or "Pascal". Therefore, when defining the
+ prefixes for ``a``, ``exclude_prefixes`` should be set to
+ ``["P"]``.
+
+ namespace : dict, optional
+ When provided, inject the unit (and all of its aliases and
+ prefixes), into the given namespace dictionary.
+
+ Returns
+ -------
+ unit : `~astropy.units.UnitBase`
+ The newly-defined unit, or a matching unit that was already
+ defined.
+ """
+ if represents is not None:
+ result = Unit(s, represents, namespace=namespace, doc=doc, format=format)
+ else:
+ result = IrreducibleUnit(s, namespace=namespace, doc=doc, format=format)
+
+ if prefixes:
+ _add_prefixes(
+ result, excludes=exclude_prefixes, namespace=namespace, prefixes=prefixes
+ )
+ return result
+
+
+def _condition_arg(value):
+ """
+ Validate value is acceptable for conversion purposes.
+
+ Will convert into an array if not a scalar, and can be converted
+ into an array
+
+ Parameters
+ ----------
+ value : int or float value, or sequence of such values
+
+ Returns
+ -------
+ Scalar value or numpy array
+
+ Raises
+ ------
+ ValueError
+ If value is not as expected
+ """
+ if isinstance(value, (np.ndarray, float, int, complex, np.void)):
+ return value
+
+ avalue = np.array(value)
+ if avalue.dtype.kind not in ["i", "f", "c"]:
+ raise ValueError(
+ "Value not scalar compatible or convertible to "
+ "an int, float, or complex array"
+ )
+ return avalue
+
+
+def unit_scale_converter(val):
+ """Function that just multiplies the value by unity.
+
+ This is a separate function so it can be recognized and
+ discarded in unit conversion.
+ """
+ return 1.0 * _condition_arg(val)
+
+
+dimensionless_unscaled = CompositeUnit(1, [], [], _error_check=False)
+# Abbreviation of the above, see #1980
+one = dimensionless_unscaled
+
+# Maintain error in old location for backward compatibility
+# TODO: Is this still needed? Should there be a deprecation warning?
+unit_format.fits.UnitScaleError = UnitScaleError
+
+import numpy as np
+from astropy.table import QTable
+from scipy.stats import norm
+import astropy.units as u
+
+from ..binning import calculate_bin_indices
+
+
+ONE_SIGMA_QUANTILE = norm.cdf(1) - norm.cdf(-1)
+
+
+
+[docs]
+def angular_resolution(
+ events, energy_bins,
+ energy_type="true",
+ quantile=ONE_SIGMA_QUANTILE,
+):
+ """
+ Calculate the angular resolution.
+
+ This implementation corresponds to the 68% containment of the angular
+ distance distribution.
+
+ Parameters
+ ----------
+ events : astropy.table.QTable
+ Astropy Table object containing the reconstructed events information.
+ energy_bins: numpy.ndarray(dtype=float, ndim=1)
+ Bin edges in energy.
+ energy_type: str
+ Either "true" or "reco" energy.
+ Default is "true".
+ quantile : float
+ Which quantile to use for the angular resolution,
+ by default, the containment of the 1-sigma region
+ of the normal distribution (~68%) is used.
+
+ Returns
+ -------
+ result : astropy.table.QTable
+ QTable containing the 68% containment of the angular
+ distance distribution per each reconstructed energy bin.
+ """
+ # create a table to make use of groupby operations
+ energy_key = f"{energy_type}_energy"
+ table = QTable(events[[energy_key, "theta"]])
+
+ bin_index, valid = calculate_bin_indices(table[energy_key], energy_bins)
+
+ result = QTable()
+ result[f"{energy_key}_low"] = energy_bins[:-1]
+ result[f"{energy_key}_high"] = energy_bins[1:]
+ 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 we get an empty input (no selected events available)
+ # we return the table filled with NaNs
+ if len(events) == 0:
+ return result
+
+ # 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)
+ return result
+
+
+import numpy as np
+from scipy.stats import norm
+from astropy.table import QTable
+import astropy.units as u
+
+from ..binning import calculate_bin_indices, UNDERFLOW_INDEX, OVERFLOW_INDEX
+
+
+NORM_LOWER_SIGMA, NORM_UPPER_SIGMA = norm(0, 1).cdf([-1, 1])
+ONE_SIGMA_COVERAGE = NORM_UPPER_SIGMA - NORM_LOWER_SIGMA
+MEDIAN = 0.5
+
+
+def energy_resolution_absolute_68(rel_error):
+ """Calculate the energy resolution as the central 68% interval.
+
+ Utility function for pyirf.benchmarks.energy_bias_resolution
+
+ Parameters
+ ----------
+ rel_error : numpy.ndarray(dtype=float, ndim=1)
+ Array of float on which the quantile is calculated.
+
+ Returns
+ -------
+ resolution: numpy.ndarray(dtype=float, ndim=1)
+ Array containing the 68% intervals
+ """
+ return np.nanquantile(np.abs(rel_error), ONE_SIGMA_COVERAGE)
+
+
+def inter_quantile_distance(rel_error):
+ """Calculate the energy resolution as the half of the 68% containment.
+
+ Percentile equivalent of the standard deviation.
+ Utility function for pyirf.benchmarks.energy_bias_resolution
+
+ Parameters
+ ----------
+ rel_error : numpy.ndarray(dtype=float, ndim=1)
+ Array of float on which the quantile is calculated.
+
+ Returns
+ -------
+ resolution: numpy.ndarray(dtype=float, ndim=1)
+ Array containing the resolution values.
+ """
+ upper_sigma = np.nanquantile(rel_error, NORM_UPPER_SIGMA)
+ lower_sigma = np.nanquantile(rel_error, NORM_LOWER_SIGMA)
+ resolution = 0.5 * (upper_sigma - lower_sigma)
+ return resolution
+
+
+
+[docs]
+def energy_bias_resolution(
+ events,
+ energy_bins,
+ energy_type="true",
+ bias_function=np.nanmedian,
+ resolution_function=inter_quantile_distance,
+):
+ """
+ Calculate bias and energy resolution.
+
+ Parameters
+ ----------
+ events: astropy.table.QTable
+ Astropy Table object containing the reconstructed events information.
+ energy_bins: numpy.ndarray(dtype=float, ndim=1)
+ Bin edges in energy.
+ energy_type: str
+ Either "true" or "reco" energy.
+ Default is "true".
+ bias_function: callable
+ Function used to calculate the energy bias
+ resolution_function: callable
+ Function used to calculate the energy resolution
+
+ Returns
+ -------
+ result : astropy.table.QTable
+ QTable containing the energy bias and resolution
+ per each bin in true energy.
+ """
+
+ # 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
+
+ energy_key = f"{energy_type}_energy"
+
+ result = QTable()
+ result[f"{energy_key}_low"] = energy_bins[:-1]
+ result[f"{energy_key}_high"] = energy_bins[1:]
+ result[f"{energy_key}_center"] = 0.5 * (energy_bins[:-1] + energy_bins[1:])
+
+ result["n_events"] = 0
+ result["bias"] = np.nan
+ result["resolution"] = np.nan
+
+ if not len(events):
+ # if we get an empty input (no selected events available)
+ # 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)
+
+ # 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["n_events"][bin_idx] = len(group)
+ result["bias"][bin_idx] = bias_function(group["rel_error"])
+ result["resolution"][bin_idx] = resolution_function(group["rel_error"])
+ return result
+
+
+
+[docs]
+def energy_bias_resolution_from_energy_dispersion(
+ energy_dispersion,
+ migration_bins,
+):
+ """
+ Calculate bias and energy resolution.
+
+ Parameters
+ ----------
+ edisp:
+ Energy dispersion matrix of shape
+ (n_energy_bins, n_migra_bins, n_source_offset_bins)
+ migration_bins: numpy.ndarray
+ Bin edges for the relative energy migration (``reco_energy / true_energy``)
+ """
+
+ bin_width = np.diff(migration_bins)
+ cdf = np.cumsum(energy_dispersion * bin_width[np.newaxis, :, np.newaxis], axis=1)
+
+ n_energy_bins, _, n_fov_bins = energy_dispersion.shape
+
+ bias = np.full((n_energy_bins, n_fov_bins), np.nan)
+ resolution = np.full((n_energy_bins, n_fov_bins), np.nan)
+
+ for energy_bin in range(n_energy_bins):
+ for fov_bin in range(n_fov_bins):
+ if np.count_nonzero(cdf[energy_bin, :, fov_bin]) == 0:
+ continue
+
+ 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
+ )
+ bias[energy_bin, fov_bin] = median - 1
+ resolution[energy_bin, fov_bin] = 0.5 * (high - low)
+
+ return bias, resolution
+
+
+"""
+Utility functions for binning
+"""
+
+import numpy as np
+from scipy.interpolate import interp1d
+import astropy.units as u
+from astropy.table import QTable
+
+
+#: Index returned by `calculate_bin_indices` for underflown values
+UNDERFLOW_INDEX = np.iinfo(np.int64).min
+#: Index returned by `calculate_bin_indices` for overflown values
+OVERFLOW_INDEX = np.iinfo(np.int64).max
+
+
+
+
+
+
+
+[docs]
+def join_bin_lo_hi(bin_lo, bin_hi):
+ """
+ Function joins bins into lo and hi part,
+ e.g. [0, 1, 2] and [1, 2, 4] into [0, 1, 2, 4]
+ It works on multidimentional arrays as long as the binning is in the last axis
+
+ Parameters
+ ----------
+ bin_lo: np.array or u.Quantity
+ Lo bin edges array
+ bin_hi: np.array or u.Quantity
+ Hi bin edges array
+
+ Returns
+ -------
+ bins: np.array of u.Quantity
+ The joint bins
+ """
+
+ if np.allclose(bin_lo[...,1:], bin_hi[...,:-1], rtol=1.e-5):
+ last_axis=len(bin_lo.shape)-1
+ bins = np.concatenate((bin_lo, bin_hi[...,-1:]), axis=last_axis)
+ return bins
+ else:
+ raise ValueError('Not matching bin edges')
+
+
+
+
+[docs]
+def split_bin_lo_hi(bins):
+ """
+ Inverted function to join_bin_hi_lo,
+ e.g. it splits [0, 1, 2, 4] into [0, 1, 2] and [1, 2, 4]
+
+ Parameters
+ ----------
+ bins: np.array of u.Quantity
+ The joint bins
+
+ Returns
+ -------
+ bin_lo: np.array or u.Quantity
+ Lo bin edges array
+ bin_hi: np.array or u.Quantity
+ Hi bin edges array
+ """
+ bin_lo=bins[...,:-1]
+ bin_hi=bins[...,1:]
+ return bin_lo, bin_hi
+
+
+
+[docs]
+def add_overflow_bins(bins, positive=True):
+ """
+ Add under and overflow bins to a bin array.
+
+ Parameters
+ ----------
+ bins: np.array or u.Quantity
+ Bin edges array
+ positive: bool
+ If True, the underflow array will start at 0, if not at ``-np.inf``
+ """
+ lower = 0 if positive else -np.inf
+ upper = np.inf
+
+ if hasattr(bins, "unit"):
+ lower *= bins.unit
+ upper *= bins.unit
+
+ if bins[0] > lower:
+ bins = np.append(lower, bins)
+
+ if bins[-1] < upper:
+ bins = np.append(bins, upper)
+
+ return bins
+
+
+
+
+[docs]
+@u.quantity_input(e_min=u.TeV, e_max=u.TeV)
+def create_bins_per_decade(e_min, e_max, bins_per_decade=5):
+ """
+ Create a bin array with bins equally spaced in logarithmic energy
+ with ``bins_per_decade`` bins per decade.
+
+ Parameters
+ ----------
+ e_min: u.Quantity[energy]
+ Minimum energy, inclusive
+ e_max: u.Quantity[energy]
+ Maximum energy, non-inclusive
+ If the endpoint exactly matches the ``n_bins_per_decade`` requirement,
+ it will be included.
+ n_bins_per_decade: int
+ number of bins per decade
+
+ Returns
+ -------
+ bins: u.Quantity[energy]
+ The created bin array, will have units of e_min
+
+ """
+ unit = e_min.unit
+ log_lower = np.log10(e_min.to_value(unit))
+ log_upper = np.log10(e_max.to_value(unit))
+
+ step = 1 / bins_per_decade
+ # include endpoint if reasonably close
+ eps = step / 10000
+ bins = 10 ** np.arange(log_lower, log_upper + eps, step)
+ return u.Quantity(bins, e_min.unit, copy=False)
+
+
+
+
+[docs]
+def calculate_bin_indices(data, bins):
+ """
+ Calculate bin indices of inidividula entries of the given data array using
+ the supplied binning. Underflow will be indicated by `UNDERFLOW_INDEX` and
+ overflow by `OVERFLOW_INDEX`.
+
+ If the bins already include underflow / overflow bins, e.g.
+ `bins[0] = -np.inf` and `bins[-1] = np.inf`, using the result of this
+ function will always be a valid index into the resulting histogram.
+
+
+ Parameters
+ ----------
+ data: ``~np.ndarray`` or ``~astropy.units.Quantity``
+ Array with the data
+
+ bins: ``~np.ndarray`` or ``~astropy.units.Quantity``
+ Array or Quantity of bin edges. Must have the same unit as ``data`` if a Quantity.
+
+
+ Returns
+ -------
+ bin_index: np.ndarray[int]
+ Indices of the histogram bin the values in data belong to.
+ Under- and overflown values will have values of `UNDERFLOW_INDEX`
+ and `OVERFLOW_INDEX` respectively.
+
+ valid: np.ndarray[bool]
+ Boolean mask indicating if a given value belongs into one of the defined bins.
+ False indicates that an entry fell into the over- or underflow bins.
+ """
+
+ if hasattr(data, "unit"):
+ if not hasattr(bins, "unit"):
+ raise TypeError(f"If ``data`` is a Quantity, so must ``bins``, got {bins}")
+ unit = data.unit
+ data = data.to_value(unit)
+ bins = bins.to_value(unit)
+
+ n_bins = len(bins) - 1
+ idx = np.digitize(data, bins) - 1
+
+ underflow = (idx < 0)
+ overflow = (idx >= n_bins)
+ idx[underflow] = UNDERFLOW_INDEX
+ idx[overflow] = OVERFLOW_INDEX
+ valid = ~underflow & ~overflow
+ return idx, valid
+
+
+
+
+[docs]
+def create_histogram_table(events, bins, key="reco_energy"):
+ """
+ Histogram a variable from events data into an astropy table.
+
+ Parameters
+ ----------
+ events : ``astropy.QTable``
+ Astropy Table object containing the reconstructed events information.
+ bins: ``~np.ndarray`` or ``~astropy.units.Quantity``
+ Array or Quantity of bin edges.
+ It must have the same units as ``data`` if a Quantity.
+ key : ``string``
+ Variable to histogram from the events table.
+
+ Returns
+ -------
+ hist: ``astropy.QTable``
+ Astropy table containg the histogram.
+ """
+ hist = QTable()
+ hist[key + "_low"] = bins[:-1]
+ hist[key + "_high"] = bins[1:]
+ hist[key + "_center"] = 0.5 * (hist[key + "_low"] + hist[key + "_high"])
+ hist["n"], _ = np.histogram(events[key], bins)
+
+ # also calculate weighted number of events
+ if "weight" in events.colnames:
+ hist["n_weighted"], _ = np.histogram(
+ events[key], bins, weights=events["weight"]
+ )
+ else:
+ hist["n_weighted"] = hist["n"]
+
+ # create counts per particle type, only works if there is at least 1 event
+ if 'particle_type' in events.colnames and len(events) > 0:
+ by_particle = events.group_by('particle_type')
+
+ for group_key, group in zip(by_particle.groups.keys, by_particle.groups):
+ particle = group_key['particle_type']
+
+ hist["n_" + particle], _ = np.histogram(group[key], bins)
+
+ # also calculate weighted number of events
+ col = "n_" + particle
+ if "weight" in events.colnames:
+ hist[col + "_weighted"], _ = np.histogram(
+ group[key], bins, weights=group["weight"]
+ )
+ else:
+ hist[col + "_weighted"] = hist[col]
+
+ return hist
+
+
+
+
+[docs]
+def resample_histogram1d(data, old_edges, new_edges, axis=0):
+ """
+ Rebinning of a histogram by interpolation along a given axis.
+
+ Parameters
+ ----------
+ data : ``numpy.ndarray`` or ``astropy.units.Quantity``
+ Histogram.
+ old_edges : ``numpy.array`` or ``astropy.units.Quantity``
+ Binning used to calculate ``data``.
+ ``len(old_edges) - 1`` needs to equal the length of ``data``
+ along interpolation axis (``axis``).
+ If quantity, needs to be compatible to ``new_edges``.
+ new_edges : ``numpy.array`` or ``astropy.units.Quantity``
+ Binning of new histogram.
+ If quantity, needs to be compatible to ``old_edges``.
+ axis : int
+ Interpolation axis.
+
+ Returns
+ -------
+ ``numpy.ndarray`` or ``astropy.units.Quantity``
+ Interpolated histogram with dimension according to ``data`` and ``new_edges``.
+ If ``data`` is a quantity, this has the same unit.
+ """
+
+ data_unit = None
+ if isinstance(data, u.Quantity):
+ data_unit = data.unit
+ data = data.to_value(data_unit)
+
+ over_underflow_bin_width = old_edges[-2] - old_edges[1]
+ old_edges = u.Quantity(
+ np.nan_to_num(
+ old_edges,
+ posinf=old_edges[-2] + over_underflow_bin_width,
+ neginf=old_edges[1] - over_underflow_bin_width,
+ )
+ )
+
+ new_edges = u.Quantity(np.nan_to_num(new_edges))
+
+ old_edges = old_edges.to(new_edges.unit)
+
+ cumsum = np.insert(data.cumsum(axis=axis), 0, 0, axis=axis)
+
+ norm = data.sum(axis=axis, keepdims=True)
+ norm[norm == 0] = 1
+ cumsum /= norm
+
+ f_integral = interp1d(
+ old_edges, cumsum, bounds_error=False,
+ fill_value=(0, 1), kind="quadratic",
+ axis=axis,
+ )
+
+ values = np.diff(f_integral(new_edges), axis=axis) * norm
+ if data_unit:
+ values = u.Quantity(values, unit=data_unit)
+
+ return values
+
+
+import numpy as np
+from astropy.table import QTable
+import astropy.units as u
+from tqdm import tqdm
+import operator
+
+from .cuts import evaluate_binned_cut, calculate_percentile_cut
+from .sensitivity import calculate_sensitivity, estimate_background
+from .binning import create_histogram_table, bin_center
+
+
+__all__ = [
+ "optimize_gh_cut",
+]
+
+
+
+[docs]
+def optimize_gh_cut(
+ signal,
+ background,
+ reco_energy_bins,
+ gh_cut_efficiencies,
+ theta_cuts,
+ op=operator.ge,
+ fov_offset_min=0 * u.deg,
+ fov_offset_max=1 * u.deg,
+ alpha=1.0,
+ progress=True,
+ **kwargs
+):
+ """
+ Optimize the gh-score cut in every energy bin of reconstructed energy
+ for best sensitivity.
+
+ This procedure is EventDisplay-like, since it only applies a
+ pre-computed theta cut and then optimizes only the gamma/hadron separation
+ cut.
+
+ Parameters
+ ----------
+ signal: astropy.table.QTable
+ event list of simulated signal events.
+ Required columns are `theta`, `reco_energy`, 'weight', `gh_score`
+ No directional (theta) or gamma/hadron cut should already be applied.
+ background: astropy.table.QTable
+ event list of simulated background events.
+ Required columns are `reco_source_fov_offset`, `reco_energy`,
+ 'weight', `gh_score`.
+ No directional (theta) or gamma/hadron cut should already be applied.
+ reco_energy_bins: astropy.units.Quantity[energy]
+ Bins in reconstructed energy to use for sensitivity computation
+ gh_cut_efficiencies: np.ndarray[float, ndim=1]
+ The cut efficiencies to scan for best sensitivity.
+ theta_cuts: astropy.table.QTable
+ cut definition of the energy dependent theta cut,
+ e.g. as created by ``calculate_percentile_cut``
+ op: comparison function with signature f(a, b) -> bool
+ The comparison function to use for the gamma hadron score.
+ Returning true means an event passes the cut, so is not discarded.
+ E.g. for gammaness-like score, use `operator.ge` (>=) and for a
+ hadroness-like score use `operator.le` (<=).
+ fov_offset_min: astropy.units.Quantity[angle]
+ Minimum distance from the fov center for background events to be taken into account
+ fov_offset_max: astropy.units.Quantity[angle]
+ Maximum distance from the fov center for background events to be taken into account
+ alpha: float
+ Size ratio of off region / on region. Will be used to
+ scale the background rate.
+ progress: bool
+ If True, show a progress bar during cut optimization
+ **kwargs are passed to ``calculate_sensitivity``
+ """
+
+ # we apply each cut for all reco_energy_bins globally, calculate the
+ # sensitivity and then lookup the best sensitivity for each
+ # bin independently
+
+ signal_selected_theta = evaluate_binned_cut(
+ signal['theta'], signal['reco_energy'], theta_cuts,
+ op=operator.le,
+ )
+
+ sensitivities = []
+ gh_cuts = []
+ for efficiency in tqdm(gh_cut_efficiencies, disable=not progress):
+
+ # calculate necessary percentile needed for
+ # ``calculate_percentile_cut`` with the correct efficiency.
+ # Depends on the operator, since we need to invert the
+ # efficiency if we compare using >=, since percentile is
+ # defines as <=.
+ if op(-1, 1): # if operator behaves like "<=", "<" etc:
+ percentile = 100 * efficiency
+ fill_value = signal['gh_score'].min()
+ else: # operator behaves like ">=", ">"
+ percentile = 100 * (1 - efficiency)
+ fill_value = signal['gh_score'].max()
+
+ gh_cut = calculate_percentile_cut(
+ signal['gh_score'], signal['reco_energy'],
+ bins=reco_energy_bins,
+ fill_value=fill_value, percentile=percentile,
+ )
+ gh_cuts.append(gh_cut)
+
+ # apply the current cut
+ signal_selected = evaluate_binned_cut(
+ signal["gh_score"], signal["reco_energy"], gh_cut, op,
+ ) & signal_selected_theta
+
+ background_selected = evaluate_binned_cut(
+ background["gh_score"], background["reco_energy"], gh_cut, op,
+ )
+
+ # create the histograms
+ signal_hist = create_histogram_table(
+ signal[signal_selected], reco_energy_bins, "reco_energy"
+ )
+
+ background_hist = estimate_background(
+ events=background[background_selected],
+ reco_energy_bins=reco_energy_bins,
+ theta_cuts=theta_cuts,
+ alpha=alpha,
+ fov_offset_min=fov_offset_min,
+ fov_offset_max=fov_offset_max,
+ )
+
+ sensitivity = calculate_sensitivity(
+ signal_hist, background_hist, alpha=alpha,
+ **kwargs,
+ )
+ sensitivities.append(sensitivity)
+
+ best_cut_table = QTable()
+ best_cut_table["low"] = reco_energy_bins[0:-1]
+ best_cut_table["center"] = bin_center(reco_energy_bins)
+ best_cut_table["high"] = reco_energy_bins[1:]
+ best_cut_table["cut"] = np.nan
+
+ best_sensitivity = sensitivities[0].copy()
+ for bin_id in range(len(reco_energy_bins) - 1):
+ sensitivities_bin = [s["relative_sensitivity"][bin_id] for s in sensitivities]
+
+ if not np.all(np.isnan(sensitivities_bin)):
+ # nanargmin won't return the index of nan entries
+ best = np.nanargmin(sensitivities_bin)
+ else:
+ # if all are invalid, just use the first one
+ best = 0
+
+ best_sensitivity[bin_id] = sensitivities[best][bin_id]
+ best_cut_table["cut"][bin_id] = gh_cuts[best]["cut"][bin_id]
+
+ return best_sensitivity, best_cut_table
+
+
+import numpy as np
+from astropy.table import Table, QTable
+from scipy.ndimage import gaussian_filter1d
+import astropy.units as u
+
+from .binning import calculate_bin_indices, bin_center
+
+__all__ = [
+ 'calculate_percentile_cut',
+ 'evaluate_binned_cut',
+ 'compare_irf_cuts',
+]
+
+
+
+[docs]
+def calculate_percentile_cut(
+ values, bin_values, bins, fill_value, percentile=68, min_value=None, max_value=None,
+ smoothing=None, min_events=10,
+):
+ """
+ Calculate cuts as the percentile of a given quantity in bins of another
+ quantity.
+
+ Parameters
+ ----------
+ values: ``~numpy.ndarray`` or ``~astropy.units.Quantity``
+ The values for which the cut should be calculated
+ bin_values: ``~numpy.ndarray`` or ``~astropy.units.Quantity``
+ The values used to sort the ``values`` into bins
+ edges: ``~numpy.ndarray`` or ``~astropy.units.Quantity``
+ Bin edges
+ fill_value: float or quantity
+ Value for bins with less than ``min_events``,
+ must have same unit as values
+ percentile: float
+ The percentile to calculate in each bin as a percentage,
+ i.e. 0 <= percentile <= 100.
+ min_value: float or quantity or None
+ If given, cuts smaller than this value are replaced with ``min_value``
+ max_value: float or quantity or None
+ If given, cuts larger than this value are replaced with ``max_value``
+ smoothing: float or None
+ If given, apply a gaussian filter of width ``sigma`` in terms
+ of bins.
+ min_events: int
+ Bins with less events than this number are replaced with ``fill_value``
+ """
+ # create a table to make use of groupby operations
+ # we use a normal table here to avoid astropy/astropy#13840
+ table = Table({"values": values}, copy=False)
+ unit = table["values"].unit
+
+ # make sure units match
+ if unit is not None:
+ fill_value = u.Quantity(fill_value).to(unit)
+
+ if min_value is not None:
+ min_value = u.Quantity(min_value).to_value(unit)
+
+ if max_value is not None:
+ max_value = u.Quantity(max_value).to_value(unit)
+
+ bin_index, valid = calculate_bin_indices(bin_values, bins)
+ by_bin = table[valid].group_by(bin_index[valid])
+
+ cut_table = QTable()
+ cut_table["low"] = bins[:-1]
+ cut_table["high"] = bins[1:]
+ cut_table["center"] = bin_center(bins)
+ cut_table["n_events"] = 0
+ cut_table["cut"] = np.asanyarray(fill_value, values.dtype)
+
+ for bin_idx, group in zip(by_bin.groups.keys, by_bin.groups):
+ # replace bins with too few events with fill_value
+ n_events = len(group)
+ cut_table["n_events"][bin_idx] = n_events
+
+ if n_events < min_events:
+ cut_table["cut"][bin_idx] = fill_value
+ else:
+ value = np.nanpercentile(group["values"], percentile)
+ if min_value is not None or max_value is not None:
+ value = np.clip(value, min_value, max_value)
+
+ cut_table["cut"].value[bin_idx] = value
+
+ if smoothing is not None:
+ cut_table['cut'].value[:] = gaussian_filter1d(
+ cut_table["cut"].value,
+ smoothing,
+ mode='nearest',
+ )
+
+ return cut_table
+
+
+
+
+[docs]
+def evaluate_binned_cut(values, bin_values, cut_table, op):
+ """
+ Evaluate a binned cut as defined in cut_table on given events.
+
+ Events with bin_values outside the bin edges defined in cut table
+ will be set to False.
+
+ Parameters
+ ----------
+ values: ``~numpy.ndarray`` or ``~astropy.units.Quantity``
+ The values on which the cut should be evaluated
+ bin_values: ``~numpy.ndarray`` or ``~astropy.units.Quantity``
+ The values used to sort the ``values`` into bins
+ cut_table: ``~astropy.table.Table``
+ A table describing the binned cuts, e.g. as created by
+ ``~pyirf.cuts.calculate_percentile_cut``.
+ Required columns:
+ - `low`: lower edges of the bins
+ - `high`: upper edges of the bins,
+ - `cut`: cut value
+ op: callable(a, b) -> bool
+ A function taking two arguments, comparing element-wise and
+ returning an array of booleans.
+ Must support vectorized application.
+
+
+ Returns
+ -------
+ result: np.ndarray[bool]
+ A mask for each entry in ``values`` indicating if the event
+ passes the bin specific cut given in cut table.
+ """
+ if not isinstance(cut_table, QTable):
+ raise ValueError('cut_table needs to be an astropy.table.QTable')
+
+ bins = np.append(cut_table["low"], cut_table["high"][-1])
+ bin_index, valid = calculate_bin_indices(bin_values, bins)
+
+ result = np.zeros(len(values), dtype=bool)
+ result[valid] = op(values[valid], cut_table["cut"][bin_index[valid]])
+ return result
+
+
+
+
+[docs]
+def compare_irf_cuts(cuts):
+ """
+ checks if the same cuts have been applied in all of them
+
+ Parameters
+ ----------
+ cuts: list of QTables
+ list of cuts each entry in the list correspond to one set of IRFs
+ Returns
+ -------
+ match: Boolean
+ if the cuts are the same in all the files
+ """
+ for i in range(len(cuts) - 1):
+ if (cuts[i] != cuts[i + 1]).any():
+ return False
+ return True
+
+
+try:
+ import gammapy
+except ImportError:
+ raise ImportError('You need gammapy installed to use this module of pyirf') from None
+
+from gammapy.irf import EffectiveAreaTable2D, PSF3D, EnergyDispersion2D
+from gammapy.maps import MapAxis
+import astropy.units as u
+
+
+
+def _create_offset_axis(fov_offset_bins):
+ return MapAxis.from_edges(fov_offset_bins, name="offset")
+
+def _create_energy_axis_true(true_energy_bins):
+ return MapAxis.from_edges(true_energy_bins, name="energy_true")
+
+
+
+[docs]
+@u.quantity_input(
+ effective_area=u.m ** 2, true_energy_bins=u.TeV, fov_offset_bins=u.deg
+)
+def create_effective_area_table_2d(
+ effective_area,
+ true_energy_bins,
+ fov_offset_bins,
+):
+ '''
+ Create a :py:class:`gammapy.irf.EffectiveAreaTable2D` from pyirf outputs.
+
+ Parameters
+ ----------
+ effective_area: astropy.units.Quantity[area]
+ Effective area array, must have shape (n_energy_bins, n_fov_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+
+ Returns
+ -------
+ gammapy.irf.EffectiveAreaTable2D
+ aeff2d: gammapy.irf.EffectiveAreaTable2D
+ '''
+ offset_axis = _create_offset_axis(fov_offset_bins)
+ energy_axis_true = _create_energy_axis_true(true_energy_bins)
+
+ return EffectiveAreaTable2D(
+ axes = [energy_axis_true,
+ offset_axis],
+ data=effective_area,
+ )
+
+
+
+
+
+[docs]
+@u.quantity_input(
+ psf=u.sr ** -1,
+ true_energy_bins=u.TeV,
+ source_offset_bins=u.deg,
+ fov_offset_bins=u.deg,
+)
+def create_psf_3d(
+ psf,
+ true_energy_bins,
+ source_offset_bins,
+ fov_offset_bins,
+):
+ """
+ Create a :py:class:`gammapy.irf.PSF3D` from pyirf outputs.
+
+ Parameters
+ ----------
+ psf: astropy.units.Quantity[(solid angle)^-1]
+ Point spread function array, must have shape
+ (n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ source_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the source offset.
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+
+ Returns
+ -------
+ psf: gammapy.irf.PSF3D
+ """
+ offset_axis = _create_offset_axis(fov_offset_bins)
+ energy_axis_true = _create_energy_axis_true(true_energy_bins)
+ rad_axis = MapAxis.from_edges(source_offset_bins, name='rad')
+
+ return PSF3D(
+ axes = [energy_axis_true,
+ offset_axis,
+ rad_axis],
+ data = psf
+ )
+
+
+
+
+[docs]
+@u.quantity_input(
+ true_energy_bins=u.TeV, fov_offset_bins=u.deg,
+)
+def create_energy_dispersion_2d(
+ energy_dispersion,
+ true_energy_bins,
+ migration_bins,
+ fov_offset_bins,
+):
+ """
+ Create a :py:class:`gammapy.irf.EnergyDispersion2D` from pyirf outputs.
+
+ Parameters
+ ----------
+ energy_dispersion: numpy.ndarray
+ Energy dispersion array, must have shape
+ (n_energy_bins, n_migra_bins, n_source_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ migration_bins: numpy.ndarray
+ Bin edges for the relative energy migration (``reco_energy / true_energy``)
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+
+ Returns
+ -------
+ edisp: gammapy.irf.EnergyDispersion2D
+ """
+ offset_axis = _create_offset_axis(fov_offset_bins)
+ energy_axis_true = _create_energy_axis_true(true_energy_bins)
+ migra_axis = MapAxis.from_edges(migration_bins, name="migra")
+
+ return EnergyDispersion2D(
+ axes = [energy_axis_true,
+ migra_axis,
+ offset_axis],
+ data = energy_dispersion,
+ )
+
+
+"""Base classes for extrapolators"""
+from abc import ABCMeta, abstractmethod
+
+import numpy as np
+from pyirf.binning import bin_center
+from pyirf.interpolation.base_interpolators import PDFNormalization
+
+__all__ = ["BaseExtrapolator", "ParametrizedExtrapolator", "DiscretePDFExtrapolator"]
+
+
+
+[docs]
+class BaseExtrapolator(metaclass=ABCMeta):
+ """
+ Base class for all extrapolators, only knowing grid-points,
+ providing a common __call__-interface.
+ """
+
+ def __init__(self, grid_points):
+ """BaseExtrapolator
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which templates exist
+
+ """
+ self.grid_points = grid_points
+ if self.grid_points.ndim == 1:
+ self.grid_points = self.grid_points.reshape(*self.grid_points.shape, 1)
+ self.N = self.grid_points.shape[0]
+ self.grid_dim = self.grid_points.shape[1]
+
+
+[docs]
+ @abstractmethod
+ def extrapolate(self, target_point):
+ """Overridable function for the actual extrapolation code"""
+
+
+
+[docs]
+ def __call__(self, target_point):
+ """Providing a common __call__ interface
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for extrapolation
+
+ Returns
+ -------
+ Extrapolated result.
+ """
+ return self.extrapolate(target_point=target_point)
+
+
+
+
+
+[docs]
+class ParametrizedExtrapolator(BaseExtrapolator):
+ """
+ Base class for all extrapolators used with IRF components that can be
+ treated independently, e.g. parametrized ones like 3Gauss
+ but also AEff. Derived from pyirf.interpolation.BaseExtrapolator
+ """
+
+ def __init__(self, grid_points, params):
+ """ParametrizedExtrapolator
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist
+ params: np.ndarray, shape=(n_points, ..., n_params)
+ Corresponding parameter values at each point in grid_points.
+ First dimesion has to correspond to number of grid_points
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseExtrapolators.__init__
+ """
+ super().__init__(grid_points)
+
+ self.params = params
+
+ if self.params.ndim == 1:
+ self.params = self.params[..., np.newaxis]
+
+
+
+
+[docs]
+class DiscretePDFExtrapolator(BaseExtrapolator):
+ """
+ Base class for all extrapolators used with binned IRF components like EDisp.
+ Derived from pyirf.interpolation.BaseExtrapolator
+ """
+
+ def __init__(
+ self, grid_points, bin_edges, binned_pdf, normalization=PDFNormalization.AREA
+ ):
+ """DiscretePDFExtrapolator
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Edges of the data binning
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points, last dimension has to correspond to number of bins for
+ the quantity that should be extrapolated (e.g. the Migra axis for EDisp)
+ normalization: PDFNormalization
+ How the PDF is normalized
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseExtrapolators.__init__
+ """
+ super().__init__(grid_points)
+
+ self.normalization = normalization
+ self.bin_edges = bin_edges
+ self.bin_mids = bin_center(self.bin_edges)
+ self.binned_pdf = binned_pdf
+
+
+"""Base classes for interpolators"""
+from abc import ABCMeta, abstractmethod
+import enum
+
+import numpy as np
+
+from ..binning import bin_center
+
+__all__ = [
+ "BaseInterpolator",
+ "ParametrizedInterpolator",
+ "DiscretePDFInterpolator",
+ "PDFNormalization",
+]
+
+
+
+[docs]
+class PDFNormalization(enum.Enum):
+ """How a discrete PDF is normalized"""
+
+ #: PDF is normalized to a "normal" area integral of 1
+ AREA = enum.auto()
+ #: PDF is normalized to 1 over the solid angle integral where the bin
+ #: edges represent the opening angles of cones in radian.
+ CONE_SOLID_ANGLE = enum.auto()
+
+
+
+
+[docs]
+class BaseInterpolator(metaclass=ABCMeta):
+ """
+ Base class for all interpolators, only knowing grid-points,
+ providing a common __call__-interface.
+ """
+
+ def __init__(self, grid_points):
+ """BaseInterpolator
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which interpolation templates exist
+
+ """
+ self.grid_points = grid_points
+ if self.grid_points.ndim == 1:
+ self.grid_points = self.grid_points.reshape(*self.grid_points.shape, 1)
+ self.n_points = self.grid_points.shape[0]
+ self.grid_dim = self.grid_points.shape[1]
+
+
+[docs]
+ @abstractmethod
+ def interpolate(self, target_point):
+ """Overridable function for the actual interpolation code"""
+
+
+
+[docs]
+ def __call__(self, target_point):
+ """Providing a common __call__ interface
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+ When target_point is outside of the grids convex hull but extrapolator is None
+
+ Returns
+ -------
+ Interpolated result.
+ """
+ return self.interpolate(target_point=target_point)
+
+
+
+
+
+[docs]
+class ParametrizedInterpolator(BaseInterpolator):
+ """
+ Base class for all interpolators used with IRF components that can be
+ independently interpolated, e.g. parametrized ones like 3Gauss
+ but also AEff. Derived from pyirf.interpolation.BaseInterpolator
+ """
+
+ def __init__(self, grid_points, params):
+ """ParametrizedInterpolator
+
+ Parameters
+ ----------
+ grid_points, np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ params: np.ndarray, shape=(n_points, ..., n_params)
+ Corresponding parameter values at each point in grid_points.
+ First dimesion has to correspond to number of grid_points
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseInterpolators.__init__
+ """
+ super().__init__(grid_points)
+
+ self.params = params
+
+ if self.params.ndim == 1:
+ self.params = self.params[..., np.newaxis]
+
+
+
+
+[docs]
+class DiscretePDFInterpolator(BaseInterpolator):
+ """
+ Base class for all interpolators used with binned IRF components like EDisp.
+ Derived from pyirf.interpolation.BaseInterpolator
+ """
+
+ def __init__(
+ self, grid_points, bin_edges, binned_pdf, normalization=PDFNormalization.AREA
+ ):
+ """DiscretePDFInterpolator
+
+ Parameters
+ ----------
+ grid_points : np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ bin_edges : np.ndarray, shape=(n_bins+1)
+ Edges of the data binning
+ binned_pdf : np.ndarray, shape=(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points, last dimension has to correspond to number of bins for
+ the quantity that should be interpolated (e.g. the Migra axis for EDisp)
+ normalization : PDFNormalization
+ How the PDF is normalized
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseInterpolators.__init__
+ """
+ super().__init__(grid_points)
+
+ self.bin_edges = bin_edges
+ self.bin_mids = bin_center(self.bin_edges)
+ self.binned_pdf = binned_pdf
+ self.normalization = normalization
+
+
+"""Classes to estimate (interpolate/extrapolate) actual IRF HDUs"""
+import warnings
+
+import astropy.units as u
+import numpy as np
+from scipy.spatial import Delaunay
+
+from .base_extrapolators import DiscretePDFExtrapolator, ParametrizedExtrapolator
+from .base_interpolators import (
+ DiscretePDFInterpolator,
+ ParametrizedInterpolator,
+ PDFNormalization,
+)
+from .griddata_interpolator import GridDataInterpolator
+from .nearest_neighbor_searcher import BaseNearestNeighborSearcher
+from .quantile_interpolator import QuantileInterpolator
+from .utils import find_nearest_simplex
+
+__all__ = [
+ "BaseComponentEstimator",
+ "DiscretePDFComponentEstimator",
+ "ParametrizedComponentEstimator",
+ "EffectiveAreaEstimator",
+ "RadMaxEstimator",
+ "EnergyDispersionEstimator",
+ "PSFTableEstimator",
+]
+
+
+
+[docs]
+class BaseComponentEstimator:
+ """
+ Base class for all Estimators working on specific IRF components.
+
+ While usable, it is encouraged to use the actual class for the respective IRF
+ component as it ensures further checks and if necessary e.g. unit handling.
+ """
+
+ def __init__(self, grid_points):
+ """
+ Base __init__, doing sanity checks on the grid, building a
+ triangulated version of the grid and instantiating inter- and extrapolator.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+
+ Raises
+ ------
+ TypeError:
+ When grid_points is not a np.ndarray of float compatible values
+ TypeError:
+ When grid_point has dtype object
+ ValueError:
+ When there are too few points in grid_points to span a volume
+ in the grid dimension.
+ """
+ if not isinstance(grid_points, np.ndarray):
+ raise TypeError("Input grid_points is not a numpy array.")
+ if grid_points.dtype == "O":
+ raise TypeError("Input grid_points array cannot be of dtype object.")
+ if not np.can_cast(grid_points.dtype, np.float128):
+ raise TypeError("Input grid_points dtype incompatible with float.")
+
+ self.grid_points = grid_points
+ if self.grid_points.ndim == 1:
+ self.grid_points = self.grid_points.reshape(*self.grid_points.shape, 1)
+ self.n_points = self.grid_points.shape[0]
+ self.grid_dim = self.grid_points.shape[1]
+
+ # Check, if number of grid point theoretically suffices to span a volume
+ # in the dimension indicated by grid
+ if self.n_points < self.grid_dim + 1:
+ raise ValueError(
+ f"To few points for grid dimension, grid-dim is {self.grid_dim},"
+ f" while there are only {self.n_points}. At least {self.grid_dim+1}"
+ f" points needed to span a volume in {self.grid_dim} dimensions."
+ )
+
+ # Build triangulation to check if target is inside of the grid for
+ # more then 1 dimension
+ if self.grid_dim > 1:
+ self.triangulation = Delaunay(self.grid_points)
+
+ def _target_in_grid(self, target_point):
+ """Check whether target_point lies within grids convex hull, uses
+ simple comparison for 1D and Delaunay triangulation for >1D."""
+ if self.grid_dim == 1:
+ return (target_point >= self.grid_points.min()) and (
+ target_point <= self.grid_points.max()
+ )
+ else:
+ # Delaunay.find_simplex() returns -1 for points outside the grids convex hull
+ simplex_ind = self.triangulation.find_simplex(target_point)
+ return simplex_ind >= 0
+
+
+[docs]
+ def __call__(self, target_point):
+ """Inter-/ Extrapolation as needed and sanity checking of
+ the target point
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+
+ Raises
+ ------
+ TypeError:
+ When target_point is not an np.ndarray
+ ValueError:
+ When more then one target_point is given
+ ValueError:
+ When target_point and grid_points have miss-matching dimensions
+ ValueError:
+ When target_point is outside of the grids convex hull but extrapolator is None
+ Warning:
+ When target_points need extrapolation
+
+ Returns
+ -------
+ Interpolated or, if necessary extrapolated, result.
+ """
+ if not isinstance(target_point, np.ndarray):
+ raise TypeError("Target point is not a numpy array.")
+
+ if target_point.ndim == 1:
+ target_point = target_point.reshape(1, *target_point.shape)
+ elif target_point.shape[0] != 1:
+ raise ValueError("Only one target_point per call supported.")
+
+ if target_point.shape[1] != self.grid_dim:
+ raise ValueError(
+ "Mismatch between target-point and grid dimension."
+ f" Grid has dimension {self.grid_dim}, target has dimension"
+ f" {target_point.shape[1]}."
+ )
+
+ if self._target_in_grid(target_point):
+ return self.interpolator(target_point)
+ elif self.extrapolator is not None:
+ warnings.warn(f"Target point {target_point} has to be extrapolated.")
+ return self.extrapolator(target_point)
+ else:
+ raise ValueError(
+ "Target point outside grids convex hull and no extrapolator given."
+ )
+
+
+
+
+
+[docs]
+class DiscretePDFComponentEstimator(BaseComponentEstimator):
+ """
+ Base class for all Estimators working on IRF components that represent discretized PDFs.
+
+ While usable, it is encouraged to use the actual class for the respective IRF
+ component as it ensures further checks and if necessary e.g. unit handling.
+ """
+
+ def __init__(
+ self,
+ grid_points,
+ bin_edges,
+ binned_pdf,
+ interpolator_cls=QuantileInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ ):
+ """
+ __init__ for all discrete PDF components, calls BaseComponentEstimator's
+ __init__ and instantiates inter- and extrapolator objects.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which interpolation templates exist
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Common set of bin-edges for all discretized PDFs.
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Discretized PDFs for all grid points and arbitrary further dimensions
+ (in IRF term e.g. field-of-view offset bins). Actual interpolation dimension,
+ meaning the dimensions that contain actual histograms, have to be along
+ the last axis.
+ interpolator_cls:
+ pyirf interpolator class, defaults to QuantileInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+
+ Raises
+ ------
+ TypeError:
+ When bin_edges is not a np.ndarray.
+ TypeError:
+ When binned_pdf is not a np.ndarray.
+ TypeError:
+ When interpolator_cls is not a DiscretePDFInterpolator subclass.
+ TypeError:
+ When extrapolator_cls is not a DiscretePDFExtrapolator subclass.
+ ValueError:
+ When number of bins in bin_edges and contents in binned_pdf is
+ not matching.
+ ValueError:
+ When number of histograms in binned_pdf and points in grid_points
+ is not matching.
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseComponentEstimator.__init__
+ """
+
+ super().__init__(
+ grid_points,
+ )
+
+ if not isinstance(binned_pdf, np.ndarray):
+ raise TypeError("Input binned_pdf is not a numpy array.")
+ elif self.n_points != binned_pdf.shape[0]:
+ raise ValueError(
+ f"Shape mismatch, number of grid_points ({self.n_points}) and "
+ f"number of histograms in binned_pdf ({binned_pdf.shape[0]}) "
+ "not matching."
+ )
+ elif not isinstance(bin_edges, np.ndarray):
+ raise TypeError("Input bin_edges is not a numpy array.")
+ elif binned_pdf.shape[-1] != (bin_edges.shape[0] - 1):
+ raise ValueError(
+ f"Shape mismatch, bin_edges ({bin_edges.shape[0] - 1} bins) "
+ f"and binned_pdf ({binned_pdf.shape[-1]} bins) not matching."
+ )
+
+ # Make sure that 1D input is sorted in increasing order
+ if self.grid_dim == 1:
+ sorting_inds = np.argsort(self.grid_points.squeeze())
+
+ self.grid_points = self.grid_points[sorting_inds]
+ binned_pdf = binned_pdf[sorting_inds]
+
+ if interpolator_kwargs is None:
+ interpolator_kwargs = {}
+
+ if extrapolator_kwargs is None:
+ extrapolator_kwargs = {}
+
+ if not issubclass(interpolator_cls, DiscretePDFInterpolator):
+ raise TypeError(
+ f"interpolator_cls must be a DiscretePDFInterpolator subclass, got {interpolator_cls}"
+ )
+
+ self.interpolator = interpolator_cls(
+ self.grid_points, bin_edges, binned_pdf, **interpolator_kwargs
+ )
+
+ if extrapolator_cls is None:
+ self.extrapolator = None
+ elif not issubclass(extrapolator_cls, DiscretePDFExtrapolator):
+ raise TypeError(
+ f"extrapolator_cls must be a DiscretePDFExtrapolator subclass, got {extrapolator_cls}"
+ )
+ else:
+ self.extrapolator = extrapolator_cls(
+ self.grid_points, bin_edges, binned_pdf, **extrapolator_kwargs
+ )
+
+
+
+
+[docs]
+class ParametrizedComponentEstimator(BaseComponentEstimator):
+ """
+ Base class for all Estimators working on IRF components that represent parametrized
+ or scalar quantities.
+
+ While usable, it is encouraged to use the actual class for the respective IRF
+ component as it ensures further checks and if necessary e.g. unit handling.
+ """
+
+ def __init__(
+ self,
+ grid_points,
+ params,
+ interpolator_cls=GridDataInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ ):
+ """
+ __init__ for all parametrized components, calls BaseComponentEstimator's
+ __init__ and instantiates inter- and extrapolator objects.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which interpolation templates exist
+ params: np.ndarray, shape=(n_points, ..., n_params)
+ Corresponding parameter values at each point in grid_points.
+ First dimension has to correspond to the number of grid_points.
+ interpolator_cls:
+ pyirf interpolator class, defaults to GridDataInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+
+ Raises
+ ------
+ TypeError:
+ When interpolator_cls is not a ParametrizedInterpolator subclass.
+ TypeError:
+ When extrapolator_cls is not a ParametrizedExtrapolator subclass.
+ TypeError:
+ When params is not a np.ndarray.
+ ValueError:
+ When number of points grid_points and params do not match.
+
+ Note
+ ----
+ Also calls pyirf.interpolation.BaseComponentEstimator.__init__
+ """
+
+ super().__init__(
+ grid_points,
+ )
+
+ if not isinstance(params, np.ndarray):
+ raise TypeError("Input params is not a numpy array.")
+ elif self.n_points != params.shape[0]:
+ raise ValueError(
+ "Shape mismatch, number of grid_points and rows in params not matching."
+ )
+
+ # Make sure that 1D input is sorted in increasing order
+ if self.grid_dim == 1:
+ sorting_inds = np.argsort(self.grid_points.squeeze())
+
+ self.grid_points = self.grid_points[sorting_inds]
+ params = params[sorting_inds]
+
+ if interpolator_kwargs is None:
+ interpolator_kwargs = {}
+
+ if extrapolator_kwargs is None:
+ extrapolator_kwargs = {}
+
+ if not issubclass(interpolator_cls, ParametrizedInterpolator):
+ raise TypeError(
+ f"interpolator_cls must be a ParametrizedInterpolator subclass, got {interpolator_cls}"
+ )
+
+ self.interpolator = interpolator_cls(
+ self.grid_points, params, **interpolator_kwargs
+ )
+
+ if extrapolator_cls is None:
+ self.extrapolator = None
+ elif not issubclass(extrapolator_cls, ParametrizedExtrapolator):
+ raise TypeError(
+ f"extrapolator_cls must be a ParametrizedExtrapolator subclass, got {extrapolator_cls}"
+ )
+ else:
+ self.extrapolator = extrapolator_cls(
+ self.grid_points, params, **extrapolator_kwargs
+ )
+
+
+
+
+[docs]
+class EffectiveAreaEstimator(ParametrizedComponentEstimator):
+ """Estimator class for effective area tables (AEFF_2D)."""
+
+ @u.quantity_input(effective_area=u.m**2, min_effective_area=u.m**2)
+ def __init__(
+ self,
+ grid_points,
+ effective_area,
+ interpolator_cls=GridDataInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ min_effective_area=1 * u.m**2,
+ ):
+ """
+ Takes a grid of effective areas for a bunch of different parameters
+ and inter-/extrapolates (log) effective areas to given value of
+ those parameters.
+
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which interpolation templates exist
+ effective_area: np.ndarray of astropy.units.Quantity[area], shape=(n_points, ...)
+ Grid of effective area. Dimensions but the first can in principle be freely
+ chosen. Class is AEFF2D compatible, which would require
+ shape=(n_points, n_energy_bins, n_fov_offset_bins).
+ interpolator_cls:
+ pyirf interpolator class, defaults to GridDataInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+ min_effective_area: astropy.units.Quantity[area]
+ Minimum value of effective area to be considered for interpolation. Values
+ lower than this value are set to this value. Defaults to 1 m**2.
+
+
+ Note
+ ----
+ Also calls __init__ of pyirf.interpolation.BaseComponentEstimator
+ and pyirf.interpolation.ParametrizedEstimator
+ """
+
+ # get rid of units
+ effective_area = effective_area.to_value(u.m**2)
+ min_effective_area = min_effective_area.to_value(u.m**2)
+
+ self.min_effective_area = min_effective_area
+
+ # remove zeros and log it
+ effective_area[
+ effective_area < self.min_effective_area
+ ] = self.min_effective_area
+ effective_area = np.log(effective_area)
+
+ super().__init__(
+ grid_points=grid_points,
+ params=effective_area,
+ interpolator_cls=interpolator_cls,
+ interpolator_kwargs=interpolator_kwargs,
+ extrapolator_cls=extrapolator_cls,
+ extrapolator_kwargs=extrapolator_kwargs,
+ )
+
+
+[docs]
+ def __call__(self, target_point):
+ """
+ Estimating effective area at target_point, inter-/extrapolates as needed and
+ specified in __init__.
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+
+ Returns
+ -------
+ aeff_interp: np.ndarray of (astropy.units.m)**2, shape=(n_points, ...)
+ Interpolated Effective area array with same shape as input
+ effective areas. For AEFF2D of shape (n_energy_bins, n_fov_offset_bins).
+ Values lower or equal to __init__'s min_effective_area are set
+ to zero.
+ """
+
+ aeff_interp = super().__call__(target_point)
+
+ # exp it and set to zero too low values
+ aeff_interp = np.exp(aeff_interp)
+ # remove entries manipulated by min_effective_area
+ aeff_interp[aeff_interp < self.min_effective_area] = 0
+
+ return u.Quantity(aeff_interp, u.m**2, copy=False)
+
+
+
+
+
+[docs]
+class RadMaxEstimator(ParametrizedComponentEstimator):
+ """Estimator class for rad-max tables (RAD_MAX, RAD_MAX_2D)."""
+
+ def __init__(
+ self,
+ grid_points,
+ rad_max,
+ fill_value=None,
+ interpolator_cls=GridDataInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ ):
+ """
+ Takes a grid of rad max values for a bunch of different parameters
+ and inter-/extrapolates rad max values to given value of those parameters.
+
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims):
+ Grid points at which interpolation templates exist
+ rad_max: np.ndarray, shape=(n_points, ...)
+ Grid of theta cuts. Dimensions but the first can in principle be freely
+ chosen. Class is RAD_MAX_2D compatible, which would require
+ shape=(n_points, n_energy_bins, n_fov_offset_bins).
+ fill_val:
+ Indicator of fill-value handling. If None, fill values are regarded as
+ normal values and no special handeling is applied. If "infer", fill values
+ will be infered as max of all values, if a value is provided,
+ it is used to flag fill values. Flagged fill-values are
+ not used for interpolation. Fill-value handling is only supported in
+ up to two grid dimensions.
+ interpolator_cls:
+ pyirf interpolator class, defaults to GridDataInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+
+ Note
+ ----
+ Also calls __init__ of pyirf.interpolation.BaseComponentEstimator
+ and pyirf.interpolation.ParametrizedEstimator
+ """
+
+ super().__init__(
+ grid_points=grid_points,
+ params=rad_max,
+ interpolator_cls=interpolator_cls,
+ interpolator_kwargs=interpolator_kwargs,
+ extrapolator_cls=extrapolator_cls,
+ extrapolator_kwargs=extrapolator_kwargs,
+ )
+
+ self.params = rad_max
+
+ if fill_value is None:
+ self.fill_val = None
+ elif fill_value == "infer":
+ self.fill_val = np.max(self.params)
+ else:
+ self.fill_val = fill_value
+
+ # Raise error if fill-values should be handled in >=3 dims
+ if self.fill_val and self.grid_dim >= 3:
+ raise ValueError(
+ "Fill-value handling only supported in up to two grid dimensions."
+ )
+
+ # If fill-values should be handled in 2D, construct a trinangulation
+ # to later determine in which simplex the target values is
+ if self.fill_val and (self.grid_dim == 2):
+ self.triangulation = Delaunay(self.grid_points)
+
+
+[docs]
+ def __call__(self, target_point):
+ """
+ Estimating rad max table at target_point, inter-/extrapolates as needed and
+ specified in __init__.
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+
+ Returns
+ -------
+ rad_max_interp: np.ndarray, shape=(n_points, ...)
+ Interpolated RAD_MAX table with same shape as input
+ effective areas. For RAD_MAX_2D of shape (n_energy_bins, n_fov_offset_bins)
+
+ """
+ # First, construct estimation without handling fill-values
+ full_estimation = super().__call__(target_point)
+ # Safeguard against extreme extrapolation cases
+ np.clip(full_estimation, 0, None, out=full_estimation)
+
+ # Early exit if fill_values should not be handled
+ if not self.fill_val:
+ return full_estimation
+
+ # Early exit if a nearest neighbor estimation would be overwritten
+ # Complex setup is needed to catch settings where the user mixes approaches and
+ # e.g. uses nearest neighbors for extrapolation and an actual interpolation otherwise
+ if self.grid_dim == 1:
+ if (
+ (target_point < self.grid_points.min())
+ or (target_point > self.grid_points.max())
+ ) and issubclass(self.extrapolator.__class__, BaseNearestNeighborSearcher):
+ return full_estimation
+ elif issubclass(self.interpolator.__class__, BaseNearestNeighborSearcher):
+ return full_estimation
+ elif self.grid_dim == 2:
+ target_simplex = self.triangulation.find_simplex(target_point)
+
+ if (target_simplex == -1) and issubclass(
+ self.extrapolator.__class__, BaseNearestNeighborSearcher
+ ):
+ return full_estimation
+ elif issubclass(self.interpolator.__class__, BaseNearestNeighborSearcher):
+ return full_estimation
+
+ # Actual fill-value handling
+ if self.grid_dim == 1:
+ # Locate target in grid
+ if target_point < self.grid_points.min():
+ segment_inds = np.array([0, 1], "int")
+ elif target_point > self.grid_points.max():
+ segment_inds = np.array([-2, -1], "int")
+ else:
+ target_bin = np.digitize(
+ target_point.squeeze(), self.grid_points.squeeze()
+ )
+ segment_inds = np.array([target_bin - 1, target_bin], "int")
+
+ mask_left = self.params[segment_inds[0]] >= self.fill_val
+ mask_right = self.params[segment_inds[1]] >= self.fill_val
+ # Indicate, wether one of the neighboring entries is a fill-value
+ mask = np.logical_or(mask_left, mask_right)
+ elif self.grid_dim == 2:
+ # Locate target
+ target_simplex = self.triangulation.find_simplex(target_point)
+
+ if target_simplex == -1:
+ target_simplex = find_nearest_simplex(self.triangulation, target_point)
+
+ simplex_nodes_indices = self.triangulation.simplices[
+ target_simplex
+ ].squeeze()
+
+ mask0 = self.params[simplex_nodes_indices[0]] >= self.fill_val
+ mask1 = self.params[simplex_nodes_indices[1]] >= self.fill_val
+ mask2 = self.params[simplex_nodes_indices[2]] >= self.fill_val
+
+ # This collected mask now counts for each entry in the estimation how many
+ # of the entries used for extrapolation contained fill-values
+ intermediate_mask = (
+ mask0.astype("int") + mask1.astype("int") + mask2.astype("int")
+ )
+ mask = np.full_like(intermediate_mask, True, dtype=bool)
+
+ # Simplest cases: All or none entries were fill-values, so either return
+ # a fill-value or the actual estimation
+ mask[intermediate_mask == 0] = False
+ mask[intermediate_mask == 3] = True
+
+ # If two out of three values were fill-values return a fill-value as estimate
+ mask[intermediate_mask == 2] = True
+
+ # If only one out of three values was a fill-value use the smallest value of the
+ # remaining two
+ mask[intermediate_mask == 1] = False
+ full_estimation = np.where(
+ intermediate_mask[np.newaxis, :] == 1,
+ np.min(self.params[simplex_nodes_indices], axis=0),
+ full_estimation,
+ )
+
+ # Set all flagged values to fill-value
+ full_estimation[mask[np.newaxis, :]] = self.fill_val
+
+ # Safeguard against extreme extrapolation cases
+ full_estimation[full_estimation > self.fill_val] = self.fill_val
+
+ return full_estimation
+
+
+
+
+
+[docs]
+class EnergyDispersionEstimator(DiscretePDFComponentEstimator):
+ """Estimator class for energy dispersions (EDISP_2D)."""
+
+ def __init__(
+ self,
+ grid_points,
+ migra_bins,
+ energy_dispersion,
+ interpolator_cls=QuantileInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ axis=-2,
+ ):
+ """
+ Takes a grid of energy dispersions for a bunch of different parameters and
+ inter-/extrapolates energy dispersions to given value of those parameters.
+
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ migra_bins: np.ndarray, shape=(n_migration_bins+1)
+ Common bin edges along migration axis.
+ energy_dispersion: np.ndarray, shape=(n_points, ..., n_migration_bins, ...)
+ EDISP MATRIX. Class is EDISP_2D compatible, which would require
+ shape=(n_points, n_energy_bins, n_migration_bins, n_fov_offset_bins).
+ This is assumed as default. If these axes are in different order
+ or e.g. missing a fov_offset axis, the axis containing n_migration_bins
+ has to be specified through axis.
+ interpolator_cls:
+ pyirf interpolator class, defaults to QuantileInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+ axis:
+ Axis, along which the actual n_migration_bins are. Input is assumed to
+ be EDISP_2D compatible, so this defaults to -2
+
+ Note
+ ----
+ Also calls __init__ of pyirf.interpolation.BaseComponentEstimator
+ and pyirf.interpolation.ParametrizedEstimator
+ """
+
+ self.axis = axis
+
+ super().__init__(
+ grid_points=grid_points,
+ bin_edges=migra_bins,
+ binned_pdf=np.swapaxes(energy_dispersion, axis, -1),
+ interpolator_cls=interpolator_cls,
+ interpolator_kwargs=interpolator_kwargs,
+ extrapolator_cls=extrapolator_cls,
+ extrapolator_kwargs=extrapolator_kwargs,
+ )
+
+
+[docs]
+ def __call__(self, target_point):
+ """
+ Estimating energy dispersions at target_point, inter-/extrapolates as needed and
+ specified in __init__.
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+
+ Returns
+ -------
+ edisp_interp: np.ndarray, shape=(n_points, ..., n_migration_bins, ...)
+ Interpolated EDISP matrix with same shape as input matrices. For EDISP_2D
+ of shape (n_points, n_energy_bins, n_migration_bins, n_fov_offset_bins)
+
+ """
+
+ return np.swapaxes(super().__call__(target_point), -1, self.axis)
+
+
+
+
+
+[docs]
+class PSFTableEstimator(DiscretePDFComponentEstimator):
+ """Estimator class for point spread function tables (PSF_TABLE)."""
+
+ @u.quantity_input(psf=u.sr**-1, source_offset_bins=u.deg)
+ def __init__(
+ self,
+ grid_points,
+ source_offset_bins,
+ psf,
+ interpolator_cls=QuantileInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ axis=-1,
+ ):
+ """
+ Takes a grid of psfs or a bunch of different parameters and
+ inter-/extrapolates psfs to given value of those parameters.
+
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ source_offset_bins: np.ndarray, shape=(n_source_offset_bins+1) of astropy.units.Quantity[deg]
+ Common bin edges along source offset axis.
+ psf: np.ndarray, shape=(n_points, ..., n_source_offset_bins) of astropy.units.Quantity[sr**-1]
+ PSF Tables. Class is PSF_TABLE compatible, which would require
+ shape=(n_points, n_energy_bins, n_fov_offset_bins, n_source_offset_bins).
+ This is assumed as default. If these axes are in different order
+ the axis containing n_source_offset_bins has to be specified through axis.
+ interpolator_cls:
+ pyirf interpolator class, defaults to QuantileInterpolator.
+ interpolator_kwargs: dict
+ Dict of all kwargs that are passed to the interpolator, defaults to
+ None which is the same as passing an empty dict.
+ extrapolator_cls:
+ pyirf extrapolator class. Can be and defaults to ``None``,
+ which raises an error if a target_point is outside the grid
+ and extrapolation would be needed.
+ extrapolator_kwargs: dict
+ Dict of all kwargs that are passed to the extrapolator, defaults to
+ None which is the same as passing an empty dict.
+ axis:
+ Axis, along which the actual n_source_offset_bins are. Input is assumed to
+ be PSF_TABLE compatible, so this defaults to -1
+
+ Note
+ ----
+ Also calls __init__ of pyirf.interpolation.BaseComponentEstimator
+ and pyirf.interpolation.ParametrizedEstimator
+ """
+
+ self.axis = axis
+
+ psf = np.swapaxes(psf, axis, -1)
+
+ if interpolator_kwargs is None:
+ interpolator_kwargs = {}
+
+ if extrapolator_kwargs is None:
+ extrapolator_kwargs = {}
+
+ interpolator_kwargs.setdefault(
+ "normalization", PDFNormalization.CONE_SOLID_ANGLE
+ )
+ extrapolator_kwargs.setdefault(
+ "normalization", PDFNormalization.CONE_SOLID_ANGLE
+ )
+
+ super().__init__(
+ grid_points=grid_points,
+ bin_edges=source_offset_bins.to_value(u.rad),
+ binned_pdf=psf,
+ interpolator_cls=interpolator_cls,
+ interpolator_kwargs=interpolator_kwargs,
+ extrapolator_cls=extrapolator_cls,
+ extrapolator_kwargs=extrapolator_kwargs,
+ )
+
+
+[docs]
+ def __call__(self, target_point):
+ """
+ Estimating psf tables at target_point, inter-/extrapolates as needed and
+ specified in __init__.
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target for inter-/extrapolation
+
+ Returns
+ -------
+ psf_interp: u.Quantity[sr-1], shape=(n_points, ..., n_source_offset_bins)
+ Interpolated psf table with same shape as input matrices. For PSF_TABLE
+ of shape (n_points, n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+
+ """
+
+ interpolated_psf_normed = super().__call__(target_point)
+
+ # Undo normalisation to get a proper PSF and return
+ return u.Quantity(
+ np.swapaxes(interpolated_psf_normed, -1, self.axis), u.sr**-1, copy=False
+ )
+
+
+
+"""
+Simple wrapper around scipy.interpolate.griddata to interpolate parametrized quantities
+"""
+from scipy.interpolate import griddata
+
+from .base_interpolators import ParametrizedInterpolator
+
+__all__ = ["GridDataInterpolator"]
+
+
+
+[docs]
+class GridDataInterpolator(ParametrizedInterpolator):
+ """ "Wrapper arounf scipy.interpolate.griddata."""
+
+ def __init__(self, grid_points, params, **griddata_kwargs):
+ """Parametrized Interpolator using scipy.interpolate.griddata
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ params: np.ndarray, shape=(n_points, ..., n_params)
+ Structured array of corresponding parameter values at each
+ point in grid_points.
+ First dimesion has to correspond to number of grid_points
+ griddata_kwargs: dict
+ Keyword-Arguments passed to scipy.griddata [1], e.g.
+ interpolation method. Defaults to None, which uses scipy's
+ defaults
+
+ Raises
+ ------
+ TypeError:
+ When params is not a np.ndarray
+ ValueError:
+ When number of points grid_points and params is not matching
+
+ References
+ ----------
+ .. [1] Scipy Documentation, scipy.interpolate.griddata
+ https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html
+
+ """
+ super().__init__(grid_points, params)
+
+ self.griddata_kwargs = griddata_kwargs
+
+
+[docs]
+ def interpolate(self, target_point):
+ """
+ Wrapper around scipy.interpolate.griddata [1]
+
+ Parameters
+ ----------
+ target_point: np.ndarray, shape=(1, n_dims)
+ Target point for interpolation
+
+ Returns
+ -------
+ interpolant: np.ndarray, shape=(1, ..., n_params)
+ Interpolated parameter values
+
+ References
+ ----------
+ .. [1] Scipy Documentation, scipy.interpolate.griddata
+ https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html
+ """
+ interpolant = griddata(
+ self.grid_points, self.params, target_point, **self.griddata_kwargs
+ ).squeeze()
+
+ return interpolant.reshape(1, *self.params.shape[1:])
+
+
+
+import numpy as np
+from pyirf.binning import bin_center, calculate_bin_indices
+from scipy.spatial import Delaunay
+
+from .base_interpolators import DiscretePDFInterpolator, PDFNormalization
+from .utils import get_bin_width
+
+__all__ = [
+ "MomentMorphInterpolator",
+]
+
+
+def _estimate_mean_std(bin_edges, binned_pdf, normalization):
+ """
+ Function to roughly estimate mean and standard deviation from a histogram.
+
+ Parameters
+ ----------
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Array of common bin-edges for binned_pdf
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ PDF values from which to compute mean and std
+ normalization : PDFNormalization
+ How the PDF is normalized
+
+ Returns
+ -------
+ mean: np.ndarray, shape=(n_points, ...)
+ Estimated mean for each input template
+ std: np.ndarray, shape=(n_points, ...)
+ Estimated standard deviation for each input template. Set to width/2 if only one bin in
+ the input template is =/= 0
+ """
+ # Create an 2darray where the 1darray mids is repeated n_template times
+ mids = np.broadcast_to(bin_center(bin_edges), binned_pdf.shape)
+
+ width = get_bin_width(bin_edges, normalization)
+
+ # integrate pdf to get probability in each bin
+ probability = binned_pdf * width
+ # Weighted averages to compute mean and std
+ mean = np.average(mids, weights=probability, axis=-1)
+ std = np.sqrt(
+ np.average((mids - mean[..., np.newaxis]) ** 2, weights=probability, axis=-1)
+ )
+
+ # Set std to 0.5*width for all those templates that have only one bin =/= 0. In those
+ # cases mids-mean = 0 and therefore std = 0. Uses the width of the one bin with
+ # binned_pdf!=0
+ mask = std == 0
+ if np.any(mask):
+ width = np.diff(bin_edges)
+ # std of a uniform distribution inside the bin
+ uniform_std = np.broadcast_to(np.sqrt(1 / 12) * width, binned_pdf[mask].shape)
+ std[mask] = uniform_std[binned_pdf[mask, :] != 0]
+
+ return mean, std
+
+
+def _lookup(bin_edges, binned_pdf, x):
+ """
+ Function to return the bin-height at a desired point.
+
+ Parameters
+ ----------
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Array of common bin-edges for binned_pdf
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Array of bin-entries, actual
+ x: numpy.ndarray, shape=(n_points, ..., n_bins)
+ Array of n_bins points for each input template, where the histogram-value (bin-height) should be found
+
+ Returns
+ -------
+ y: numpy.ndarray, shape=(n_points, ..., n_bins)
+ Array of the bin-heights at the n_bins points x, set to 0 at each point outside the histogram
+
+ """
+ # Find the bin where each point x is located in
+ binnr, valid = calculate_bin_indices(x, bin_edges)
+
+ # Set under/overflow-bins (invalid bins) to 0 to avoid errors below
+ binnr[~valid] = 0
+
+ # Loop over every combination of flattend input histograms and flattend binning
+ lu = np.array(
+ [
+ cont[binnr_row]
+ for cont, binnr_row in zip(
+ binned_pdf.reshape(-1, binned_pdf.shape[-1]),
+ binnr.reshape(-1, binnr.shape[-1]),
+ )
+ ]
+ ).reshape(binned_pdf.shape)
+
+ # Set all invalid bins to 0
+ lu[~valid] = 0
+
+ # Set under-/ overflowbins to 0, reshape to original shape
+ return lu
+
+
+def linesegment_1D_interpolation_coefficients(grid_points, target_point):
+ """
+ Compute 1D interpolation coefficients for moment morph interpolation,
+ as in eq. (6) of [1]
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(2, 1)
+ Points spanning a triangle in which
+ target_point: numpy.ndarray, shape=(1, 1)
+ Value at which the histogram should be interpolated
+
+ Returns
+ -------
+ coefficients: numpy.ndarray, shape=(2,)
+ Interpolation coefficients for all three interpolation simplex vertices
+ to interpolate to the target_point
+
+ References
+ ----------
+ .. [1] M. Baak, S. Gadatsch, R. Harrington and W. Verkerke (2015). Interpolation between
+ multi-dimensional histograms using a new non-linear moment morphing method
+ Nucl. Instrum. Methods Phys. Res. A 771, 39-48. https://doi.org/10.1016/j.nima.2014.10.033
+ """
+ # Set zeroth grid point as reference value
+ m0 = grid_points[0, :]
+
+ # Compute matrix M as in eq. (2) of [1]
+ j = np.arange(0, grid_points.shape[0], 1)
+ m_ij = (grid_points - m0) ** j
+
+ # Compute coefficients, eq. (6) from [1]
+ return np.einsum("...j, ji -> ...i", (target_point - m0) ** j, np.linalg.inv(m_ij))
+
+
+def barycentric_2D_interpolation_coefficients(grid_points, target_point):
+ """
+ Compute barycentric 2D interpolation coefficients for triangular
+ interpolation, see e.g. [1]
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(3, 2)
+ Points spanning a triangle in which
+ target_point: np.ndarray, shape=(1, 2)
+ Value at which barycentric interpolation is needed
+
+ Returns
+ -------
+ coefficients: numpy.ndarray, shape=(3,)
+ Interpolation coefficients for all three interpolation simplex vertices
+ to interpolate to the target_point
+
+ References
+ ----------
+ .. [1] https://codeplea.com/triangular-interpolation
+ """
+ # Compute distance vectors between the grid points
+ d13 = grid_points[0, :] - grid_points[2, :]
+ d23 = grid_points[1, :] - grid_points[2, :]
+
+ # Compute distance vector between target and third grid point
+ dp3 = target_point.squeeze() - grid_points[2, :]
+
+ # Compute first and second weight
+ w1 = ((d23[1] * dp3[0]) + (-d23[0] * dp3[1])) / (
+ (d23[1] * d13[0]) + (-d23[0] * d13[1])
+ )
+ w2 = ((-d13[1] * dp3[0]) + (d13[0] * dp3[1])) / (
+ (d23[1] * d13[0]) + (-d23[0] * d13[1])
+ )
+
+ # Use w1+w2+w3 = 1 for third weight
+ w3 = 1 - w1 - w2
+
+ coefficients = np.array([w1, w2, w3])
+
+ return coefficients
+
+
+def moment_morph_estimation(bin_edges, binned_pdf, coefficients, normalization):
+ """
+ Function that wraps up the moment morph procedure [1] adopted for histograms.
+
+ Parameters
+ ----------
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Array of common bin-edges for binned_pdf
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Array of bin-entries, actual
+ coefficients: np.ndarray, shape=(n_points)
+ Estimation coefficients for each entry in binned_pdf
+ normalization : PDFNormalization
+ How the PDF is normalized
+
+ Returns
+ -------
+ f_new: numpy.ndarray, shape=(1, n_bins)
+ Interpolated histogram
+
+ References
+ ----------
+ .. [1] M. Baak, S. Gadatsch, R. Harrington and W. Verkerke (2015). Interpolation between
+ multi-dimensional histograms using a new non-linear moment morphing method
+ Nucl. Instrum. Methods Phys. Res. A 771, 39-48. https://doi.org/10.1016/j.nima.2014.10.033
+ """
+ bin_mids = bin_center(bin_edges)
+
+ # Catch all those templates, where at least one template histogram is all zeros.
+ zero_templates = ~np.all(~np.isclose(np.sum(binned_pdf, axis=-1), 0), 0)
+
+ # Manipulate those templates so that computations pass without error
+ binned_pdf[:, zero_templates] = np.full(len(bin_mids), 1 / len(bin_mids))
+
+ # Estimate mean and std for each input template histogram. First adaption needed to extend
+ # the moment morph procedure to histograms
+ mus, sigs = _estimate_mean_std(
+ bin_edges=bin_edges, binned_pdf=binned_pdf, normalization=normalization
+ )
+ coefficients = coefficients.reshape(
+ binned_pdf.shape[0], *np.ones(mus.ndim - 1, "int")
+ )
+
+ # Transform mean and std as in eq. (11) and (12) in [1]
+ # cs = np.broadcast_to(cs, mus.shape)
+ mu_prime = np.sum(coefficients * mus, axis=0)
+ sig_prime = np.sum(coefficients * sigs, axis=0)
+
+ # Compute slope and offset as in eq. (14) and (15) in [1]
+ aij = sigs / sig_prime
+ bij = mus - mu_prime * aij
+
+ # Transformation as in eq. (13) in [1]
+ mids = np.broadcast_to(bin_mids, binned_pdf.shape)
+ transf_mids = aij[..., np.newaxis] * mids + bij[..., np.newaxis]
+
+ # Compute the morphed historgram according to eq. (18) in [1]. The function "lookup" "resamples"
+ # the histogram at the transformed bin-mids by using the templates historgam value at the transformed
+ # bin-mid as new value for a whole transformed bin. Second adaption needed to extend
+ # the moment morph procedure to histograms, adaptes the behaviour of eq. (16)
+
+ transf_hist = _lookup(bin_edges=bin_edges, binned_pdf=binned_pdf, x=transf_mids)
+
+ f_new = np.sum(
+ np.expand_dims(coefficients, -1) * transf_hist * np.expand_dims(aij, -1), axis=0
+ )
+
+ # Reset interpolation resolts for those templates with partially zero entries from above to 0
+ f_new[zero_templates] = np.zeros(len(bin_mids))
+
+ # Re-Normalize, needed, as the estimation of the std used above is not exact but the result is scaled with
+ # the estimated std
+ bin_widths = get_bin_width(bin_edges, normalization)
+ norm = np.expand_dims(np.sum(f_new * bin_widths, axis=-1), -1)
+
+ return np.divide(f_new, norm, out=np.zeros_like(f_new), where=norm != 0).reshape(
+ 1, *binned_pdf.shape[1:]
+ )
+
+
+
+[docs]
+class MomentMorphInterpolator(DiscretePDFInterpolator):
+ """Interpolator class providing Moment Morphing to interpolate discretized PDFs."""
+
+ def __init__(
+ self, grid_points, bin_edges, binned_pdf, normalization=PDFNormalization.AREA
+ ):
+ """
+ Interpolator class using moment morphing.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist. May be one ot two dimensional.
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Edges of the data binning
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points. Interpolation dimension, meaning the
+ the quantity that should be interpolated (e.g. the Migra axis for EDisp)
+ has to be at axis specified by axis-keyword as well as having entries
+ corresponding to the number of bins given through bin_edges keyword.
+ normalization : PDFNormalization
+ How the PDF is normalized
+
+ Note
+ ----
+ Also calls pyirf.interpolation.DiscretePDFInterpolator.__init__.
+ """
+ super().__init__(grid_points, bin_edges, binned_pdf, normalization)
+
+ if self.grid_dim == 2:
+ self.triangulation = Delaunay(self.grid_points)
+ elif self.grid_dim > 2:
+ raise NotImplementedError(
+ "Interpolation in more then two dimension not impemented."
+ )
+
+ def _interpolate1D(self, target_point):
+ """
+ Function to find target inside 1D self.grid_points and interpolate
+ on this subset.
+ """
+ target_bin = np.digitize(target_point.squeeze(), self.grid_points.squeeze())
+ segment_inds = np.array([target_bin - 1, target_bin], "int")
+ coefficients = linesegment_1D_interpolation_coefficients(
+ grid_points=self.grid_points[segment_inds],
+ target_point=target_point,
+ )
+
+ return moment_morph_estimation(
+ bin_edges=self.bin_edges,
+ binned_pdf=self.binned_pdf[segment_inds],
+ coefficients=coefficients,
+ normalization=self.normalization,
+ )
+
+ def _interpolate2D(self, target_point):
+ """
+ Function to find target inside 2D self.grid_points and interpolate
+ on this subset.
+ """
+ simplex_inds = self.triangulation.simplices[
+ self.triangulation.find_simplex(target_point)
+ ].squeeze()
+ coefficients = barycentric_2D_interpolation_coefficients(
+ grid_points=self.grid_points[simplex_inds],
+ target_point=target_point,
+ )
+
+ return moment_morph_estimation(
+ bin_edges=self.bin_edges,
+ binned_pdf=self.binned_pdf[simplex_inds],
+ coefficients=coefficients,
+ normalization=self.normalization,
+ )
+
+
+[docs]
+ def interpolate(self, target_point):
+ """
+ Takes a grid of binned pdfs for a bunch of different parameters
+ and interpolates it to given value of those parameters.
+ This function calls implementations of the moment morphing interpolation
+ pocedure introduced in [1].
+
+ Parameters
+ ----------
+ target_point: numpy.ndarray, shape=(1, n_dims)
+ Value for which the interpolation is performed (target point)
+
+ Returns
+ -------
+ f_new: numpy.ndarray, shape=(1,...,n_bins)
+ Interpolated and binned pdf
+
+ References
+ ----------
+ .. [1] M. Baak, S. Gadatsch, R. Harrington and W. Verkerke (2015). Interpolation between
+ multi-dimensional histograms using a new non-linear moment morphing method
+ Nucl. Instrum. Methods Phys. Res. A 771, 39-48. https://doi.org/10.1016/j.nima.2014.10.033
+ """
+ if self.grid_dim == 1:
+ interpolant = self._interpolate1D(target_point)
+ elif self.grid_dim == 2:
+ interpolant = self._interpolate2D(target_point)
+
+ return interpolant
+
+
+
+import numpy as np
+
+from .base_extrapolators import DiscretePDFExtrapolator, ParametrizedExtrapolator
+from .base_interpolators import (
+ BaseInterpolator,
+ DiscretePDFInterpolator,
+ ParametrizedInterpolator,
+)
+
+__all__ = [
+ "BaseNearestNeighborSearcher",
+ "DiscretePDFNearestNeighborSearcher",
+ "ParametrizedNearestNeighborSearcher",
+]
+
+
+
+[docs]
+class BaseNearestNeighborSearcher(BaseInterpolator):
+ """
+ Dummy NearestNeighbor approach usable instead of
+ actual Interpolation/Extrapolation
+ """
+
+ def __init__(self, grid_points, values, norm_ord=2):
+ """
+ BaseNearestNeighborSearcher
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist
+ values: np.ndarray, shape=(n_points, ...)
+ Corresponding IRF values at grid_points
+ norm_ord: non-zero int
+ Order of the norm which is used to compute the distances,
+ passed to numpy.linalg.norm [1]. Defaults to 2,
+ which uses the euclidean norm.
+
+ Raises
+ ------
+ TypeError:
+ If norm_ord is not non-zero integer
+
+ Notes
+ -----
+ Also calls pyirf.interpolation.BaseInterpolators.__init__
+ """
+ super().__init__(grid_points)
+
+ self.values = values
+
+ # Test wether norm_ord is a number
+ try:
+ norm_ord > 0
+ except TypeError:
+ raise ValueError(
+ f"Only positiv integers allowed for norm_ord, got {norm_ord}."
+ )
+
+ # Test wether norm_ord is a finite, positive integer
+ if (norm_ord <= 0) or ~np.isfinite(norm_ord) or (norm_ord != int(norm_ord)):
+ raise ValueError(
+ f"Only positiv integers allowed for norm_ord, got {norm_ord}."
+ )
+
+ self.norm_ord = norm_ord
+
+
+[docs]
+ def interpolate(self, target_point):
+ """
+ Takes a grid of IRF values for a bunch of different parameters and returns
+ the values at the nearest grid point as seen from the target point.
+
+ Parameters
+ ----------
+ target_point: numpy.ndarray, shape=(1, n_dims)
+ Value for which the nearest neighbor should be found (target point)
+
+ Returns
+ -------
+ content_new: numpy.ndarray, shape=(1, ...)
+ values at nearest neighbor
+
+ Notes
+ -----
+ In case of multiple nearest neighbors, the values corresponding
+ to the first one are returned.
+ """
+
+ if target_point.ndim == 1:
+ target_point = target_point.reshape(1, *target_point.shape)
+
+ distances = np.linalg.norm(
+ self.grid_points - target_point, ord=self.norm_ord, axis=1
+ )
+
+ index = np.argmin(distances)
+
+ return self.values[index, :]
+
+
+
+
+
+[docs]
+class DiscretePDFNearestNeighborSearcher(BaseNearestNeighborSearcher):
+ """
+ Dummy NearestNeighbor approach usable instead of
+ actual interpolation/extrapolation.
+ Compatible with discretized PDF IRF component API.
+ """
+
+ def __init__(self, grid_points, bin_edges, binned_pdf, norm_ord=2):
+ """
+ NearestNeighborSearcher compatible with discretized PDF IRF components API
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Edges of the data binning. Ignored for nearest neighbor searching.
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points, last dimension has to correspond to number of bins for
+ the quantity that should be interpolated (e.g. the Migra axis for EDisp)
+ norm_ord: non-zero int
+ Order of the norm which is used to compute the distances,
+ passed to numpy.linalg.norm [1]. Defaults to 2,
+ which uses the euclidean norm.
+
+ Notes
+ -----
+ Also calls pyirf.interpolation.BaseNearestNeighborSearcher.__init__
+ """
+
+ super().__init__(grid_points=grid_points, values=binned_pdf, norm_ord=norm_ord)
+
+
+
+DiscretePDFInterpolator.register(DiscretePDFNearestNeighborSearcher)
+DiscretePDFExtrapolator.register(DiscretePDFNearestNeighborSearcher)
+
+
+
+[docs]
+class ParametrizedNearestNeighborSearcher(BaseNearestNeighborSearcher):
+ """
+ Dummy NearestNeighbor approach usable instead of
+ actual interpolation/extrapolation
+ Compatible with parametrized IRF component API.
+ """
+
+ def __init__(self, grid_points, params, norm_ord=2):
+ """
+ NearestNeighborSearcher compatible with parametrized IRF components API
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist
+ params: np.ndarray, shape=(n_points, ..., n_params)
+ Corresponding parameter values at each point in grid_points.
+ First dimesion has to correspond to number of grid_points
+ norm_ord: non-zero int
+ Order of the norm which is used to compute the distances,
+ passed to numpy.linalg.norm [1]. Defaults to 2,
+ which uses the euclidean norm.
+
+ Notes
+ ----
+ Also calls pyirf.interpolation.BaseNearestNeighborSearcher.__init__
+ """
+
+ super().__init__(grid_points=grid_points, values=params, norm_ord=norm_ord)
+
+
+
+ParametrizedInterpolator.register(ParametrizedNearestNeighborSearcher)
+ParametrizedExtrapolator.register(ParametrizedNearestNeighborSearcher)
+
+"""
+Extrapolators for Parametrized and DiscretePDF components extrapolating from the
+nearest simplex
+"""
+import warnings
+
+import numpy as np
+from scipy.spatial import Delaunay
+
+from .base_extrapolators import (
+ DiscretePDFExtrapolator,
+ ParametrizedExtrapolator,
+ PDFNormalization,
+)
+from .moment_morph_interpolator import (
+ barycentric_2D_interpolation_coefficients,
+ linesegment_1D_interpolation_coefficients,
+ moment_morph_estimation,
+)
+from .utils import find_nearest_simplex, get_bin_width
+
+__all__ = [
+ "MomentMorphNearestSimplexExtrapolator",
+ "ParametrizedNearestSimplexExtrapolator",
+]
+
+
+
+[docs]
+class ParametrizedNearestSimplexExtrapolator(ParametrizedExtrapolator):
+ """Extrapolator class extending linear or baryzentric interpolation outside a grid's convex hull."""
+
+ def __init__(self, grid_points, params):
+ """
+ Extrapolator class using linear or baryzentric extrapolation in one ore two
+ grid-dimensions.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist. May be one ot two dimensional.
+ Have to be sorted in accending order for 1D.
+ params: np.ndarray, shape=(n_points, ...)
+ Array of corresponding parameter values at each point in grid_points.
+ First dimesion has to correspond to number of grid_points
+
+ Note
+ ----
+ Also calls pyirf.interpolation.ParametrizedInterpolator.__init__.
+ """
+ super().__init__(grid_points, params)
+
+ if self.grid_dim == 2:
+ self.triangulation = Delaunay(self.grid_points)
+ elif self.grid_dim > 2:
+ raise NotImplementedError(
+ "Extrapolation in more then two dimension not impemented."
+ )
+
+ def _extrapolate1D(self, segment_inds, target_point):
+ """
+ Function to compute extrapolation coefficients for a target_point on a
+ specified grid segment and extrapolate from this subset
+ """
+ coefficients = linesegment_1D_interpolation_coefficients(
+ grid_points=self.grid_points[segment_inds],
+ target_point=target_point.squeeze(),
+ )
+
+ # reshape to be broadcastable
+ coefficients = coefficients.reshape(
+ coefficients.shape[0], *np.ones(self.params.ndim - 1, "int")
+ )
+
+ return np.sum(coefficients * self.params[segment_inds, :], axis=0)[
+ np.newaxis, :
+ ]
+
+ def _extrapolate2D(self, simplex_inds, target_point):
+ """
+ Function to compute extrapolation coeficcients and extrapolate from the nearest
+ simplex by extending barycentric interpolation
+ """
+ coefficients = barycentric_2D_interpolation_coefficients(
+ grid_points=self.grid_points[simplex_inds],
+ target_point=target_point,
+ )
+
+ # reshape to be broadcastable
+ coefficients = coefficients.reshape(
+ coefficients.shape[0], *np.ones(self.params.ndim - 1, "int")
+ )
+
+ return np.sum(coefficients * self.params[simplex_inds, :], axis=0)[
+ np.newaxis, :
+ ]
+
+
+[docs]
+ def extrapolate(self, target_point):
+ """
+ Takes a grid of scalar values for a bunch of different parameters
+ and extrapolates it to given value of those parameters.
+
+ Parameters
+ ----------
+ target_point: numpy.ndarray, shape=(1, n_dims)
+ Value for which the extrapolation is performed (target point)
+
+ Returns
+ -------
+ values: numpy.ndarray, shape=(1,...)
+ Extrapolated values
+
+ """
+ if self.grid_dim == 1:
+ if target_point < self.grid_points.min():
+ segment_inds = np.array([0, 1], "int")
+ else:
+ segment_inds = np.array([-2, -1], "int")
+
+ extrapolant = self._extrapolate1D(segment_inds, target_point)
+ elif self.grid_dim == 2:
+ nearest_simplex_ind = find_nearest_simplex(
+ self.triangulation, target_point.squeeze()
+ )
+ simplex_indices = self.triangulation.simplices[nearest_simplex_ind]
+
+ extrapolant = self._extrapolate2D(simplex_indices, target_point)
+
+ return extrapolant
+
+
+
+
+
+[docs]
+class MomentMorphNearestSimplexExtrapolator(DiscretePDFExtrapolator):
+ """Extrapolator class extending moment morphing interpolation outside a grid's convex hull."""
+
+ def __init__(
+ self, grid_points, bin_edges, binned_pdf, normalization=PDFNormalization.AREA
+ ):
+ """
+ Extrapolator class extending/reusing parts of Moment Morphing
+ by allowing for negative extrapolation coefficients computed
+ by from the nearest simplex in 1D or 2D (so either a line-segement
+ or a triangle).
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(n_points, n_dims)
+ Grid points at which templates exist. May be one ot two dimensional.
+ Have to be sorted in accending order for 1D.
+ bin_edges: np.ndarray, shape=(n_bins+1)
+ Edges of the data binning
+ binned_pdf: np.ndarray, shape=(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points. Extrapolation dimension, meaning the
+ the quantity that should be interpolated (e.g. the Migra axis for EDisp)
+ has to be at the last axis as well as having entries
+ corresponding to the number of bins given through bin_edges keyword.
+ normalization : PDFNormalization
+ How the PDF is normalized
+
+ Note
+ ----
+ Also calls pyirf.interpolation.DiscretePDFExtrapolator.__init__.
+ """
+ super().__init__(grid_points, bin_edges, binned_pdf, normalization)
+
+ if self.grid_dim == 2:
+ self.triangulation = Delaunay(self.grid_points)
+ elif self.grid_dim > 2:
+ raise NotImplementedError(
+ "Extrapolation in more then two dimension not impemented."
+ )
+
+ def _extrapolate1D(self, segment_inds, target_point):
+ """
+ Function to compute extrapolation coefficients for a target_point on a
+ specified grid segment and extrapolate from this subset
+ """
+ coefficients = linesegment_1D_interpolation_coefficients(
+ grid_points=self.grid_points[segment_inds],
+ target_point=target_point.squeeze(),
+ )
+
+ return moment_morph_estimation(
+ bin_edges=self.bin_edges,
+ binned_pdf=self.binned_pdf[segment_inds],
+ coefficients=coefficients,
+ normalization=self.normalization,
+ )
+
+ def _extrapolate2D(self, simplex_inds, target_point):
+ """
+ Function to compute extrapolation coeficcients and extrapolate from the nearest
+ simplex by extending barycentric interpolation
+ """
+ coefficients = barycentric_2D_interpolation_coefficients(
+ grid_points=self.grid_points[simplex_inds],
+ target_point=target_point,
+ )
+
+ return moment_morph_estimation(
+ bin_edges=self.bin_edges,
+ binned_pdf=self.binned_pdf[simplex_inds],
+ coefficients=coefficients,
+ normalization=self.normalization,
+ )
+
+
+[docs]
+ def extrapolate(self, target_point):
+ """
+ Takes a grid of discretized PDFs for a bunch of different parameters
+ and extrapolates it to given value of those parameters.
+
+ Parameters
+ ----------
+ target_point: numpy.ndarray, shape=(1, n_dims)
+ Value for which the extrapolation is performed (target point)
+
+ Returns
+ -------
+ values: numpy.ndarray, shape=(1, ..., n_bins)
+ Extrapolated discretized PDFs
+
+ """
+ if self.grid_dim == 1:
+ if target_point < self.grid_points.min():
+ segment_inds = np.array([0, 1], "int")
+ else:
+ segment_inds = np.array([-2, -1], "int")
+
+ extrapolant = self._extrapolate1D(segment_inds, target_point)
+ elif self.grid_dim == 2:
+ nearest_simplex_ind = find_nearest_simplex(
+ self.triangulation, target_point.squeeze()
+ )
+ simplex_indices = self.triangulation.simplices[nearest_simplex_ind]
+
+ extrapolant = self._extrapolate2D(simplex_indices, target_point)
+
+ if not np.all(extrapolant >= 0):
+ warnings.warn(
+ "Some bin-entries where below zero after extrapolation and "
+ "thus cut off. Check result carefully."
+ )
+
+ # cut off values below 0 and re-normalize
+ extrapolant[extrapolant < 0] = 0
+ bin_width = get_bin_width(self.bin_edges, self.normalization)
+ norm = np.expand_dims(np.sum(extrapolant * bin_width, axis=-1), -1)
+ return np.divide(
+ extrapolant, norm, out=np.zeros_like(extrapolant), where=norm != 0
+ ).reshape(1, *self.binned_pdf.shape[1:])
+ else:
+ return extrapolant
+
+
+
+import numpy as np
+from scipy.interpolate import griddata, interp1d
+
+from .base_interpolators import DiscretePDFInterpolator, PDFNormalization
+from .utils import get_bin_width
+
+__all__ = ["QuantileInterpolator"]
+
+
+def cdf_values(binned_pdf, bin_edges, normalization):
+ """
+ compute cdf values and assure they are normed to unity
+ """
+ bin_widths = get_bin_width(bin_edges, normalization)
+ cdfs = np.cumsum(binned_pdf * bin_widths, axis=-1)
+
+ # assure the last cdf value is 1, ignore errors for empty pdfs as they are reset to 0 by nan_to_num
+ with np.errstate(invalid="ignore"):
+ cdfs = np.nan_to_num(cdfs / np.max(cdfs, axis=-1)[..., np.newaxis])
+
+ return cdfs
+
+
+def ppf_values(bin_mids, cdfs, quantiles):
+ """
+ Compute ppfs from cdfs and interpolate them to the desired interpolation point
+
+ Parameters
+ ----------
+ bin_mids: numpy.ndarray, shape=(n_bins)
+ Bin-mids for each bin along interpolation axis
+
+ cdfs: numpy.ndarray, shape=(n_points,...,n_bins)
+ Corresponding cdf-values for all quantiles
+
+ quantiles: numpy.ndarray, shape=(n_quantiles)
+ Quantiles for which the ppf-values should be estimated
+
+ Returns
+ -------
+ ppfs: numpy.ndarray, shape=(1,...,n_quantiles)
+ Corresponding ppf-values for all quantiles at the target interpolation point
+ """
+
+ def cropped_interp(cdf):
+ """
+ create ppf-values through inverse interpolation of the cdf, avoiding repeating 0 and 1 entries
+ around the first and last bins as well as repeating values due to zero bins
+ in between filled bins. Both cases would result in division by zero errors when computing
+ the interpolation polynom.
+ """
+
+ # Find last 0 and first 1 entry
+ last_0 = np.nonzero(cdf == 0)[0][-1] if cdf[0] == 0 else 0
+ first_1 = np.nonzero(cdf == 1.0)[0][0]
+
+ # Predefine selection mask
+ selection = np.ones(len(cdf), dtype=bool)
+
+ # Keep only the first of subsequently matching values
+ selection[1:] = cdf[1:] != cdf[:-1]
+
+ # Keep only the last 0 and first 1 entry
+ selection[:last_0] = False
+ selection[last_0] = True
+ selection[first_1 + 1 :] = False
+ selection[first_1] = True
+
+ # create ppf values from selected bins
+ return interp1d(
+ cdf[selection],
+ bin_mids[selection],
+ bounds_error=False,
+ fill_value="extrapolate",
+ )(quantiles)
+
+ # create ppf values from cdf samples via interpolation of the cdfs
+ # return nan for empty pdfs
+ ppfs = np.apply_along_axis(
+ lambda cdf: cropped_interp(cdf)
+ if np.sum(cdf) > 0
+ else np.full_like(quantiles, np.nan),
+ -1,
+ cdfs,
+ )
+ # nD interpolation of ppf values
+ return ppfs
+
+
+def pdf_from_ppf(bin_edges, interp_ppfs, quantiles):
+ """
+ Reconstruct pdf from ppf and evaluate at desired points.
+
+ Parameters
+ ----------
+ bin_edges: numpy.ndarray, shape=(n_bins+1)
+ Edges of the bins in which the final pdf should be binned
+
+ interp_ppfs: numpy.ndarray, shape=(1,...,n_quantiles)
+ Corresponding ppf-values for all quantiles at the target_point,
+ not to be confused with QunatileInterpolators self.ppfs, the ppfs
+ computed from the input distributions.
+
+ quantiles: numpy.ndarray, shape=(n_quantiles)
+ Quantiles corresponding to the ppf-values in interp_ppfs
+
+ Returns
+ -------
+ pdf_values: numpy.ndarray, shape=(1,...,n_bins)
+ Recomputed, binned pdf at target_point
+ """
+ # recalculate pdf values through numerical differentiation
+ pdf_interpolant = np.nan_to_num(np.diff(quantiles) / np.diff(interp_ppfs, axis=-1))
+
+ # Unconventional solution to make this usable with np.apply_along_axis for readability
+ # The ppf bin-mids are computed since the pdf-values are derived through derivation
+ # from the ppf-values
+ xyconcat = np.concatenate(
+ (interp_ppfs[..., :-1] + np.diff(interp_ppfs) / 2, pdf_interpolant), axis=-1
+ )
+
+ def interpolate_ppf(xy):
+ ppf = xy[: len(xy) // 2]
+ pdf = xy[len(xy) // 2 :]
+ interpolate = interp1d(ppf, pdf, bounds_error=False, fill_value=(0, 0))
+ result = np.nan_to_num(interpolate(bin_edges[:-1]))
+ return result
+
+ # Interpolate pdf samples and evaluate at bin edges, weight with the bin_width to estimate
+ # correct bin height via the midpoint rule formulation of the trapezoidal rule
+ pdf_values = np.apply_along_axis(interpolate_ppf, -1, xyconcat)
+
+ return pdf_values
+
+
+def norm_pdf(pdf_values, bin_edges, normalization):
+ """
+ Normalize binned_pdf to a sum of 1
+ """
+ norm = np.sum(pdf_values, axis=-1)
+ width = get_bin_width(bin_edges, normalization)
+
+ # Norm all binned_pdfs to unity that are not empty
+ normed_pdf_values = np.divide(
+ pdf_values,
+ norm[..., np.newaxis] * width,
+ out=np.zeros_like(pdf_values),
+ where=norm[..., np.newaxis] != 0,
+ )
+
+ return normed_pdf_values
+
+
+
+[docs]
+class QuantileInterpolator(DiscretePDFInterpolator):
+ """Interpolator class providing quantile interpoalation."""
+
+ def __init__(
+ self,
+ grid_points,
+ bin_edges,
+ binned_pdf,
+ quantile_resolution=1e-3,
+ normalization=PDFNormalization.AREA,
+ ):
+ """
+ Parameters
+ ----------
+ grid_points : np.ndarray, shape=(n_points, n_dims)
+ Grid points at which interpolation templates exist
+ bin_edges : np.ndarray, shape=(n_bins+1)
+ Edges of the data binning
+ binned_pdf : np.ndarray, shape(n_points, ..., n_bins)
+ Content of each bin in bin_edges for
+ each point in grid_points. First dimesion has to correspond to number
+ of grid_points, the last axis has to correspond to number
+ of bins for the quantity that should be interpolated
+ (e.g. the Migra axis for EDisp)
+ quantile_resolution : float
+ Spacing between quantiles
+ normalization : PDFNormalization
+ How the discrete PDF is normalized
+
+ Raises
+ ------
+ ValueError:
+ When last axis in binned_pdf and number of bins are not equal.
+
+ Note
+ ----
+ Also calls __init__ of pyirf.interpolation.BaseInterpolator and
+ DiscretePDFInterpolator
+ """
+ # Remember input shape
+ self.input_shape = binned_pdf.shape
+
+ if self.input_shape[-1] != len(bin_edges) - 1:
+ raise ValueError(
+ "Number of bins along last axis and those specified by bin_edges not matching."
+ )
+
+ # include 0-bin at first position in each pdf to avoid edge-effects where the CDF would otherwise
+ # start at a value != 0, also extend edges with one bin to the left
+ fill_zeros = np.zeros(shape=binned_pdf.shape[:-1])[..., np.newaxis]
+ binned_pdf = np.concatenate((fill_zeros, binned_pdf), axis=-1)
+ bin_edges = np.append(bin_edges[0] - np.diff(bin_edges)[0], bin_edges)
+
+ # compute quantiles from quantile_resolution
+ self.quantiles = np.linspace(
+ 0, 1, int(np.round(1 / quantile_resolution, decimals=0))
+ )
+
+ super().__init__(
+ grid_points=grid_points,
+ bin_edges=bin_edges,
+ binned_pdf=binned_pdf,
+ normalization=normalization,
+ )
+
+ # Compute CDF values
+ self.cdfs = cdf_values(self.binned_pdf, self.bin_edges, self.normalization)
+
+ # compute ppf values at quantiles, determine quantile step of [1]
+ self.ppfs = ppf_values(self.bin_mids, self.cdfs, self.quantiles)
+
+
+[docs]
+ def interpolate(self, target_point):
+ """
+ Takes a grid of binned pdfs for a bunch of different parameters
+ and interpolates it to given value of those parameters.
+ This function provides an adapted version of the quantile interpolation introduced
+ in [1].
+ Instead of following this method closely, it implements different approaches to the
+ steps shown in Fig. 5 of [1].
+
+ Parameters
+ ----------
+ target_point: numpy.ndarray, shape=(1, n_dims)
+ Value for which the interpolation is performed (target point)
+
+ Returns
+ -------
+ f_new: numpy.ndarray, shape=(1, ..., n_bins)
+ Interpolated and binned pdf
+
+ References
+ ----------
+ .. [1] B. E. Hollister and A. T. Pang (2013). Interpolation of Non-Gaussian Probability Distributions
+ for Ensemble Visualization
+ https://engineering.ucsc.edu/sites/default/files/technical-reports/UCSC-SOE-13-13.pdf
+ """
+
+ # interpolate ppfs to target point, interpolate quantiles step of [1]
+ interpolated_ppfs = griddata(self.grid_points, self.ppfs, target_point)
+
+ # compute pdf values for all bins, evaluate interpolant PDF values step of [1], drop the earlier
+ # introduced extra bin
+ interpolated_pdfs = pdf_from_ppf(
+ self.bin_edges, interpolated_ppfs, self.quantiles
+ )[..., 1:]
+
+ # Renormalize pdf to sum of 1
+ normed_interpolated_pdfs = norm_pdf(
+ interpolated_pdfs, self.bin_edges[1:], self.normalization
+ )
+
+ # Re-swap axes and set all nans to zero
+ return np.nan_to_num(normed_interpolated_pdfs).reshape(1, *self.input_shape[1:])
+
+
+
+"""
+Extrapolators for Parametrized and DiscretePDF components that combine extrapolations
+from all visible simplices (by blending over visible edges) to get a smooth extrapolation
+outside the grids convex hull.
+"""
+import numpy as np
+from scipy.spatial import Delaunay
+
+from .nearest_simplex_extrapolator import ParametrizedNearestSimplexExtrapolator
+from .utils import find_simplex_to_facet, point_facet_angle
+
+__all__ = ["ParametrizedVisibleEdgesExtrapolator"]
+
+
+def find_visible_facets(grid_points, target_point):
+ """
+ Find all facets of a convex hull visible from an outside point.
+
+ To do so, this function constructs a triangulation containing
+ the target point and returns all facets that span a triangulation simplex with
+ it.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(N, M)
+ Grid points at which templates exist. May be one ot two dimensional.
+ Have to be sorted in accending order for 1D.
+ target_point: numpy.ndarray, shape=(1, M)
+ Value for which the extrapolation is performed (target point)
+
+ Returns
+ -------
+ visible_facets: np.ndarray, shape=(L, M)
+ L visible facets, spanned by a simplex in M-1 dimensions
+ (thus a line for M=2)
+ """
+ # Build a triangulation including the target point
+ full_set = np.vstack((grid_points, target_point))
+ triag = Delaunay(full_set)
+
+ # The target point is included in a simplex with all facets
+ # visible by it
+ simplices = triag.points[triag.simplices]
+ matches_target = np.all(simplices == target_point, axis=-1)
+ target_in_simplex = np.any(matches_target, axis=-1)
+
+ # The visible facets are spanned by those points in the matched
+ # simplices that are not the target
+ facet_point_mask = ~matches_target[target_in_simplex]
+ visible_facets = np.array(
+ [
+ triag.points[simplex[mask]]
+ for simplex, mask in zip(
+ triag.simplices[target_in_simplex], facet_point_mask
+ )
+ ]
+ )
+
+ return visible_facets
+
+
+def compute_extrapolation_weights(visible_facet_points, target_point, m):
+ """
+ Compute extrapolation weight according to [1].
+
+ Parameters
+ ----------
+ visible_facet_points: np.ndarray, shape=(L, M)
+ L facets visible from target_point
+ target_point: numpy.ndarray, shape=(1, M)
+ Value for which the extrapolation is performed (target point)
+
+ Returns
+ -------
+ extrapolation_weights: np.ndarray, shape=(L)
+ Weights for each visible facet, corresponding to the extrapolation
+ weight for the respective triangulation simplex. Weigths sum to unity.
+
+ References
+ ----------
+ .. [1] P. Alfred (1984). Triangular Extrapolation. Technical summary rept.,
+ Univ. of Wisconsin-Madison. https://apps.dtic.mil/sti/pdfs/ADA144660.pdf
+ """
+
+ angles = np.array(
+ [
+ point_facet_angle(line, target_point.squeeze())
+ for line in visible_facet_points
+ ]
+ )
+ weights = np.arccos(angles) ** (m + 1)
+
+ return weights / weights.sum()
+
+
+
+[docs]
+class ParametrizedVisibleEdgesExtrapolator(ParametrizedNearestSimplexExtrapolator):
+ """
+ Extrapolator using blending over visible edges.
+
+ While the ParametrizedNearestSimplexExtrapolator does not result in a smooth
+ extrapolation outside of the grid due to using only the nearest available
+ simplex, this extrapolator blends over all visible edges as discussed in [1].
+ For one grid-dimension this is equal to the ParametrizedNearestSimplexExtrapolator,
+ the same holds for grids consisting of only one simplex or constellations,
+ where only one simplex is visible from a target.
+
+ Parameters
+ ----------
+ grid_points: np.ndarray, shape=(N, ...)
+ Grid points at which templates exist. May be one ot two dimensional.
+ Have to be sorted in accending order for 1D.
+ params: np.ndarray, shape=(N, ...)
+ Array of corresponding parameter values at each point in grid_points.
+ First dimesion has to correspond to number of grid_points
+ m: non-zero int >= 1
+ Degree of smoothness wanted in the extrapolation region. See [1] for
+ additional information. Defaults to 1.
+
+ Raises
+ ------
+ TypeError:
+ If m is not a number
+ ValueError:
+ If m is not a non-zero integer
+
+ Note
+ ----
+ Also calls pyirf.interpolation.ParametrizedNearestSimplexExtrapolator.__init__.
+
+ References
+ ----------
+ .. [1] P. Alfred (1984). Triangular Extrapolation. Technical summary rept.,
+ Univ. of Wisconsin-Madison. https://apps.dtic.mil/sti/pdfs/ADA144660.pdf
+
+ """
+
+ def __init__(self, grid_points, params, m=1):
+ super().__init__(grid_points, params)
+
+ # Test wether m is a number
+ try:
+ m > 0
+ except TypeError:
+ raise TypeError(f"Only positive integers allowed for m, got {m}.")
+
+ # Test wether m is a finite, positive integer
+ if (m <= 0) or ~np.isfinite(m) or (m != int(m)):
+ raise ValueError(f"Only positive integers allowed for m, got {m}.")
+
+ self.m = m
+
+
+[docs]
+ def extrapolate(self, target_point):
+ if self.grid_dim == 1:
+ return super().extrapolate(target_point)
+ elif self.grid_dim == 2:
+ visible_facet_points = find_visible_facets(self.grid_points, target_point)
+
+ if visible_facet_points.shape[0] == 1:
+ return super().extrapolate(target_point)
+ else:
+ simplices_points = self.triangulation.points[
+ self.triangulation.simplices
+ ]
+
+ visible_simplices_indices = np.array(
+ [
+ find_simplex_to_facet(simplices_points, facet)
+ for facet in visible_facet_points
+ ]
+ )
+
+ extrapolation_weigths = compute_extrapolation_weights(
+ visible_facet_points, target_point, self.m
+ )
+
+ extrapolation_weigths = extrapolation_weigths.reshape(
+ extrapolation_weigths.shape[0],
+ *np.ones(self.params.ndim - 1, "int"),
+ )
+
+ # Function has to be copied outside list comprehention as the super() short-form
+ # cannot be used inside it (at least until python 3.11)
+ extrapolate2D = super()._extrapolate2D
+
+ simplex_extrapolations = np.array(
+ [
+ extrapolate2D(
+ self.triangulation.simplices[ind], target_point
+ ).squeeze()
+ for ind in visible_simplices_indices
+ ]
+ )
+
+ extrapolant = np.sum(
+ extrapolation_weigths * simplex_extrapolations, axis=0
+ )[np.newaxis, :]
+
+ return extrapolant
+
+
+
+import logging
+
+from astropy.table import QTable, unique
+import astropy.units as u
+
+from ..simulations import SimulatedEventsInfo
+
+
+log = logging.getLogger(__name__)
+
+
+COLUMN_MAP = {
+ "obs_id": "OBS_ID",
+ "event_id": "EVENT_ID",
+ "true_energy": "MC_ENERGY",
+ "reco_energy": "ENERGY",
+ "true_alt": "MC_ALT",
+ "true_az": "MC_AZ",
+ "pointing_alt": "PNT_ALT",
+ "pointing_az": "PNT_AZ",
+ "reco_alt": "ALT",
+ "reco_az": "AZ",
+ "gh_score": "GH_MVA",
+ "multiplicity": "MULTIP",
+}
+
+
+
+[docs]
+def read_eventdisplay_fits(infile, use_histogram=True):
+ """
+ Read a DL2 FITS file as produced by the EventDisplay DL2 converter
+ from ROOT files:
+ https://github.com/Eventdisplay/Converters/blob/master/DL2/generate_DL2_file.py
+
+ Parameters
+ ----------
+ infile : str or pathlib.Path
+ Path to the input fits file
+ use_histogram : bool
+ If True, use number of simulated events from histogram provided in fits file,
+ if False, estimate this number from the unique run_id, pointing direction
+ combinations and the number of events per run in the run header.
+ This will fail e.g. for protons with cuts already applied, since many
+ runs will have 0 events surviving cuts.
+
+ Returns
+ -------
+ events: astropy.QTable
+ Astropy Table object containing the reconstructed events information.
+ simulated_events: ``~pyirf.simulations.SimulatedEventsInfo``
+ """
+ log.debug(f"Reading {infile}")
+ events = QTable.read(infile, hdu="EVENTS")
+ sim_events = QTable.read(infile, hdu="SIMULATED EVENTS")
+ run_header = QTable.read(infile, hdu="RUNHEADER")[0]
+
+ for new, old in COLUMN_MAP.items():
+ events.rename_column(old, new)
+
+ n_runs = len(unique(events[['obs_id', 'pointing_az', 'pointing_alt']]))
+ log.info(f"Estimated number of runs from obs ids and pointing position: {n_runs}")
+
+ n_showers_guessed = n_runs * run_header["num_use"] * run_header["num_showers"]
+ n_showers_hist = int(sim_events["EVENTS"].sum())
+
+ if use_histogram:
+ n_showers = n_showers_hist
+ else:
+ n_showers = n_showers_guessed
+
+ log.debug("Number of events histogram: %d", n_showers_hist)
+ log.debug("Number of events from n_runs and run header: %d", n_showers_guessed)
+ log.debug("Using number of events from %s", "histogram" if use_histogram else "guess")
+
+ sim_info = SimulatedEventsInfo(
+ n_showers=n_showers,
+ energy_min=u.Quantity(run_header["E_range"][0], u.TeV),
+ energy_max=u.Quantity(run_header["E_range"][1], u.TeV),
+ max_impact=u.Quantity(run_header["core_range"][1], u.m),
+ spectral_index=run_header["spectral_index"],
+ viewcone_min=u.Quantity(run_header["viewcone"][0], u.deg),
+ viewcone_max=u.Quantity(run_header["viewcone"][1], u.deg),
+ )
+
+ return events, sim_info
+
+
+from astropy.table import QTable
+import astropy.units as u
+from astropy.io.fits import Header, BinTableHDU
+import numpy as np
+from astropy.time import Time
+import pyirf.binning as binning
+
+from ..version import __version__
+
+
+__all__ = [
+ "create_aeff2d_hdu",
+ "create_energy_dispersion_hdu",
+ "create_psf_table_hdu",
+ "create_rad_max_hdu",
+]
+
+
+DEFAULT_HEADER = Header()
+DEFAULT_HEADER["CREATOR"] = f"pyirf v{__version__}"
+# fmt: off
+DEFAULT_HEADER["HDUDOC"] = "https://github.com/open-gamma-ray-astro/gamma-astro-data-formats"
+DEFAULT_HEADER["HDUVERS"] = "0.2"
+DEFAULT_HEADER["HDUCLASS"] = "GADF"
+
+
+def _add_header_cards(header, **header_cards):
+ for k, v in header_cards.items():
+ header[k] = v
+
+
+
+[docs]
+@u.quantity_input(
+ effective_area=u.m ** 2, true_energy_bins=u.TeV, fov_offset_bins=u.deg
+)
+def create_aeff2d_hdu(
+ effective_area,
+ true_energy_bins,
+ fov_offset_bins,
+ extname="EFFECTIVE AREA",
+ point_like=True,
+ **header_cards,
+):
+ """
+ Create a fits binary table HDU in GADF format for effective area.
+ See the specification at
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/aeff/index.html
+
+ Parameters
+ ----------
+ effective_area: astropy.units.Quantity[area]
+ Effective area array, must have shape (n_energy_bins, n_fov_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+ point_like: bool
+ If the provided effective area was calculated after applying a direction cut,
+ pass ``True``, else ``False`` for a full-enclosure effective area.
+ extname: str
+ Name for BinTableHDU
+ **header_cards
+ Additional metadata to add to the header, use this to set e.g. TELESCOP or
+ INSTRUME.
+ """
+ aeff = QTable()
+ aeff["ENERG_LO"], aeff["ENERG_HI"] = binning.split_bin_lo_hi(true_energy_bins[np.newaxis, :].to(u.TeV))
+ aeff["THETA_LO"], aeff["THETA_HI"] = binning.split_bin_lo_hi(fov_offset_bins[np.newaxis, :].to(u.deg))
+ # transpose because FITS uses opposite dimension order than numpy
+ aeff["EFFAREA"] = effective_area.T[np.newaxis, ...].to(u.m ** 2)
+
+ # required header keywords
+ header = DEFAULT_HEADER.copy()
+ header["HDUCLAS1"] = "RESPONSE"
+ header["HDUCLAS2"] = "EFF_AREA"
+ header["HDUCLAS3"] = "POINT-LIKE" if point_like else "FULL-ENCLOSURE"
+ header["HDUCLAS4"] = "AEFF_2D"
+ header["DATE"] = Time.now().utc.iso
+ idx = aeff.colnames.index("EFFAREA") + 1
+ header[f"CREF{idx}"] = "(ENERG_LO:ENERG_HI,THETA_LO:THETA_HI)"
+ _add_header_cards(header, **header_cards)
+
+ return BinTableHDU(aeff, header=header, name=extname)
+
+
+
+
+[docs]
+@u.quantity_input(
+ psf=u.sr ** -1,
+ true_energy_bins=u.TeV,
+ source_offset_bins=u.deg,
+ fov_offset_bins=u.deg,
+)
+def create_psf_table_hdu(
+ psf,
+ true_energy_bins,
+ source_offset_bins,
+ fov_offset_bins,
+ extname="PSF",
+ **header_cards,
+):
+ """
+ Create a fits binary table HDU in GADF format for the PSF table.
+ See the specification at
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/psf/psf_table/index.html
+
+ Parameters
+ ----------
+ psf: astropy.units.Quantity[(solid angle)^-1]
+ Point spread function array, must have shape
+ (n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ source_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the source offset.
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+ extname: str
+ Name for BinTableHDU
+ **header_cards
+ Additional metadata to add to the header, use this to set e.g. TELESCOP or
+ INSTRUME.
+ """
+
+ psf_ = QTable()
+ psf_["ENERG_LO"], psf_["ENERG_HI"] = binning.split_bin_lo_hi(true_energy_bins[np.newaxis, :].to(u.TeV))
+ psf_["THETA_LO"], psf_["THETA_HI"] = binning.split_bin_lo_hi(fov_offset_bins[np.newaxis, :].to(u.deg))
+ psf_["RAD_LO"], psf_["RAD_HI"] = binning.split_bin_lo_hi(source_offset_bins[np.newaxis, :].to(u.deg))
+ # transpose as FITS uses opposite dimension order
+ psf_["RPSF"] = psf.T[np.newaxis, ...].to(1 / u.sr)
+
+ # required header keywords
+ header = DEFAULT_HEADER.copy()
+ header["HDUCLAS1"] = "RESPONSE"
+ header["HDUCLAS2"] = "PSF"
+ header["HDUCLAS3"] = "FULL-ENCLOSURE"
+ header["HDUCLAS4"] = "PSF_TABLE"
+ header["DATE"] = Time.now().utc.iso
+ idx = psf_.colnames.index("RPSF") + 1
+ header[f"CREF{idx}"] = "(ENERG_LO:ENERG_HI,THETA_LO:THETA_HI,RAD_LO:RAD_HI)"
+ _add_header_cards(header, **header_cards)
+
+ return BinTableHDU(psf_, header=header, name=extname)
+
+
+
+
+[docs]
+@u.quantity_input(
+ true_energy_bins=u.TeV, fov_offset_bins=u.deg,
+)
+def create_energy_dispersion_hdu(
+ energy_dispersion,
+ true_energy_bins,
+ migration_bins,
+ fov_offset_bins,
+ point_like=True,
+ extname="EDISP",
+ **header_cards,
+):
+ """
+ Create a fits binary table HDU in GADF format for the energy dispersion.
+ See the specification at
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/edisp/index.html
+
+ Parameters
+ ----------
+ energy_dispersion: numpy.ndarray
+ Energy dispersion array, must have shape
+ (n_energy_bins, n_migra_bins, n_source_offset_bins)
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ migration_bins: numpy.ndarray
+ Bin edges for the relative energy migration (``reco_energy / true_energy``)
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+ point_like: bool
+ If the provided effective area was calculated after applying a direction cut,
+ pass ``True``, else ``False`` for a full-enclosure effective area.
+ extname: str
+ Name for BinTableHDU
+ **header_cards
+ Additional metadata to add to the header, use this to set e.g. TELESCOP or
+ INSTRUME.
+ """
+
+ edisp = QTable()
+ edisp["ENERG_LO"], edisp["ENERG_HI"] = binning.split_bin_lo_hi(true_energy_bins[np.newaxis, :].to(u.TeV))
+ edisp["MIGRA_LO"], edisp["MIGRA_HI"] = binning.split_bin_lo_hi(migration_bins[np.newaxis, :])
+ edisp["THETA_LO"], edisp["THETA_HI"] = binning.split_bin_lo_hi(fov_offset_bins[np.newaxis, :].to(u.deg))
+ # transpose as FITS uses opposite dimension order
+ edisp["MATRIX"] = u.Quantity(energy_dispersion.T[np.newaxis, ...]).to(u.one)
+
+ # required header keywords
+ header = DEFAULT_HEADER.copy()
+ header["HDUCLAS1"] = "RESPONSE"
+ header["HDUCLAS2"] = "EDISP"
+ header["HDUCLAS3"] = "POINT-LIKE" if point_like else "FULL-ENCLOSURE"
+ header["HDUCLAS4"] = "EDISP_2D"
+ header["DATE"] = Time.now().utc.iso
+ idx = edisp.colnames.index("MATRIX") + 1
+ header[f"CREF{idx}"] = "(ENERG_LO:ENERG_HI,MIGRA_LO:MIGRA_HI,THETA_LO:THETA_HI)"
+ _add_header_cards(header, **header_cards)
+
+ return BinTableHDU(edisp, header=header, name=extname)
+
+
+
+#: Unit to store background rate in GADF format
+#:
+#: see https://github.com/open-gamma-ray-astro/gamma-astro-data-formats/issues/153
+#: for a discussion on why this is MeV not TeV as everywhere else
+GADF_BACKGROUND_UNIT = u.Unit("MeV-1 s-1 sr-1")
+
+
+
+[docs]
+@u.quantity_input(
+ background=GADF_BACKGROUND_UNIT, reco_energy_bins=u.TeV, fov_offset_bins=u.deg,
+)
+def create_background_2d_hdu(
+ background_2d,
+ reco_energy_bins,
+ fov_offset_bins,
+ extname="BACKGROUND",
+ **header_cards,
+):
+ """
+ Create a fits binary table HDU in GADF format for the background 2d table.
+ See the specification at
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/bkg/index.html#bkg-2d
+
+ Parameters
+ ----------
+ background_2d: astropy.units.Quantity[(MeV s sr)^-1]
+ Background rate, must have shape
+ (n_energy_bins, n_fov_offset_bins)
+ reco_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in reconstructed energy
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ extname: str
+ Name for BinTableHDU
+ **header_cards
+ Additional metadata to add to the header, use this to set e.g. TELESCOP or
+ INSTRUME.
+ """
+
+ bkg = QTable()
+ bkg["ENERG_LO"], bkg["ENERG_HI"] = binning.split_bin_lo_hi(reco_energy_bins[np.newaxis, :].to(u.TeV))
+ bkg["THETA_LO"], bkg["THETA_HI"] = binning.split_bin_lo_hi(fov_offset_bins[np.newaxis, :].to(u.deg))
+ # transpose as FITS uses opposite dimension order
+ bkg["BKG"] = background_2d.T[np.newaxis, ...].to(GADF_BACKGROUND_UNIT)
+
+ # required header keywords
+ header = DEFAULT_HEADER.copy()
+ header["HDUCLAS1"] = "RESPONSE"
+ header["HDUCLAS2"] = "BKG"
+ header["HDUCLAS3"] = "FULL-ENCLOSURE"
+ header["HDUCLAS4"] = "BKG_2D"
+ header["DATE"] = Time.now().utc.iso
+ idx = bkg.colnames.index("BKG") + 1
+ header[f"CREF{idx}"] = "(ENERG_LO:ENERG_HI,THETA_LO:THETA_HI)"
+ _add_header_cards(header, **header_cards)
+
+ return BinTableHDU(bkg, header=header, name=extname)
+
+
+
+
+[docs]
+@u.quantity_input(
+ rad_max=u.deg,
+ reco_energy_bins=u.TeV,
+ fov_offset_bins=u.deg,
+)
+def create_rad_max_hdu(
+ rad_max,
+ reco_energy_bins,
+ fov_offset_bins,
+ point_like=True,
+ extname="RAD_MAX",
+ **header_cards,
+):
+ """
+ Create a fits binary table HDU in GADF format for the directional cut.
+ See the specification at
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/point_like/index.html#rad-max
+
+ Parameters
+ ----------
+ rad_max: astropy.units.Quantity[angle]
+ Array of the directional (theta) cut.
+ Must have shape (n_reco_energy_bins, n_fov_offset_bins)
+ reco_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in reconstructed energy
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+ extname: str
+ Name for BinTableHDU
+ **header_cards
+ Additional metadata to add to the header, use this to set e.g. TELESCOP or
+ INSTRUME.
+ """
+
+ rad_max_table = QTable()
+ rad_max_table["ENERG_LO"], rad_max_table["ENERG_HI"] = binning.split_bin_lo_hi(reco_energy_bins[np.newaxis, :].to(u.TeV))
+ rad_max_table["THETA_LO"], rad_max_table["THETA_HI"] = binning.split_bin_lo_hi(fov_offset_bins[np.newaxis, :].to(u.deg))
+ # transpose as FITS uses opposite dimension order
+ rad_max_table["RAD_MAX"] = rad_max.T[np.newaxis, ...].to(u.deg)
+
+ # required header keywords
+ header = DEFAULT_HEADER.copy()
+ header["HDUCLAS1"] = "RESPONSE"
+ header["HDUCLAS2"] = "RAD_MAX"
+ header["HDUCLAS3"] = "POINT-LIKE"
+ header["HDUCLAS4"] = "RAD_MAX_2D"
+ header["DATE"] = Time.now().utc.iso
+ idx = rad_max_table.colnames.index("RAD_MAX") + 1
+ header[f"CREF{idx}"] = "(ENERG_LO:ENERG_HI,THETA_LO:THETA_HI)"
+ _add_header_cards(header, **header_cards)
+
+ return BinTableHDU(rad_max_table, header=header, name=extname)
+
+
+import astropy.units as u
+import numpy as np
+
+from ..utils import cone_solid_angle
+
+#: Unit of the background rate IRF
+BACKGROUND_UNIT = u.Unit('s-1 TeV-1 sr-1')
+
+
+
+[docs]
+def background_2d(events, reco_energy_bins, fov_offset_bins, t_obs):
+ """
+ Calculate background rates in radially symmetric bins in the field of view.
+
+ GADF documentation here:
+ https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/bkg/index.html#bkg-2d
+
+ Parameters
+ ----------
+ events: astropy.table.QTable
+ DL2 events table of the selected background events.
+ Needed columns for this function: `reco_source_fov_offset`, `reco_energy`, `weight`
+ reco_energy: astropy.units.Quantity[energy]
+ The bins in reconstructed energy to be used for the IRF
+ fov_offset_bins: astropy.units.Quantity[angle]
+ The bins in the field of view offset to be used for the IRF
+ t_obs: astropy.units.Quantity[time]
+ Observation time. This must match with how the individual event
+ weights are calculated.
+
+ Returns
+ -------
+ bg_rate: astropy.units.Quantity
+ The background rate as particles per energy, time and solid angle
+ in the specified bins.
+
+ Shape: (len(reco_energy_bins) - 1, len(fov_offset_bins) - 1)
+ """
+
+ hist, _, _ = np.histogram2d(
+ events["reco_energy"].to_value(u.TeV),
+ events["reco_source_fov_offset"].to_value(u.deg),
+ bins=[
+ reco_energy_bins.to_value(u.TeV),
+ fov_offset_bins.to_value(u.deg),
+ ],
+ weights=events['weight'],
+ )
+
+ # divide all energy bins by their width
+ # hist has shape (n_energy, n_fov_offset) so we need to transpose and then back
+ bin_width_energy = np.diff(reco_energy_bins)
+ per_energy = (hist.T / bin_width_energy).T
+
+ # divide by solid angle in each fov bin and the observation time
+ bin_solid_angle = np.diff(cone_solid_angle(fov_offset_bins))
+ bg_rate = per_energy / t_obs / bin_solid_angle
+
+ return bg_rate.to(BACKGROUND_UNIT)
+
+
+import numpy as np
+import astropy.units as u
+from ..binning import create_histogram_table
+
+
+__all__ = [
+ "effective_area",
+ "effective_area_per_energy",
+ "effective_area_per_energy_and_fov",
+]
+
+
+
+[docs]
+@u.quantity_input(area=u.m ** 2)
+def effective_area(n_selected, n_simulated, area):
+ """
+ Calculate effective area for histograms of selected and total simulated events
+
+ Parameters
+ ----------
+ n_selected: int or numpy.ndarray[int]
+ The number of surviving (e.g. triggered, analysed, after cuts)
+ n_simulated: int or numpy.ndarray[int]
+ The total number of events simulated
+ area: astropy.units.Quantity[area]
+ Area in which particle's core position was simulated
+ """
+ return (n_selected / n_simulated) * area
+
+
+
+
+[docs]
+def effective_area_per_energy(selected_events, simulation_info, true_energy_bins):
+ """
+ Calculate effective area in bins of true energy.
+
+ Parameters
+ ----------
+ selected_events: astropy.table.QTable
+ DL2 events table, required columns for this function: `true_energy`.
+ simulation_info: pyirf.simulations.SimulatedEventsInfo
+ The overall statistics of the simulated events
+ true_energy_bins: astropy.units.Quantity[energy]
+ The bin edges in which to calculate effective area.
+ """
+ area = np.pi * simulation_info.max_impact ** 2
+
+ hist_selected = create_histogram_table(
+ selected_events, true_energy_bins, "true_energy"
+ )
+ hist_simulated = simulation_info.calculate_n_showers_per_energy(true_energy_bins)
+
+ return effective_area(hist_selected["n"], hist_simulated, area)
+
+
+
+
+[docs]
+def effective_area_per_energy_and_fov(
+ selected_events, simulation_info, true_energy_bins, fov_offset_bins
+):
+ """
+ Calculate effective area in bins of true energy and field of view offset.
+
+ Parameters
+ ----------
+ selected_events: astropy.table.QTable
+ DL2 events table, required columns for this function:
+ - `true_energy`
+ - `true_source_fov_offset`
+ simulation_info: pyirf.simulations.SimulatedEventsInfo
+ The overall statistics of the simulated events
+ true_energy_bins: astropy.units.Quantity[energy]
+ The true energy bin edges in which to calculate effective area.
+ fov_offset_bins: astropy.units.Quantity[angle]
+ The field of view radial bin edges in which to calculate effective area.
+ """
+ area = np.pi * simulation_info.max_impact ** 2
+
+ hist_simulated = simulation_info.calculate_n_showers_per_energy_and_fov(
+ true_energy_bins, fov_offset_bins
+ )
+
+ hist_selected, _, _ = np.histogram2d(
+ selected_events["true_energy"].to_value(u.TeV),
+ selected_events["true_source_fov_offset"].to_value(u.deg),
+ bins=[
+ true_energy_bins.to_value(u.TeV),
+ fov_offset_bins.to_value(u.deg),
+ ],
+ )
+
+ return effective_area(hist_selected, hist_simulated, area)
+
+
+import warnings
+import numpy as np
+import astropy.units as u
+from ..binning import resample_histogram1d
+
+
+__all__ = [
+ "energy_dispersion",
+ "energy_dispersion_to_migration"
+]
+
+
+def _normalize_hist(hist, migration_bins):
+ # make sure we do not mutate the input array
+ hist = hist.copy()
+ bin_width = np.diff(migration_bins)
+
+ # calculate number of events along the N_MIGRA axis to get events
+ # per energy per fov
+ norm = hist.sum(axis=1)
+
+ with np.errstate(invalid="ignore"):
+ # hist shape is (N_E, N_MIGRA, N_FOV), norm shape is (N_E, N_FOV)
+ # so we need to add a new axis in the middle to get (N_E, 1, N_FOV)
+ # bin_width is 1d, so we need newaxis, use the values, newaxis
+ hist = hist / norm[:, np.newaxis, :] / bin_width[np.newaxis, :, np.newaxis]
+
+ return np.nan_to_num(hist)
+
+
+
+[docs]
+def energy_dispersion(
+ selected_events, true_energy_bins, fov_offset_bins, migration_bins,
+):
+ """
+ Calculate energy dispersion for the given DL2 event list.
+ Energy dispersion is defined as the probability of finding an event
+ at a given relative deviation ``(reco_energy / true_energy)`` for a given
+ true energy.
+
+ Parameters
+ ----------
+ selected_events: astropy.table.QTable
+ Table of the DL2 events.
+ Required columns: ``reco_energy``, ``true_energy``, ``true_source_fov_offset``.
+ true_energy_bins: astropy.units.Quantity[energy]
+ Bin edges in true energy
+ migration_bins: astropy.units.Quantity[energy]
+ Bin edges in relative deviation, recommended range: [0.2, 5]
+ fov_offset_bins: astropy.units.Quantity[angle]
+ Bin edges in the field of view offset.
+ For Point-Like IRFs, only giving a single bin is appropriate.
+
+ Returns
+ -------
+ energy_dispersion: numpy.ndarray
+ Energy dispersion matrix
+ with shape (n_true_energy_bins, n_migration_bins, n_fov_ofset_bins)
+ """
+ mu = (selected_events["reco_energy"] / selected_events["true_energy"]).to_value(
+ u.one
+ )
+
+ energy_dispersion, _ = np.histogramdd(
+ np.column_stack(
+ [
+ selected_events["true_energy"].to_value(u.TeV),
+ mu,
+ selected_events["true_source_fov_offset"].to_value(u.deg),
+ ]
+ ),
+ bins=[
+ true_energy_bins.to_value(u.TeV),
+ migration_bins,
+ fov_offset_bins.to_value(u.deg),
+ ],
+ )
+
+ energy_dispersion = _normalize_hist(energy_dispersion, migration_bins)
+
+ return energy_dispersion
+
+
+
+def energy_dispersion_to_migration(
+ dispersion_matrix,
+ disp_true_energy_edges,
+ disp_migration_edges,
+ new_true_energy_edges,
+ new_reco_energy_edges,
+):
+ """
+ Construct a energy migration matrix from a energy
+ dispersion matrix.
+ Depending on the new energy ranges, the sum over the first axis
+ can be smaller than 1.
+ The new true energy bins need to be a subset of the old range,
+ extrapolation is not supported.
+ New reconstruction bins outside of the old migration range are filled with
+ zeros.
+
+ Parameters
+ ----------
+ dispersion_matrix: numpy.ndarray
+ Energy dispersion_matrix
+ disp_true_energy_edges: astropy.units.Quantity[energy]
+ True energy edges matching the first dimension of the dispersion matrix
+ disp_migration_edges: numpy.ndarray
+ Migration edges matching the second dimension of the dispersion matrix
+ new_true_energy_edges: astropy.units.Quantity[energy]
+ True energy edges matching the first dimension of the output
+ new_reco_energy_edges: astropy.units.Quantity[energy]
+ Reco energy edges matching the second dimension of the output
+
+ Returns:
+ --------
+ migration_matrix: numpy.ndarray
+ Three-dimensional energy migration matrix. The third dimension
+ equals the fov offset dimension of the energy dispersion matrix.
+ """
+
+ migration_matrix = np.zeros((
+ len(new_true_energy_edges) - 1,
+ len(new_reco_energy_edges) - 1,
+ dispersion_matrix.shape[2],
+ ))
+
+ true_energy_interpolation = resample_histogram1d(
+ dispersion_matrix,
+ disp_true_energy_edges,
+ new_true_energy_edges,
+ axis=0,
+ )
+
+ norm = np.sum(true_energy_interpolation, axis=1, keepdims=True)
+ norm[norm == 0] = 1
+ true_energy_interpolation /= norm
+
+ for idx, e_true in enumerate(
+ (new_true_energy_edges[1:] + new_true_energy_edges[:-1]) / 2
+ ):
+
+ # get migration for the new true energy bin
+ e_true_dispersion = true_energy_interpolation[idx]
+
+ with warnings.catch_warnings():
+ # silence inf/inf division warning
+ warnings.filterwarnings('ignore', 'invalid value encountered in true_divide')
+ interpolation_edges = new_reco_energy_edges / e_true
+
+ y = resample_histogram1d(
+ e_true_dispersion,
+ disp_migration_edges,
+ interpolation_edges,
+ axis=0,
+ )
+
+ migration_matrix[idx, :, :] = y
+
+ return migration_matrix
+
+import numpy as np
+import astropy.units as u
+
+from ..utils import cone_solid_angle
+
+
+
+[docs]
+def psf_table(events, true_energy_bins, source_offset_bins, fov_offset_bins):
+ """
+ Calculate the table based PSF (radially symmetrical bins around the true source)
+ """
+
+ array = np.column_stack(
+ [
+ events["true_energy"].to_value(u.TeV),
+ events["true_source_fov_offset"].to_value(u.deg),
+ events["theta"].to_value(u.deg),
+ ]
+ )
+
+ hist, _ = np.histogramdd(
+ array,
+ [
+ true_energy_bins.to_value(u.TeV),
+ fov_offset_bins.to_value(u.deg),
+ source_offset_bins.to_value(u.deg),
+ ],
+ )
+
+ psf = _normalize_psf(hist, source_offset_bins)
+ return psf
+
+
+
+def _normalize_psf(hist, source_offset_bins):
+ """Normalize the psf histogram to a probability densitity over solid angle"""
+ solid_angle = np.diff(cone_solid_angle(source_offset_bins))
+
+ # ignore numpy zero division warning
+ with np.errstate(invalid="ignore"):
+
+ # normalize over the theta axis
+ n_events = hist.sum(axis=2)
+ # normalize and replace nans with 0
+ psf = np.nan_to_num(hist / n_events[:, :, np.newaxis])
+
+ return psf / solid_angle
+
+"""
+Functions to calculate sensitivity
+"""
+import numpy as np
+from scipy.optimize import brentq
+import logging
+
+from astropy.table import QTable
+import astropy.units as u
+
+from .statistics import li_ma_significance
+from .utils import check_histograms, cone_solid_angle
+from .binning import create_histogram_table, bin_center
+
+
+__all__ = [
+ "relative_sensitivity",
+ "calculate_sensitivity",
+ "estimate_background",
+]
+
+
+log = logging.getLogger(__name__)
+
+
+def _relative_sensitivity(
+ n_on,
+ n_off,
+ alpha,
+ min_significance=5,
+ min_signal_events=10,
+ min_excess_over_background=0.05,
+ significance_function=li_ma_significance,
+):
+ if np.isnan(n_on) or np.isnan(n_off):
+ return np.nan
+
+ if n_on < 0 or n_off < 0:
+ raise ValueError(f'n_on and n_off must be positive, got {n_on}, {n_off}')
+
+ n_background = n_off * alpha
+ n_signal = n_on - n_background
+
+ if n_signal <= 0:
+ return np.inf
+
+ def equation(relative_flux):
+ n_on = n_signal * relative_flux + n_background
+ s = significance_function(n_on, n_off, alpha)
+ return s - min_significance
+
+ try:
+ # brentq needs a lower and an upper bound
+ # we will use the simple, analytically solvable significance formula and scale it
+ # with 10 to be sure it's above the Li and Ma solution
+ # so rel * n_signal / sqrt(n_background) = target_significance
+ if n_off > 1:
+ relative_flux_naive = min_significance * np.sqrt(n_background) / n_signal
+ upper_bound = 10 * relative_flux_naive
+ lower_bound = 0.01 * relative_flux_naive
+ else:
+ upper_bound = 100
+ lower_bound = 1e-4
+
+ relative_flux = brentq(equation, lower_bound, upper_bound)
+
+ except (RuntimeError, ValueError) as e:
+ log.warn(
+ "Could not calculate relative significance for"
+ f" n_signal={n_signal:.1f}, n_off={n_off:.1f}, returning nan {e}"
+ )
+ return np.nan
+
+ # scale to achieved flux level
+ n_signal = n_signal * relative_flux
+ min_excess = min_excess_over_background * n_background
+ min_signal = max(min_signal_events, min_excess)
+
+ # if we violate the min signal events condition,
+ # increase flux until we meet the requirement
+ if n_signal < min_signal:
+ scale = min_signal / n_signal
+ else:
+ scale = 1.0
+
+ return relative_flux * scale
+
+
+_relative_sensitivity_vectorized = np.vectorize(
+ _relative_sensitivity,
+ excluded=['significance_function']
+)
+
+
+
+[docs]
+def relative_sensitivity(
+ n_on,
+ n_off,
+ alpha,
+ min_significance=5,
+ min_signal_events=10,
+ min_excess_over_background=0.05,
+ significance_function=li_ma_significance,
+):
+ """
+ Calculate the relative sensitivity defined as the flux
+ relative to the reference source that is detectable with
+ significance ``target_significance``.
+
+ Given measured ``n_on`` and ``n_off``,
+ we estimate the number of gamma events ``n_signal`` as ``n_on - alpha * n_off``.
+
+ The number of background events ``n_background` is estimated as ``n_off * alpha``.
+
+ In the end, we find the relative sensitivity as the scaling factor for ``n_signal``
+ that yields a significance of ``target_significance``.
+
+ The reference time should be incorporated by appropriately weighting the events
+ before calculating ``n_on`` and ``n_off``.
+
+ All input values with the exception of ``significance_function``
+ must be broadcastable to a single, common shape.
+
+ Parameters
+ ----------
+ n_on: int or array-like
+ Number of signal-like events for the on observations
+ n_off: int or array-like
+ Number of signal-like events for the off observations
+ alpha: float or array-like
+ Scaling factor between on and off observations.
+ 1 / number of off regions for wobble observations.
+ min_significance: float or array-like
+ Significance necessary for a detection
+ min_signal_events: int or array-like
+ Minimum number of signal events required.
+ The relative flux will be scaled up from the one yielding ``min_significance``
+ if this condition is violated.
+ min_excess_over_background: float or array-like
+ Minimum number of signal events expressed as the proportion of the
+ background.
+ So the required number of signal events will be
+ ``min_excess_over_background * alpha * n_off``.
+ The relative flux will be scaled up from the one yielding ``min_significance``
+ if this condition is violated.
+ significance_function: function
+ A function f(n_on, n_off, alpha) -> significance in sigma
+ Used to calculate the significance, default is the Li&Ma
+ likelihood ratio test formula.
+ Li, T-P., and Y-Q. Ma.
+ "Analysis methods for results in gamma-ray astronomy."
+ The Astrophysical Journal 272 (1983): 317-324.
+ Formula (17)
+ """
+ return _relative_sensitivity_vectorized(
+ n_on=n_on,
+ n_off=n_off,
+ alpha=alpha,
+ min_significance=min_significance,
+ min_signal_events=min_signal_events,
+ min_excess_over_background=min_excess_over_background,
+ significance_function=significance_function,
+ )
+
+
+
+
+[docs]
+def calculate_sensitivity(
+ signal_hist,
+ background_hist,
+ alpha,
+ min_significance=5,
+ min_signal_events=10,
+ min_excess_over_background=0.05,
+ significance_function=li_ma_significance,
+):
+ """
+ Calculate sensitivity for DL2 event lists in bins of reconstructed energy.
+
+ Sensitivity is defined as the minimum flux detectable with ``target_significance``
+ sigma significance in a certain time.
+
+ This time must be incorporated into the event weights.
+
+ Two conditions are required for the sensitivity:
+ - At least ten weighted signal events
+ - The weighted signal must be larger than 5 % of the weighted background
+ - At least 5 sigma (so relative_sensitivity > 1)
+
+ If the conditions are not met, the sensitivity will be set to nan.
+
+ Parameters
+ ----------
+ signal_hist: astropy.table.QTable
+ Histogram of detected signal events as a table.
+ Required columns: n and n_weighted.
+ See ``pyirf.binning.create_histogram_table``
+ background_hist: astropy.table.QTable
+ Histogram of detected events as a table.
+ Required columns: n and n_weighted.
+ See ``pyirf.binning.create_histogram_table``
+ alpha: float
+ Size ratio of signal region to background region
+ min_significance: float
+ Significance necessary for a detection
+ min_signal_events: int
+ Minimum number of signal events required.
+ The relative flux will be scaled up from the one yielding ``min_significance``
+ if this condition is violated.
+ min_excess_over_background: float
+ Minimum number of signal events expressed as the proportion of the
+ background.
+ So the required number of signal events will be
+ ``min_excess_over_background * alpha * n_off``.
+ The relative flux will be scaled up from the one yielding ``min_significance``
+ if this condition is violated.
+ significance_function: callable
+ A function with signature (n_on, n_off, alpha) -> significance.
+ Default is the Li & Ma likelihood ratio test.
+
+ Returns
+ -------
+ sensitivity_table: astropy.table.QTable
+ Table with sensitivity information.
+ Contains weighted and unweighted number of signal and background events
+ and the ``relative_sensitivity``, the scaling applied to the signal events
+ that yields ``target_significance`` sigma of significance according to
+ the ``significance_function``
+ """
+ check_histograms(signal_hist, background_hist)
+
+ n_on = signal_hist["n_weighted"] + alpha * background_hist["n_weighted"]
+
+ # convert any quantities to arrays,
+ # since quantitites don't work with vectorize
+ n_on = u.Quantity(n_on, copy=False).to_value(u.one)
+ n_off = u.Quantity(background_hist["n_weighted"], copy=False).to_value(u.one)
+
+ # calculate sensitivity in each bin
+ rel_sens = relative_sensitivity(
+ n_on=n_on,
+ n_off=n_off,
+ alpha=alpha,
+ min_significance=min_significance,
+ min_signal_events=min_signal_events,
+ min_excess_over_background=min_excess_over_background,
+ significance_function=significance_function,
+ )
+
+ # fill output table
+ s = QTable()
+ for key in ("low", "high", "center"):
+ k = "reco_energy_" + key
+ s[k] = signal_hist[k]
+
+ with np.errstate(invalid="ignore"):
+ s["n_signal"] = signal_hist["n"] * rel_sens
+ s["n_signal_weighted"] = signal_hist["n_weighted"] * rel_sens
+ s["n_background"] = background_hist["n"]
+ s["n_background_weighted"] = background_hist["n_weighted"]
+
+ # copy also "n_proton" / "n_electron_weighted" etc. if available
+ for k in filter(lambda c: c.startswith('n_') and c != 'n_weighted', background_hist.colnames):
+ s[k] = background_hist[k]
+
+ s["significance"] = significance_function(
+ n_on=s["n_signal_weighted"] + alpha * s["n_background_weighted"],
+ n_off=s["n_background_weighted"],
+ alpha=alpha,
+ )
+ s["relative_sensitivity"] = rel_sens
+
+ return s
+
+
+
+
+[docs]
+def estimate_background(
+ events, reco_energy_bins, theta_cuts, alpha,
+ fov_offset_min, fov_offset_max,
+):
+ '''
+ Estimate the number of background events for a point-like sensitivity.
+
+ Due to limited statistics, it is often not possible to just apply the same
+ theta cut to the background events as to the signal events around an assumed
+ source position.
+
+ Here we calculate the expected number of background events for the off
+ regions by taking all background events between ``fov_offset_min`` and
+ ``fov_offset_max`` from the camera center and then scale these to the size
+ of the off region, which is scaled by 1 / alpha from the size of the on
+ region given by the theta cuts.
+
+
+ Parameters
+ ----------
+ events: astropy.table.QTable
+ DL2 event list of background surviving event selection
+ and inside ``fov_offset_max`` from the center of the FOV
+ Required columns for this function:
+ - `reco_energy`,
+ - `reco_source_fov_offset`.
+ reco_energy_bins: astropy.units.Quantity[energy]
+ Desired bin edges in reconstructed energy for the background rate
+ theta_cuts: astropy.table.QTable
+ The cuts table for the theta cut,
+ e.g. as returned by ``~pyirf.cuts.calculate_percentile_cut``.
+ Columns `center` and `cut` are required for this function.
+ alpha: float
+ size of the on region divided by the size of the off region.
+ fov_offset_min: astropy.units.Quantity[angle]
+ Minimum distance from the fov center for background events to be taken into account
+ fov_offset_max: astropy.units.Quantity[angle]
+ Maximum distance from the fov center for background events to be taken into account
+ '''
+ in_ring = (
+ (events['reco_source_fov_offset'] >= fov_offset_min)
+ & (events['reco_source_fov_offset'] < fov_offset_max)
+ )
+
+ bg = create_histogram_table(
+ events[in_ring],
+ reco_energy_bins,
+ key='reco_energy',
+ )
+
+ # scale number of background events according to the on region size
+ # background radius and alpha
+ center = bin_center(reco_energy_bins)
+ # interpolate the theta cut to the bins used here
+ theta_cuts_bg_bins = np.interp(
+ center,
+ theta_cuts['center'],
+ theta_cuts['cut']
+ )
+
+ solid_angle_on = cone_solid_angle(theta_cuts_bg_bins)
+ solid_angle_ring = cone_solid_angle(fov_offset_max) - cone_solid_angle(fov_offset_min)
+ size_ratio = (solid_angle_on / solid_angle_ring).to_value(u.one)
+
+ for key in filter(lambda col: col.startswith('n'), bg.colnames):
+ # *= not possible due to upcast from int to float
+ bg[key] = bg[key] * size_ratio / alpha
+
+ return bg
+
+
+import astropy.units as u
+import numpy as np
+
+__all__ = [
+ 'SimulatedEventsInfo',
+]
+
+
+
+[docs]
+class SimulatedEventsInfo:
+ """
+ Information about all simulated events, for calculating event weights.
+
+ Attributes
+ ----------
+ n_showers: int
+ Total number of simulated showers. If reuse was used, this
+ should already include the reuse.
+ energy_min: u.Quantity[energy]
+ Lower limit of the simulated energy range
+ energy_max: u.Quantity[energy]
+ Upper limit of the simulated energy range
+ max_impact: u.Quantity[length]
+ Maximum simulated impact parameter
+ spectral_index: float
+ Spectral Index of the simulated power law with sign included.
+ viewcone_min: u.Quantity[angle]
+ Inner angle of the viewcone
+ viewcone_max: u.Quantity[angle]
+ Outer angle of the viewcone
+ """
+
+ __slots__ = (
+ "n_showers",
+ "energy_min",
+ "energy_max",
+ "max_impact",
+ "spectral_index",
+ "viewcone_min",
+ "viewcone_max",
+ )
+
+ @u.quantity_input(
+ energy_min=u.TeV, energy_max=u.TeV, max_impact=u.m, viewcone_min=u.deg, viewcone_max=u.deg
+ )
+ def __init__(
+ self, n_showers, energy_min, energy_max, max_impact, spectral_index, viewcone_min, viewcone_max,
+ ):
+ #: Total number of simulated showers, if reuse was used, this must
+ #: already include reuse
+ self.n_showers = n_showers
+ #: Lower limit of the simulated energy range
+ self.energy_min = energy_min
+ #: Upper limit of the simulated energy range
+ self.energy_max = energy_max
+ #: Maximum simualted impact radius
+ self.max_impact = max_impact
+ #: Spectral index of the simulated power law with sign included
+ self.spectral_index = spectral_index
+ #: Inner viewcone angle
+ self.viewcone_min = viewcone_min
+ #: Outer viewcone angle
+ self.viewcone_max = viewcone_max
+
+ if spectral_index > -1:
+ raise ValueError("spectral index must be <= -1")
+
+
+[docs]
+ @u.quantity_input(energy_bins=u.TeV)
+ def calculate_n_showers_per_energy(self, energy_bins):
+ """
+ Calculate number of showers that were simulated in the given energy intervals
+
+ This assumes the events were generated and from a powerlaw
+ like CORSIKA simulates events.
+
+ Parameters
+ ----------
+ energy_bins: astropy.units.Quantity[energy]
+ The interval edges for which to calculate the number of simulated showers
+
+ Returns
+ -------
+ n_showers: numpy.ndarray
+ The expected number of events inside each of the ``energy_bins``.
+ This is a floating point number.
+ The actual numbers will follow a poissionian distribution around this
+ expected value.
+ """
+ bins = energy_bins
+ e_low = bins[:-1]
+ e_high = bins[1:]
+ e_min = self.energy_min
+ e_max = self.energy_max
+
+ integral = _powerlaw_pdf_integral(
+ self.spectral_index, e_low, e_high, e_min, e_max
+ )
+
+ integral[e_high <= e_min] = 0
+ integral[e_low >= e_max] = 0
+
+ mask = (e_high > e_max) & (e_low < e_max)
+ integral[mask] = _powerlaw_pdf_integral(
+ self.spectral_index, e_low[mask], e_max, e_min, e_max
+ )
+
+ mask = (e_high > e_min) & (e_low < e_min)
+ integral[mask] = _powerlaw_pdf_integral(
+ self.spectral_index, e_min, e_high[mask], e_min, e_max
+ )
+
+ return self.n_showers * integral
+
+
+
+[docs]
+ def calculate_n_showers_per_fov(self, fov_bins):
+ """
+ Calculate number of showers that were simulated in the given fov bins.
+
+ This assumes the events were generated uniformly distributed per solid angle,
+ like CORSIKA simulates events with the VIEWCONE option.
+
+ Parameters
+ ----------
+ fov_bins: astropy.units.Quantity[angle]
+ The FOV bin edges for which to calculate the number of simulated showers
+
+ Returns
+ -------
+ n_showers: numpy.ndarray(ndim=2)
+ The expected number of events inside each of the ``fov_bins``.
+ This is a floating point number.
+ The actual numbers will follow a poissionian distribution around this
+ expected value.
+ """
+ fov_bins = fov_bins
+ fov_low = fov_bins[:-1]
+ fov_high = fov_bins[1:]
+ fov_integral = _viewcone_pdf_integral(self.viewcone_min, self.viewcone_max, fov_low, fov_high)
+ return self.n_showers * fov_integral
+
+
+
+[docs]
+ @u.quantity_input(energy_bins=u.TeV, fov_bins=u.deg)
+ def calculate_n_showers_per_energy_and_fov(self, energy_bins, fov_bins):
+ """
+ Calculate number of showers that were simulated in the given
+ energy and fov bins.
+
+ This assumes the events were generated uniformly distributed per solid angle,
+ and from a powerlaw in energy like CORSIKA simulates events.
+
+ Parameters
+ ----------
+ energy_bins: astropy.units.Quantity[energy]
+ The energy bin edges for which to calculate the number of simulated showers
+ fov_bins: astropy.units.Quantity[angle]
+ The FOV bin edges for which to calculate the number of simulated showers
+
+ Returns
+ -------
+ n_showers: numpy.ndarray(ndim=2)
+ The expected number of events inside each of the
+ ``energy_bins`` and ``fov_bins``.
+ Dimension (n_energy_bins, n_fov_bins)
+ This is a floating point number.
+ The actual numbers will follow a poissionian distribution around this
+ expected value.
+ """
+ # energy distribution and fov distribution are independent in CORSIKA,
+ # so just multiply both distributions.
+ e_integral = self.calculate_n_showers_per_energy(energy_bins)
+ fov_integral = self.calculate_n_showers_per_fov(fov_bins)
+ return e_integral[:, np.newaxis] * fov_integral / self.n_showers
+
+
+ def __repr__(self):
+ return (
+ f"{self.__class__.__name__}("
+ f"n_showers={self.n_showers}, "
+ f"energy_min={self.energy_min:.3f}, "
+ f"energy_max={self.energy_max:.2f}, "
+ f"spectral_index={self.spectral_index:.1f}, "
+ f"max_impact={self.max_impact:.2f}, "
+ f"viewcone_min={self.viewcone_min}"
+ f"viewcone_max={self.viewcone_max}"
+ ")"
+ )
+
+
+
+def _powerlaw_pdf_integral(index, e_low, e_high, e_min, e_max):
+ # strip units, make sure all in the same unit
+ e_low = e_low.to_value(u.TeV)
+ e_high = e_high.to_value(u.TeV)
+ e_min = e_min.to_value(u.TeV)
+ e_max = e_max.to_value(u.TeV)
+
+ int_index = index + 1
+ normalization = 1 / (e_max ** int_index - e_min ** int_index)
+ e_term = e_high ** int_index - e_low ** int_index
+ return e_term * normalization
+
+
+def _viewcone_pdf_integral(viewcone_min, viewcone_max, fov_low, fov_high):
+ """
+ CORSIKA draws particles in the viewcone uniform per solid angle between
+ viewcone_min and viewcone_max, the associated pdf is:
+
+ pdf(theta, theta_min, theta_max) = sin(theta) / (cos(theta_min) - cos(theta_max))
+ """
+ scalar = np.asanyarray(fov_low).ndim == 0
+
+ fov_low = np.atleast_1d(fov_low)
+ fov_high = np.atleast_1d(fov_high)
+
+ if (viewcone_max - viewcone_min).value == 0:
+ raise ValueError("Only supported for diffuse simulations")
+ else:
+ norm = 1 / (np.cos(viewcone_min) - np.cos(viewcone_max))
+
+ inside = (fov_high >= viewcone_min) & (fov_low <= viewcone_max)
+
+ integral = np.zeros(fov_low.shape)
+ lower = np.where(fov_low[inside] > viewcone_min, fov_low[inside], viewcone_min)
+ upper = np.where(fov_high[inside] < viewcone_max, fov_high[inside], viewcone_max)
+
+ integral[inside] = np.cos(lower) - np.cos(upper)
+ integral *= norm
+
+ if scalar:
+ return np.squeeze(integral)
+ return integral
+
+"""
+Functions and classes for calculating spectral weights
+"""
+import sys
+from importlib.resources import as_file, files
+
+import astropy.units as u
+import numpy as np
+from astropy.table import QTable
+from scipy.interpolate import interp1d
+
+from .utils import cone_solid_angle
+
+#: Unit of a point source flux
+#:
+#: Number of particles per Energy, time and area
+POINT_SOURCE_FLUX_UNIT = (1 / u.TeV / u.s / u.m**2).unit
+
+#: Unit of a diffuse flux
+#:
+#: Number of particles per Energy, time, area and solid_angle
+DIFFUSE_FLUX_UNIT = POINT_SOURCE_FLUX_UNIT / u.sr
+
+
+__all__ = [
+ "POINT_SOURCE_FLUX_UNIT",
+ "DIFFUSE_FLUX_UNIT",
+ "calculate_event_weights",
+ "PowerLaw",
+ "LogParabola",
+ "PowerLawWithExponentialGaussian",
+ "CRAB_HEGRA",
+ "CRAB_MAGIC_JHEAP2015",
+ "PDG_ALL_PARTICLE",
+ "IRFDOC_PROTON_SPECTRUM",
+ "IRFDOC_ELECTRON_SPECTRUM",
+ "TableInterpolationSpectrum",
+ "DAMPE_P_He_SPECTRUM",
+]
+
+
+
+[docs]
+@u.quantity_input(true_energy=u.TeV)
+def calculate_event_weights(true_energy, target_spectrum, simulated_spectrum):
+ r"""
+ Calculate event weights
+
+ Events with a certain ``simulated_spectrum`` are reweighted to ``target_spectrum``.
+
+ .. math::
+ w_i = \frac{\Phi_\text{Target}(E_i)}{\Phi_\text{Simulation}(E_i)}
+
+ Parameters
+ ----------
+ true_energy: astropy.units.Quantity[energy]
+ True energy of the event
+ target_spectrum: callable
+ The target spectrum. Must be a allable with signature (energy) -> flux
+ simulated_spectrum: callable
+ The simulated spectrum. Must be a callable with signature (energy) -> flux
+
+ Returns
+ -------
+ weights: numpy.ndarray
+ Weights for each event
+ """
+ return (target_spectrum(true_energy) / simulated_spectrum(true_energy)).to_value(
+ u.one
+ )
+
+
+
+
+[docs]
+class PowerLaw:
+ r"""
+ A power law with normalization, reference energy and index.
+ Index includes the sign:
+
+ .. math::
+
+ \Phi(E, \Phi_0, \gamma, E_\text{ref}) =
+ \Phi_0 \left(\frac{E}{E_\text{ref}}\right)^{\gamma}
+
+ Attributes
+ ----------
+ normalization: astropy.units.Quantity[flux]
+ :math:`\Phi_0`,
+ index: float
+ :math:`\gamma`
+ e_ref: astropy.units.Quantity[energy]
+ :math:`E_\text{ref}`
+ """
+
+ @u.quantity_input(
+ normalization=[DIFFUSE_FLUX_UNIT, POINT_SOURCE_FLUX_UNIT], e_ref=u.TeV
+ )
+ def __init__(self, normalization, index, e_ref=1 * u.TeV):
+ """Create a new PowerLaw spectrum"""
+ if index > 0:
+ raise ValueError(f"Index must be < 0, got {index}")
+
+ self.normalization = normalization
+ self.index = index
+ self.e_ref = e_ref
+
+
+[docs]
+ @u.quantity_input(energy=u.TeV)
+ def __call__(self, energy):
+ e = (energy / self.e_ref).to_value(u.one)
+ return self.normalization * e**self.index
+
+
+
+[docs]
+ @classmethod
+ @u.quantity_input(obstime=u.hour, e_ref=u.TeV)
+ def from_simulation(cls, simulated_event_info, obstime, e_ref=1 * u.TeV):
+ """
+ Calculate the flux normalization for simulated events drawn
+ from a power law for a certain observation time.
+ """
+ e_min = simulated_event_info.energy_min
+ e_max = simulated_event_info.energy_max
+ index = simulated_event_info.spectral_index
+ n_showers = simulated_event_info.n_showers
+ viewcone_min = simulated_event_info.viewcone_min
+ viewcone_max = simulated_event_info.viewcone_max
+
+ if (viewcone_max - viewcone_min).value > 0:
+ solid_angle = cone_solid_angle(viewcone_max) - cone_solid_angle(viewcone_min)
+ unit = DIFFUSE_FLUX_UNIT
+ else:
+ solid_angle = 1
+ unit = POINT_SOURCE_FLUX_UNIT
+
+ A = np.pi * simulated_event_info.max_impact**2
+
+ delta = e_max ** (index + 1) - e_min ** (index + 1)
+ nom = (index + 1) * e_ref**index * n_showers
+ denom = (A * obstime * solid_angle) * delta
+
+ return cls(
+ normalization=(nom / denom).to(unit),
+ index=index,
+ e_ref=e_ref,
+ )
+
+
+ def __repr__(self):
+ return f"{self.__class__.__name__}({self.normalization} * (E / {self.e_ref})**{self.index})"
+
+
+[docs]
+ @u.quantity_input(inner=u.rad, outer=u.rad)
+ def integrate_cone(self, inner, outer):
+ """Integrate this powerlaw over solid angle in the given cone
+
+ Parameters
+ ----------
+ inner : astropy.units.Quantity[angle]
+ inner opening angle of cone
+ outer : astropy.units.Quantity[angle]
+ outer opening angle of cone
+
+ Returns
+ -------
+ integrated : PowerLaw
+ A new powerlaw instance with new normalization with the integration
+ result.
+ """
+ if not self.normalization.unit.is_equivalent(DIFFUSE_FLUX_UNIT):
+ raise ValueError("Can only integrate a diffuse flux over solid angle")
+
+ solid_angle = cone_solid_angle(outer) - cone_solid_angle(inner)
+
+ return PowerLaw(
+ normalization=self.normalization * solid_angle,
+ index=self.index,
+ e_ref=self.e_ref,
+ )
+
+
+
+
+
+[docs]
+class LogParabola:
+ r"""
+ A log parabola flux parameterization.
+
+ .. math::
+
+ \Phi(E, \Phi_0, \alpha, \beta, E_\text{ref}) =
+ \Phi_0 \left(
+ \frac{E}{E_\text{ref}}
+ \right)^{\alpha + \beta \cdot \log_{10}(E / E_\text{ref})}
+
+ Attributes
+ ----------
+ normalization: astropy.units.Quantity[flux]
+ :math:`\Phi_0`,
+ a: float
+ :math:`\alpha`
+ b: float
+ :math:`\beta`
+ e_ref: astropy.units.Quantity[energy]
+ :math:`E_\text{ref}`
+ """
+
+ @u.quantity_input(
+ normalization=[DIFFUSE_FLUX_UNIT, POINT_SOURCE_FLUX_UNIT], e_ref=u.TeV
+ )
+ def __init__(self, normalization, a, b, e_ref=1 * u.TeV):
+ """Create a new LogParabola spectrum"""
+ self.normalization = normalization
+ self.a = a
+ self.b = b
+ self.e_ref = e_ref
+
+
+[docs]
+ @u.quantity_input(energy=u.TeV)
+ def __call__(self, energy):
+ e = (energy / self.e_ref).to_value(u.one)
+ return self.normalization * e ** (self.a + self.b * np.log10(e))
+
+
+ def __repr__(self):
+ return f"{self.__class__.__name__}({self.normalization} * (E / {self.e_ref})**({self.a} + {self.b} * log10(E / {self.e_ref}))"
+
+
+
+
+[docs]
+class PowerLawWithExponentialGaussian(PowerLaw):
+ r"""
+ A power law with an additional Gaussian bump.
+ Beware that the Gaussian is not normalized!
+
+ .. math::
+
+ \Phi(E, \Phi_0, \gamma, f, \mu, \sigma, E_\text{ref}) =
+ \Phi_0 \left(
+ \frac{E}{E_\text{ref}}
+ \right)^{\gamma}
+ \cdot \left(
+ 1 + f \cdot
+ \left(
+ \exp\left(
+ \operatorname{Gauss}(\log_{10}(E / E_\text{ref}), \mu, \sigma)
+ \right) - 1
+ \right)
+ \right)
+
+ Where :math:`\operatorname{Gauss}` is the unnormalized Gaussian distribution:
+
+ .. math::
+ \operatorname{Gauss}(x, \mu, \sigma) = \exp\left(
+ -\frac{1}{2} \left(\frac{x - \mu}{\sigma}\right)^2
+ \right)
+
+ Attributes
+ ----------
+ normalization: astropy.units.Quantity[flux]
+ :math:`\Phi_0`,
+ a: float
+ :math:`\alpha`
+ b: float
+ :math:`\beta`
+ e_ref: astropy.units.Quantity[energy]
+ :math:`E_\text{ref}`
+ """
+
+ @u.quantity_input(
+ normalization=[DIFFUSE_FLUX_UNIT, POINT_SOURCE_FLUX_UNIT], e_ref=u.TeV
+ )
+ def __init__(self, normalization, index, e_ref, f, mu, sigma):
+ """Create a new PowerLawWithExponentialGaussian spectrum"""
+ super().__init__(normalization=normalization, index=index, e_ref=e_ref)
+ self.f = f
+ self.mu = mu
+ self.sigma = sigma
+
+
+[docs]
+ @u.quantity_input(energy=u.TeV)
+ def __call__(self, energy):
+ power = super().__call__(energy)
+ log10_e = np.log10(energy / self.e_ref)
+ # ROOT's TMath::Gauss does not add the normalization
+ # this is missing from the IRFDocs
+ # the code used for the plot can be found here:
+ # https://gitlab.cta-observatory.org/cta-consortium/aswg/irfs-macros/cosmic-rays-spectra/-/blob/master/electron_spectrum.C#L508
+ gauss = np.exp(-0.5 * ((log10_e - self.mu) / self.sigma) ** 2)
+ return power * (1 + self.f * (np.exp(gauss) - 1))
+
+
+ def __repr__(self):
+ s = super().__repr__()
+ gauss = f"Gauss(log10(E / {self.e_ref}), {self.mu}, {self.sigma})"
+ return s[:-1] + f" * (1 + {self.f} * (exp({gauss}) - 1))"
+
+
+
+
+[docs]
+class TableInterpolationSpectrum:
+ """
+ Interpolate flux points to obtain a spectrum.
+
+ By default, flux is interpolated linearly in log-log space.
+ """
+
+ def __init__(
+ self, energy, flux, log_energy=True, log_flux=True, reference_energy=1 * u.TeV
+ ):
+ """Create a new TableInterpolationSpectrum spectrum"""
+ self.energy = energy
+ self.flux = flux
+ self.flux_unit = flux.unit
+ self.log_energy = log_energy
+ self.log_flux = log_flux
+ self.reference_energy = reference_energy
+
+ x = (energy / reference_energy).to_value(u.one)
+ y = flux.to_value(self.flux_unit)
+
+ if log_energy:
+ x = np.log10(x)
+
+ if log_flux:
+ y = np.log10(y)
+
+ self.interp = interp1d(x, y, bounds_error=False, fill_value="extrapolate")
+
+
+[docs]
+ def __call__(self, energy):
+
+ x = (energy / self.reference_energy).to_value(u.one)
+
+ if self.log_energy:
+ x = np.log10(x)
+
+ y = self.interp(x)
+
+ if self.log_flux:
+ y = 10**y
+
+ return u.Quantity(y, self.flux_unit, copy=False)
+
+
+
+[docs]
+ @classmethod
+ def from_table(
+ cls, table: QTable, log_energy=True, log_flux=True, reference_energy=1 * u.TeV
+ ):
+ return cls(
+ table["energy"],
+ table["flux"],
+ log_energy=log_energy,
+ log_flux=log_flux,
+ reference_energy=reference_energy,
+ )
+
+
+
+[docs]
+ @classmethod
+ def from_file(
+ cls, path, log_energy=True, log_flux=True, reference_energy=1 * u.TeV
+ ):
+ return cls.from_table(
+ QTable.read(path),
+ log_energy=log_energy,
+ log_flux=log_flux,
+ reference_energy=reference_energy,
+ )
+
+
+
+
+#: Power Law parametrization of the Crab Nebula spectrum as published by HEGRA
+#:
+#: From "The Crab Nebula and Pulsar between 500 GeV and 80 TeV: Observations with the HEGRA stereoscopic air Cherenkov telescopes",
+#: Aharonian et al, 2004, ApJ 614.2
+#: doi.org/10.1086/423931
+CRAB_HEGRA = PowerLaw(
+ normalization=2.83e-11 / (u.TeV * u.cm**2 * u.s),
+ index=-2.62,
+ e_ref=1 * u.TeV,
+)
+
+#: Log-Parabola parametrization of the Crab Nebula spectrum as published by MAGIC
+#:
+#: From "Measurement of the Crab Nebula spectrum over three decades in energy with the MAGIC telescopes",
+#: Aleksìc et al., 2015, JHEAP
+#: https://doi.org/10.1016/j.jheap.2015.01.002
+CRAB_MAGIC_JHEAP2015 = LogParabola(
+ normalization=3.23e-11 / (u.TeV * u.cm**2 * u.s),
+ a=-2.47,
+ b=-0.24,
+)
+
+
+#: All particle spectrum
+#:
+#: (30.2) from "The Review of Particle Physics (2020)"
+#: https://pdg.lbl.gov/2020/reviews/rpp2020-rev-cosmic-rays.pdf
+PDG_ALL_PARTICLE = PowerLaw(
+ normalization=1.8e4 / (u.GeV * u.m**2 * u.s * u.sr),
+ index=-2.7,
+ e_ref=1 * u.GeV,
+)
+
+#: Proton spectrum definition defined in the CTA Prod3b IRF Document
+#:
+#: From "Description of CTA Instrument Response Functions (Production 3b Simulation)", section 4.3.1
+#: https://gitlab.cta-observatory.org/cta-consortium/aswg/documentation/internal_reports/irfs-reports/prod3b-irf-description
+IRFDOC_PROTON_SPECTRUM = PowerLaw(
+ normalization=9.8e-6 / (u.cm**2 * u.s * u.TeV * u.sr),
+ index=-2.62,
+ e_ref=1 * u.TeV,
+)
+
+#: Electron spectrum definition defined in the CTA Prod3b IRF Document
+#:
+#: From "Description of CTA Instrument Response Functions (Production 3b Simulation)", section 4.3.1
+#: https://gitlab.cta-observatory.org/cta-consortium/aswg/documentation/internal_reports/irfs-reports/prod3b-irf-description
+IRFDOC_ELECTRON_SPECTRUM = PowerLawWithExponentialGaussian(
+ normalization=2.385e-9 / (u.TeV * u.cm**2 * u.s * u.sr),
+ index=-3.43,
+ e_ref=1 * u.TeV,
+ mu=-0.101,
+ sigma=0.741,
+ f=1.950,
+)
+
+#: Proton + Helium interpolated from DAMPE measurements
+#:
+#: Datapoints obtained from obtained from:
+#: https://inspirehep.net/files/62efc8374ffced58ea7e3a333bfa1217
+#: Points are from DAMPE, up to 8 TeV.
+#: For higher energies we assume a
+#: flattening of the dF/dE*E^2.7 more or less in the middle of the large
+#: spread of the available data reported on the same proceeding.
+with as_file(files("pyirf") / "resources/dampe_p+he.ecsv") as _path:
+ DAMPE_P_He_SPECTRUM = TableInterpolationSpectrum.from_file(_path)
+
+import numpy as np
+
+from .utils import is_scalar
+
+__all__ = ["li_ma_significance"]
+
+
+
+[docs]
+def li_ma_significance(n_on, n_off, alpha=0.2):
+ """
+ Calculate the Li & Ma significance.
+
+ Formula (17) in https://doi.org/10.1086/161295
+
+ This functions returns 0 significance when n_on < alpha * n_off
+ instead of the negative sensitivities that would result from naively
+ evaluating the formula.
+
+ Parameters
+ ----------
+ n_on: integer or array like
+ Number of events for the on observations
+ n_off: integer or array like
+ Number of events for the off observations
+ alpha: float
+ Ratio between the on region and the off region size or obstime.
+
+ Returns
+ -------
+ s_lima: float or array
+ The calculated significance
+ """
+
+ scalar = is_scalar(n_on)
+
+ # Cast everything into float64 to avoid numeric instabilties
+ # when multiplying very small and very big numbers to get t1 and t2
+ n_on = np.array(n_on, copy=False, ndmin=1, dtype=np.float64)
+ n_off = np.array(n_off, copy=False, ndmin=1, dtype=np.float64)
+ alpha = np.float64(alpha)
+
+ with np.errstate(divide="ignore", invalid="ignore"):
+ p_on = n_on / (n_on + n_off)
+ p_off = n_off / (n_on + n_off)
+
+ t1 = n_on * np.log(((1 + alpha) / alpha) * p_on)
+ t2 = n_off * np.log((1 + alpha) * p_off)
+
+ # lim x+->0 (x log(x)) = 0
+ t1[n_on == 0] = 0
+ t2[n_off == 0] = 0
+
+ ts = t1 + t2
+
+ significance = np.sqrt(ts * 2)
+
+ significance[n_on < (alpha * n_off)] = 0
+
+ if scalar:
+ return significance[0]
+
+ return significance
+
+
+import numpy as np
+import astropy.units as u
+from astropy.coordinates import angular_separation
+
+from .exceptions import MissingColumns, WrongColumnUnit
+
+
+__all__ = [
+ "is_scalar",
+ "calculate_theta",
+ "calculate_source_fov_offset",
+ "check_histograms",
+ "cone_solid_angle",
+]
+
+
+
+[docs]
+def is_scalar(val):
+ """Workaround that also supports astropy quantities
+
+ Parameters
+ ----------
+ val : object
+ Any object (value, list, etc...)
+
+ Returns
+ -------
+ result: bool
+ True is if input object is a scalar, False otherwise.
+ """
+ result = np.array(val, copy=False).shape == tuple()
+ return result
+
+
+
+
+[docs]
+@u.quantity_input(assumed_source_az=u.deg, assumed_source_alt=u.deg)
+def calculate_theta(events, assumed_source_az, assumed_source_alt):
+ """Calculate sky separation between assumed and reconstructed positions.
+
+ Parameters
+ ----------
+ events : astropy.QTable
+ Astropy Table object containing the reconstructed events information.
+ assumed_source_az: astropy.units.Quantity
+ Assumed Azimuth angle of the source.
+ assumed_source_alt: astropy.units.Quantity
+ Assumed Altitude angle of the source.
+
+ Returns
+ -------
+ theta: astropy.units.Quantity
+ Angular separation between the assumed and reconstructed positions
+ in the sky.
+ """
+ theta = angular_separation(
+ assumed_source_az,
+ assumed_source_alt,
+ events["reco_az"],
+ events["reco_alt"],
+ )
+
+ return theta.to(u.deg)
+
+
+
+
+[docs]
+def calculate_source_fov_offset(events, prefix="true"):
+ """Calculate angular separation between true and pointing positions.
+
+ Parameters
+ ----------
+ events : astropy.QTable
+ Astropy Table object containing the reconstructed events information.
+
+ prefix: str
+ Column prefix for az / alt, can be used to calculate reco or true
+ source fov offset.
+
+ Returns
+ -------
+ theta: astropy.units.Quantity
+ Angular separation between the true and pointing positions
+ in the sky.
+ """
+ theta = angular_separation(
+ events[f"{prefix}_az"],
+ events[f"{prefix}_alt"],
+ events["pointing_az"],
+ events["pointing_alt"],
+ )
+
+ return theta.to(u.deg)
+
+
+
+
+[docs]
+def check_histograms(hist1, hist2, key="reco_energy"):
+ """
+ Check if two histogram tables have the same binning
+
+ Parameters
+ ----------
+ hist1: ``~astropy.table.Table``
+ First histogram table, as created by
+ ``~pyirf.binning.create_histogram_table``
+ hist2: ``~astropy.table.Table``
+ Second histogram table
+ """
+
+ # check binning information and add to output
+ for k in ("low", "center", "high"):
+ k = key + "_" + k
+ if not np.all(hist1[k] == hist2[k]):
+ raise ValueError(
+ "Binning for signal_hist and background_hist must be equal"
+ )
+
+
+
+
+[docs]
+def cone_solid_angle(angle):
+ """Calculate the solid angle of a view cone.
+
+ Parameters
+ ----------
+ angle: astropy.units.Quantity or astropy.coordinates.Angle
+ Opening angle of the view cone.
+
+ Returns
+ -------
+ solid_angle: astropy.units.Quantity
+ Solid angle of a view cone with opening angle ``angle``.
+
+ """
+ solid_angle = 2 * np.pi * (1 - np.cos(angle)) * u.sr
+ return solid_angle
+
+
+
+def check_table(table, required_columns=None, required_units=None):
+ """Check a table for required columns and units.
+
+ Parameters
+ ----------
+ table: astropy.table.QTable
+ Table to check
+ required_columns: iterable[str]
+ Column names that are required to be present
+ required_units: Mapping[str->astropy.units.Unit]
+ Required units for columns as a Mapping from column names to units.
+ Checks if the units are convertible, not if they are identical
+
+ Raises
+ ------
+ MissingColumns: If any of the columns specified in ``required_columns`` or
+ as keys in ``required_units are`` not present in the table.
+ WrongColumnUnit: if any column has the wrong unit
+ """
+ if required_columns is not None:
+ missing = set(required_columns) - set(table.colnames)
+ if missing:
+ raise MissingColumns(missing)
+
+ if required_units is not None:
+ for col, expected in required_units.items():
+ if col not in table.colnames:
+ raise MissingColumns(col)
+
+ unit = table[col].unit
+ if not expected.is_equivalent(unit):
+ raise WrongColumnUnit(col, unit, expected)
+' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/api/pyirf.benchmarks.angular_resolution.html b/api/pyirf.benchmarks.angular_resolution.html new file mode 100644 index 000000000..d79c91c10 --- /dev/null +++ b/api/pyirf.benchmarks.angular_resolution.html @@ -0,0 +1,183 @@ + + + + + + +Calculate the angular resolution.
+This implementation corresponds to the 68% containment of the angular +distance distribution.
+Astropy Table object containing the reconstructed events information.
+Bin edges in energy.
+Either “true” or “reco” energy. +Default is “true”.
+Which quantile to use for the angular resolution, +by default, the containment of the 1-sigma region +of the normal distribution (~68%) is used.
+QTable containing the 68% containment of the angular +distance distribution per each reconstructed energy bin.
+Calculate bias and energy resolution.
+Astropy Table object containing the reconstructed events information.
+Bin edges in energy.
+Either “true” or “reco” energy. +Default is “true”.
+Function used to calculate the energy bias
+Function used to calculate the energy resolution
+QTable containing the energy bias and resolution +per each bin in true energy.
+Calculate bias and energy resolution.
+Energy dispersion matrix of shape +(n_energy_bins, n_migra_bins, n_source_offset_bins)
+Bin edges for the relative energy migration (reco_energy / true_energy)
Calculate bin indices of inidividula entries of the given data array using +the supplied binning. Underflow will be indicated by UNDERFLOW_INDEX and +overflow by OVERFLOW_INDEX.
+If the bins already include underflow / overflow bins, e.g. +bins[0] = -np.inf and bins[-1] = np.inf, using the result of this +function will always be a valid index into the resulting histogram.
+Array with the data
+Array or Quantity of bin edges. Must have the same unit as data if a Quantity.
Indices of the histogram bin the values in data belong to. +Under- and overflown values will have values of UNDERFLOW_INDEX +and OVERFLOW_INDEX respectively.
+Boolean mask indicating if a given value belongs into one of the defined bins. +False indicates that an entry fell into the over- or underflow bins.
+Create a bin array with bins equally spaced in logarithmic energy
+with bins_per_decade bins per decade.
Minimum energy, inclusive
+Maximum energy, non-inclusive
+If the endpoint exactly matches the n_bins_per_decade requirement,
+it will be included.
number of bins per decade
+The created bin array, will have units of e_min
+Histogram a variable from events data into an astropy table.
+astropy.QTableAstropy Table object containing the reconstructed events information.
+Array or Quantity of bin edges.
+It must have the same units as data if a Quantity.
stringVariable to histogram from the events table.
+astropy.QTableAstropy table containg the histogram.
+Function joins bins into lo and hi part, +e.g. [0, 1, 2] and [1, 2, 4] into [0, 1, 2, 4] +It works on multidimentional arrays as long as the binning is in the last axis
+Lo bin edges array
+Hi bin edges array
+The joint bins
+Rebinning of a histogram by interpolation along a given axis.
+numpy.ndarray or astropy.units.QuantityHistogram.
+numpy.array or astropy.units.QuantityBinning used to calculate data.
+len(old_edges) - 1 needs to equal the length of data
+along interpolation axis (axis).
+If quantity, needs to be compatible to new_edges.
numpy.array or astropy.units.QuantityBinning of new histogram.
+If quantity, needs to be compatible to old_edges.
Interpolation axis.
+numpy.ndarray or astropy.units.QuantityInterpolated histogram with dimension according to data and new_edges.
+If data is a quantity, this has the same unit.
Inverted function to join_bin_hi_lo, +e.g. it splits [0, 1, 2, 4] into [0, 1, 2] and [1, 2, 4]
+The joint bins
+Lo bin edges array
+Hi bin edges array
+Optimize the gh-score cut in every energy bin of reconstructed energy +for best sensitivity.
+This procedure is EventDisplay-like, since it only applies a +pre-computed theta cut and then optimizes only the gamma/hadron separation +cut.
+event list of simulated signal events. +Required columns are theta, reco_energy, ‘weight’, gh_score +No directional (theta) or gamma/hadron cut should already be applied.
+event list of simulated background events. +Required columns are reco_source_fov_offset, reco_energy, +‘weight’, gh_score. +No directional (theta) or gamma/hadron cut should already be applied.
+Bins in reconstructed energy to use for sensitivity computation
+The cut efficiencies to scan for best sensitivity.
+cut definition of the energy dependent theta cut,
+e.g. as created by calculate_percentile_cut
The comparison function to use for the gamma hadron score. +Returning true means an event passes the cut, so is not discarded. +E.g. for gammaness-like score, use operator.ge (>=) and for a +hadroness-like score use operator.le (<=).
+Minimum distance from the fov center for background events to be taken into account
+Maximum distance from the fov center for background events to be taken into account
+Size ratio of off region / on region. Will be used to +scale the background rate.
+If True, show a progress bar during cut optimization
+Calculate cuts as the percentile of a given quantity in bins of another +quantity.
+The values for which the cut should be calculated
+The values used to sort the values into bins
Bin edges
+Value for bins with less than min_events,
+must have same unit as values
The percentile to calculate in each bin as a percentage, +i.e. 0 <= percentile <= 100.
+If given, cuts smaller than this value are replaced with min_value
If given, cuts larger than this value are replaced with max_value
If given, apply a gaussian filter of width sigma in terms
+of bins.
Bins with less events than this number are replaced with fill_value
Evaluate a binned cut as defined in cut_table on given events.
+Events with bin_values outside the bin edges defined in cut table +will be set to False.
+The values on which the cut should be evaluated
+The values used to sort the values into bins
A table describing the binned cuts, e.g. as created by
+~pyirf.cuts.calculate_percentile_cut.
+Required columns:
+- low: lower edges of the bins
+- high: upper edges of the bins,
+- cut: cut value
A function taking two arguments, comparing element-wise and +returning an array of booleans. +Must support vectorized application.
+A mask for each entry in values indicating if the event
+passes the bin specific cut given in cut table.
Create a gammapy.irf.EffectiveAreaTable2D from pyirf outputs.
Effective area array, must have shape (n_energy_bins, n_fov_offset_bins)
+Bin edges in true energy
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Create a gammapy.irf.EnergyDispersion2D from pyirf outputs.
Energy dispersion array, must have shape +(n_energy_bins, n_migra_bins, n_source_offset_bins)
+Bin edges in true energy
+Bin edges for the relative energy migration (reco_energy / true_energy)
Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Create a gammapy.irf.PSF3D from pyirf outputs.
Point spread function array, must have shape +(n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+Bin edges in true energy
+Bin edges in the source offset.
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Bases: object
Base class for all Estimators working on specific IRF components.
+While usable, it is encouraged to use the actual class for the respective IRF +component as it ensures further checks and if necessary e.g. unit handling.
+Methods Summary
+
|
+Inter-/ Extrapolation as needed and sanity checking of the target point |
+
Methods Documentation
+Inter-/ Extrapolation as needed and sanity checking of +the target point
+Target for inter-/extrapolation
+When target_point is not an np.ndarray
+When more then one target_point is given
+When target_point and grid_points have miss-matching dimensions
+When target_point is outside of the grids convex hull but extrapolator is None
+When target_points need extrapolation
+Bases: object
Base class for all extrapolators, only knowing grid-points, +providing a common __call__-interface.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual extrapolation code |
+
Methods Documentation
+ + + + +Bases: object
Base class for all interpolators, only knowing grid-points, +providing a common __call__-interface.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual interpolation code |
+
Methods Documentation
+ + + + +Bases: BaseInterpolator
Dummy NearestNeighbor approach usable instead of +actual Interpolation/Extrapolation
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of IRF values for a bunch of different parameters and returns the values at the nearest grid point as seen from the target point. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Takes a grid of IRF values for a bunch of different parameters and returns +the values at the nearest grid point as seen from the target point.
+Value for which the nearest neighbor should be found (target point)
+values at nearest neighbor
+Notes
+In case of multiple nearest neighbors, the values corresponding +to the first one are returned.
+Bases: BaseComponentEstimator
Base class for all Estimators working on IRF components that represent discretized PDFs.
+While usable, it is encouraged to use the actual class for the respective IRF +component as it ensures further checks and if necessary e.g. unit handling.
+Methods Summary
+
|
+Inter-/ Extrapolation as needed and sanity checking of the target point |
+
Methods Documentation
+Inter-/ Extrapolation as needed and sanity checking of +the target point
+Target for inter-/extrapolation
+When target_point is not an np.ndarray
+When more then one target_point is given
+When target_point and grid_points have miss-matching dimensions
+When target_point is outside of the grids convex hull but extrapolator is None
+When target_points need extrapolation
+Bases: BaseExtrapolator
Base class for all extrapolators used with binned IRF components like EDisp. +Derived from pyirf.interpolation.BaseExtrapolator
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual extrapolation code |
+
Methods Documentation
+Providing a common __call__ interface
+Target for extrapolation
+Overridable function for the actual extrapolation code
+Bases: BaseInterpolator
Base class for all interpolators used with binned IRF components like EDisp. +Derived from pyirf.interpolation.BaseInterpolator
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual interpolation code |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Overridable function for the actual interpolation code
+Bases: BaseNearestNeighborSearcher
Dummy NearestNeighbor approach usable instead of +actual interpolation/extrapolation. +Compatible with discretized PDF IRF component API.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of IRF values for a bunch of different parameters and returns the values at the nearest grid point as seen from the target point. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Takes a grid of IRF values for a bunch of different parameters and returns +the values at the nearest grid point as seen from the target point.
+Value for which the nearest neighbor should be found (target point)
+values at nearest neighbor
+Notes
+In case of multiple nearest neighbors, the values corresponding +to the first one are returned.
+Bases: ParametrizedComponentEstimator
Estimator class for effective area tables (AEFF_2D).
+Methods Summary
+
|
+Estimating effective area at target_point, inter-/extrapolates as needed and specified in __init__. |
+
Methods Documentation
+Estimating effective area at target_point, inter-/extrapolates as needed and +specified in __init__.
+Target for inter-/extrapolation
+Interpolated Effective area array with same shape as input +effective areas. For AEFF2D of shape (n_energy_bins, n_fov_offset_bins). +Values lower or equal to __init__’s min_effective_area are set +to zero.
+Bases: DiscretePDFComponentEstimator
Estimator class for energy dispersions (EDISP_2D).
+Methods Summary
+
|
+Estimating energy dispersions at target_point, inter-/extrapolates as needed and specified in __init__. |
+
Methods Documentation
+Estimating energy dispersions at target_point, inter-/extrapolates as needed and +specified in __init__.
+Target for inter-/extrapolation
+Interpolated EDISP matrix with same shape as input matrices. For EDISP_2D +of shape (n_points, n_energy_bins, n_migration_bins, n_fov_offset_bins)
+Bases: ParametrizedInterpolator
“Wrapper arounf scipy.interpolate.griddata.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Wrapper around scipy.interpolate.griddata [1] |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Wrapper around scipy.interpolate.griddata [1]
+Target point for interpolation
+Interpolated parameter values
+References
+Scipy Documentation, scipy.interpolate.griddata +https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html
+Bases: DiscretePDFInterpolator
Interpolator class providing Moment Morphing to interpolate discretized PDFs.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of binned pdfs for a bunch of different parameters and interpolates it to given value of those parameters. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Takes a grid of binned pdfs for a bunch of different parameters +and interpolates it to given value of those parameters. +This function calls implementations of the moment morphing interpolation +pocedure introduced in [1].
+Value for which the interpolation is performed (target point)
+Interpolated and binned pdf
+References
+M. Baak, S. Gadatsch, R. Harrington and W. Verkerke (2015). Interpolation between +multi-dimensional histograms using a new non-linear moment morphing method +Nucl. Instrum. Methods Phys. Res. A 771, 39-48. https://doi.org/10.1016/j.nima.2014.10.033
+Bases: DiscretePDFExtrapolator
Extrapolator class extending moment morphing interpolation outside a grid’s convex hull.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of discretized PDFs for a bunch of different parameters and extrapolates it to given value of those parameters. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for extrapolation
+Takes a grid of discretized PDFs for a bunch of different parameters +and extrapolates it to given value of those parameters.
+Value for which the extrapolation is performed (target point)
+Extrapolated discretized PDFs
+Bases: Enum
How a discrete PDF is normalized
+Attributes Summary
+| + | PDF is normalized to a "normal" area integral of 1 |
+
| + | PDF is normalized to 1 over the solid angle integral where the bin edges represent the opening angles of cones in radian. |
+
Attributes Documentation
+PDF is normalized to a “normal” area integral of 1
+PDF is normalized to 1 over the solid angle integral where the bin +edges represent the opening angles of cones in radian.
+Bases: DiscretePDFComponentEstimator
Estimator class for point spread function tables (PSF_TABLE).
+Methods Summary
+
|
+Estimating psf tables at target_point, inter-/extrapolates as needed and specified in __init__. |
+
Methods Documentation
+Estimating psf tables at target_point, inter-/extrapolates as needed and +specified in __init__.
+Target for inter-/extrapolation
+Interpolated psf table with same shape as input matrices. For PSF_TABLE +of shape (n_points, n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+Bases: BaseComponentEstimator
Base class for all Estimators working on IRF components that represent parametrized +or scalar quantities.
+While usable, it is encouraged to use the actual class for the respective IRF +component as it ensures further checks and if necessary e.g. unit handling.
+Methods Summary
+
|
+Inter-/ Extrapolation as needed and sanity checking of the target point |
+
Methods Documentation
+Inter-/ Extrapolation as needed and sanity checking of +the target point
+Target for inter-/extrapolation
+When target_point is not an np.ndarray
+When more then one target_point is given
+When target_point and grid_points have miss-matching dimensions
+When target_point is outside of the grids convex hull but extrapolator is None
+When target_points need extrapolation
+Bases: BaseExtrapolator
Base class for all extrapolators used with IRF components that can be +treated independently, e.g. parametrized ones like 3Gauss +but also AEff. Derived from pyirf.interpolation.BaseExtrapolator
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual extrapolation code |
+
Methods Documentation
+Providing a common __call__ interface
+Target for extrapolation
+Overridable function for the actual extrapolation code
+Bases: BaseInterpolator
Base class for all interpolators used with IRF components that can be +independently interpolated, e.g. parametrized ones like 3Gauss +but also AEff. Derived from pyirf.interpolation.BaseInterpolator
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Overridable function for the actual interpolation code |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Overridable function for the actual interpolation code
+Bases: BaseNearestNeighborSearcher
Dummy NearestNeighbor approach usable instead of +actual interpolation/extrapolation +Compatible with parametrized IRF component API.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of IRF values for a bunch of different parameters and returns the values at the nearest grid point as seen from the target point. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Takes a grid of IRF values for a bunch of different parameters and returns +the values at the nearest grid point as seen from the target point.
+Value for which the nearest neighbor should be found (target point)
+values at nearest neighbor
+Notes
+In case of multiple nearest neighbors, the values corresponding +to the first one are returned.
+Bases: ParametrizedExtrapolator
Extrapolator class extending linear or baryzentric interpolation outside a grid’s convex hull.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of scalar values for a bunch of different parameters and extrapolates it to given value of those parameters. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for extrapolation
+Takes a grid of scalar values for a bunch of different parameters +and extrapolates it to given value of those parameters.
+Value for which the extrapolation is performed (target point)
+Extrapolated values
+Bases: ParametrizedNearestSimplexExtrapolator
Extrapolator using blending over visible edges.
+While the ParametrizedNearestSimplexExtrapolator does not result in a smooth +extrapolation outside of the grid due to using only the nearest available +simplex, this extrapolator blends over all visible edges as discussed in [1]. +For one grid-dimension this is equal to the ParametrizedNearestSimplexExtrapolator, +the same holds for grids consisting of only one simplex or constellations, +where only one simplex is visible from a target.
+Grid points at which templates exist. May be one ot two dimensional. +Have to be sorted in accending order for 1D.
+Array of corresponding parameter values at each point in grid_points. +First dimesion has to correspond to number of grid_points
+Degree of smoothness wanted in the extrapolation region. See [1] for +additional information. Defaults to 1.
+If m is not a number
+If m is not a non-zero integer
+References
+P. Alfred (1984). Triangular Extrapolation. Technical summary rept., +Univ. of Wisconsin-Madison. https://apps.dtic.mil/sti/pdfs/ADA144660.pdf
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of scalar values for a bunch of different parameters and extrapolates it to given value of those parameters. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for extrapolation
+Takes a grid of scalar values for a bunch of different parameters +and extrapolates it to given value of those parameters.
+Value for which the extrapolation is performed (target point)
+Extrapolated values
+Bases: DiscretePDFInterpolator
Interpolator class providing quantile interpoalation.
+Methods Summary
+
|
+Providing a common __call__ interface |
+
|
+Takes a grid of binned pdfs for a bunch of different parameters and interpolates it to given value of those parameters. |
+
Methods Documentation
+Providing a common __call__ interface
+Target for inter-/extrapolation +When target_point is outside of the grids convex hull but extrapolator is None
+Takes a grid of binned pdfs for a bunch of different parameters +and interpolates it to given value of those parameters. +This function provides an adapted version of the quantile interpolation introduced +in [1]. +Instead of following this method closely, it implements different approaches to the +steps shown in Fig. 5 of [1].
+Value for which the interpolation is performed (target point)
+Interpolated and binned pdf
+References
+B. E. Hollister and A. T. Pang (2013). Interpolation of Non-Gaussian Probability Distributions +for Ensemble Visualization +https://engineering.ucsc.edu/sites/default/files/technical-reports/UCSC-SOE-13-13.pdf
+Bases: ParametrizedComponentEstimator
Estimator class for rad-max tables (RAD_MAX, RAD_MAX_2D).
+Methods Summary
+
|
+Estimating rad max table at target_point, inter-/extrapolates as needed and specified in __init__. |
+
Methods Documentation
+Estimating rad max table at target_point, inter-/extrapolates as needed and +specified in __init__.
+Target for inter-/extrapolation
+Interpolated RAD_MAX table with same shape as input +effective areas. For RAD_MAX_2D of shape (n_energy_bins, n_fov_offset_bins)
+Create a fits binary table HDU in GADF format for effective area. +See the specification at +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/aeff/index.html
+Effective area array, must have shape (n_energy_bins, n_fov_offset_bins)
+Bin edges in true energy
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+If the provided effective area was calculated after applying a direction cut,
+pass True, else False for a full-enclosure effective area.
Name for BinTableHDU
+Additional metadata to add to the header, use this to set e.g. TELESCOP or +INSTRUME.
+Create a fits binary table HDU in GADF format for the background 2d table. +See the specification at +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/bkg/index.html#bkg-2d
+Background rate, must have shape +(n_energy_bins, n_fov_offset_bins)
+Bin edges in reconstructed energy
+Bin edges in the field of view offset.
+Name for BinTableHDU
+Additional metadata to add to the header, use this to set e.g. TELESCOP or +INSTRUME.
+Create a fits binary table HDU in GADF format for the energy dispersion. +See the specification at +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/edisp/index.html
+Energy dispersion array, must have shape +(n_energy_bins, n_migra_bins, n_source_offset_bins)
+Bin edges in true energy
+Bin edges for the relative energy migration (reco_energy / true_energy)
Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+If the provided effective area was calculated after applying a direction cut,
+pass True, else False for a full-enclosure effective area.
Name for BinTableHDU
+Additional metadata to add to the header, use this to set e.g. TELESCOP or +INSTRUME.
+Create a fits binary table HDU in GADF format for the PSF table. +See the specification at +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/psf/psf_table/index.html
+Point spread function array, must have shape +(n_energy_bins, n_fov_offset_bins, n_source_offset_bins)
+Bin edges in true energy
+Bin edges in the source offset.
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Name for BinTableHDU
+Additional metadata to add to the header, use this to set e.g. TELESCOP or +INSTRUME.
+Create a fits binary table HDU in GADF format for the directional cut. +See the specification at +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/point_like/index.html#rad-max
+Array of the directional (theta) cut. +Must have shape (n_reco_energy_bins, n_fov_offset_bins)
+Bin edges in reconstructed energy
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Name for BinTableHDU
+Additional metadata to add to the header, use this to set e.g. TELESCOP or +INSTRUME.
+Read a DL2 FITS file as produced by the EventDisplay DL2 converter +from ROOT files: +https://github.com/Eventdisplay/Converters/blob/master/DL2/generate_DL2_file.py
+Path to the input fits file
+If True, use number of simulated events from histogram provided in fits file, +if False, estimate this number from the unique run_id, pointing direction +combinations and the number of events per run in the run header. +This will fail e.g. for protons with cuts already applied, since many +runs will have 0 events surviving cuts.
+Astropy Table object containing the reconstructed events information.
+~pyirf.simulations.SimulatedEventsInfoCalculate background rates in radially symmetric bins in the field of view.
+GADF documentation here: +https://gamma-astro-data-formats.readthedocs.io/en/latest/irfs/full_enclosure/bkg/index.html#bkg-2d
+DL2 events table of the selected background events. +Needed columns for this function: reco_source_fov_offset, reco_energy, weight
+The bins in reconstructed energy to be used for the IRF
+The bins in the field of view offset to be used for the IRF
+Observation time. This must match with how the individual event +weights are calculated.
+The background rate as particles per energy, time and solid angle +in the specified bins.
+Shape: (len(reco_energy_bins) - 1, len(fov_offset_bins) - 1)
+Calculate effective area for histograms of selected and total simulated events
+The number of surviving (e.g. triggered, analysed, after cuts)
+The total number of events simulated
+Area in which particle’s core position was simulated
+Calculate effective area in bins of true energy.
+DL2 events table, required columns for this function: true_energy.
+The overall statistics of the simulated events
+The bin edges in which to calculate effective area.
+Calculate effective area in bins of true energy and field of view offset.
+DL2 events table, required columns for this function: +- true_energy +- true_source_fov_offset
+The overall statistics of the simulated events
+The true energy bin edges in which to calculate effective area.
+The field of view radial bin edges in which to calculate effective area.
+Calculate energy dispersion for the given DL2 event list.
+Energy dispersion is defined as the probability of finding an event
+at a given relative deviation (reco_energy / true_energy) for a given
+true energy.
Table of the DL2 events.
+Required columns: reco_energy, true_energy, true_source_fov_offset.
Bin edges in true energy
+Bin edges in relative deviation, recommended range: [0.2, 5]
+Bin edges in the field of view offset. +For Point-Like IRFs, only giving a single bin is appropriate.
+Energy dispersion matrix +with shape (n_true_energy_bins, n_migration_bins, n_fov_ofset_bins)
+Calculate sensitivity for DL2 event lists in bins of reconstructed energy.
+Sensitivity is defined as the minimum flux detectable with target_significance
+sigma significance in a certain time.
This time must be incorporated into the event weights.
+Two conditions are required for the sensitivity: +- At least ten weighted signal events +- The weighted signal must be larger than 5 % of the weighted background +- At least 5 sigma (so relative_sensitivity > 1)
+If the conditions are not met, the sensitivity will be set to nan.
+Histogram of detected signal events as a table.
+Required columns: n and n_weighted.
+See pyirf.binning.create_histogram_table
Histogram of detected events as a table.
+Required columns: n and n_weighted.
+See pyirf.binning.create_histogram_table
Size ratio of signal region to background region
+Significance necessary for a detection
+Minimum number of signal events required.
+The relative flux will be scaled up from the one yielding min_significance
+if this condition is violated.
Minimum number of signal events expressed as the proportion of the
+background.
+So the required number of signal events will be
+min_excess_over_background * alpha * n_off.
+The relative flux will be scaled up from the one yielding min_significance
+if this condition is violated.
A function with signature (n_on, n_off, alpha) -> significance. +Default is the Li & Ma likelihood ratio test.
+Table with sensitivity information.
+Contains weighted and unweighted number of signal and background events
+and the relative_sensitivity, the scaling applied to the signal events
+that yields target_significance sigma of significance according to
+the significance_function
Estimate the number of background events for a point-like sensitivity.
+Due to limited statistics, it is often not possible to just apply the same +theta cut to the background events as to the signal events around an assumed +source position.
+Here we calculate the expected number of background events for the off
+regions by taking all background events between fov_offset_min and
+fov_offset_max from the camera center and then scale these to the size
+of the off region, which is scaled by 1 / alpha from the size of the on
+region given by the theta cuts.
DL2 event list of background surviving event selection
+and inside fov_offset_max from the center of the FOV
+Required columns for this function:
+- reco_energy,
+- reco_source_fov_offset.
Desired bin edges in reconstructed energy for the background rate
+The cuts table for the theta cut,
+e.g. as returned by ~pyirf.cuts.calculate_percentile_cut.
+Columns center and cut are required for this function.
size of the on region divided by the size of the off region.
+Minimum distance from the fov center for background events to be taken into account
+Maximum distance from the fov center for background events to be taken into account
+Calculate the relative sensitivity defined as the flux
+relative to the reference source that is detectable with
+significance target_significance.
Given measured n_on and n_off,
+we estimate the number of gamma events n_signal as n_on - alpha * n_off.
The number of background events n_background` is estimated as ``n_off * alpha.
In the end, we find the relative sensitivity as the scaling factor for n_signal
+that yields a significance of target_significance.
The reference time should be incorporated by appropriately weighting the events
+before calculating n_on and n_off.
All input values with the exception of significance_function
+must be broadcastable to a single, common shape.
Number of signal-like events for the on observations
+Number of signal-like events for the off observations
+Scaling factor between on and off observations. +1 / number of off regions for wobble observations.
+Significance necessary for a detection
+Minimum number of signal events required.
+The relative flux will be scaled up from the one yielding min_significance
+if this condition is violated.
Minimum number of signal events expressed as the proportion of the
+background.
+So the required number of signal events will be
+min_excess_over_background * alpha * n_off.
+The relative flux will be scaled up from the one yielding min_significance
+if this condition is violated.
A function f(n_on, n_off, alpha) -> significance in sigma +Used to calculate the significance, default is the Li&Ma +likelihood ratio test formula. +Li, T-P., and Y-Q. Ma. +“Analysis methods for results in gamma-ray astronomy.” +The Astrophysical Journal 272 (1983): 317-324. +Formula (17)
+Bases: object
Information about all simulated events, for calculating event weights.
+Total number of simulated showers. If reuse was used, this +should already include the reuse.
+Lower limit of the simulated energy range
+Upper limit of the simulated energy range
+Maximum simulated impact parameter
+Spectral Index of the simulated power law with sign included.
+Inner angle of the viewcone
+Outer angle of the viewcone
+Attributes Summary
+| + | Upper limit of the simulated energy range |
+
| + | Lower limit of the simulated energy range |
+
| + | Maximum simualted impact radius |
+
| + | Total number of simulated showers, if reuse was used, this must already include reuse |
+
| + | Spectral index of the simulated power law with sign included |
+
| + | Outer viewcone angle |
+
| + | Inner viewcone angle |
+
Methods Summary
+
|
+Calculate number of showers that were simulated in the given energy intervals |
+
| + | Calculate number of showers that were simulated in the given energy and fov bins. |
+
|
+Calculate number of showers that were simulated in the given fov bins. |
+
Attributes Documentation
+Upper limit of the simulated energy range
+Lower limit of the simulated energy range
+Maximum simualted impact radius
+Total number of simulated showers, if reuse was used, this must +already include reuse
+Spectral index of the simulated power law with sign included
+Outer viewcone angle
+Inner viewcone angle
+Methods Documentation
+Calculate number of showers that were simulated in the given energy intervals
+This assumes the events were generated and from a powerlaw +like CORSIKA simulates events.
+The interval edges for which to calculate the number of simulated showers
+The expected number of events inside each of the energy_bins.
+This is a floating point number.
+The actual numbers will follow a poissionian distribution around this
+expected value.
Calculate number of showers that were simulated in the given +energy and fov bins.
+This assumes the events were generated uniformly distributed per solid angle, +and from a powerlaw in energy like CORSIKA simulates events.
+The energy bin edges for which to calculate the number of simulated showers
+The FOV bin edges for which to calculate the number of simulated showers
+The expected number of events inside each of the
+energy_bins and fov_bins.
+Dimension (n_energy_bins, n_fov_bins)
+This is a floating point number.
+The actual numbers will follow a poissionian distribution around this
+expected value.
Calculate number of showers that were simulated in the given fov bins.
+This assumes the events were generated uniformly distributed per solid angle, +like CORSIKA simulates events with the VIEWCONE option.
+The FOV bin edges for which to calculate the number of simulated showers
+The expected number of events inside each of the fov_bins.
+This is a floating point number.
+The actual numbers will follow a poissionian distribution around this
+expected value.
Power Law parametrization of the Crab Nebula spectrum as published by HEGRA
+From “The Crab Nebula and Pulsar between 500 GeV and 80 TeV: Observations with the HEGRA stereoscopic air Cherenkov telescopes”, +Aharonian et al, 2004, ApJ 614.2 +doi.org/10.1086/423931
+Log-Parabola parametrization of the Crab Nebula spectrum as published by MAGIC
+From “Measurement of the Crab Nebula spectrum over three decades in energy with the MAGIC telescopes”, +Aleksìc et al., 2015, JHEAP +https://doi.org/10.1016/j.jheap.2015.01.002
+Electron spectrum definition defined in the CTA Prod3b IRF Document
+From “Description of CTA Instrument Response Functions (Production 3b Simulation)”, section 4.3.1 +https://gitlab.cta-observatory.org/cta-consortium/aswg/documentation/internal_reports/irfs-reports/prod3b-irf-description
+Proton spectrum definition defined in the CTA Prod3b IRF Document
+From “Description of CTA Instrument Response Functions (Production 3b Simulation)”, section 4.3.1 +https://gitlab.cta-observatory.org/cta-consortium/aswg/documentation/internal_reports/irfs-reports/prod3b-irf-description
+Bases: object
A log parabola flux parameterization.
+\(\Phi_0\),
+\(\alpha\)
+\(\beta\)
+\(E_\text{ref}\)
+Methods Summary
+
|
+Call self as a function. |
+
Methods Documentation
+ + +All particle spectrum
+(30.2) from “The Review of Particle Physics (2020)” +https://pdg.lbl.gov/2020/reviews/rpp2020-rev-cosmic-rays.pdf
+Bases: object
A power law with normalization, reference energy and index. +Index includes the sign:
+\(\Phi_0\),
+\(\gamma\)
+\(E_\text{ref}\)
+Methods Summary
+
|
+Call self as a function. |
+
|
+Calculate the flux normalization for simulated events drawn from a power law for a certain observation time. |
+
|
+Integrate this powerlaw over solid angle in the given cone |
+
Methods Documentation
+ + +Calculate the flux normalization for simulated events drawn +from a power law for a certain observation time.
+Integrate this powerlaw over solid angle in the given cone
+inner opening angle of cone
+outer opening angle of cone
+A new powerlaw instance with new normalization with the integration +result.
+Bases: PowerLaw
A power law with an additional Gaussian bump. +Beware that the Gaussian is not normalized!
+Where \(\operatorname{Gauss}\) is the unnormalized Gaussian distribution:
+\(\Phi_0\),
+\(\alpha\)
+\(\beta\)
+\(E_\text{ref}\)
+Methods Summary
+
|
+Call self as a function. |
+
Methods Documentation
+ + +Bases: object
Interpolate flux points to obtain a spectrum.
+By default, flux is interpolated linearly in log-log space.
+Methods Summary
+
|
+Call self as a function. |
+
|
++ |
|
++ |
Methods Documentation
+ + + + + + +Calculate event weights
+Events with a certain simulated_spectrum are reweighted to target_spectrum.
True energy of the event
+The target spectrum. Must be a allable with signature (energy) -> flux
+The simulated spectrum. Must be a callable with signature (energy) -> flux
+Weights for each event
+Calculate the Li & Ma significance.
+Formula (17) in https://doi.org/10.1086/161295
+This functions returns 0 significance when n_on < alpha * n_off +instead of the negative sensitivities that would result from naively +evaluating the formula.
+Number of events for the on observations
+Number of events for the off observations
+Ratio between the on region and the off region size or obstime.
+The calculated significance
+Calculate angular separation between true and pointing positions.
+Astropy Table object containing the reconstructed events information.
+Column prefix for az / alt, can be used to calculate reco or true +source fov offset.
+Angular separation between the true and pointing positions +in the sky.
+Calculate sky separation between assumed and reconstructed positions.
+Astropy Table object containing the reconstructed events information.
+Assumed Azimuth angle of the source.
+Assumed Altitude angle of the source.
+Angular separation between the assumed and reconstructed positions +in the sky.
+Check if two histogram tables have the same binning
+First histogram table, as created by
+~pyirf.binning.create_histogram_table
Second histogram table
+Calculate the solid angle of a view cone.
+Opening angle of the view cone.
+Solid angle of a view cone with opening angle angle.
Functions to calculate benchmarks.
+
|
+Calculate bias and energy resolution. |
+
| + | Calculate bias and energy resolution. |
+
|
+Calculate the angular resolution. |
+
Utility functions for binning
+
|
+Add under and overflow bins to a bin array. |
+
|
++ |
|
+Calculate bin indices of inidividula entries of the given data array using the supplied binning. |
+
|
+Create a bin array with bins equally spaced in logarithmic energy with |
+
|
+Histogram a variable from events data into an astropy table. |
+
|
+Function joins bins into lo and hi part, e.g. [0, 1, 2] and [1, 2, 4] into [0, 1, 2, 4] It works on multidimentional arrays as long as the binning is in the last axis. |
+
|
+Rebinning of a histogram by interpolation along a given axis. |
+
|
+Inverted function to join_bin_hi_lo, e.g. it splits [0, 1, 2, 4] into [0, 1, 2] and [1, 2, 4]. |
+
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]
Adds an extrapolator for parametrized compontents utilizing blending over visible edges, resulting +in a smooth extrapolation compared to the NearestSimplexExtrapolator. [#253]
Ignore warnings about invalid floating point operations when calculating n_signal and n_signal_weigthed because the relative sensitivty is frequently NaN. [#264]
Add basic combinatoric fill-value handling for RAD_MAX estimation. [#282]
Fix PowerLaw.from_simulation for the new format of SimulatedEventsInformation,
+it was broken since splitting the single viewcone into viewcone_min and viewcone_max. [#258]
This release contains an important bug fix for the energy dispersion computation, +it was wrongly normalized before.
+In prior versions of pyirf, the energy dispersion matrix was normalized to a +sum of 1 over the migration axis. +This is wrong, the correct normalization is to an integral of 1, which is fixed now.
+The internal API of the interpolation functions had to be adapted to take in additional +keywords, mainly the bin edges and the kind of normalization (standard or solid angle cone sections). [#250]
+Replace single viewcone argument of SimulationInfo with
+viewcone_min and viewcone_max, e.g. to correctly enable
+ring wobble simulations. [#239]
See above on the energy dispersion change.
Add option to specify which containment to use for angular resolution. [#234]
Change the interpolation API to top-level estimator classes that instantiate
+inter- and extrapolator objects. Drops the interpolate_xyz functions
+originally used to interpolate a xyz IRF component in favour of a XYZEstimator
+class. Moves data checks from intepolator to estimator classes.
Direct usage of interpolator objects is now discuraged, use estimator objects instead. [#228]
+Correctly fill n_events in angular_resolution, was always 0 before. [#231]
Remove condition that relative sensitivity must be > 1. +This condition was added by error and resulted in returning +nan if the flux needed to fulfill the conditions is larger than +the reference flux used to weight the events. [#241]
Add moment morphing as second interpolation method able to handle discretized PDF +components of IRFs. [#229]
Add a base structure for extrapolators similar to the interpolation case +as well as a first extrapolator for parametrized components, extrapolating from the +nearest simplex in one or two dimensions. [#236]
Add an extrapolator for discretized PDF components, extrapolating from the +nearest simplex in one or two dimensions utilizing the same approach moment morphing +interpolation uses. [#237]
Add a DiscretePDFNearestNeighborSearcher and a ParametrizedNearestNeighborSearcher to support nearest neighbor approaches
+as alternatives to inter-/ and extrapolation [#232]
Migrating the interpolation methods from pyirf.interpolation to interpolator
+objects, allowing for later inheritance for new algorithms and reusability. [#210]
Add and enable towncrier in CI. [#207]
Add a fixture containing three IRFs from the prod5 IRF data-release +for unit testing. Specifically the fixture contains the contents of:
++++
+- +
Prod5-North-20deg-AverageAz-4LSTs.180000s-v0.1.fits.gz.
- +
Prod5-North-40deg-AverageAz-4LSTs.180000s-v0.1.fits.gz
- +
Prod5-North-60deg-AverageAz-4LSTs.180000s-v0.1.fits.gz
The user has to download these irfs to
+irfs/usingdownload_irfs.py, +github’s CI does so automatically and caches them for convenience. [#211]
For releases between v0.4.1 and v0.8.1, please refer to the GitHub releases page.
+Released March 22nd, 2021
1 Contributors
Maximilian Nöthe
Released November 11th, 2020
2 Contributors
In order of number of commits:
+Maximilian Nöthe
Michele Peresano
This release is an important update that introduces three +changes in the cut optimization, background estimation and sensitivity calculation.
+Together, these changes bring the calculated sensitivities much closer to the ones calculated by +EventDisplay.
+Scale the relative flux calculated to reach the target sensitivity
+up if the requirements on the minimum number of signal events are not met.
+Essentially, instead of always calculating the flux that
+yields target_sensitivity and then checking if the two other conditions are met,
+we increase the required flux to meet the other requirements.
+This can result in new sensitivities where before pyirf would report no sensitivities,
+and report better sensitivities everywhere where the event number conditions where not
+met before at the target significance.
+The best sensitivity now is the lowest flux that just barely satisfies all
+requirements (so is at the minimum requirement of one of the three).
Differentiate between reco_source_fov_offset and true_source_fov_offset, +using the former for background rates and the latter for everything concerning +signal events.
Change optimize_gh_cut to do the optimization in terms of efficiency and
+limit this efficiency to max. 80 % in the EventDisplay comparison.
Smaller improvements also include:
+It is now possible to include a particle_type column in the event lists,
+which will result in additionally reporting all event counts also per particle_type.
+E.g. if particle_type is included in the background table consisting of both
+electrons and protons, estimate_background will not only report n_background(_weighted)
+but also n_electron(_weighted) and n_proton(_weighted)
relative_sensitivity now supports vectorized application and broadcasting
+of inputs, as previously wrongly advertized in the docstring.
#110 Optimize cuts in efficiency steps with maximum efficiency of 80% for EventDisplay comparison
#104 Scale flux for conditions, differenatiate reco and true source_fov_offset
#108 Add counts / weighted counts per particle type
#107 Small update to installation instructions
#106 Use vectorize for relative_sensitivity
Released October 5th, 2020
5 Contributors
In order of number of commits:
+Maximilian Nöthe
Michele Peresano
Noah Biederbeck
Lukas Nickel
Gaia Verna
This release is the result of the IRF sprint week in September 2020. +Many bug fixes and improvements were made to the code.
+As the target for the sprint week was to reproduce the approach of EventDisplay and
+the resulting IRFs, one scheme of cut optimization is implemented.
+The examples/calculate_eventdisplay_irfs.py should follow the approach
+of EventDisplay closely and shows what is currently implemented in pyirf.
+In the central and upper energy range, pyirf now reproduces the EventDisplay sensitivity
+exactly, the lower energy bins still show some disagreement.
+The cut optimization seems not yet to be the same as EventDisplay’s and will be further investigated.
+This example could be used as a starting point if you also want to do cut optimization for best sensitivity.
At least one version of each IRF is now implemented and can be stored in the GADF format. +Computation of full-enclosure IRFs should be possible but is of now not yet tested +on a reference dataset.
+#97 Store correct signal amount, store information on which checks failed for sensitivity bins (Maximilian Nöthe)
#96 Add integration test (Michele Peresano)
#98 Remove option point_like for psf (Maximilian Nöthe)
#95 Cut updates (Maximilian Nöthe)
#91 Fix conditions to take relative sensitivity into account, fixes #90 (Maximilian Nöthe)
#89 Fix brentq returning the lower bound of 0 for flat li ma function (Maximilian Nöthe)
#85 Improve comparison to EventDisplay (Maximilian Nöthe)
#75 Add a function to check a table for required cols / units (Maximilian Nöthe)
#86 Fix Li & Ma significance for n_off = 0 (Maximilian Nöthe)
#76 Feature resample histogram (Noah Biederbeck, Lukas Nickel)
#79 Fix integration of power law pdf in simulations.py (Gaia Verna)
#80 Estimate unique runs taking pointing pos into account (Maximilian Nöthe)
#71 Background estimation (Maximilian Nöthe)
#78 Change argument order in create_rad_max_hdu (Lukas Nickel)
#77 Calculate optimized cut on only the events surviving gh separation (Maximilian Nöthe)
#68 Effective area 2d (Maximilian Nöthe)
#67 Add method integrating sim. events in FOV bins (Maximilian Nöthe)
#63 Verify hdus using ogadf-schema (Maximilian Nöthe)
#58 Implement Background2d (Maximilian Nöthe)
#52 Add sections about tests, coverage and building docs to docs (Maximilian Nöthe)
#46 Add PyPI deploy and metadata (Maximilian Nöthe)
Released September 27th, 2020
4 Contributors
In order of number of commits:
+Maximilian Nöthe
Michele Peresano
Lukas Nickel
Hugo van Kemenade
For this version, pyirf’s API was completely rewritten from scratch, +merging code from several projects (pyirf, pyfact, fact-project/irf) to provide a library to compute IACT +IRFs and sensitivity and store them in the GADF data format.
+The class based API using a configuration file was replaced by a finer grained +function based API.
+Implemented are point-like IRFs and sensitivity.
+This release was the starting point for the IRF sprint week in September 2020, +where the refactoring continued.
+This is a pre-release.
+Released September 16th, 2020
This is a pre-release.
+Released May 27th, 2020
3 contributors
Started basic maintenance
Started refactoring
First tests with CTA-LST data
In alphabetical order by last name:
+Lea Jouvin
Michele Peresano
Thomas Vuillaume
We use the GitHub issue tracker +for individual issues and the GitHub Projects page can give you a quick overview.
+If you found a bug or you are missing a feature, please check the existing +issues and then open a new one or contribute to the existing issue.
+We use the standard GitHub workflow.
+If you are not part of the cta-observatory organization,
+you need to fork the repository to contribute.
+See the GitHub tutorial on forks if you are unsure how to do this.
When you find something that is wrong or missing
++++
+- +
Go to the issue tracker and check if an issue already exists for your bug or feature
- +
In general it is always better to anticipate a PR with a new issue and link the two
To work on a bug fix or new feature, create a new branch, add commits and open your pull request
+If you think your pull request is good to go and ready to be reviewed, +you can directly open it as normal pull request.
You can also open it as a “Draft Pull Request”, if you are not yet finished +but want to get early feedback on your ideas.
Especially when working on a bug, it makes sense to first add a new +test that fails due to the bug and in a later commit add the fix showing +that the test is then passing. +This helps understanding the bug and will prevent it from reappearing later.
Create a changelog entry in docs/changes, please note the README.md there.
+Minor changes (on the magnitude of fixing a broken link or renaming a variable) can receive the no-changelog-needed label.
+This should, however, be a rare exception.
Wait for review comments and then implement or discuss requested changes.
We use Github Actions to +run the unit tests and documentation building automatically for every pull request. +Passing unit tests and coverage of the changed code are required for all pull requests.
+For more immediate feedback, you should run the tests locally before pushing, +as builds on travis take quite long.
+To run the tests locally, make sure you have the tests extras installed and then +run
+$ pytest -v
+To also inspect the coverage, run
+$ pytest --cov=pyirf --cov-report=html -v
+This will create a coverage report in html form in the htmlcov directory,
+which you can serve locally using
$ python -m http.server -d htmlcov
+After this, you can view the report in your browser by visiting the url printed +to the terminal.
+This documentation uses sphinx and restructured text. +For an Introduction, see the Sphinx documentation.
+To build the docs locally, enter the docs directory and call:
make html
+Some changes require a full remake of the documentation, for that call
+make clean html
+If you created or deleted file or submodule, you also need to remove the
+api directory, it will be regenerated automatically.
Make sure the docs are built without warnings from sphinx, as these +will be treated as errors in the build in the CI system as they most often +result in broken styling.
+To look at the docs, use
+$ python -m http.server _build/html
+and visit the printed URL in your browser.
+Together with the changes that will come with you PR, you should check that the +following maintenance files are up-to-date:
+.mailmap
CODEOWNERS
.zenodo.json
Please also have a look at the
+ctapipe development guidelines
The Open Gamma-Ray Astronomy data formats +which also describe the IRF formats and their definitions.
ctools documentation page on IRFs
|
+Optimize the gh-score cut in every energy bin of reconstructed energy for best sensitivity. |
+
|
+Calculate cuts as the percentile of a given quantity in bins of another quantity. |
+
|
+Evaluate a binned cut as defined in cut_table on given events. |
+
|
+checks if the same cuts have been applied in all of them |
+
The examples/calculate_eventdisplay_irfs.py file is
+using pyirf to optimize cuts, calculate sensitivity and IRFs
+and then store these to FITS files for DL2 event lists from EventDisplay.
The ROOT files were provided by Gernot Maier and converted to FITS format +using the EventDisplay DL2 converter script. +The resulting FITS files are the input to the example and can be downloaded using:
+./download_private_data.sh
+This requires curl and unzip to be installed.
+The download is password protected, please ask one of the maintainers for the
+password.
A detailed explanation of the contents of such DL2 files can be found +here (internal).
+The example can then be run from the root of the repository after installing pyirf +by running:
+python examples/calculate_eventdisplay_irfs.py
+A jupyter notebook plotting the results and comparing them to the EventDisplay output
+is available in examples/comparison_with_EventDisplay.ipynb
The examples/plot_spectra.py visualizes the Flux models included
+in pyirf for Crab Nebula, cosmic ray and electron flux.
This module provides functions to convert the pyirf quantities
+for IRFs and the binning to the corresponding gammapy classes.
| + | Create a |
+
| + | Create a |
+
|
+Create a |
+
| + | + |
| + | + |
| + | + |
| + | + |
| + |
| + |
| + | + |
|
+ + |
| + |
| + |
| + |
| + | + |
| + | + |
| + |
| + | + |
pyirf is a prototype for the generation of Instrument Response Functions (IRFs) +for the Cherenkov Telescope Array +(CTA). +The package is being developed and tested by members of the CTA consortium and +is a spin-off of the analog sub-process of the +pipeline protopype.
+Its main features are currently to
++++
+- +
find the best cutoff in gammaness/score, to discriminate between signal +and background, as well as the angular cut to obtain the best sensitivity +for a given amount of observation time and a given template for the +source of interest (Cut Optimization)
- +
compute the instrument response functions, effective area, +point spread function and energy resolution (Instrument Response Functions)
- +
estimate the sensitivity of the array (Sensitivity),
with plans to extend its capabilities to reach the requirements of the +future observatory.
+The source code is hosted on a GitHub repository, to +which this documentation is linked.
+Warning
+This is not yet stable code, so expect large and rapid changes.
+If you use a released version of this software for a publication, +please cite it by using the corresponding DOI.
+latest : 
v0.5.0 : 
v0.4.0 : 
Overview
+ +API Documentation
+pyirf requires Python ≥3.7 and pip, plus the packages defined in
+the setup.py.
Core dependencies are
+numpy
astropy
scipy
We provide an environment file for Anaconda or Miniconda users.
+To install a released version, just install the pyirf package using
$ pip install pyirf
+or add it to the dependencies of your project.
+If you want to work on pyirf itself, clone the repository and install the local +copy of pyirf in development mode.
+The dependencies required to perform unit-testing and to build the documentation
+are defined in extras under tests and docs respectively.
These requirements can also be enabled by installing the all extra:
$ pip install -e '.[all]' # or [docs,tests] to install them separately
+You should isolate your pyirf development environment from the rest of your system.
+Either by using a virtual environment or by using conda environments.
+pyirf provides a conda environment.yml, that includes all dependencies:
$ conda env create -f environment.yml
+$ conda activate pyirf
+$ pip install -e '.[all]'
+In order to have passing unit-tests you have to download some CTA IRFs +from zenodo <https://zenodo.org/record/5499840>. Simply run
+$ python download_irfs.py
+which will download and unpack three IRF files to irfs/.
Run the tests to make sure everything is OK:
+$ pytest
+This module contains functions to inter- or extrapolate from a set of IRFs for different +conditions to a new IRF. Implementations of interpolation and extrapolation algorithms +exist as interpolator and extrapolator classes and are applied by top-level estimator +classes to IRF components. +Direct usage of the inter- and extrapolator classes is discouraged, as only the estimator classes +check the data for consistency.
+Most methods support an arbitrary number of interpolation dimensions although it +is strongly advised to limit those for reasonable results. +The herein provided functionalities can e.g. be used to interpolate the IRF +for a zenith angle of 30° from available IRFs at 20° and 40°.
+| + | Estimator class for effective area tables (AEFF_2D). |
+
| + | Estimator class for rad-max tables (RAD_MAX, RAD_MAX_2D). |
+
| + | Estimator class for energy dispersions (EDISP_2D). |
+
| + | Estimator class for point spread function tables (PSF_TABLE). |
+
This module provides inter- and extrapolation classes that can be +plugged into the estimator classes. +Not all of these classes support arbitrary grid-dimensions where the grid +in this context is the grid of e.g. observation parameters like zenith angle and +magnetic field inclination (this would be a 2D grid) on which template IRFs exist +and are meant to be inter- or extrapolated.
+For parametrized components (Effective Areas and Rad-Max tables) these classes are:
+Name |
+Type |
+Grid-Dim |
+Note |
+
|---|---|---|---|
| + | Interpolation |
+Arbitrary |
+See also |
+
| + | Extrapolation |
+1D or 2D |
+Linear (1D) or baryzentric (2D) extension outside the grid’s convex hull from the nearest simplex. |
+
| + | Extrapolation |
+1D or 2D |
+Like |
+
| + | Nearest Neighbor |
+Arbitrary |
+Nearest neighbor finder usable instead of inter- and/or extrapolation. |
+
For components represented by discretized PDFs (PSF and EDISP tables) these classes are:
+Name |
+Type |
+Grid-Dim |
+Note |
+
|---|---|---|---|
| + | Interpolation |
+Arbitrary |
++ |
| + | Interpolation |
+1D or 2D |
+Adaption of [Baa+15] to discretized PDFs. |
+
| + | Extrapolation |
+1D or 2D |
+Extension of [Baa+15] beyond the grid’s convex hull from the nearest simplex. |
+
| + | Nearest Neighbor |
+Arbitrary |
+Nearest neighbor finder usable instead of inter- and/or extrapolation. |
+
P. Alfred (1984). Triangular Extrapolation. +Technical summary rept., Univ. of Wisconsin-Madison. https://apps.dtic.mil/sti/pdfs/ADA144660.pdf
+B. E. Hollister and A. T. Pang (2013). Interpolation of Non-Gaussian Probability Distributions for Ensemble Visualization. +https://engineering.ucsc.edu/sites/default/files/technical-reports/UCSC-SOE-13-13.pdf
+A. L. Read (1999). Linear Interpolation of Histograms. +Nucl. Instrum. Methods Phys. Res. A 425, 357-360. https://doi.org/10.1016/S0168-9002(98)01347-3
+M. Baak, S. Gadatsch, R. Harrington and W. Verkerke (2015). Interpolation between +multi-dimensional histograms using a new non-linear moment morphing method +Nucl. Instrum. Methods Phys. Res. A 771, 39-48. https://doi.org/10.1016/j.nima.2014.10.033
+Usage of the estimator classes is simple.
+As an example, consider CTA’s Prod5 IRFs [CTA+21], they can be downloaded manually or by executing
+download_irfs.py in pyirf's root directory, which downloads them to .../pyirf/irfs/.
+The estimator classes can simply be used by first creating an instance of the respective class with all
+relevant information and then using the object’s __call__ interface the obtain results for a specific
+target point.
+As the energy dispersion represents one of the discretized PDF IRF components, one can use the
+MomentMorphInterpolator for interpolation and the DiscretePDFNearestNeighborSearcher
+for extrapolation.
import numpy as np
+
+from gammapy.irf import load_irf_dict_from_file
+from glob import glob
+from pyirf.interpolation import (
+ EnergyDispersionEstimator,
+ MomentMorphInterpolator,
+ DiscretePDFNearestNeighborSearcher
+)
+
+# Load IRF data, replace path with actual path
+PROD5_IRF_PATH = "pyirf/irfs/*.fits.gz"
+
+irfs = [load_irf_dict_from_file(path) for path in sorted(glob(PROD5_IRF_PATH))]
+
+edisps = np.array([irf["edisp"].quantity for irf in irfs])
+bin_edges = irfs[0]["edisp"].axes["migra"].edges
+# IRFs are for zenith distances of 20, 40 and 60 deg
+zen_pnt = np.array([[20], [40], [60]])
+
+# Create estimator instance
+edisp_estimator = EnergyDispersionEstimator(
+ grid_points=zen_pnt,
+ migra_bins=bin_edges,
+ energy_dispersion=edisps,
+ interpolator_cls=MomentMorphInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=DiscretePDFNearestNeighborSearcher,
+ extrapolator_kwargs=None,
+ )
+
+ # Estimate energy dispersions
+ interpolated_edisp = edisp_estimator(np.array([[30]]))
+ extrapolated_edisp = edisp_estimator(np.array([[10]]))
+Cherenkov Telescope Array Observatory & Cherenkov Telescope Array Consortium. (2021). +CTAO Instrument Response Functions - prod5 version v0.1 (v0.1) [Data set]. Zenodo. +https://doi.org/10.5281/zenodo.5499840
+To create a estimator class for an IRF component not yet implemented, one can simply +inherit from respective base class. +There are two, tailored to either parametrized or discrete PDF components.
+| + | Base class for all Estimators working on IRF components that represent parametrized or scalar quantities. |
+
| + | Base class for all Estimators working on IRF components that represent discretized PDFs. |
+
Consider an example, where one is interested in an estimator for simple Gaussians.
+As this is already the scope of the DiscretePDFComponentEstimator base class and
+for the sake of this demonstration, let the Gaussians come with some
+units attached that need handling:
import astropy.units as u
+from pyirf.interpolation import (DiscretePDFComponentEstimator,
+ MomentMorphInterpolator)
+
+class GaussianEstimatior(DiscretePDFComponentEstimator):
+ @u.quantity_input(gaussians=u.m)
+ def __init__(
+ self,
+ grid_points,
+ bin_edges,
+ gaussians,
+ interpolator_cls=MomentMorphInterpolator,
+ interpolator_kwargs=None,
+ extrapolator_cls=None,
+ extrapolator_kwargs=None,
+ ):
+ if interpolator_kwargs is None:
+ interpolator_kwargs = {}
+
+ if extrapolator_kwargs is None:
+ extrapolator_kwargs = {}
+
+ self.unit = gaussians.unit
+
+ super().__init__(
+ grid_points=grid_points,
+ bin_edges=bin_edges,
+ binned_pdf=gaussians.to_value(u.m),
+ interpolator_cls=interpolator_cls,
+ interpolator_kwargs=interpolator_kwargs,
+ extrapolator_cls=extrapolator_cls,
+ extrapolator_kwargs=extrapolator_kwargs,
+ )
+
+ def __call__(self, target_point):
+ res = super().__call__(target_point)
+
+ # Return result with correct unit
+ return u.Quantity(res, u.m, copy=False).to(self.unit)
+This new estimator class can now be used just like any other estimator class already
+implemented in pyirf.interpolation.
+While the extrapolator_cls argument can be empty when creating an instance of
+GaussianEstimator, effectively disabling extrapolation and raising an error in
+case it would be needed regardless, assume the desired extrapolation method to be
+MomentMorphNearestSimplexExtrapolator:
import numpy as np
+from pyirf.interpolation import MomentMorphNearestSimplexExtrapolator
+from scipy.stats import norm
+
+bins = np.linspace(-10, 10, 51)
+grid = np.array([[1], [2], [3]])
+
+gaussians = np.array([np.diff(norm(loc=x, scale=1/x).cdf(bins))/np.diff(bins) for x in grid])
+
+estimator = GaussianEstimatior(
+ grid_points = grid,
+ bin_edges = bins,
+ gaussians = gaussians * u.m,
+ interpolator_cls = MomentMorphInterpolator,
+ extrapolator_cls = MomentMorphNearestSimplexExtrapolator
+)
+This estimator object can now easily be used to estimate Gaussians at arbitrary target points:
+targets = np.array([[0.9], [1.5]])
+
+results = u.Quantity([estimator(target).squeeze() for target in targets])
+| + | How a discrete PDF is normalized |
+
| + | Base class for all Estimators working on specific IRF components. |
+
| + | Base class for all Estimators working on IRF components that represent parametrized or scalar quantities. |
+
| + | Base class for all Estimators working on IRF components that represent discretized PDFs. |
+
| + | Base class for all interpolators, only knowing grid-points, providing a common __call__-interface. |
+
| + | Base class for all interpolators used with IRF components that can be independently interpolated, e.g. parametrized ones like 3Gauss but also AEff. |
+
| + | Base class for all interpolators used with binned IRF components like EDisp. |
+
| + | Base class for all extrapolators, only knowing grid-points, providing a common __call__-interface. |
+
| + | Base class for all extrapolators used with IRF components that can be treated independently, e.g. parametrized ones like 3Gauss but also AEff. |
+
| + | Base class for all extrapolators used with binned IRF components like EDisp. |
+
| + | Dummy NearestNeighbor approach usable instead of actual Interpolation/Extrapolation |
+
|
+Base class for all Estimators working on specific IRF components. |
+
|
+Base class for all interpolators, only knowing grid-points, providing a common __call__-interface. |
+
|
+Dummy NearestNeighbor approach usable instead of actual Interpolation/Extrapolation |
+
|
+Base class for all extrapolators, only knowing grid-points, providing a common __call__-interface. |
+
|
+How a discrete PDF is normalized |
+
|
+Base class for all extrapolators used with binned IRF components like EDisp. |
+
|
+Base class for all extrapolators used with IRF components that can be treated independently, e.g. parametrized ones like 3Gauss but also AEff. |
+
|
+Base class for all Estimators working on IRF components that represent discretized PDFs. |
+
|
+Base class for all interpolators used with binned IRF components like EDisp. |
+
|
+Dummy NearestNeighbor approach usable instead of actual interpolation/extrapolation. |
+
|
+"Wrapper arounf scipy.interpolate.griddata. |
+
|
+Interpolator class providing Moment Morphing to interpolate discretized PDFs. |
+
|
+Extrapolator class extending moment morphing interpolation outside a grid's convex hull. |
+
|
+Base class for all Estimators working on IRF components that represent parametrized or scalar quantities. |
+
|
+Base class for all interpolators used with IRF components that can be independently interpolated, e.g. parametrized ones like 3Gauss but also AEff. |
+
|
+Dummy NearestNeighbor approach usable instead of actual interpolation/extrapolation Compatible with parametrized IRF component API. |
+
| + | Extrapolator class extending linear or baryzentric interpolation outside a grid's convex hull. |
+
|
+Extrapolator using blending over visible edges. |
+
|
+Interpolator class providing quantile interpoalation. |
+
|
+Estimator class for effective area tables (AEFF_2D). |
+
|
+Estimator class for rad-max tables (RAD_MAX, RAD_MAX_2D). |
+
|
+Estimator class for energy dispersions (EDISP_2D). |
+
|
+Estimator class for point spread function tables (PSF_TABLE). |
+
pyirfpyirf aims to provide functions to calculate the Instrument Response Functions (IRFs)
+and sensitivity for Imaging Air Cherenkov Telescopes.
To support a wide range of use cases, pyirf opts for a library approach of
+composable building blocks with well-defined inputs and outputs.
For more information on IRFs, have a look at the Specification of the Data Formats for Gamma-Ray Astronomy +or the ctools documentation on IRFs.
+Currently, pyirf allows calculation of the usual factorization of the IRFs into:
Effective area
Energy migration
Point spread function
Additionally, functions for calculating point-source flux sensitivity are provided. +Flux sensitivity is defined as the smallest flux an IACT can detect with a certain significance, +usually 5 σ according to the Li&Ma likelihood ratio test, in a specified amount of time.
+pyirf also provides functions to calculate event weights, that are needed
+to translate a set of simulations to a physical flux for calculating sensitivity
+and expected event counts.
Event selection with energy dependent cuts is also supported, +but at the moment, only rudimentary functions to find optimal cuts are provided.
+pyirf does not rely on specific input file formats.
+All functions take numpy arrays, astropy quantities or astropy tables for the
+required data and also return the results as these objects.
~pyirf.io provides functions to export the internal IRF representation
+to FITS files following the Specification of the Data Formats for Gamma-Ray Astronomy
Most functions for calculating IRFs need DL2 event lists as input.
+We use ~astropy.table.QTable instances for this.
+QTable are very similar to the standard ~astropy.table.Table,
+but offer better interoperability with astropy.units.Quantity.
We expect certain columns to be present in the tables with the appropriate units. +To learn which functions need which columns to be present, have a look at the API Documentation
+Most functions only need a small subgroup of these columns.
+Column |
+Unit |
+Explanation |
+
|---|---|---|
true_energy |
+TeV |
+True energy of the simulated shower |
+
weight |
++ | Event weight |
+
true_source_fov_offset |
+deg |
+Distance of the true origin to the FOV center |
+
reco_source_fov_offset |
+deg |
+Distance of the reco origin to the FOV center |
+
true_alt |
+deg |
+True altitude of the shower origin |
+
true_az |
+deg |
+True azimuth of the shower origin |
+
pointing_alt |
+deg |
+Altitude of the field of view center |
+
pointing_az |
+deg |
+Azimuth of the field of view center |
+
reco_energy |
+TeV |
+Reconstructed energy of the simulated shower |
+
reco_alt |
+deg |
+Reconstructed altitude of shower origin |
+
reco_az |
+deg |
+Reconstructed azimuth of shower origin |
+
gh_score |
++ | Gamma/Hadron classification output |
+
multiplicity |
++ | Number of telescopes used in the reconstruction |
+
This module contains functions to read input data and write IRFs in GADF format.
+Currently there is only support for reading EventDisplay DL2 FITS files, +which were converted from the ROOT files by using EventDisplay DL2 conversion scripts.
+
|
+Read a DL2 FITS file as produced by the EventDisplay DL2 converter from ROOT files: https://github.com/Eventdisplay/Converters/blob/master/DL2/generate_DL2_file.py |
+
|
+Create a fits binary table HDU in GADF format for the PSF table. |
+
|
+Create a fits binary table HDU in GADF format for effective area. |
+
|
+Create a fits binary table HDU in GADF format for the energy dispersion. |
+
|
+Create a fits binary table HDU in GADF format for the PSF table. |
+
|
+Create a fits binary table HDU in GADF format for the directional cut. |
+
|
+Create a fits binary table HDU in GADF format for the background 2d table. |
+
The collection area, which is proportional to the gamma-ray efficiency +of detection, is computed as a function of the true energy. The events which +are considered are the ones passing the threshold of the best cutoff plus +the angular cuts.
+The energy dispersion matrix, ratio of the reconstructed energy over the true energy +as a function of the true energy, is computed with the events passing the +threshold of the best cutoff plus the angular cuts.
+The corresponding energy migration matrix can be build from the dispersion matrix.
+The PSF describes the probability of measuring a gamma ray +of a given true energy and true position at a reconstructed position.
+The background rate is calculated as the number of background-like events per +second, reconstructed energy and solid angle. +The current version is computed in radially symmetric bins in the Field Of View.
+
|
+Calculate effective area for histograms of selected and total simulated events |
+
|
+Calculate effective area in bins of true energy. |
+
| + | Calculate effective area in bins of true energy and field of view offset. |
+
|
+Calculate energy dispersion for the given DL2 event list. |
+
|
+Calculate the table based PSF (radially symmetrical bins around the true source) |
+
|
+Calculate background rates in radially symmetric bins in the field of view. |
+
pyirf to calculate IRFs from the FACT Open DataNote In FACT, we used a different terminology, partly because of being a monoscopic telescope or out of confusion witht the CTA terms, in this context DL3 are reconstructed events, but not necessarily already with the IRF
+[1]:
+import numpy as np
+import astropy.units as u
+import matplotlib.pyplot as plt
+import subprocess as sp
+[2]:
+%matplotlib inline
+[3]:
+path = "gamma_test_dl3.hdf5"
+url = f"https://factdata.app.tu-dortmund.de/dl3/FACT-Tools/v1.1.2/{path}"
+ret = sp.run(["curl", "-z", path, "-fsSLO", url], stdout=sp.PIPE, stderr=sp.PIPE, encoding='utf-8')
+if ret.returncode != 0:
+ raise IOError(ret.stderr)
+[4]:
+from astropy.table import QTable
+import astropy.units as u
+import tables
+Currently, pyirf only works with powerlaw simulated events, like CORSIKA does it. We want to also support arbitrary histograms / event distributions, but that is not yet implemented.
+This can be created from a file with that information, but I will just create it here.
+[5]:
+from pyirf.simulations import SimulatedEventsInfo
+
+simulation_info = SimulatedEventsInfo(
+ energy_min=200 * u.GeV,
+ energy_max=50 * u.TeV,
+ spectral_index=-2.7,
+ n_showers=12600000,
+ max_impact=300 * u.m,
+ viewcone_min=0 * u.deg,
+ viewcone_max=0 * u.deg,
+)
+pyirf does not prescribe or use a specific DL2 file format. You need to read the data into an astropy.table.QTable following our conventions, detailed in the docs here:
https://cta-observatory.github.io/pyirf/introduction.html#dl2-event-lists
+[6]:
+gammas = QTable()
+
+# mapping of <target column name>: (<column in the file, unit>)
+columns = {
+ 'obs_id': ('run_id', None),
+ 'event_id': ('event_num', None),
+ 'reco_energy': ('gamma_energy_prediction', u.GeV),
+ 'true_energy': ('corsika_event_header_total_energy', u.GeV),
+ 'true_az': ('source_position_az', u.deg),
+ 'pointing_az': ('pointing_position_az', u.deg),
+ 'theta': ('theta_deg', u.deg),
+ 'gh_score': ('gamma_prediction', None),
+}
+
+with tables.open_file('gamma_test_dl3.hdf5', mode='r') as f:
+ events = f.root.events
+
+ for col, (name, unit) in columns.items():
+ if unit is not None:
+ gammas[col] = u.Quantity(events[name][:], unit, copy=False)
+ else:
+ gammas[col] = events[name][:]
+
+ gammas['true_alt'] = u.Quantity(90 - events['source_position_zd'][:], u.deg, copy=False)
+ gammas['pointing_alt'] = u.Quantity(90 - events['pointing_position_zd'][:], u.deg, copy=False)
+
+
+# make it display nice
+for col in gammas.colnames:
+ if gammas[col].dtype == float:
+ gammas[col].info.format = '.2f'
+[7]:
+gammas[:10]
+[7]:
+| obs_id | event_id | reco_energy | true_energy | true_az | pointing_az | theta | gh_score | true_alt | pointing_alt |
|---|---|---|---|---|---|---|---|---|---|
| GeV | GeV | deg | deg | deg | deg | deg | |||
| int64 | int64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 |
| 11583 | 403 | 638.00 | 712.87 | 353.00 | 349.76 | 1.49 | 0.45 | 79.34 | 79.33 |
| 106806 | 237 | 815.28 | 885.04 | 353.00 | 42.35 | 0.02 | 0.82 | 89.37 | 89.23 |
| 11325 | 166 | 838.62 | 928.05 | 353.00 | -4.95 | 0.26 | 0.75 | 83.37 | 83.92 |
| 13486 | 165 | 680.72 | 420.22 | 353.00 | 348.77 | 0.13 | 0.78 | 81.92 | 82.02 |
| 14228 | 122 | 1896.68 | 2458.86 | 353.00 | 351.27 | 0.08 | 0.88 | 70.51 | 70.69 |
| 108312 | 221 | 4430.69 | 5347.98 | 353.00 | -5.94 | 0.05 | 0.97 | 66.55 | 66.12 |
| 13327 | 310 | 3649.23 | 4550.83 | 353.00 | 347.98 | 0.04 | 0.91 | 83.53 | 83.75 |
| 107296 | 237 | 1723.47 | 2109.52 | 353.00 | 350.67 | 0.05 | 0.20 | 82.56 | 82.05 |
| 14269 | 217 | 956.90 | 953.94 | 353.00 | -5.98 | 0.17 | 0.79 | 69.53 | 70.02 |
| 108669 | 183 | 804.27 | 626.66 | 353.00 | -6.38 | 0.12 | 0.84 | 61.06 | 60.54 |
We remove likely hadronic events by requiring a minimal gh_score.
We will calculate point-like IRFs, that means selecting events in a radius around the assumed source position.
+[8]:
+gammas['selected_gh'] = gammas['gh_score'] > 0.8
+gammas['selected_theta'] = gammas['theta'] < 0.16 * u.deg
+
+gammas['selected'] = gammas['selected_gh'] & gammas['selected_theta']
+
+np.count_nonzero(gammas['selected']) / len(gammas)
+[8]:
+
+0.18115575805640652
+We only have point-like simulations at a specific wobble offset (0.6° for FACT), so we calculate the effective area for all events at once, equivalent to a single fov offset bin.
+[9]:
+from pyirf.binning import create_bins_per_decade, bin_center
+[10]:
+true_energy_bins = create_bins_per_decade(simulation_info.energy_min, simulation_info.energy_max, 5)
+
+# single offset bin around the wobble distance
+# since we are dealing with point-like simulations
+wobble_offset = 0.6 * u.deg
+fov_offset_bins = [0.59, 0.61] * u.deg
+Effective area is calculated before and after cuts, for the IRF, we only need after the event selection has been applied.
+The difference between point-like IRFs and Full-Enclosure IRFs is if a theta cut has been applied or not.
+[11]:
+from pyirf.irf import effective_area_per_energy
+
+aeff_all = effective_area_per_energy(gammas, simulation_info, true_energy_bins)
+aeff_selected = effective_area_per_energy(gammas[gammas['selected']], simulation_info, true_energy_bins)
+Let’s use gammapy to plot the IRF
+[12]:
+# utility function to converet pyirf Quantities to the gammapy classes
+from pyirf.gammapy import create_effective_area_table_2d
+
+plt.figure()
+
+for aeff, label in zip((aeff_all, aeff_selected), ('All Events', 'Selected Events')):
+ aeff_gammapy = create_effective_area_table_2d(
+ # add a new dimension for the single fov offset bin
+ effective_area=aeff[..., np.newaxis],
+ true_energy_bins=true_energy_bins,
+ fov_offset_bins=fov_offset_bins,
+ )
+
+
+ aeff_gammapy.plot_energy_dependence(label=label, offset=[wobble_offset])
+
+plt.xlim(true_energy_bins.min().to_value(u.GeV), true_energy_bins.max().to_value(u.GeV))
+plt.yscale('log')
+plt.xscale('log')
+plt.legend()
+
+print(aeff_gammapy)
+
+/opt/hostedtoolcache/Python/3.9.19/x64/lib/python3.9/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
+ from .autonotebook import tqdm as notebook_tqdm
+
+EffectiveAreaTable2D
+--------------------
+
+ axes : ['energy_true', 'offset']
+ shape : (11, 1)
+ ndim : 2
+ unit : m2
+ dtype : float64
+
+
+The point spread function describes how well the direction of the gamma rays is estimated.
+[13]:
+from pyirf.irf import psf_table
+from pyirf.utils import calculate_source_fov_offset
+
+
+gammas['true_source_fov_offset'] = calculate_source_fov_offset(gammas)
+
+
+source_offset_bins = np.linspace(0, 3, 100) * u.deg
+
+# calculate this only for the events after the gamma/hadron separation
+psf = psf_table(gammas[gammas['selected_gh']], true_energy_bins, source_offset_bins, fov_offset_bins)
+[14]:
+psf.shape
+[14]:
+
+(11, 1, 99)
+Again, let’s use gammapy to plot:
+[15]:
+from pyirf.gammapy import create_psf_3d
+
+psf_gammapy = create_psf_3d(psf, true_energy_bins, source_offset_bins, fov_offset_bins)
+
+plt.figure()
+psf_gammapy.plot_psf_vs_rad(offset=[wobble_offset], energy_true=[1., 10.]*u.TeV)
+plt.legend(plt.gca().lines, ['1 TeV', '10 TeV'])
+[15]:
+
+<matplotlib.legend.Legend at 0x7f233171e0d0>
+
+Describes how well the energy is estimated
+[16]:
+from pyirf.irf import energy_dispersion
+
+# logarithmic space, is "symmetric" in terms of ratios 0.1 is a factor of 10 from 1 is a factor of 10 from 10
+migration_bins = np.geomspace(0.1, 10, 100)
+
+edisp = energy_dispersion(
+ gammas[gammas['selected']],
+ true_energy_bins=true_energy_bins,
+ fov_offset_bins=fov_offset_bins,
+ migration_bins=migration_bins,
+)
+Plot edisp
+[17]:
+from gammapy.irf import EnergyDispersion2D
+
+plt.figure()
+plt.pcolormesh(
+ true_energy_bins.to_value(u.GeV),
+ migration_bins,
+ edisp[:, :, 0].T,
+ cmap='inferno'
+)
+
+plt.xlabel('$E_\mathrm{true} / \mathrm{GeV}$')
+plt.ylabel('$\mu$')
+plt.yscale('log')
+plt.xscale('log')
+
+We use the classes and methods from astropy.io.fits and pyirf.io.gadf to write files following the GADF specification, which can be found here:
https://gamma-astro-data-formats.readthedocs.io/en/latest/
+[18]:
+from pyirf.io.gadf import create_aeff2d_hdu, create_energy_dispersion_hdu, create_psf_table_hdu
+from astropy.io import fits
+from astropy.time import Time
+from pyirf import __version__
+
+# set some common meta data for all hdus
+meta = dict(
+ CREATOR='pyirf-v' + __version__,
+ TELESCOP='FACT',
+ INSTRUME='FACT',
+ DATE=Time.now().iso,
+)
+
+hdus = []
+
+# every fits file has to have an Image HDU as first HDU.
+# GADF only uses Binary Table HDUs, so we need to add an empty HDU in front
+hdus.append(fits.PrimaryHDU(header=fits.Header(meta)))
+
+hdus.append(create_aeff2d_hdu(aeff_selected, true_energy_bins, fov_offset_bins, **meta))
+hdus.append(create_energy_dispersion_hdu(edisp, true_energy_bins, migration_bins, fov_offset_bins, **meta))
+hdus.append(create_psf_table_hdu(psf, true_energy_bins, source_offset_bins, fov_offset_bins, **meta))
+
+fits.HDUList(hdus).writeto('fact_irf.fits.gz', overwrite=True)
+| obs_id | event_id | reco_energy | true_energy | true_az | pointing_az | theta | gh_score | true_alt | pointing_alt |
|---|---|---|---|---|---|---|---|---|---|
| GeV | GeV | deg | deg | deg | deg | deg | |||
| int64 | int64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 |
| 11583 | 403 | 638.00 | 712.87 | 353.00 | 349.76 | 1.49 | 0.45 | 79.34 | 79.33 |
| 106806 | 237 | 815.28 | 885.04 | 353.00 | 42.35 | 0.02 | 0.82 | 89.37 | 89.23 |
| 11325 | 166 | 838.62 | 928.05 | 353.00 | -4.95 | 0.26 | 0.75 | 83.37 | 83.92 |
| 13486 | 165 | 680.72 | 420.22 | 353.00 | 348.77 | 0.13 | 0.78 | 81.92 | 82.02 |
| 14228 | 122 | 1896.68 | 2458.86 | 353.00 | 351.27 | 0.08 | 0.88 | 70.51 | 70.69 |
| 108312 | 221 | 4430.69 | 5347.98 | 353.00 | -5.94 | 0.05 | 0.97 | 66.55 | 66.12 |
| 13327 | 310 | 3649.23 | 4550.83 | 353.00 | 347.98 | 0.04 | 0.91 | 83.53 | 83.75 |
| 107296 | 237 | 1723.47 | 2109.52 | 353.00 | 350.67 | 0.05 | 0.20 | 82.56 | 82.05 |
| 14269 | 217 | 956.90 | 953.94 | 353.00 | -5.98 | 0.17 | 0.79 | 69.53 | 70.02 |
| 108669 | 183 | 804.27 | 626.66 | 353.00 | -6.38 | 0.12 | 0.84 | 61.06 | 60.54 |
| + p | ||
| + |
+ pyirf | + |
| + |
+ pyirf.benchmarks | + |
| + |
+ pyirf.binning | + |
| + |
+ pyirf.cut_optimization | + |
| + |
+ pyirf.cuts | + |
| + |
+ pyirf.gammapy | + |
| + |
+ pyirf.io | + |
| + |
+ pyirf.irf | + |
| + |
+ pyirf.sensitivity | + |
| + |
+ pyirf.simulations | + |
| + |
+ pyirf.spectral | + |
| + |
+ pyirf.statistics | + |
| + |
+ pyirf.utils | + |
pyirf", "Input / Output", "Instrument Response Functions", "Using pyirf to calculate IRFs from the FACT Open Data", "Example Notebooks", "Sensitivity", "Simulation Information", "Event Weighting and Spectrum Definitions", "Statistics", "Utility functions"], "titleterms": {"": 85, "0": 79, "03": 79, "05": 79, "07": 79, "08": 79, "09": 79, "1": 79, "10": 79, "11": 79, "14": 79, "15": 79, "16": 79, "19": 79, "2": 79, "2020": 79, "2021": 79, "2023": 79, "2024": 79, "22": 79, "23": 79, "27": 79, "3": 79, "4": 79, "8": 79, "9": 79, "add_overflow_bin": 4, "alpha": 79, "angular_resolut": 1, "api": [78, 79, 81, 82, 84, 85, 87, 89, 90, 93, 94, 95, 96, 97], "appli": [82, 91], "area": [90, 91], "author": 0, "background": 90, "background_2d": 48, "base": 87, "basecomponentestim": 19, "baseextrapol": 20, "baseinterpol": 21, "basenearestneighborsearch": 22, "benchmark": 77, "bin": [78, 91], "bin_cent": 5, "bug": 79, "build": 80, "calcul": [82, 83, 91], "calculate_bin_indic": 6, "calculate_event_weight": 70, "calculate_percentile_cut": 13, "calculate_sensit": 54, "calculate_source_fov_offset": 72, "calculate_theta": 73, "chang": 79, "changelog": 79, "check_histogram": 74, "cite": 85, "class": [87, 94, 95], "column": 88, "compare_irf_cut": 14, "compon": 87, "cone_solid_angl": 75, "contribut": 80, "contributor": 79, "coverag": 80, "crab_hegra": 58, "crab_magic_jheap2015": 59, "creat": [87, 91], "create_aeff2d_hdu": 42, "create_background_2d_hdu": 43, "create_bins_per_decad": 7, "create_effective_area_table_2d": 16, "create_energy_dispersion_2d": 17, "create_energy_dispersion_hdu": 44, "create_histogram_t": 8, "create_psf_3d": 18, "create_psf_table_hdu": 45, "create_rad_max_hdu": 46, "current": 80, "cut": [81, 82], "cut_optim": 81, "dampe_p_he_spectrum": 60, "data": [83, 91], "definit": [88, 95], "descript": 79, "detail": 80, "dev55": 79, "develop": [80, 86], "diffuse_flux_unit": 61, "discretepdfcomponentestim": 23, "discretepdfextrapol": 24, "discretepdfinterpol": 25, "discretepdfnearestneighborsearch": 26, "dispers": [90, 91], "dl2": [83, 88, 91], "document": [80, 85], "download": 91, "effect": [90, 91], "effective_area": 49, "effective_area_per_energi": 50, "effective_area_per_energy_and_fov": 51, "effectiveareaestim": 27, "energi": [90, 91], "energy_bias_resolut": 2, "energy_bias_resolution_from_energy_dispers": 3, "energy_dispers": 52, "energydispersionestim": 28, "estim": 87, "estimate_background": 55, "evaluate_binned_cut": 15, "event": [88, 91, 95], "eventdisplai": 83, "exampl": [83, 92], "export": 91, "extrapol": 87, "fact": 91, "featur": 79, "file": 91, "fit": 91, "fix": 79, "flux": 83, "format": 88, "from": 91, "full": 87, "function": [77, 78, 81, 82, 84, 89, 90, 91, 93, 95, 96, 97], "further": 80, "g0fefb93": 79, "gadf": 91, "gammapi": 84, "griddatainterpol": 29, "helper": 87, "histogram": 78, "how": 80, "includ": 83, "indic": 85, "info": 91, "inform": 94, "input": [88, 89], "instal": 86, "instrument": 90, "inter": 87, "interoper": 84, "interpol": 87, "introduct": [88, 89], "io": 89, "irf": [83, 87, 90, 91], "irfdoc_electron_spectrum": 62, "irfdoc_proton_spectrum": 63, "is_scalar": 76, "issu": 80, "join_bin_lo_hi": 9, "li_ma_signific": 71, "list": [88, 91], "logparabola": 64, "look": 80, "mainten": 79, "make": 80, "matrix": 90, "merg": 79, "model": 83, "modul": [78, 81, 82, 84, 93, 94, 95, 96, 97], "momentmorphinterpol": 30, "momentmorphnearestsimplexextrapol": 31, "new": [79, 87], "notebook": 92, "older": 79, "open": 91, "optim": [79, 81], "optimize_gh_cut": 12, "output": 89, "overview": 85, "packag": [77, 89, 90], "parametrizedcomponentestim": 34, "parametrizedextrapol": 35, "parametrizedinterpol": 36, "parametrizednearestneighborsearch": 37, "parametrizednearestsimplexextrapol": 38, "parametrizedvisibleedgesextrapol": 39, "pdfnormal": 32, "pdg_all_particl": 65, "point": [90, 91], "point_source_flux_unit": 66, "powerlaw": 67, "powerlawwithexponentialgaussian": 68, "procedur": 80, "project": [79, 80], "psf_tabl": 53, "psftableestim": 33, "pull": 79, "pyirf": [77, 78, 79, 81, 82, 84, 85, 88, 89, 90, 91, 93, 94, 95, 96, 97], "quantileinterpol": 40, "radmaxestim": 41, "rate": 90, "read": 91, "read_eventdisplay_fit": 47, "refactor": 79, "refer": [78, 81, 82, 84, 89, 90, 93, 94, 95, 96, 97], "relat": 79, "relative_sensit": 56, "releas": [79, 86], "request": 79, "resample_histogram1d": 10, "respons": 90, "run": 80, "select": 91, "sensit": [83, 93], "simul": [91, 94], "simulatedeventsinfo": 57, "softwar": 85, "spectral": 95, "spectrum": 95, "split_bin_lo_hi": 11, "spread": [90, 91], "statist": 96, "summari": 79, "tabl": 85, "tableinterpolationspectrum": 69, "test": 80, "thi": 85, "tracker": 80, "us": [87, 91], "util": [78, 97], "v0": 79, "variabl": 95, "version": 86, "visibl": 80, "visual": 83, "weight": 95, "welcom": 85, "your": 80}})
\ No newline at end of file
diff --git a/sensitivity.html b/sensitivity.html
new file mode 100644
index 000000000..e691b3b3c
--- /dev/null
+++ b/sensitivity.html
@@ -0,0 +1,174 @@
+
+
+
+
+
+
+ Functions to calculate sensitivity
+
|
+Calculate the relative sensitivity defined as the flux relative to the reference source that is detectable with significance |
+
|
+Calculate sensitivity for DL2 event lists in bins of reconstructed energy. |
+
|
+Estimate the number of background events for a point-like sensitivity. |
+
|
+Information about all simulated events, for calculating event weights. |
+
Functions and classes for calculating spectral weights
+
|
+Calculate event weights |
+
|
+A power law with normalization, reference energy and index. |
+
|
+A log parabola flux parameterization. |
+
| + | A power law with an additional Gaussian bump. |
+
|
+Interpolate flux points to obtain a spectrum. |
+
| + | Unit of a point source flux |
+
| + | Unit of a diffuse flux |
+
| + | Power Law parametrization of the Crab Nebula spectrum as published by HEGRA |
+
| + | Log-Parabola parametrization of the Crab Nebula spectrum as published by MAGIC |
+
| + | All particle spectrum |
+
| + | Proton spectrum definition defined in the CTA Prod3b IRF Document |
+
| + | Electron spectrum definition defined in the CTA Prod3b IRF Document |
+
| + | Interpolate flux points to obtain a spectrum. |
+
|
+Calculate the Li & Ma significance. |
+
|
+Workaround that also supports astropy quantities |
+
|
+Calculate sky separation between assumed and reconstructed positions. |
+
|
+Calculate angular separation between true and pointing positions. |
+
|
+Check if two histogram tables have the same binning |
+
|
+Calculate the solid angle of a view cone. |
+