files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import logging
  import numpy as np
  import astropy.units as u
  from astropy.io import fits
  from astropy.nddata.utils import NoOverlapError
  from astropy.table import Table
  from astropy.utils import lazyproperty
  from regions import CircleSkyRegion
  from gammapy.cube.edisp_map import EDispMap
  from gammapy.cube.psf_kernel import PSFKernel
  from gammapy.cube.psf_map import PSFMap
  from gammapy.data import GTI
  from gammapy.irf import EDispKernel, EffectiveAreaTable
  from gammapy.maps import Map, MapAxis
  from gammapy.modeling import Dataset, Parameters
  from gammapy.modeling.models import BackgroundModel, SkyModel, SkyModels
  from gammapy.modeling.parameter import _get_parameters_str
  from gammapy.spectrum import SpectrumDataset, SpectrumDatasetOnOff
  from gammapy.stats import cash, cash_sum_cython, wstat
  from gammapy.utils.random import get_random_state
  from gammapy.utils.scripts import make_name, make_path
  from .exposure import _map_spectrum_weight
  
  __all__ = ["MapDataset", "MapDatasetOnOff"]
  
  log = logging.getLogger(__name__)
  
  CUTOUT_MARGIN = 0.1 * u.deg
  RAD_MAX = 0.66
  RAD_AXIS_DEFAULT = MapAxis.from_bounds(
      0, RAD_MAX, nbin=66, node_type="edges", name="theta", unit="deg"
  )
  MIGRA_AXIS_DEFAULT = MapAxis.from_bounds(
      0.2, 5, nbin=48, node_type="edges", name="migra"
  )
  
  BINSZ_IRF_DEFAULT = 0.2
  
  
  class MapDataset(Dataset):
      """Perform sky model likelihood fit on maps.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Source sky models.
      counts : `~gammapy.maps.WcsNDMap`
          Counts cube
      exposure : `~gammapy.maps.WcsNDMap`
          Exposure cube
      mask_fit : `~gammapy.maps.WcsNDMap`
          Mask to apply to the likelihood for fitting.
      psf : `~gammapy.cube.PSFKernel` or `~gammapy.cube.PSFMap`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel` or `~gammapy.cube.EDispMap`
          Energy dispersion kernel
      background_model : `~gammapy.modeling.models.BackgroundModel`
          Background model to use for the fit.
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
          The "local" mode evaluates the model components on smaller grids to save computation time.
          This mode is recommended for local optimization algorithms.
          The "global" evaluation mode evaluates the model components on the full map.
          This mode is recommended for global optimization algorithms.
      mask_safe : `~gammapy.maps.WcsNDMap`
          Mask defining the safe data range.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
      """
  
      stat_type = "cash"
      tag = "MapDataset"
  
      def __init__(
          self,
          models=None,
          counts=None,
          exposure=None,
          mask_fit=None,
          psf=None,
          edisp=None,
          background_model=None,
          name=None,
          evaluation_mode="local",
          mask_safe=None,
          gti=None,
      ):
          if mask_fit is not None and mask_fit.data.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          if mask_safe is not None and mask_safe.data.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.evaluation_mode = evaluation_mode
          self.counts = counts
          self.exposure = exposure
          self.mask_fit = mask_fit
          self.psf = psf
          self.edisp = edisp
          self.background_model = background_model
          self.models = models
          self.mask_safe = mask_safe
          self.gti = gti
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
  
          # check whether a reference geom is defined
          _ = self._geom
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}\n"
          str_ += "\n"
  
          str_ += "\t{:32}: {} \n\n".format("Name", self.name)
  
          counts = np.nan
          if self.counts is not None:
              counts = np.sum(self.counts.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts", counts)
  
          npred = np.nan
          if self.models is not None or self.background_model is not None:
              npred = np.sum(self.npred().data)
          str_ += "\t{:32}: {:.2f}\n".format("Total predicted counts", npred)
  
          background = np.nan
          if self.background_model is not None:
              background = np.sum(self.background_model.evaluate().data)
          str_ += "\t{:32}: {:.2f}\n\n".format("Total background counts", background)
  
          exposure_min, exposure_max, exposure_unit = np.nan, np.nan, ""
          if self.exposure is not None:
              mask = self.mask_safe.reduce_over_axes(np.logical_or).data
              if not mask.any():
                  mask = None
              exposure_min = np.min(self.exposure.data[..., mask])
              exposure_max = np.max(self.exposure.data[..., mask])
              exposure_unit = self.exposure.unit
  
          str_ += "\t{:32}: {:.2e} {}\n".format(
              "Exposure min", exposure_min, exposure_unit
          )
          str_ += "\t{:32}: {:.2e} {}\n\n".format(
              "Exposure max", exposure_max, exposure_unit
          )
  
          # data section
          n_bins = 0
          if self.counts is not None:
              n_bins = self.counts.data.size
          str_ += "\t{:32}: {} \n".format("Number of total bins", n_bins)
  
          n_fit_bins = 0
          if self.mask is not None:
              n_fit_bins = np.sum(self.mask.data)
          str_ += "\t{:32}: {} \n\n".format("Number of fit bins", n_fit_bins)
  
          # likelihood section
          str_ += "\t{:32}: {}\n".format("Fit statistic type", self.stat_type)
  
          stat = np.nan
          if self.counts is not None and (
              self.models is not None or self.background_model is not None
          ):
              stat = self.stat_sum()
          str_ += "\t{:32}: {:.2f}\n\n".format("Fit statistic value (-2 log(L))", stat)
  
          # model section
          n_models = 0
          if self.models is not None:
              n_models = len(self.models)
  
          if self.background_model is not None:
              n_models += 1
  
          str_ += "\t{:32}: {} \n".format("Number of models", n_models)
  
          str_ += "\t{:32}: {}\n".format("Number of parameters", len(self.parameters))
          str_ += "\t{:32}: {}\n\n".format(
              "Number of free parameters", len(self.parameters.free_parameters)
          )
  
          components = []
  
          if self.models is not None:
              components += self.models
  
          if self.background_model is not None:
              components += [self.background_model]
  
          for idx, model in enumerate(components):
              str_ += f"\tComponent {idx}: \n"
              str_ += "\t\t{:28}: {}\n".format("Name", model.name)
              str_ += "\t\t{:28}: {}\n".format("Type", model.__class__.__name__)
  
              if isinstance(model, SkyModel):
                  str_ += "\t\t{:28}: {}\n".format(
                      "Spatial  model type", model.spatial_model.__class__.__name__
                  )
                  str_ += "\t\t{:28}: {}\n".format(
                      "Spectral model type", model.spectral_model.__class__.__name__
                  )
  
              str_ += "\t\tParameters:\n"
              info = _get_parameters_str(model.parameters)
              lines = info.split("\n")
              str_ += "\t\t" + "\n\t\t".join(lines[:-1])
  
              str_ += "\n\n"
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def models(self):
          """Models (`~gammapy.modeling.models.SkyModels`)."""
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
          evaluators = []
  
          if self.models is not None:
              for model in self.models:
                  evaluator = MapEvaluator(model, evaluation_mode=self.evaluation_mode)
                  evaluator.update(self.exposure, self.psf, self.edisp, self._geom)
                  evaluators.append(evaluator)
  
          self._evaluators = evaluators
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters_list = []
  
          if self.models:
              parameters_list.append(self.models.parameters)
  
          if self.background_model:
              parameters_list.append(self.background_model.parameters)
  
          return Parameters.from_stack(parameters_list)
  
      @property
      def _geom(self):
          """Main analysis geometry"""
          if self.counts is not None:
              return self.counts.geom
          elif self.background_model is not None:
              return self.background_model.map.geom
          elif self.mask_safe is not None:
              return self.mask_safe.geom
          elif self.mask_fit is not None:
              return self.mask_fit.geom
          else:
              raise ValueError(
                  "Either 'counts', 'background_model', 'mask_fit'"
                  " or 'mask_safe' must be defined."
              )
  
      @property
      def data_shape(self):
          """Shape of the counts or background data (tuple)"""
          return self._geom.data_shape
  
      def npred(self):
          """Predicted source and background counts (`~gammapy.maps.Map`)."""
          npred_total = Map.from_geom(self._geom, dtype=float)
  
          if self.background_model:
              npred_total += self.background_model.evaluate()
  
          if self.models:
              for evaluator in self._evaluators:
                  # if the model component drifts out of its support the evaluator has
                  # has to be updated
                  if evaluator.needs_update:
                      evaluator.update(self.exposure, self.psf, self.edisp, self._geom)
  
                  if evaluator.contributes:
                      npred = evaluator.compute_npred()
                      npred_total.stack(npred)
  
          return npred_total
  
      @classmethod
      def from_geoms(
          cls,
          geom,
          geom_exposure,
          geom_psf,
          geom_edisp,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """
          Create a MapDataset object with zero filled maps according to the specified geometries
  
          Parameters
          ----------
          geom : `Geom`
              geometry for the counts and background maps
          geom_exposure : `Geom`
              geometry for the exposure map
          geom_psf : `Geom`
              geometry for the psf map
          geom_edisp : `Geom`
              geometry for the energy dispersion map
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDataset`
              A MapDataset containing zero filled maps
          """
          counts = Map.from_geom(geom, unit="")
  
          background = Map.from_geom(geom, unit="")
          background_model = BackgroundModel(background)
  
          exposure = Map.from_geom(geom_exposure, unit="m2 s")
          edisp = EDispMap.from_geom(geom_edisp)
          psf = PSFMap.from_geom(geom_psf)
  
          gti = GTI.create([] * u.s, [] * u.s, reference_time=reference_time)
  
          mask_safe = Map.from_geom(geom, unit="", dtype=bool)
  
          return cls(
              counts=counts,
              exposure=exposure,
              psf=psf,
              edisp=edisp,
              background_model=background_model,
              gti=gti,
              mask_safe=mask_safe,
              name=name,
              **kwargs,
          )
  
      @classmethod
      def create(
          cls,
          geom,
          energy_axis_true=None,
          migra_axis=None,
          rad_axis=None,
          binsz_irf=None,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """Create a MapDataset object with zero filled maps.
  
          Parameters
          ----------
          geom : `~gammapy.maps.WcsGeom`
              Reference target geometry in reco energy, used for counts and background maps
          energy_axis_true : `~gammapy.maps.MapAxis`
              True energy axis used for IRF maps
          migra_axis : `~gammapy.maps.MapAxis`
              Migration axis for the energy dispersion map
          rad_axis : `~gammapy.maps.MapAxis`
              Rad axis for the psf map
          binsz_irf : float
              IRF Map pixel size in degrees.
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDataset`
              A MapDataset containing zero filled maps
          """
          migra_axis = migra_axis or MIGRA_AXIS_DEFAULT
          rad_axis = rad_axis or RAD_AXIS_DEFAULT
          energy_axis_true = energy_axis_true or geom.get_axis_by_name("energy")
          binsz_irf = binsz_irf or BINSZ_IRF_DEFAULT
  
          geom_image = geom.to_image()
          geom_exposure = geom_image.to_cube([energy_axis_true])
          geom_irf = geom_image.to_binsz(binsz=binsz_irf)
          geom_psf = geom_irf.to_cube([rad_axis, energy_axis_true])
          geom_edisp = geom_irf.to_cube([migra_axis, energy_axis_true])
  
          return cls.from_geoms(
              geom,
              geom_exposure,
              geom_psf,
              geom_edisp,
              reference_time=reference_time,
              name=name,
              **kwargs,
          )
  
      def stack(self, other):
          """Stack another dataset in place.
  
          Parameters
          ----------
          other: `~gammapy.cube.MapDataset`
              Map dataset to be stacked with this one.
          """
  
          if self.counts and other.counts:
              self.counts *= self.mask_safe
              self.counts.stack(other.counts, weights=other.mask_safe)
  
          if self.exposure and other.exposure:
              mask_image = self.mask_safe.reduce_over_axes(func=np.logical_or)
              self.exposure *= mask_image.data
              # TODO: apply energy dependent mask to exposure. Does this require
              #  a mask_safe in true energy?
              mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
              self.exposure.stack(other.exposure, weights=mask_image_other)
  
          if self.background_model and other.background_model:
              bkg = self.background_model.evaluate()
              bkg *= self.mask_safe
              other_bkg = other.background_model.evaluate()
              bkg.stack(other_bkg, weights=other.mask_safe)
  
              self.background_model = BackgroundModel(
                  bkg, name=self.background_model.name
              )
  
          if self.mask_safe is not None and other.mask_safe is not None:
              self.mask_safe.stack(other.mask_safe)
  
          if self.psf and other.psf:
              if isinstance(self.psf, PSFMap) and isinstance(other.psf, PSFMap):
                  mask_irf = self._mask_safe_irf(self.psf.psf_map, mask_image)
                  self.psf.psf_map *= mask_irf.data
                  self.psf.exposure_map *= mask_irf.data
  
                  mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
                  mask_irf_other = self._mask_safe_irf(
                      other.psf.psf_map, mask_image_other
                  )
                  self.psf.stack(other.psf, weights=mask_irf_other)
              else:
                  raise ValueError("Stacking of PSF kernels not supported")
  
          if self.edisp and other.edisp:
              if isinstance(self.edisp, EDispMap) and isinstance(other.edisp, EDispMap):
                  mask_irf = self._mask_safe_irf(self.edisp.edisp_map, mask_image)
                  self.edisp.edisp_map *= mask_irf.data
                  self.edisp.exposure_map *= mask_irf.data
  
                  mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
                  mask_irf_other = self._mask_safe_irf(
                      other.edisp.edisp_map, mask_image_other
                  )
                  self.edisp.stack(other.edisp, weights=mask_irf_other)
              else:
                  raise ValueError("Stacking of edisp kernels not supported")
  
          if self.gti and other.gti:
              self.gti = self.gti.stack(other.gti).union()
  
      @staticmethod
      def _mask_safe_irf(irf_map, mask):
          geom = irf_map.geom.to_image()
          coords = geom.get_coord()
          data = mask.get_by_coord(coords).astype(bool)
          return Map.from_geom(geom=geom, data=data)
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          return cash(n_on=self.counts.data, mu_on=self.npred().data)
  
      def residuals(self, method="diff"):
          """Compute residuals map.
  
          Parameters
          ----------
          method: {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - "diff" (default): data - model
                  - "diff/model": (data - model) / model
                  - "diff/sqrt(model)": (data - model) / sqrt(model)
  
          Returns
          -------
          residuals : `gammapy.maps.WcsNDMap`
              Residual map.
          """
          return self._compute_residuals(self.counts, self.npred(), method=method)
  
      def plot_residuals(
          self,
          method="diff",
          smooth_kernel="gauss",
          smooth_radius="0.1 deg",
          region=None,
          figsize=(12, 4),
          **kwargs,
      ):
          """
          Plot spatial and spectral residuals.
  
          The spectral residuals are extracted from the provided region, and the
          normalization used for the residuals computation can be controlled using
          the method parameter. If no region is passed, only the spatial
          residuals are shown.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          smooth_kernel : {'gauss', 'box'}
              Kernel shape.
          smooth_radius: `~astropy.units.Quantity`, str or float
              Smoothing width given as quantity or float. If a float is given it
              is interpreted as smoothing width in pixels.
          region: `~regions.Region`
              Region (pixel or sky regions accepted)
          figsize : tuple
              Figure size used for the plotting.
          **kwargs : dict
              Keyword arguments passed to `~matplotlib.pyplot.imshow`.
  
          Returns
          -------
          ax_image, ax_spec : `~matplotlib.pyplot.Axes`,
              Image and spectrum axes.
          """
          import matplotlib.pyplot as plt
  
          fig = plt.figure(figsize=figsize)
  
          counts, npred = self.counts, self.npred()
  
          if self.mask is not None:
              counts = counts * self.mask
              npred = npred * self.mask
  
          counts_spatial = counts.sum_over_axes().smooth(
              width=smooth_radius, kernel=smooth_kernel
          )
          npred_spatial = npred.sum_over_axes().smooth(
              width=smooth_radius, kernel=smooth_kernel
          )
          spatial_residuals = self._compute_residuals(
              counts_spatial, npred_spatial, method
          )
  
          if self.mask_safe is not None:
              mask = self.mask_safe.reduce_over_axes(func=np.logical_or)
              spatial_residuals.data[~mask.data] = np.nan
  
          # If no region is provided, skip spectral residuals
          ncols = 2 if region is not None else 1
          ax_image = fig.add_subplot(1, ncols, 1, projection=spatial_residuals.geom.wcs)
          ax_spec = None
  
          kwargs.setdefault("cmap", "coolwarm")
          kwargs.setdefault("stretch", "linear")
          kwargs.setdefault("vmin", -5)
          kwargs.setdefault("vmax", 5)
          spatial_residuals.plot(ax=ax_image, add_cbar=True, **kwargs)
  
          # Spectral residuals
          if region:
              ax_spec = fig.add_subplot(1, 2, 2)
              counts_spec = counts.get_spectrum(region=region)
              npred_spec = npred.get_spectrum(region=region)
              residuals = self._compute_residuals(counts_spec, npred_spec, method)
              ax = residuals.plot()
              ax.axhline(0, color="black", lw=0.5)
  
              y_max = 2 * np.nanmax(residuals.data)
              plt.ylim(-y_max, y_max)
              label = self._residuals_labels[method]
              plt.ylabel(f"Residuals ({label})")
  
              # Overlay spectral extraction region on the spatial residuals
              pix_region = region.to_pixel(wcs=spatial_residuals.geom.wcs)
              pix_region.plot(ax=ax_image)
  
          return ax_image, ax_spec
  
      @lazyproperty
      def _counts_data(self):
          return self.counts.data.astype(float)
  
      def stat_sum(self):
          """Total likelihood given the current model parameters."""
          counts, npred = self._counts_data, self.npred().data
  
          if self.mask is not None:
              return cash_sum_cython(counts[self.mask.data], npred[self.mask.data])
          else:
              return cash_sum_cython(counts.ravel(), npred.ravel())
  
      def fake(self, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced IRFs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
                  Defines random number generator initialisation.
                  Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
          self.counts = npred
  
      def to_hdulist(self):
          """Convert map dataset to list of HDUs.
  
          Returns
          -------
          hdulist : `~astropy.io.fits.HDUList`
              Map dataset list of HDUs.
          """
          # TODO: what todo about the model and background model parameters?
          exclude_primary = slice(1, None)
  
          hdu_primary = fits.PrimaryHDU()
          hdulist = fits.HDUList([hdu_primary])
          if self.counts is not None:
              hdulist += self.counts.to_hdulist(hdu="counts")[exclude_primary]
  
          if self.exposure is not None:
              hdulist += self.exposure.to_hdulist(hdu="exposure")[exclude_primary]
  
          if self.background_model is not None:
              hdulist += self.background_model.map.to_hdulist(hdu="background")[
                  exclude_primary
              ]
  
          if self.edisp is not None:
              if isinstance(self.edisp, EDispKernel):
                  hdus = self.edisp.to_hdulist()
                  hdus["MATRIX"].name = "edisp_matrix"
                  hdus["EBOUNDS"].name = "edisp_matrix_ebounds"
                  hdulist.append(hdus["EDISP_MATRIX"])
                  hdulist.append(hdus["EDISP_MATRIX_EBOUNDS"])
              else:
                  hdulist += self.edisp.edisp_map.to_hdulist(hdu="EDISP")[exclude_primary]
                  hdulist += self.edisp.exposure_map.to_hdulist(hdu="edisp_exposure")[
                      exclude_primary
                  ]
  
          if self.psf is not None:
              if isinstance(self.psf, PSFKernel):
                  hdulist += self.psf.psf_kernel_map.to_hdulist(hdu="psf_kernel")[
                      exclude_primary
                  ]
              else:
                  hdulist += self.psf.psf_map.to_hdulist(hdu="psf")[exclude_primary]
                  hdulist += self.psf.exposure_map.to_hdulist(hdu="psf_exposure")[
                      exclude_primary
                  ]
  
          if self.mask_safe is not None:
              mask_safe_int = self.mask_safe.copy()
              mask_safe_int.data = mask_safe_int.data.astype(int)
              hdulist += mask_safe_int.to_hdulist(hdu="mask_safe")[exclude_primary]
  
          if self.mask_fit is not None:
              mask_fit_int = self.mask_fit.copy()
              mask_fit_int.data = mask_fit_int.data.astype(int)
              hdulist += mask_fit_int.to_hdulist(hdu="mask_fit")[exclude_primary]
  
          if self.gti is not None:
              hdulist.append(fits.BinTableHDU(self.gti.table, name="GTI"))
  
          return hdulist
  
      @classmethod
      def from_hdulist(cls, hdulist, name=""):
          """Create map dataset from list of HDUs.
  
          Parameters
          ----------
          hdulist : `~astropy.io.fits.HDUList`
              List of HDUs.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          kwargs = {"name": name}
  
          if "COUNTS" in hdulist:
              kwargs["counts"] = Map.from_hdulist(hdulist, hdu="counts")
  
          if "EXPOSURE" in hdulist:
              kwargs["exposure"] = Map.from_hdulist(hdulist, hdu="exposure")
  
          if "BACKGROUND" in hdulist:
              background_map = Map.from_hdulist(hdulist, hdu="background")
              kwargs["background_model"] = BackgroundModel(background_map)
  
          if "EDISP_MATRIX" in hdulist:
              kwargs["edisp"] = EDispKernel.from_hdulist(
                  hdulist, hdu1="EDISP_MATRIX", hdu2="EDISP_MATRIX_EBOUNDS"
              )
          if "EDISP" in hdulist:
              edisp_map = Map.from_hdulist(hdulist, hdu="edisp")
              exposure_map = Map.from_hdulist(hdulist, hdu="edisp_exposure")
              kwargs["edisp"] = EDispMap(edisp_map, exposure_map)
  
          if "PSF_KERNEL" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf_kernel")
              kwargs["psf"] = PSFKernel(psf_map)
          if "PSF" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf")
              exposure_map = Map.from_hdulist(hdulist, hdu="psf_exposure")
              kwargs["psf"] = PSFMap(psf_map, exposure_map)
  
          if "MASK_SAFE" in hdulist:
              mask_safe = Map.from_hdulist(hdulist, hdu="mask_safe")
              mask_safe.data = mask_safe.data.astype(bool)
              kwargs["mask_safe"] = mask_safe
  
          if "MASK_FIT" in hdulist:
              mask_fit = Map.from_hdulist(hdulist, hdu="mask_fit")
              mask_fit.data = mask_fit.data.astype(bool)
              kwargs["mask_fit"] = mask_fit
  
          if "GTI" in hdulist:
              gti = GTI(Table.read(hdulist, hdu="GTI"))
              kwargs["gti"] = gti
  
          return cls(**kwargs)
  
      def write(self, filename, overwrite=False):
          """Write map dataset to file.
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite file if it exists.
          """
          self.to_hdulist().writeto(make_path(filename), overwrite=overwrite)
  
      @classmethod
      def read(cls, filename, name=""):
          """Read map dataset from file.
  
          Parameters
          ----------
          filename : str
              Filename to read from.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          with fits.open(make_path(filename), memmap=False) as hdulist:
              return cls.from_hdulist(hdulist, name=name)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create from dicts and models list generated from YAML serialization."""
          dataset = cls.read(data["filename"], name=data["name"])
          bkg_name = data["background"]
          model_names = data["models"]
          for component in components["components"]:
              if component["type"] == "BackgroundModel":
                  if component["name"] == bkg_name:
                      if "filename" not in component:
                          component["map"] = dataset.background_model.map
                      background_model = BackgroundModel.from_dict(component)
                      dataset.background_model = background_model
  
          models_list = [model for model in models if model.name in model_names]
          dataset.models = SkyModels(models_list)
          return dataset
  
      def to_dict(self, filename=""):
          """Convert to dict for YAML serialization."""
          if self.models is None:
              models = []
          else:
              models = [_.name for _ in self.models]
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "background": self.background_model.name,
              "filename": str(filename),
          }
  
      def to_spectrum_dataset(self, on_region, containment_correction=False):
          """Return a ~gammapy.spectrum.SpectrumDataset from on_region.
  
          Counts and background are summed in the on_region.
  
          Effective area is taken from the average exposure divided by the livetime.
          Here we assume it is the sum of the GTIs.
  
          The energy dispersion kernel is obtained at the on_region center.
          Only regions with centers are supported.
  
          The model is not exported to the ~gammapy.spectrum.SpectrumDataset.
          It must be set after the dataset extraction.
  
          Parameters
          ----------
          on_region : `~regions.SkyRegion`
              the input ON region on which to extract the spectrum
          containment_correction : bool
              Apply containment correction for point sources and circular on regions
  
          Returns
          -------
          dataset : `~gammapy.spectrum.SpectrumDataset`
              the resulting reduced dataset
          """
          kwargs = {"gti": self.gti, "name": self.name}
  
          if self.gti is not None:
              kwargs["livetime"] = self.gti.time_sum
          else:
              raise ValueError("No GTI in `MapDataset`, cannot compute livetime")
  
          if self.counts is not None:
              kwargs["counts"] = self.counts.get_spectrum(on_region, np.sum)
  
          if self.background_model is not None:
              kwargs["background"] = self.background_model.evaluate().get_spectrum(
                  on_region, np.sum
              )
  
          if self.exposure is not None:
              exposure = self.exposure.get_spectrum(on_region, np.mean)
              kwargs["aeff"] = EffectiveAreaTable(
                  energy_lo=exposure.energy.edges[:-1],
                  energy_hi=exposure.energy.edges[1:],
                  data=exposure.quantity / kwargs["livetime"],
              )
  
          if containment_correction:
              if not isinstance(on_region, CircleSkyRegion):
                  raise TypeError(
                      "Containement correction is only supported for"
                      " `CircleSkyRegion`."
                  )
              elif self.psf is None or isinstance(self.psf, PSFKernel):
                  raise ValueError("No PSFMap set. Containement correction impossible")
              else:
                  psf = self.psf.get_energy_dependent_table_psf(on_region.center)
                  containment = psf.containment(
                      kwargs["aeff"].energy.center, on_region.radius
                  )
                  kwargs["aeff"].data.data *= containment.squeeze()
  
          if self.edisp is not None:
              if isinstance(self.edisp, EDispKernel):
                  edisp = self.edisp
              else:
                  axis = self._geom.get_axis_by_name("energy")
                  edisp = self.edisp.get_edisp_kernel(on_region.center, e_reco=axis.edges)
              kwargs["edisp"] = edisp
  
          return SpectrumDataset(**kwargs)
  
      def to_image(self, spectrum=None):
          """Create images by summing over the energy axis.
  
          Exposure is weighted with an assumed spectrum,
          resulting in a weighted mean exposure image.
  
          Currently the PSFMap and EdispMap are dropped from the
          resulting image dataset.
  
          Parameters
          ----------
          spectrum : `~gammapy.modeling.models.SpectralModel`
              Spectral model to compute the weights.
              Default is power-law with spectral index of 2.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset containing images.
          """
          counts = self.counts * self.mask_safe
          background = self.background_model.evaluate() * self.mask_safe
  
          counts = counts.sum_over_axes(keepdims=True)
          exposure = _map_spectrum_weight(self.exposure, spectrum)
          exposure = exposure.sum_over_axes(keepdims=True)
          background = background.sum_over_axes(keepdims=True)
  
          mask_image = self.mask_safe.reduce_over_axes(func=np.logical_or, keepdims=True)
  
          # TODO: add edisp and psf
          edisp = None
  
          if self.psf is not None:
              psf = self.psf.to_image()
          else:
              psf = None
  
          return self.__class__(
              counts=counts,
              exposure=exposure,
              background_model=BackgroundModel(background),
              mask_safe=mask_image,
              edisp=edisp,
              psf=psf,
              gti=self.gti,
              name=self.name,
          )
  
      def cutout(self, position, width, mode="trim"):
          """Cutout map dataset.
  
          Parameters
          ----------
          position : `~astropy.coordinates.SkyCoord`
              Center position of the cutout region.
          width : tuple of `~astropy.coordinates.Angle`
              Angular sizes of the region in (lon, lat) in that specific order.
              If only one value is passed, a square region is extracted.
          mode : {'trim', 'partial', 'strict'}
              Mode option for Cutout2D, for details see `~astropy.nddata.utils.Cutout2D`.
  
          Returns
          -------
          cutout : `MapDataset`
              Cutout map dataset.
          """
          kwargs = {"gti": self.gti}
          cutout_kwargs = {"position": position, "width": width, "mode": mode}
  
          if self.counts is not None:
              kwargs["counts"] = self.counts.cutout(**cutout_kwargs)
  
          if self.exposure is not None:
              kwargs["exposure"] = self.exposure.cutout(**cutout_kwargs)
  
          if self.background_model is not None:
              bkg_map = self.background_model.map.cutout(**cutout_kwargs)
              bkg_model = BackgroundModel(bkg_map)
              factors = [par.factor for par in self.background_model.parameters]
              bkg_model.parameters.set_parameter_factors(factors)
              kwargs["background_model"] = bkg_model
  
          if self.edisp is not None:
              kwargs["edisp"] = self.edisp.cutout(**cutout_kwargs)
  
          if self.psf is not None:
              kwargs["psf"] = self.psf.cutout(**cutout_kwargs)
  
          if self.mask_safe is not None:
              kwargs["mask_safe"] = self.mask_safe.cutout(**cutout_kwargs)
  
          if self.mask_fit is not None:
              kwargs["mask_fit"] = self.mask_fit.cutout(**cutout_kwargs)
  
          return self.__class__(**kwargs)
  
  
  class MapDatasetOnOff(MapDataset):
      """Map dataset for on-off likelihood fitting.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Source sky models.
      counts : `~gammapy.maps.WcsNDMap`
          Counts cube
      counts_off : `~gammapy.maps.WcsNDMap`
          Ring-convolved counts cube
      acceptance : `~gammapy.maps.WcsNDMap`
          Acceptance from the IRFs
      acceptance_off : `~gammapy.maps.WcsNDMap`
          Acceptance off
      exposure : `~gammapy.maps.WcsNDMap`
          Exposure cube
      mask_fit : `~numpy.ndarray`
          Mask to apply to the likelihood for fitting.
      psf : `~gammapy.cube.PSFKernel`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      background_model : `~gammapy.modeling.models.BackgroundModel`
          Background model to use for the fit.
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
          The "local" mode evaluates the model components on smaller grids to save computation time.
          This mode is recommended for local optimization algorithms.
          The "global" evaluation mode evaluates the model components on the full map.
          This mode is recommended for global optimization algorithms.
      mask_safe : `~numpy.ndarray`
          Mask defining the safe data range.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
      """
  
      stat_type = "wstat"
      tag = "MapDatasetOnOff"
  
      def __init__(
          self,
          models=None,
          counts=None,
          counts_off=None,
          acceptance=None,
          acceptance_off=None,
          exposure=None,
          mask_fit=None,
          psf=None,
          edisp=None,
          background_model=None,
          name="",
          evaluation_mode="local",
          mask_safe=None,
          gti=None,
      ):
          if mask_fit is not None and mask_fit.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.evaluation_mode = evaluation_mode
          self.counts = counts
          self.counts_off = counts_off
  
          if np.isscalar(acceptance):
              acceptance = np.ones(self.data_shape) * acceptance
  
          if np.isscalar(acceptance_off):
              acceptance_off = np.ones(self.data_shape) * acceptance_off
  
          self.acceptance = acceptance
          self.acceptance_off = acceptance_off
          self.exposure = exposure
          self.background_model = None
          self.mask_fit = mask_fit
          self.psf = psf
          self.edisp = edisp
          self.models = models
          self.name = name
          self.mask_safe = mask_safe
          self.gti = gti
  
      def __str__(self):
          str_ = super().__str__()
  
          counts_off = np.nan
          if self.counts_off is not None:
              counts_off = np.sum(self.counts_off.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts_off", counts_off)
  
          acceptance = np.nan
          if self.acceptance is not None:
              acceptance = np.sum(self.acceptance.data)
          str_ += "\t{:32}: {:.0f} \n".format("Acceptance", acceptance)
  
          acceptance_off = np.nan
          if self.acceptance_off is not None:
              acceptance_off = np.sum(self.acceptance_off.data)
          str_ += "\t{:32}: {:.0f} \n".format("Acceptance off", acceptance_off)
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          if self.models:
              parameters += self.models.parameters
  
          return Parameters(parameters)
  
      @property
      def alpha(self):
          """Exposure ratio between signal and background regions"""
          alpha = self.acceptance / self.acceptance_off
          alpha.data = np.nan_to_num(alpha.data)
          return alpha
  
      @property
      def background(self):
          """Predicted background in the on region.
  
          Notice that this definition is valid under the assumption of cash statistic.
          """
          return self.alpha * self.counts_off
  
      @property
      def excess(self):
          """Excess (counts - alpha * counts_off)"""
          return self.counts.data - self.background.data
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          mu_sig = self.npred().data
          on_stat_ = wstat(
              n_on=self.counts.data,
              n_off=self.counts_off.data,
              alpha=list(self.alpha.data),
              mu_sig=mu_sig,
          )
          return np.nan_to_num(on_stat_)
  
      @classmethod
      def from_geoms(
          cls,
          geom,
          geom_exposure,
          geom_psf,
          geom_edisp,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """
          Create a MapDatasetOnOff object with zero filled maps according to the specified geometries
  
          Parameters
          ----------
          geom : `gammapy.maps.WcsGeom`
              geometry for the counts, counts_off, acceptance and acceptance_off maps
          geom_exposure : `gammapy.maps.WcsGeom`
              geometry for the exposure map
          geom_psf : `gammapy.maps.WcsGeom`
              geometry for the psf map
          geom_edisp : `gammapy.maps.WcsGeom`
              geometry for the energy dispersion map
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDatasetOnOff`
              A MapDatasetOnOff containing zero filled maps
          """
          maps = {}
          for aname in ["counts", "counts_off", "acceptance", "acceptance_off"]:
              maps[aname] = Map.from_geom(geom, unit="")
  
          exposure = Map.from_geom(geom_exposure, unit="m2 s")
          edisp = EDispMap.from_geom(geom_edisp)
          psf = PSFMap.from_geom(geom_psf)
  
          gti = GTI.create([] * u.s, [] * u.s, reference_time=reference_time)
  
          mask_safe = Map.from_geom(geom, dtype=bool)
  
          return cls(
              counts=maps["counts"],
              counts_off=maps["counts_off"],
              acceptance=maps["acceptance"],
              acceptance_off=maps["acceptance_off"],
              exposure=exposure,
              psf=psf,
              edisp=edisp,
              gti=gti,
              mask_safe=mask_safe,
              name=name,
              **kwargs,
          )
  
      def _is_stackable(self):
          """Check if the Dataset contains enough information to be stacked"""
          if (
              self.acceptance_off is None
              or self.acceptance is None
              or self.counts_off is None
          ):
              return False
          else:
              return True
  
      def stack(self, other):
          r"""Stack another dataset in place.
  
          The ``acceptance`` of the stacked dataset is normalized to 1,
          and the stacked ``acceptance_off`` is scaled so that:
  
          .. math::
              \alpha_\text{stacked} =
              \frac{1}{a_\text{off}} =
              \frac{\alpha_1\text{OFF}_1 + \alpha_2\text{OFF}_2}{\text{OFF}_1 + OFF_2}
  
          Parameters
          ----------
          other : `MapDatasetOnOff`
              Other dataset
          """
          if not isinstance(other, MapDatasetOnOff):
              raise TypeError("Incompatible types for MapDatasetOnOff stacking")
  
          if not self._is_stackable() or not other._is_stackable():
              raise ValueError("Cannot stack incomplete MapDatsetOnOff.")
  
          # Factor containing: self.alpha * self.counts_off + other.alpha * other.counts_off
          tmp_factor = (self.alpha * self.counts_off).copy()
          tmp_factor.data[~self.mask_safe.data] = 0
          tmp_factor.stack(other.alpha * other.counts_off, weights=other.mask_safe.data)
  
          # Stack the off counts (in place)
          self.counts_off.data[~self.mask_safe.data] = 0
          self.counts_off.stack(other.counts_off, weights=other.mask_safe.data)
  
          self.acceptance_off = self.counts_off / tmp_factor
          self.acceptance.data = np.ones(self.data_shape)
  
          super().stack(other)
  
      def stat_sum(self):
          """Total likelihood given the current model parameters."""
          return Dataset.stat_sum(self)
  
      def fake(self, background_model, random_state="random-seed"):
          """Simulate fake counts (on and off) for the current model and reduced IRFs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
                  Defines random number generator initialisation.
                  Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
  
          npred_bkg = background_model.copy()
          npred_bkg.data = random_state.poisson(npred_bkg.data)
  
          self.counts = npred + npred_bkg
  
          npred_off = background_model / self.alpha
          npred_off.data = random_state.poisson(npred_off.data)
          self.counts_off = npred_off
  
      def to_hdulist(self):
          """Convert map dataset to list of HDUs.
  
          Returns
          -------
          hdulist : `~astropy.io.fits.HDUList`
              Map dataset list of HDUs.
          """
          hdulist = super().to_hdulist()
          exclude_primary = slice(1, None)
  
          if self.counts_off is not None:
              hdulist += self.counts_off.to_hdulist(hdu="counts_off")[exclude_primary]
  
          if self.acceptance is not None:
              hdulist += self.acceptance.to_hdulist(hdu="acceptance")[exclude_primary]
  
          if self.acceptance_off is not None:
              hdulist += self.acceptance_off.to_hdulist(hdu="acceptance_off")[
                  exclude_primary
              ]
  
          return hdulist
  
      @classmethod
      def from_hdulist(cls, hdulist, name=""):
          """Create map dataset from list of HDUs.
  
          Parameters
          ----------
          hdulist : `~astropy.io.fits.HDUList`
              List of HDUs.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          kwargs = {}
          kwargs["name"] = name
          if "COUNTS" in hdulist:
              kwargs["counts"] = Map.from_hdulist(hdulist, hdu="counts")
  
          if "COUNTS_OFF" in hdulist:
              kwargs["counts_off"] = Map.from_hdulist(hdulist, hdu="counts_off")
  
          if "ACCEPTANCE" in hdulist:
              kwargs["acceptance"] = Map.from_hdulist(hdulist, hdu="acceptance")
  
          if "ACCEPTANCE_OFF" in hdulist:
              kwargs["acceptance_off"] = Map.from_hdulist(hdulist, hdu="acceptance_off")
  
          if "EXPOSURE" in hdulist:
              kwargs["exposure"] = Map.from_hdulist(hdulist, hdu="exposure")
  
          if "EDISP_MATRIX" in hdulist:
              kwargs["edisp"] = EDispKernel.from_hdulist(
                  hdulist, hdu1="EDISP_MATRIX", hdu2="EDISP_MATRIX_EBOUNDS"
              )
  
          if "PSF_KERNEL" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf_kernel")
              kwargs["psf"] = PSFKernel(psf_map)
  
          if "MASK_SAFE" in hdulist:
              mask_safe_map = Map.from_hdulist(hdulist, hdu="mask_safe")
              kwargs["mask_safe"] = mask_safe_map.data.astype(bool)
  
          if "MASK_FIT" in hdulist:
              mask_fit_map = Map.from_hdulist(hdulist, hdu="mask_fit")
              kwargs["mask_fit"] = mask_fit_map.data.astype(bool)
  
          if "GTI" in hdulist:
              gti = GTI(Table.read(hdulist, hdu="GTI"))
              kwargs["gti"] = gti
          return cls(**kwargs)
  
      def to_spectrum_dataset(self, on_region, containment_correction=False):
          """Return a ~gammapy.spectrum.SpectrumDatasetOnOff from on_region.
  
          Counts and OFF counts are summed in the on_region.
  
          Acceptance is the average of all acceptances while acceptance OFF
          is taken such that number of excess is preserved in the on_region.
  
          Effective area is taken from the average exposure divided by the livetime.
          Here we assume it is the sum of the GTIs.
  
          The energy dispersion kernel is obtained at the on_region center.
          Only regions with centers are supported.
  
          The model is not exported to the ~gammapy.spectrum.SpectrumDataset.
          It must be set after the dataset extraction.
  
          Parameters
          ----------
          on_region : `~regions.SkyRegion`
              the input ON region on which to extract the spectrum
          containment_correction : bool
              Apply containment correction for point sources and circular on regions
  
          Returns
          -------
          dataset : `~gammapy.spectrum.SpectrumDatasetOnOff`
              the resulting reduced dataset
          """
          dataset = super().to_spectrum_dataset(on_region, containment_correction)
  
          kwargs = {}
          if self.counts_off is not None:
              kwargs["counts_off"] = self.counts_off.get_spectrum(on_region, np.sum)
  
          if self.acceptance is not None:
              kwargs["acceptance"] = self.acceptance.get_spectrum(on_region, np.mean)
              background = self.background.get_spectrum(on_region, np.sum)
              kwargs["acceptance_off"] = (
                  kwargs["acceptance"] * kwargs["counts_off"] / background
              )
  
          return SpectrumDatasetOnOff.from_spectrum_dataset(dataset=dataset, **kwargs)
  
      def cutout(self, position, width, mode="trim"):
          """Cutout map dataset.
  
          Parameters
          ----------
          position : `~astropy.coordinates.SkyCoord`
              Center position of the cutout region.
          width : tuple of `~astropy.coordinates.Angle`
              Angular sizes of the region in (lon, lat) in that specific order.
              If only one value is passed, a square region is extracted.
          mode : {'trim', 'partial', 'strict'}
              Mode option for Cutout2D, for details see `~astropy.nddata.utils.Cutout2D`.
  
          Returns
          -------
          cutout : `MapDatasetOnOff`
              Cutout map dataset.
          """
          cutout_kwargs = {"position": position, "width": width, "mode": mode}
  
          cutout_dataset = super().cutout(**cutout_kwargs)
  
          if self.counts_off is not None:
              cutout_dataset.counts_off = self.counts_off.cutout(**cutout_kwargs)
  
          if self.acceptance is not None:
              cutout_dataset.acceptance = self.acceptance.cutout(**cutout_kwargs)
  
          if self.acceptance_off is not None:
              cutout_dataset.acceptance_off = self.acceptance_off.cutout(**cutout_kwargs)
  
          return cutout_dataset
  
  
  class MapEvaluator:
      """Sky model evaluation on maps.
  
      This evaluates a sky model on a 3D map and convolves with the IRFs,
      and returns a map of the predicted counts.
      Note that background counts are not added.
  
      For now, we only make it work for 3D WCS maps with an energy axis.
      No HPX, no other axes, those can be added later here or via new
      separate model evaluator classes.
  
      Parameters
      ----------
      model : `~gammapy.modeling.models.SkyModel`
          Sky model
      exposure : `~gammapy.maps.Map`
          Exposure map
      psf : `~gammapy.cube.PSFKernel`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
      """
  
      def __init__(
          self, model=None, exposure=None, psf=None, edisp=None, evaluation_mode="local"
      ):
          self.model = model
          self.exposure = exposure
          self.psf = psf
          self.edisp = edisp
          self.contributes = True
  
          if evaluation_mode not in {"local", "global"}:
              raise ValueError(f"Invalid evaluation_mode: {evaluation_mode!r}")
  
          self.evaluation_mode = evaluation_mode
  
      @property
      def geom(self):
          """True energy map geometry (`~gammapy.maps.Geom`)"""
          return self.exposure.geom
  
      @property
      def needs_update(self):
          """Check whether the model component has drifted away from its support."""
          if self.evaluation_mode == "global" or self.model.evaluation_radius is None:
              return False
          else:
              position = self.model.position
              separation = self._init_position.separation(position)
              update = separation > (self.model.evaluation_radius + CUTOUT_MARGIN)
          return update
  
      def update(self, exposure, psf, edisp, geom):
          """Update MapEvaluator, based on the current position of the model component.
  
          Parameters
          ----------
          exposure : `~gammapy.maps.Map`
              Exposure map.
          psf : `gammapy.cube.PSFMap`
              PSF map.
          edisp : `gammapy.cube.EDispMap`
              Edisp map.
          geom : `WcsGeom`
              Counts geom
          """
          log.debug("Updating model evaluator")
          # cache current position of the model component
  
          if isinstance(edisp, EDispMap):
              e_reco = geom.get_axis_by_name("energy").edges
              self.edisp = edisp.get_edisp_kernel(self.model.position, e_reco=e_reco)
          else:
              self.edisp = edisp
  
          if isinstance(psf, PSFMap):
              self.psf = psf.get_psf_kernel(self.model.position, geom=exposure.geom)
          else:
              self.psf = psf
  
          if self.evaluation_mode == "local" and self.model.evaluation_radius is not None:
              self._init_position = self.model.position
              if self.psf is not None:
                  psf_width = np.max(self.psf.psf_kernel_map.geom.width)
              else:
                  psf_width = 0 * u.deg
  
              width = psf_width + 2 * (self.model.evaluation_radius + CUTOUT_MARGIN)
              try:
                  self.exposure = exposure.cutout(
                      position=self.model.position, width=width
                  )
                  self.contributes = True
              except (NoOverlapError, ValueError):
                  self.contributes = False
          else:
              self.exposure = exposure
  
      def compute_dnde(self):
          """Compute model differential flux at map pixel centers.
  
          Returns
          -------
          model_map : `~gammapy.maps.Map`
              Sky cube with data filled with evaluated model values.
              Units: ``cm-2 s-1 TeV-1 deg-2``
          """
          return self.model.evaluate_geom(self.geom)
  
      def compute_flux(self):
          """Compute model integral flux over map pixel volumes.
  
          For now, we simply multiply dnde with bin volume.
          """
          dnde = self.compute_dnde()
          volume = self.geom.bin_volume()
          return dnde * volume
  
      def apply_exposure(self, flux):
          """Compute npred cube
  
          For now just divide flux cube by exposure
          """
          npred = (flux * self.exposure.quantity).to_value("")
          return Map.from_geom(self.geom, data=npred, unit="")
  
      def apply_psf(self, npred):
          """Convolve npred cube with PSF"""
          tmp = npred.convolve(self.psf)
          tmp.data[tmp.data < 0.0] = 0
          return tmp
  
      def apply_edisp(self, npred):
          """Convolve map data with energy dispersion.
  
          Parameters
          ----------
          npred : `~gammapy.maps.Map`
              Predicted counts in true energy bins
  
          Returns
          -------
          npred_reco : `~gammapy.maps.Map`
              Predicted counts in reco energy bins
          """
          return npred.apply_edisp(self.edisp)
  
      def compute_npred(self):
          """
          Evaluate model predicted counts.
  
          Returns
          -------
          npred : `~gammapy.maps.Map`
              Predicted counts on the map (in reco energy bins)
          """
          flux = self.compute_flux()
          npred = self.apply_exposure(flux)
          if self.psf is not None:
              npred = self.apply_psf(npred)
          if self.edisp is not None:
              npred = self.apply_edisp(npred)
  
          return npred
  
files: gammapy/cube/fit.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import logging
  import numpy as np
  import astropy.units as u
  from astropy.io import fits
  from astropy.nddata.utils import NoOverlapError
  from astropy.table import Table
  from astropy.utils import lazyproperty
  from regions import CircleSkyRegion
  from gammapy.cube.edisp_map import EDispMap
  from gammapy.cube.psf_kernel import PSFKernel
  from gammapy.cube.psf_map import PSFMap
  from gammapy.data import GTI
  from gammapy.irf import EffectiveAreaTable, EDispKernel
  from gammapy.maps import Map, MapAxis
  from gammapy.modeling import Dataset, Parameters
  from gammapy.modeling.models import BackgroundModel, SkyModel, SkyModels
  from gammapy.modeling.parameter import _get_parameters_str
  from gammapy.spectrum import SpectrumDataset, SpectrumDatasetOnOff
  from gammapy.stats import cash, cash_sum_cython, wstat
  from gammapy.utils.random import get_random_state
  from gammapy.utils.scripts import make_path
  from .exposure import _map_spectrum_weight
  
  __all__ = ["MapDataset", "MapDatasetOnOff"]
  
  log = logging.getLogger(__name__)
  
  CUTOUT_MARGIN = 0.1 * u.deg
  RAD_MAX = 0.66
  RAD_AXIS_DEFAULT = MapAxis.from_bounds(
      0, RAD_MAX, nbin=66, node_type="edges", name="theta", unit="deg"
  )
  MIGRA_AXIS_DEFAULT = MapAxis.from_bounds(
      0.2, 5, nbin=48, node_type="edges", name="migra"
  )
  
  BINSZ_IRF_DEFAULT = 0.2
  
  
  class MapDataset(Dataset):
      """Perform sky model likelihood fit on maps.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Source sky models.
      counts : `~gammapy.maps.WcsNDMap`
          Counts cube
      exposure : `~gammapy.maps.WcsNDMap`
          Exposure cube
      mask_fit : `~gammapy.maps.WcsNDMap`
          Mask to apply to the likelihood for fitting.
      psf : `~gammapy.cube.PSFKernel` or `~gammapy.cube.PSFMap`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel` or `~gammapy.cube.EDispMap`
          Energy dispersion kernel
      background_model : `~gammapy.modeling.models.BackgroundModel`
          Background model to use for the fit.
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
          The "local" mode evaluates the model components on smaller grids to save computation time.
          This mode is recommended for local optimization algorithms.
          The "global" evaluation mode evaluates the model components on the full map.
          This mode is recommended for global optimization algorithms.
      mask_safe : `~gammapy.maps.WcsNDMap`
          Mask defining the safe data range.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
      """
  
      stat_type = "cash"
      tag = "MapDataset"
  
      def __init__(
          self,
          models=None,
          counts=None,
          exposure=None,
          mask_fit=None,
          psf=None,
          edisp=None,
          background_model=None,
          name="",
          evaluation_mode="local",
          mask_safe=None,
          gti=None,
      ):
          if mask_fit is not None and mask_fit.data.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          if mask_safe is not None and mask_safe.data.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.evaluation_mode = evaluation_mode
          self.counts = counts
          self.exposure = exposure
          self.mask_fit = mask_fit
          self.psf = psf
          self.edisp = edisp
          self.background_model = background_model
          self.models = models
          self.name = name
          self.mask_safe = mask_safe
          self.gti = gti
  
          # check whether a reference geom is defined
          _ = self._geom
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}\n"
          str_ += "\n"
  
          str_ += "\t{:32}: {} \n\n".format("Name", self.name)
  
          counts = np.nan
          if self.counts is not None:
              counts = np.sum(self.counts.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts", counts)
  
          npred = np.nan
          if self.models is not None or self.background_model is not None:
              npred = np.sum(self.npred().data)
          str_ += "\t{:32}: {:.2f}\n".format("Total predicted counts", npred)
  
          background = np.nan
          if self.background_model is not None:
              background = np.sum(self.background_model.evaluate().data)
          str_ += "\t{:32}: {:.2f}\n\n".format("Total background counts", background)
  
          exposure_min, exposure_max, exposure_unit = np.nan, np.nan, ""
          if self.exposure is not None:
              mask = self.mask_safe.reduce_over_axes(np.logical_or).data
              if not mask.any():
                  mask = None
              exposure_min = np.min(self.exposure.data[..., mask])
              exposure_max = np.max(self.exposure.data[..., mask])
              exposure_unit = self.exposure.unit
  
          str_ += "\t{:32}: {:.2e} {}\n".format(
              "Exposure min", exposure_min, exposure_unit
          )
          str_ += "\t{:32}: {:.2e} {}\n\n".format(
              "Exposure max", exposure_max, exposure_unit
          )
  
          # data section
          n_bins = 0
          if self.counts is not None:
              n_bins = self.counts.data.size
          str_ += "\t{:32}: {} \n".format("Number of total bins", n_bins)
  
          n_fit_bins = 0
          if self.mask is not None:
              n_fit_bins = np.sum(self.mask.data)
          str_ += "\t{:32}: {} \n\n".format("Number of fit bins", n_fit_bins)
  
          # likelihood section
          str_ += "\t{:32}: {}\n".format("Fit statistic type", self.stat_type)
  
          stat = np.nan
          if self.counts is not None and (
              self.models is not None or self.background_model is not None
          ):
              stat = self.stat_sum()
          str_ += "\t{:32}: {:.2f}\n\n".format("Fit statistic value (-2 log(L))", stat)
  
          # model section
          n_models = 0
          if self.models is not None:
              n_models = len(self.models)
  
          if self.background_model is not None:
              n_models += 1
  
          str_ += "\t{:32}: {} \n".format("Number of models", n_models)
  
          str_ += "\t{:32}: {}\n".format("Number of parameters", len(self.parameters))
          str_ += "\t{:32}: {}\n\n".format(
              "Number of free parameters", len(self.parameters.free_parameters)
          )
  
          components = []
  
          if self.models is not None:
              components += self.models
  
          if self.background_model is not None:
              components += [self.background_model]
  
          for idx, model in enumerate(components):
              str_ += f"\tComponent {idx}: \n"
              str_ += "\t\t{:28}: {}\n".format("Name", model.name)
              str_ += "\t\t{:28}: {}\n".format("Type", model.__class__.__name__)
  
              if isinstance(model, SkyModel):
                  str_ += "\t\t{:28}: {}\n".format(
                      "Spatial  model type", model.spatial_model.__class__.__name__
                  )
                  str_ += "\t\t{:28}: {}\n".format(
                      "Spectral model type", model.spectral_model.__class__.__name__
                  )
  
              str_ += "\t\tParameters:\n"
              info = _get_parameters_str(model.parameters)
              lines = info.split("\n")
              str_ += "\t\t" + "\n\t\t".join(lines[:-1])
  
              str_ += "\n\n"
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def models(self):
          """Models (`~gammapy.modeling.models.SkyModels`)."""
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
          evaluators = []
  
          if self.models is not None:
              for model in self.models:
                  evaluator = MapEvaluator(model, evaluation_mode=self.evaluation_mode)
                  evaluator.update(self.exposure, self.psf, self.edisp, self._geom)
                  evaluators.append(evaluator)
  
          self._evaluators = evaluators
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters_list = []
  
          if self.models:
              parameters_list.append(self.models.parameters)
  
          if self.background_model:
              parameters_list.append(self.background_model.parameters)
  
          return Parameters.from_stack(parameters_list)
  
      @property
      def _geom(self):
          """Main analysis geometry"""
          if self.counts is not None:
              return self.counts.geom
          elif self.background_model is not None:
              return self.background_model.map.geom
          elif self.mask_safe is not None:
              return self.mask_safe.geom
          elif self.mask_fit is not None:
              return self.mask_fit.geom
          else:
              raise ValueError("Either 'counts', 'background_model', 'mask_fit'"
                               " or 'mask_safe' must be defined.")
  
      @property
      def data_shape(self):
          """Shape of the counts or background data (tuple)"""
          return self._geom.data_shape
  
      def npred(self):
          """Predicted source and background counts (`~gammapy.maps.Map`)."""
          npred_total = Map.from_geom(self._geom, dtype=float)
  
          if self.background_model:
              npred_total += self.background_model.evaluate()
  
          if self.models:
              for evaluator in self._evaluators:
                  # if the model component drifts out of its support the evaluator has
                  # has to be updated
                  if evaluator.needs_update:
                      evaluator.update(self.exposure, self.psf, self.edisp, self._geom)
  
                  if evaluator.contributes:
                      npred = evaluator.compute_npred()
                      npred_total.stack(npred)
  
          return npred_total
  
      @classmethod
      def from_geoms(
          cls,
          geom,
          geom_exposure,
          geom_psf,
          geom_edisp,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """
          Create a MapDataset object with zero filled maps according to the specified geometries
  
          Parameters
          ----------
          geom : `Geom`
              geometry for the counts and background maps
          geom_exposure : `Geom`
              geometry for the exposure map
          geom_psf : `Geom`
              geometry for the psf map
          geom_edisp : `Geom`
              geometry for the energy dispersion map
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDataset`
              A MapDataset containing zero filled maps
          """
          counts = Map.from_geom(geom, unit="")
  
          background = Map.from_geom(geom, unit="")
          background_model = BackgroundModel(background)
  
          exposure = Map.from_geom(geom_exposure, unit="m2 s")
          edisp = EDispMap.from_geom(geom_edisp)
          psf = PSFMap.from_geom(geom_psf)
  
          gti = GTI.create([] * u.s, [] * u.s, reference_time=reference_time)
  
          mask_safe = Map.from_geom(geom, unit="", dtype=bool)
  
          return cls(
              counts=counts,
              exposure=exposure,
              psf=psf,
              edisp=edisp,
              background_model=background_model,
              gti=gti,
              mask_safe=mask_safe,
              name=name,
              **kwargs,
          )
  
      @classmethod
      def create(
          cls,
          geom,
          energy_axis_true=None,
          migra_axis=None,
          rad_axis=None,
          binsz_irf=None,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """Create a MapDataset object with zero filled maps.
  
          Parameters
          ----------
          geom : `~gammapy.maps.WcsGeom`
              Reference target geometry in reco energy, used for counts and background maps
          energy_axis_true : `~gammapy.maps.MapAxis`
              True energy axis used for IRF maps
          migra_axis : `~gammapy.maps.MapAxis`
              Migration axis for the energy dispersion map
          rad_axis : `~gammapy.maps.MapAxis`
              Rad axis for the psf map
          binsz_irf : float
              IRF Map pixel size in degrees.
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDataset`
              A MapDataset containing zero filled maps
          """
          migra_axis = migra_axis or MIGRA_AXIS_DEFAULT
          rad_axis = rad_axis or RAD_AXIS_DEFAULT
          energy_axis_true = energy_axis_true or geom.get_axis_by_name("energy")
          binsz_irf = binsz_irf or BINSZ_IRF_DEFAULT
  
          geom_image = geom.to_image()
          geom_exposure = geom_image.to_cube([energy_axis_true])
          geom_irf = geom_image.to_binsz(binsz=binsz_irf)
          geom_psf = geom_irf.to_cube([rad_axis, energy_axis_true])
          geom_edisp = geom_irf.to_cube([migra_axis, energy_axis_true])
  
          return cls.from_geoms(
              geom,
              geom_exposure,
              geom_psf,
              geom_edisp,
              reference_time=reference_time,
              name=name,
              **kwargs,
          )
  
      def stack(self, other):
          """Stack another dataset in place.
  
          Parameters
          ----------
          other: `~gammapy.cube.MapDataset`
              Map dataset to be stacked with this one.
          """
  
          if self.counts and other.counts:
              self.counts *= self.mask_safe
              self.counts.stack(other.counts, weights=other.mask_safe)
  
          if self.exposure and other.exposure:
              mask_image = self.mask_safe.reduce_over_axes(func=np.logical_or)
              self.exposure *= mask_image.data
              # TODO: apply energy dependent mask to exposure. Does this require
              #  a mask_safe in true energy?
              mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
              self.exposure.stack(other.exposure, weights=mask_image_other)
  
          if self.background_model and other.background_model:
              bkg = self.background_model.evaluate()
              bkg *= self.mask_safe
              other_bkg = other.background_model.evaluate()
              bkg.stack(other_bkg, weights=other.mask_safe)
  
              self.background_model = BackgroundModel(
                  bkg, name=self.background_model.name
              )
  
          if self.mask_safe is not None and other.mask_safe is not None:
              self.mask_safe.stack(other.mask_safe)
  
          if self.psf and other.psf:
              if isinstance(self.psf, PSFMap) and isinstance(other.psf, PSFMap):
                  mask_irf = self._mask_safe_irf(self.psf.psf_map, mask_image)
                  self.psf.psf_map *= mask_irf.data
                  self.psf.exposure_map *= mask_irf.data
  
                  mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
                  mask_irf_other = self._mask_safe_irf(
                      other.psf.psf_map, mask_image_other
                  )
                  self.psf.stack(other.psf, weights=mask_irf_other)
              else:
                  raise ValueError("Stacking of PSF kernels not supported")
  
          if self.edisp and other.edisp:
              if isinstance(self.edisp, EDispMap) and isinstance(other.edisp, EDispMap):
                  mask_irf = self._mask_safe_irf(self.edisp.edisp_map, mask_image)
                  self.edisp.edisp_map *= mask_irf.data
                  self.edisp.exposure_map *= mask_irf.data
  
                  mask_image_other = other.mask_safe.reduce_over_axes(func=np.logical_or)
                  mask_irf_other = self._mask_safe_irf(
                      other.edisp.edisp_map, mask_image_other
                  )
                  self.edisp.stack(other.edisp, weights=mask_irf_other)
              else:
                  raise ValueError("Stacking of edisp kernels not supported")
  
          if self.gti and other.gti:
              self.gti = self.gti.stack(other.gti).union()
  
      @staticmethod
      def _mask_safe_irf(irf_map, mask):
          geom = irf_map.geom.to_image()
          coords = geom.get_coord()
          data = mask.get_by_coord(coords).astype(bool)
          return Map.from_geom(geom=geom, data=data)
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          return cash(n_on=self.counts.data, mu_on=self.npred().data)
  
      def residuals(self, method="diff"):
          """Compute residuals map.
  
          Parameters
          ----------
          method: {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - "diff" (default): data - model
                  - "diff/model": (data - model) / model
                  - "diff/sqrt(model)": (data - model) / sqrt(model)
  
          Returns
          -------
          residuals : `gammapy.maps.WcsNDMap`
              Residual map.
          """
          return self._compute_residuals(self.counts, self.npred(), method=method)
  
      def plot_residuals(
          self,
          method="diff",
          smooth_kernel="gauss",
          smooth_radius="0.1 deg",
          region=None,
          figsize=(12, 4),
          **kwargs,
      ):
          """
          Plot spatial and spectral residuals.
  
          The spectral residuals are extracted from the provided region, and the
          normalization used for the residuals computation can be controlled using
          the method parameter. If no region is passed, only the spatial
          residuals are shown.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          smooth_kernel : {'gauss', 'box'}
              Kernel shape.
          smooth_radius: `~astropy.units.Quantity`, str or float
              Smoothing width given as quantity or float. If a float is given it
              is interpreted as smoothing width in pixels.
          region: `~regions.Region`
              Region (pixel or sky regions accepted)
          figsize : tuple
              Figure size used for the plotting.
          **kwargs : dict
              Keyword arguments passed to `~matplotlib.pyplot.imshow`.
  
          Returns
          -------
          ax_image, ax_spec : `~matplotlib.pyplot.Axes`,
              Image and spectrum axes.
          """
          import matplotlib.pyplot as plt
  
          fig = plt.figure(figsize=figsize)
  
          counts, npred = self.counts, self.npred()
  
          if self.mask is not None:
              counts = counts * self.mask
              npred = npred * self.mask
  
          counts_spatial = counts.sum_over_axes().smooth(
              width=smooth_radius, kernel=smooth_kernel
          )
          npred_spatial = npred.sum_over_axes().smooth(
              width=smooth_radius, kernel=smooth_kernel
          )
          spatial_residuals = self._compute_residuals(
              counts_spatial, npred_spatial, method
          )
  
          if self.mask_safe is not None:
              mask = self.mask_safe.reduce_over_axes(func=np.logical_or)
              spatial_residuals.data[~mask.data] = np.nan
  
          # If no region is provided, skip spectral residuals
          ncols = 2 if region is not None else 1
          ax_image = fig.add_subplot(1, ncols, 1, projection=spatial_residuals.geom.wcs)
          ax_spec = None
  
          kwargs.setdefault("cmap", "coolwarm")
          kwargs.setdefault("stretch", "linear")
          kwargs.setdefault("vmin", -5)
          kwargs.setdefault("vmax", 5)
          spatial_residuals.plot(ax=ax_image, add_cbar=True, **kwargs)
  
          # Spectral residuals
          if region:
              ax_spec = fig.add_subplot(1, 2, 2)
              counts_spec = counts.get_spectrum(region=region)
              npred_spec = npred.get_spectrum(region=region)
              residuals = self._compute_residuals(counts_spec, npred_spec, method)
              ax = residuals.plot()
              ax.axhline(0, color="black", lw=0.5)
  
              y_max = 2 * np.nanmax(residuals.data)
              plt.ylim(-y_max, y_max)
              label = self._residuals_labels[method]
              plt.ylabel(f"Residuals ({label})")
  
              # Overlay spectral extraction region on the spatial residuals
              pix_region = region.to_pixel(wcs=spatial_residuals.geom.wcs)
              pix_region.plot(ax=ax_image)
  
          return ax_image, ax_spec
  
      @lazyproperty
      def _counts_data(self):
          return self.counts.data.astype(float)
  
      def stat_sum(self):
          """Total likelihood given the current model parameters."""
          counts, npred = self._counts_data, self.npred().data
  
          if self.mask is not None:
              return cash_sum_cython(counts[self.mask.data], npred[self.mask.data])
          else:
              return cash_sum_cython(counts.ravel(), npred.ravel())
  
      def fake(self, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced IRFs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
                  Defines random number generator initialisation.
                  Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
          self.counts = npred
  
      def to_hdulist(self):
          """Convert map dataset to list of HDUs.
  
          Returns
          -------
          hdulist : `~astropy.io.fits.HDUList`
              Map dataset list of HDUs.
          """
          # TODO: what todo about the model and background model parameters?
          exclude_primary = slice(1, None)
  
          hdu_primary = fits.PrimaryHDU()
          hdulist = fits.HDUList([hdu_primary])
          if self.counts is not None:
              hdulist += self.counts.to_hdulist(hdu="counts")[exclude_primary]
  
          if self.exposure is not None:
              hdulist += self.exposure.to_hdulist(hdu="exposure")[exclude_primary]
  
          if self.background_model is not None:
              hdulist += self.background_model.map.to_hdulist(hdu="background")[
                  exclude_primary
              ]
  
          if self.edisp is not None:
              if isinstance(self.edisp, EDispKernel):
                  hdus = self.edisp.to_hdulist()
                  hdus["MATRIX"].name = "edisp_matrix"
                  hdus["EBOUNDS"].name = "edisp_matrix_ebounds"
                  hdulist.append(hdus["EDISP_MATRIX"])
                  hdulist.append(hdus["EDISP_MATRIX_EBOUNDS"])
              else:
                  hdulist += self.edisp.edisp_map.to_hdulist(hdu="EDISP")[exclude_primary]
                  hdulist += self.edisp.exposure_map.to_hdulist(hdu="edisp_exposure")[
                      exclude_primary
                  ]
  
          if self.psf is not None:
              if isinstance(self.psf, PSFKernel):
                  hdulist += self.psf.psf_kernel_map.to_hdulist(hdu="psf_kernel")[
                      exclude_primary
                  ]
              else:
                  hdulist += self.psf.psf_map.to_hdulist(hdu="psf")[exclude_primary]
                  hdulist += self.psf.exposure_map.to_hdulist(hdu="psf_exposure")[
                      exclude_primary
                  ]
  
          if self.mask_safe is not None:
              mask_safe_int = self.mask_safe.copy()
              mask_safe_int.data = mask_safe_int.data.astype(int)
              hdulist += mask_safe_int.to_hdulist(hdu="mask_safe")[exclude_primary]
  
          if self.mask_fit is not None:
              mask_fit_int = self.mask_fit.copy()
              mask_fit_int.data = mask_fit_int.data.astype(int)
              hdulist += mask_fit_int.to_hdulist(hdu="mask_fit")[exclude_primary]
  
          if self.gti is not None:
              hdulist.append(fits.BinTableHDU(self.gti.table, name="GTI"))
  
          return hdulist
  
      @classmethod
      def from_hdulist(cls, hdulist, name=""):
          """Create map dataset from list of HDUs.
  
          Parameters
          ----------
          hdulist : `~astropy.io.fits.HDUList`
              List of HDUs.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          kwargs = {"name": name}
  
          if "COUNTS" in hdulist:
              kwargs["counts"] = Map.from_hdulist(hdulist, hdu="counts")
  
          if "EXPOSURE" in hdulist:
              kwargs["exposure"] = Map.from_hdulist(hdulist, hdu="exposure")
  
          if "BACKGROUND" in hdulist:
              background_map = Map.from_hdulist(hdulist, hdu="background")
              kwargs["background_model"] = BackgroundModel(background_map)
  
          if "EDISP_MATRIX" in hdulist:
              kwargs["edisp"] = EDispKernel.from_hdulist(
                  hdulist, hdu1="EDISP_MATRIX", hdu2="EDISP_MATRIX_EBOUNDS"
              )
          if "EDISP" in hdulist:
              edisp_map = Map.from_hdulist(hdulist, hdu="edisp")
              exposure_map = Map.from_hdulist(hdulist, hdu="edisp_exposure")
              kwargs["edisp"] = EDispMap(edisp_map, exposure_map)
  
          if "PSF_KERNEL" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf_kernel")
              kwargs["psf"] = PSFKernel(psf_map)
          if "PSF" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf")
              exposure_map = Map.from_hdulist(hdulist, hdu="psf_exposure")
              kwargs["psf"] = PSFMap(psf_map, exposure_map)
  
          if "MASK_SAFE" in hdulist:
              mask_safe = Map.from_hdulist(hdulist, hdu="mask_safe")
              mask_safe.data = mask_safe.data.astype(bool)
              kwargs["mask_safe"] = mask_safe
  
          if "MASK_FIT" in hdulist:
              mask_fit = Map.from_hdulist(hdulist, hdu="mask_fit")
              mask_fit.data = mask_fit.data.astype(bool)
              kwargs["mask_fit"] = mask_fit
  
          if "GTI" in hdulist:
              gti = GTI(Table.read(hdulist, hdu="GTI"))
              kwargs["gti"] = gti
  
          return cls(**kwargs)
  
      def write(self, filename, overwrite=False):
          """Write map dataset to file.
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite file if it exists.
          """
          self.to_hdulist().writeto(make_path(filename), overwrite=overwrite)
  
      @classmethod
      def read(cls, filename, name=""):
          """Read map dataset from file.
  
          Parameters
          ----------
          filename : str
              Filename to read from.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          with fits.open(make_path(filename), memmap=False) as hdulist:
              return cls.from_hdulist(hdulist, name=name)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create from dicts and models list generated from YAML serialization."""
          dataset = cls.read(data["filename"], name=data["name"])
          bkg_name = data["background"]
          model_names = data["models"]
          for component in components["components"]:
              if component["type"] == "BackgroundModel":
                  if component["name"] == bkg_name:
                      if "filename" not in component:
                          component["map"] = dataset.background_model.map
                      background_model = BackgroundModel.from_dict(component)
                      dataset.background_model = background_model
  
          models_list = [model for model in models if model.name in model_names]
          dataset.models = SkyModels(models_list)
          return dataset
  
      def to_dict(self, filename=""):
          """Convert to dict for YAML serialization."""
          if self.models is None:
              models = []
          else:
              models = [_.name for _ in self.models]
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "background": self.background_model.name,
              "filename": str(filename),
          }
  
      def to_spectrum_dataset(self, on_region, containment_correction=False):
          """Return a ~gammapy.spectrum.SpectrumDataset from on_region.
  
          Counts and background are summed in the on_region.
  
          Effective area is taken from the average exposure divided by the livetime.
          Here we assume it is the sum of the GTIs.
  
          The energy dispersion kernel is obtained at the on_region center.
          Only regions with centers are supported.
  
          The model is not exported to the ~gammapy.spectrum.SpectrumDataset.
          It must be set after the dataset extraction.
          
          Parameters
          ----------
          on_region : `~regions.SkyRegion`
              the input ON region on which to extract the spectrum
          containment_correction : bool
              Apply containment correction for point sources and circular on regions
  
          Returns
          -------
          dataset : `~gammapy.spectrum.SpectrumDataset`
              the resulting reduced dataset
          """
          kwargs = {"gti": self.gti, "name": self.name}
  
          if self.gti is not None:
              kwargs["livetime"] = self.gti.time_sum
          else:
              raise ValueError("No GTI in `MapDataset`, cannot compute livetime")
  
          if self.counts is not None:
              kwargs["counts"] = self.counts.get_spectrum(on_region, np.sum)
  
          if self.background_model is not None:
              kwargs["background"] = self.background_model.evaluate().get_spectrum(
                  on_region, np.sum
              )
  
          if self.exposure is not None:
              exposure = self.exposure.get_spectrum(on_region, np.mean)
              kwargs["aeff"] = EffectiveAreaTable(
                  energy_lo=exposure.energy.edges[:-1],
                  energy_hi=exposure.energy.edges[1:],
                  data=exposure.quantity / kwargs["livetime"],
              )
  
          if containment_correction:
              if not isinstance(on_region, CircleSkyRegion):
                  raise TypeError(
                      "Containement correction is only supported for"
                      " `CircleSkyRegion`."
                  )
              elif self.psf is None or isinstance(self.psf, PSFKernel):
                  raise ValueError("No PSFMap set. Containement correction impossible")
              else:
                  psf = self.psf.get_energy_dependent_table_psf(on_region.center)
                  containment = psf.containment(kwargs["aeff"].energy.center, on_region.radius)
                  kwargs["aeff"].data.data *= containment.squeeze()
  
          if self.edisp is not None:
              if isinstance(self.edisp, EDispKernel):
                  edisp = self.edisp
              else:
                  axis = self._geom.get_axis_by_name("energy")
                  edisp = self.edisp.get_edisp_kernel(
                      on_region.center, e_reco=axis.edges
                  )
              kwargs["edisp"] = edisp
  
          return SpectrumDataset(**kwargs)
  
      def to_image(self, spectrum=None):
          """Create images by summing over the energy axis.
  
          Exposure is weighted with an assumed spectrum,
          resulting in a weighted mean exposure image.
  
          Currently the PSFMap and EdispMap are dropped from the
          resulting image dataset.
  
          Parameters
          ----------
          spectrum : `~gammapy.modeling.models.SpectralModel`
              Spectral model to compute the weights.
              Default is power-law with spectral index of 2.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset containing images.
          """
          counts = self.counts * self.mask_safe
          background = self.background_model.evaluate() * self.mask_safe
  
          counts = counts.sum_over_axes(keepdims=True)
          exposure = _map_spectrum_weight(self.exposure, spectrum)
          exposure = exposure.sum_over_axes(keepdims=True)
          background = background.sum_over_axes(keepdims=True)
  
          mask_image = self.mask_safe.reduce_over_axes(func=np.logical_or, keepdims=True)
  
          # TODO: add edisp and psf
          edisp = None
  
          if self.psf is not None:
              psf = self.psf.to_image()
          else:
              psf = None
  
          return self.__class__(
              counts=counts,
              exposure=exposure,
              background_model=BackgroundModel(background),
              mask_safe=mask_image,
              edisp=edisp,
              psf=psf,
              gti=self.gti,
              name=self.name,
          )
  
      def cutout(self, position, width, mode="trim"):
          """Cutout map dataset.
  
          Parameters
          ----------
          position : `~astropy.coordinates.SkyCoord`
              Center position of the cutout region.
          width : tuple of `~astropy.coordinates.Angle`
              Angular sizes of the region in (lon, lat) in that specific order.
              If only one value is passed, a square region is extracted.
          mode : {'trim', 'partial', 'strict'}
              Mode option for Cutout2D, for details see `~astropy.nddata.utils.Cutout2D`.
  
          Returns
          -------
          cutout : `MapDataset`
              Cutout map dataset.
          """
          kwargs = {"gti": self.gti}
          cutout_kwargs = {"position": position, "width": width, "mode": mode}
  
          if self.counts is not None:
              kwargs["counts"] = self.counts.cutout(**cutout_kwargs)
  
          if self.exposure is not None:
              kwargs["exposure"] = self.exposure.cutout(**cutout_kwargs)
  
          if self.background_model is not None:
              bkg_map = self.background_model.map.cutout(**cutout_kwargs)
              bkg_model = BackgroundModel(bkg_map)
              factors = [par.factor for par in self.background_model.parameters]
              bkg_model.parameters.set_parameter_factors(factors)
              kwargs["background_model"] = bkg_model
  
          if self.edisp is not None:
              kwargs["edisp"] = self.edisp.cutout(**cutout_kwargs)
  
          if self.psf is not None:
              kwargs["psf"] = self.psf.cutout(**cutout_kwargs)
  
          if self.mask_safe is not None:
              kwargs["mask_safe"] = self.mask_safe.cutout(**cutout_kwargs)
  
          if self.mask_fit is not None:
              kwargs["mask_fit"] = self.mask_fit.cutout(**cutout_kwargs)
  
          return self.__class__(**kwargs)
  
  
  class MapDatasetOnOff(MapDataset):
      """Map dataset for on-off likelihood fitting.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Source sky models.
      counts : `~gammapy.maps.WcsNDMap`
          Counts cube
      counts_off : `~gammapy.maps.WcsNDMap`
          Ring-convolved counts cube
      acceptance : `~gammapy.maps.WcsNDMap`
          Acceptance from the IRFs
      acceptance_off : `~gammapy.maps.WcsNDMap`
          Acceptance off
      exposure : `~gammapy.maps.WcsNDMap`
          Exposure cube
      mask_fit : `~numpy.ndarray`
          Mask to apply to the likelihood for fitting.
      psf : `~gammapy.cube.PSFKernel`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      background_model : `~gammapy.modeling.models.BackgroundModel`
          Background model to use for the fit.
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
          The "local" mode evaluates the model components on smaller grids to save computation time.
          This mode is recommended for local optimization algorithms.
          The "global" evaluation mode evaluates the model components on the full map.
          This mode is recommended for global optimization algorithms.
      mask_safe : `~numpy.ndarray`
          Mask defining the safe data range.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
      """
  
      stat_type = "wstat"
      tag = "MapDatasetOnOff"
  
      def __init__(
          self,
          models=None,
          counts=None,
          counts_off=None,
          acceptance=None,
          acceptance_off=None,
          exposure=None,
          mask_fit=None,
          psf=None,
          edisp=None,
          background_model=None,
          name="",
          evaluation_mode="local",
          mask_safe=None,
          gti=None,
      ):
          if mask_fit is not None and mask_fit.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.evaluation_mode = evaluation_mode
          self.counts = counts
          self.counts_off = counts_off
  
          if np.isscalar(acceptance):
              acceptance = np.ones(self.data_shape) * acceptance
  
          if np.isscalar(acceptance_off):
              acceptance_off = np.ones(self.data_shape) * acceptance_off
  
          self.acceptance = acceptance
          self.acceptance_off = acceptance_off
          self.exposure = exposure
          self.background_model = None
          self.mask_fit = mask_fit
          self.psf = psf
          self.edisp = edisp
          self.models = models
          self.name = name
          self.mask_safe = mask_safe
          self.gti = gti
  
      def __str__(self):
          str_ = super().__str__()
  
          counts_off = np.nan
          if self.counts_off is not None:
              counts_off = np.sum(self.counts_off.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts_off", counts_off)
  
          acceptance = np.nan
          if self.acceptance is not None:
              acceptance = np.sum(self.acceptance.data)
          str_ += "\t{:32}: {:.0f} \n".format("Acceptance", acceptance)
  
          acceptance_off = np.nan
          if self.acceptance_off is not None:
              acceptance_off = np.sum(self.acceptance_off.data)
          str_ += "\t{:32}: {:.0f} \n".format("Acceptance off", acceptance_off)
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          if self.models:
              parameters += self.models.parameters
  
          return Parameters(parameters)
  
      @property
      def alpha(self):
          """Exposure ratio between signal and background regions"""
          alpha = self.acceptance / self.acceptance_off
          alpha.data = np.nan_to_num(alpha.data)
          return alpha
  
      @property
      def background(self):
          """Predicted background in the on region.
  
          Notice that this definition is valid under the assumption of cash statistic.
          """
          return self.alpha * self.counts_off
  
      @property
      def excess(self):
          """Excess (counts - alpha * counts_off)"""
          return self.counts.data - self.background.data
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          mu_sig = self.npred().data
          on_stat_ = wstat(
              n_on=self.counts.data,
              n_off=self.counts_off.data,
              alpha=list(self.alpha.data),
              mu_sig=mu_sig,
          )
          return np.nan_to_num(on_stat_)
  
      @classmethod
      def from_geoms(
          cls,
          geom,
          geom_exposure,
          geom_psf,
          geom_edisp,
          reference_time="2000-01-01",
          name="",
          **kwargs,
      ):
          """
          Create a MapDatasetOnOff object with zero filled maps according to the specified geometries
  
          Parameters
          ----------
          geom : `gammapy.maps.WcsGeom`
              geometry for the counts, counts_off, acceptance and acceptance_off maps
          geom_exposure : `gammapy.maps.WcsGeom`
              geometry for the exposure map
          geom_psf : `gammapy.maps.WcsGeom`
              geometry for the psf map
          geom_edisp : `gammapy.maps.WcsGeom`
              geometry for the energy dispersion map
          reference_time : `~astropy.time.Time`
              the reference time to use in GTI definition
          name : str
              Name of the dataset.
  
          Returns
          -------
          empty_maps : `MapDatasetOnOff`
              A MapDatasetOnOff containing zero filled maps
          """
          maps = {}
          for aname in ["counts", "counts_off", "acceptance", "acceptance_off"]:
              maps[aname] = Map.from_geom(geom, unit="")
  
          exposure = Map.from_geom(geom_exposure, unit="m2 s")
          edisp = EDispMap.from_geom(geom_edisp)
          psf = PSFMap.from_geom(geom_psf)
  
          gti = GTI.create([] * u.s, [] * u.s, reference_time=reference_time)
  
          mask_safe = Map.from_geom(geom, dtype=bool)
  
          return cls(
              counts=maps["counts"],
              counts_off=maps["counts_off"],
              acceptance=maps["acceptance"],
              acceptance_off=maps["acceptance_off"],
              exposure=exposure,
              psf=psf,
              edisp=edisp,
              gti=gti,
              mask_safe=mask_safe,
              name=name,
              **kwargs,
          )
  
      def _is_stackable(self):
          """Check if the Dataset contains enough information to be stacked"""
          if (
              self.acceptance_off is None
              or self.acceptance is None
              or self.counts_off is None
          ):
              return False
          else:
              return True
  
      def stack(self, other):
          r"""Stack another dataset in place.
  
          The ``acceptance`` of the stacked dataset is normalized to 1,
          and the stacked ``acceptance_off`` is scaled so that:
  
          .. math::
              \alpha_\text{stacked} =
              \frac{1}{a_\text{off}} =
              \frac{\alpha_1\text{OFF}_1 + \alpha_2\text{OFF}_2}{\text{OFF}_1 + OFF_2}
  
          Parameters
          ----------
          other : `MapDatasetOnOff`
              Other dataset
          """
          if not isinstance(other, MapDatasetOnOff):
              raise TypeError("Incompatible types for MapDatasetOnOff stacking")
  
          if not self._is_stackable() or not other._is_stackable():
              raise ValueError("Cannot stack incomplete MapDatsetOnOff.")
  
          # Factor containing: self.alpha * self.counts_off + other.alpha * other.counts_off
          tmp_factor = (self.alpha * self.counts_off).copy()
          tmp_factor.data[~self.mask_safe.data] = 0
          tmp_factor.stack(other.alpha * other.counts_off, weights=other.mask_safe.data)
  
          # Stack the off counts (in place)
          self.counts_off.data[~self.mask_safe.data] = 0
          self.counts_off.stack(other.counts_off, weights=other.mask_safe.data)
  
          self.acceptance_off = self.counts_off / tmp_factor
          self.acceptance.data = np.ones(self.data_shape)
  
          super().stack(other)
  
      def stat_sum(self):
          """Total likelihood given the current model parameters."""
          return Dataset.stat_sum(self)
  
      def fake(self, background_model, random_state="random-seed"):
          """Simulate fake counts (on and off) for the current model and reduced IRFs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
                  Defines random number generator initialisation.
                  Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
  
          npred_bkg = background_model.copy()
          npred_bkg.data = random_state.poisson(npred_bkg.data)
  
          self.counts = npred + npred_bkg
  
          npred_off = background_model / self.alpha
          npred_off.data = random_state.poisson(npred_off.data)
          self.counts_off = npred_off
  
      def to_hdulist(self):
          """Convert map dataset to list of HDUs.
  
          Returns
          -------
          hdulist : `~astropy.io.fits.HDUList`
              Map dataset list of HDUs.
          """
          hdulist = super().to_hdulist()
          exclude_primary = slice(1, None)
  
          if self.counts_off is not None:
              hdulist += self.counts_off.to_hdulist(hdu="counts_off")[exclude_primary]
  
          if self.acceptance is not None:
              hdulist += self.acceptance.to_hdulist(hdu="acceptance")[exclude_primary]
  
          if self.acceptance_off is not None:
              hdulist += self.acceptance_off.to_hdulist(hdu="acceptance_off")[
                  exclude_primary
              ]
  
          return hdulist
  
      @classmethod
      def from_hdulist(cls, hdulist, name=""):
          """Create map dataset from list of HDUs.
  
          Parameters
          ----------
          hdulist : `~astropy.io.fits.HDUList`
              List of HDUs.
  
          Returns
          -------
          dataset : `MapDataset`
              Map dataset.
          """
          kwargs = {}
          kwargs["name"] = name
          if "COUNTS" in hdulist:
              kwargs["counts"] = Map.from_hdulist(hdulist, hdu="counts")
  
          if "COUNTS_OFF" in hdulist:
              kwargs["counts_off"] = Map.from_hdulist(hdulist, hdu="counts_off")
  
          if "ACCEPTANCE" in hdulist:
              kwargs["acceptance"] = Map.from_hdulist(hdulist, hdu="acceptance")
  
          if "ACCEPTANCE_OFF" in hdulist:
              kwargs["acceptance_off"] = Map.from_hdulist(
                  hdulist, hdu="acceptance_off"
              )
  
          if "EXPOSURE" in hdulist:
              kwargs["exposure"] = Map.from_hdulist(hdulist, hdu="exposure")
  
          if "EDISP_MATRIX" in hdulist:
              kwargs["edisp"] = EDispKernel.from_hdulist(
                  hdulist, hdu1="EDISP_MATRIX", hdu2="EDISP_MATRIX_EBOUNDS"
              )
  
          if "PSF_KERNEL" in hdulist:
              psf_map = Map.from_hdulist(hdulist, hdu="psf_kernel")
              kwargs["psf"] = PSFKernel(psf_map)
  
          if "MASK_SAFE" in hdulist:
              mask_safe_map = Map.from_hdulist(hdulist, hdu="mask_safe")
              kwargs["mask_safe"] = mask_safe_map.data.astype(bool)
  
          if "MASK_FIT" in hdulist:
              mask_fit_map = Map.from_hdulist(hdulist, hdu="mask_fit")
              kwargs["mask_fit"] = mask_fit_map.data.astype(bool)
  
          if "GTI" in hdulist:
              gti = GTI(Table.read(hdulist, hdu="GTI"))
              kwargs["gti"] = gti
          return cls(**kwargs)
  
      def to_spectrum_dataset(self, on_region, containment_correction=False):
          """Return a ~gammapy.spectrum.SpectrumDatasetOnOff from on_region.
  
          Counts and OFF counts are summed in the on_region.
  
          Acceptance is the average of all acceptances while acceptance OFF
          is taken such that number of excess is preserved in the on_region.
  
          Effective area is taken from the average exposure divided by the livetime.
          Here we assume it is the sum of the GTIs.
  
          The energy dispersion kernel is obtained at the on_region center.
          Only regions with centers are supported.
  
          The model is not exported to the ~gammapy.spectrum.SpectrumDataset.
          It must be set after the dataset extraction.
  
          Parameters
          ----------
          on_region : `~regions.SkyRegion`
              the input ON region on which to extract the spectrum
          containment_correction : bool
              Apply containment correction for point sources and circular on regions
  
          Returns
          -------
          dataset : `~gammapy.spectrum.SpectrumDatasetOnOff`
              the resulting reduced dataset
          """
          dataset = super().to_spectrum_dataset(on_region, containment_correction)
  
          kwargs = {}
          if self.counts_off is not None:
              kwargs["counts_off"] = self.counts_off.get_spectrum(on_region, np.sum)
  
          if self.acceptance is not None:
              kwargs["acceptance"] = self.acceptance.get_spectrum(on_region, np.mean)
              background = self.background.get_spectrum(on_region, np.sum)
              kwargs["acceptance_off"] = kwargs["acceptance"] * kwargs["counts_off"] / background
  
          return SpectrumDatasetOnOff.from_spectrum_dataset(
              dataset=dataset, **kwargs
          )
  
      def cutout(self, position, width, mode="trim"):
          """Cutout map dataset.
  
          Parameters
          ----------
          position : `~astropy.coordinates.SkyCoord`
              Center position of the cutout region.
          width : tuple of `~astropy.coordinates.Angle`
              Angular sizes of the region in (lon, lat) in that specific order.
              If only one value is passed, a square region is extracted.
          mode : {'trim', 'partial', 'strict'}
              Mode option for Cutout2D, for details see `~astropy.nddata.utils.Cutout2D`.
  
          Returns
          -------
          cutout : `MapDatasetOnOff`
              Cutout map dataset.
          """
          cutout_kwargs = {"position": position, "width": width, "mode": mode}
  
          cutout_dataset = super().cutout(**cutout_kwargs)
  
          if self.counts_off is not None:
              cutout_dataset.counts_off = self.counts_off.cutout(**cutout_kwargs)
  
          if self.acceptance is not None:
              cutout_dataset.acceptance = self.acceptance.cutout(**cutout_kwargs)
  
          if self.acceptance_off is not None:
              cutout_dataset.acceptance_off = self.acceptance_off.cutout(**cutout_kwargs)
  
          return cutout_dataset
  
  
  class MapEvaluator:
      """Sky model evaluation on maps.
  
      This evaluates a sky model on a 3D map and convolves with the IRFs,
      and returns a map of the predicted counts.
      Note that background counts are not added.
  
      For now, we only make it work for 3D WCS maps with an energy axis.
      No HPX, no other axes, those can be added later here or via new
      separate model evaluator classes.
  
      Parameters
      ----------
      model : `~gammapy.modeling.models.SkyModel`
          Sky model
      exposure : `~gammapy.maps.Map`
          Exposure map
      psf : `~gammapy.cube.PSFKernel`
          PSF kernel
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      evaluation_mode : {"local", "global"}
          Model evaluation mode.
      """
  
      def __init__(
          self, model=None, exposure=None, psf=None, edisp=None, evaluation_mode="local"
      ):
          self.model = model
          self.exposure = exposure
          self.psf = psf
          self.edisp = edisp
          self.contributes = True
  
          if evaluation_mode not in {"local", "global"}:
              raise ValueError(f"Invalid evaluation_mode: {evaluation_mode!r}")
  
          self.evaluation_mode = evaluation_mode
  
      @property
      def geom(self):
          """True energy map geometry (`~gammapy.maps.Geom`)"""
          return self.exposure.geom
  
      @property
      def needs_update(self):
          """Check whether the model component has drifted away from its support."""
          if self.evaluation_mode == "global" or self.model.evaluation_radius is None:
              return False
          else:
              position = self.model.position
              separation = self._init_position.separation(position)
              update = separation > (self.model.evaluation_radius + CUTOUT_MARGIN)
          return update
  
      def update(self, exposure, psf, edisp, geom):
          """Update MapEvaluator, based on the current position of the model component.
  
          Parameters
          ----------
          exposure : `~gammapy.maps.Map`
              Exposure map.
          psf : `gammapy.cube.PSFMap`
              PSF map.
          edisp : `gammapy.cube.EDispMap`
              Edisp map.
          geom : `WcsGeom`
              Counts geom
          """
          log.debug("Updating model evaluator")
          # cache current position of the model component
  
          if isinstance(edisp, EDispMap):
              e_reco = geom.get_axis_by_name("energy").edges
              self.edisp = edisp.get_edisp_kernel(self.model.position, e_reco=e_reco)
          else:
              self.edisp = edisp
  
          if isinstance(psf, PSFMap):
              self.psf = psf.get_psf_kernel(self.model.position, geom=exposure.geom)
          else:
              self.psf = psf
  
          if self.evaluation_mode == "local" and self.model.evaluation_radius is not None:
              self._init_position = self.model.position
              if self.psf is not None:
                  psf_width = np.max(self.psf.psf_kernel_map.geom.width)
              else:
                  psf_width = 0 * u.deg
  
              width = psf_width + 2 * (self.model.evaluation_radius + CUTOUT_MARGIN)
              try:
                  self.exposure = exposure.cutout(
                      position=self.model.position, width=width
                  )
                  self.contributes = True
              except (NoOverlapError, ValueError):
                  self.contributes = False
          else:
              self.exposure = exposure
  
      def compute_dnde(self):
          """Compute model differential flux at map pixel centers.
  
          Returns
          -------
          model_map : `~gammapy.maps.Map`
              Sky cube with data filled with evaluated model values.
              Units: ``cm-2 s-1 TeV-1 deg-2``
          """
          return self.model.evaluate_geom(self.geom)
  
      def compute_flux(self):
          """Compute model integral flux over map pixel volumes.
  
          For now, we simply multiply dnde with bin volume.
          """
          dnde = self.compute_dnde()
          volume = self.geom.bin_volume()
          return dnde * volume
  
      def apply_exposure(self, flux):
          """Compute npred cube
  
          For now just divide flux cube by exposure
          """
          npred = (flux * self.exposure.quantity).to_value("")
          return Map.from_geom(self.geom, data=npred, unit="")
  
      def apply_psf(self, npred):
          """Convolve npred cube with PSF"""
          tmp = npred.convolve(self.psf)
          tmp.data[tmp.data < 0.0] = 0
          return tmp
  
      def apply_edisp(self, npred):
          """Convolve map data with energy dispersion.
  
          Parameters
          ----------
          npred : `~gammapy.maps.Map`
              Predicted counts in true energy bins
  
          Returns
          -------
          npred_reco : `~gammapy.maps.Map`
              Predicted counts in reco energy bins
          """
          return npred.apply_edisp(self.edisp)
  
      def compute_npred(self):
          """
          Evaluate model predicted counts.
  
          Returns
          -------
          npred : `~gammapy.maps.Map`
              Predicted counts on the map (in reco energy bins)
          """
          flux = self.compute_flux()
          npred = self.apply_exposure(flux)
          if self.psf is not None:
              npred = self.apply_psf(npred)
          if self.edisp is not None:
              npred = self.apply_edisp(npred)
  
          return npred
  
files: gammapy/cube/fit.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import abc
  import collections.abc
  import copy
  from warnings import warn
  import numpy as np
  from gammapy.utils.scripts import make_name, make_path, read_yaml, write_yaml
  from gammapy.utils.table import table_from_row_data
  from ..maps import WcsNDMap
  from .parameter import Parameters
  
  __all__ = ["Dataset", "Datasets"]
  
  
  class Dataset(abc.ABC):
      """Dataset abstract base class.
  
      TODO: add tutorial how to create your own dataset types.
  
      For now, see existing examples in Gammapy how this works:
  
      - `gammapy.cube.MapDataset`
      - `gammapy.spectrum.SpectrumDataset`
      - `gammapy.spectrum.FluxPointsDataset`
      """
  
      _residuals_labels = {
          "diff": "data - model",
          "diff/model": "(data - model) / model",
          "diff/sqrt(model)": "(data - model) / sqrt(model)",
      }
  
      @property
      def mask(self):
          """Combined fit and safe mask"""
          mask_safe = (
              self.mask_safe.data
              if isinstance(self.mask_safe, WcsNDMap)
              else self.mask_safe
          )
          mask_fit = (
              self.mask_fit.data if isinstance(self.mask_fit, WcsNDMap) else self.mask_fit
          )
          if mask_safe is not None and mask_fit is not None:
              mask = mask_safe & mask_fit
          elif mask_fit is not None:
              mask = mask_fit
          elif mask_safe is not None:
              mask = mask_safe
          else:
              mask = None
          return mask
  
      def stat_sum(self):
          """Total statistic given the current model parameters."""
          stat = self.stat_array()
  
          if self.mask is not None:
              stat = stat[self.mask]
  
          return np.sum(stat, dtype=np.float64)
  
      @abc.abstractmethod
      def stat_array(self):
          """Statistic array, one value per data point."""
  
      def copy(self, name=None):
          """A deep copy."""
          new = copy.deepcopy(self)
          if name is None:
              new.name = make_name()
          else:
              new.name = name
          return new
  
      @staticmethod
      def _compute_residuals(data, model, method="diff"):
          with np.errstate(invalid="ignore"):
              if method == "diff":
                  residuals = data - model
              elif method == "diff/model":
                  residuals = (data - model) / model
              elif method == "diff/sqrt(model)":
                  residuals = (data - model) / np.sqrt(model)
              else:
                  raise AttributeError(
                      f"Invalid method: {method!r}. Choose between 'diff',"
                      " 'diff/model' and 'diff/sqrt(model)'"
                  )
          return residuals
  
  
  class Datasets(collections.abc.Sequence):
      """Dataset collection.
  
      Parameters
      ----------
      datasets : `Dataset` or list of `Dataset`
          Datasets
      """
  
      def __init__(self, datasets):
          if isinstance(datasets, Datasets):
              datasets = list(datasets)
          elif isinstance(datasets, list):
              pass
          else:
              raise TypeError(f"Invalid type: {datasets!r}")
  
          unique_names = []
          for dataset in datasets:
              while dataset.name in unique_names:
                  dataset.name = make_name()  # replace duplicate
                  warn("Dateset names must be unique, auto-replaced duplicates")
              unique_names.append(dataset.name)
  
          self._datasets = datasets
  
      @property
      def parameters(self):
          """Unique parameters (`~gammapy.modeling.Parameters`).
  
          Duplicate parameter objects have been removed.
          The order of the unique parameters remains.
          """
          parameters = Parameters.from_stack(_.parameters for _ in self)
          return parameters.unique_parameters
  
      @property
      def is_all_same_type(self):
          """Whether all contained datasets are of the same type"""
          return len(set(_.__class__ for _ in self)) == 1
  
      @property
      def is_all_same_shape(self):
          """Whether all contained datasets have the same data shape"""
          return len(set(_.data_shape for _ in self)) == 1
  
      def stat_sum(self):
          """Compute joint likelihood"""
          stat_sum = 0
          # TODO: add parallel evaluation of likelihoods
          for dataset in self:
              stat_sum += dataset.stat_sum()
          return stat_sum
  
      def __str__(self):
          str_ = self.__class__.__name__ + "\n"
          str_ += "--------\n"
  
          for idx, dataset in enumerate(self):
              str_ += f"idx={idx}, id={hex(id(dataset))!r}, name={dataset.name!r}\n"
  
          return str_
  
      def copy(self):
          """A deep copy."""
          return copy.deepcopy(self)
  
      @classmethod
      def read(cls, filedata, filemodel):
          """De-serialize datasets from YAML and FITS files.
  
          Parameters
          ----------
          filedata : str
              filepath to yaml datasets file
          filemodel : str
              filepath to yaml models file
  
          Returns
          -------
          dataset : 'gammapy.modeling.Datasets'
              Datasets
          """
          from .serialize import dict_to_datasets
  
          components = read_yaml(make_path(filemodel))
          data_list = read_yaml(make_path(filedata))
          datasets = dict_to_datasets(data_list, components)
          return cls(datasets)
  
      def write(self, path, prefix="", overwrite=False):
          """Serialize datasets to YAML and FITS files.
  
          Parameters
          ----------
          path : `pathlib.Path`
              path to write files
          prefix : str
              common prefix of file names
          overwrite : bool
              overwrite datasets FITS files
          """
          from .serialize import datasets_to_dict
  
          path = make_path(path)
  
          datasets_dict, components_dict = datasets_to_dict(self, path, prefix, overwrite)
          write_yaml(datasets_dict, path / f"{prefix}_datasets.yaml", sort_keys=False)
          write_yaml(components_dict, path / f"{prefix}_models.yaml", sort_keys=False)
  
      def stack_reduce(self):
          """Reduce the Datasets to a unique Dataset by stacking them together.
  
          This works only if all Dataset are of the same type and if a proper
          in-place stack method exists for the Dataset type.
  
          Returns
          -------
          dataset : ~gammapy.utils.Dataset
              the stacked dataset
          """
          if not self.is_all_same_type:
              raise ValueError(
                  "Stacking impossible: all Datasets contained are not of a unique type."
              )
  
          dataset = self[0].copy()
          for ds in self[1:]:
              dataset.stack(ds)
          return dataset
  
      def info_table(self, cumulative=False):
          """Get info table for datasets.
  
          Parameters
          ----------
          cumulative : bool
              Cumulate info across all observations
  
          Returns
          -------
          info_table : `~astropy.table.Table`
              Info table.
          """
          if not self.is_all_same_type:
              raise ValueError("Info table not supported for mixed dataset type.")
  
          stacked = self[0].copy()
  
          rows = [stacked.info_dict()]
  
          for dataset in self[1:]:
              if cumulative:
                  stacked.stack(dataset)
                  row = stacked.info_dict()
              else:
                  row = dataset.info_dict()
  
              rows.append(row)
  
          return table_from_row_data(rows=rows)
  
      def __getitem__(self, val):
          if isinstance(val, (int, slice)):
              return self._datasets[val]
          elif isinstance(val, str):
              for idx, dataset in enumerate(self._datasets):
                  if val == dataset.name:
                      return self._datasets[idx]
              raise IndexError(f"No dataset: {val!r}")
          else:
              raise TypeError(f"Invalid type: {type(val)!r}")
  
      def __len__(self):
          return len(self._datasets)
  
files: gammapy/modeling/datasets.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import abc
  import collections.abc
  import copy
  import numpy as np
  from gammapy.utils.scripts import make_path, read_yaml, write_yaml
  from gammapy.utils.table import table_from_row_data
  from ..maps import WcsNDMap
  from .parameter import Parameters
  
  __all__ = ["Dataset", "Datasets"]
  
  
  class Dataset(abc.ABC):
      """Dataset abstract base class.
  
      TODO: add tutorial how to create your own dataset types.
  
      For now, see existing examples in Gammapy how this works:
  
      - `gammapy.cube.MapDataset`
      - `gammapy.spectrum.SpectrumDataset`
      - `gammapy.spectrum.FluxPointsDataset`
      """
  
      _residuals_labels = {
          "diff": "data - model",
          "diff/model": "(data - model) / model",
          "diff/sqrt(model)": "(data - model) / sqrt(model)",
      }
  
      @property
      def mask(self):
          """Combined fit and safe mask"""
          mask_safe = (
              self.mask_safe.data
              if isinstance(self.mask_safe, WcsNDMap)
              else self.mask_safe
          )
          mask_fit = (
              self.mask_fit.data if isinstance(self.mask_fit, WcsNDMap) else self.mask_fit
          )
          if mask_safe is not None and mask_fit is not None:
              mask = mask_safe & mask_fit
          elif mask_fit is not None:
              mask = mask_fit
          elif mask_safe is not None:
              mask = mask_safe
          else:
              mask = None
          return mask
  
      def stat_sum(self):
          """Total statistic given the current model parameters."""
          stat = self.stat_array()
  
          if self.mask is not None:
              stat = stat[self.mask]
  
          return np.sum(stat, dtype=np.float64)
  
      @abc.abstractmethod
      def stat_array(self):
          """Statistic array, one value per data point."""
  
      def copy(self):
          """A deep copy."""
          return copy.deepcopy(self)
  
      @staticmethod
      def _compute_residuals(data, model, method="diff"):
          with np.errstate(invalid="ignore"):
              if method == "diff":
                  residuals = data - model
              elif method == "diff/model":
                  residuals = (data - model) / model
              elif method == "diff/sqrt(model)":
                  residuals = (data - model) / np.sqrt(model)
              else:
                  raise AttributeError(
                      f"Invalid method: {method!r}. Choose between 'diff',"
                      " 'diff/model' and 'diff/sqrt(model)'"
                  )
          return residuals
  
  
  class Datasets(collections.abc.Sequence):
      """Dataset collection.
  
      Parameters
      ----------
      datasets : `Dataset` or list of `Dataset`
          Datasets
      """
  
      def __init__(self, datasets):
          if isinstance(datasets, Datasets):
              self._datasets = list(datasets)
          elif isinstance(datasets, list):
              self._datasets = datasets
          else:
              raise TypeError(f"Invalid type: {datasets!r}")
  
      @property
      def parameters(self):
          """Unique parameters (`~gammapy.modeling.Parameters`).
  
          Duplicate parameter objects have been removed.
          The order of the unique parameters remains.
          """
          parameters = Parameters.from_stack(_.parameters for _ in self)
          return parameters.unique_parameters
  
      @property
      def is_all_same_type(self):
          """Whether all contained datasets are of the same type"""
          return len(set(_.__class__ for _ in self)) == 1
  
      @property
      def is_all_same_shape(self):
          """Whether all contained datasets have the same data shape"""
          return len(set(_.data_shape for _ in self)) == 1
  
      def stat_sum(self):
          """Compute joint likelihood"""
          stat_sum = 0
          # TODO: add parallel evaluation of likelihoods
          for dataset in self:
              stat_sum += dataset.stat_sum()
          return stat_sum
  
      def __str__(self):
          str_ = self.__class__.__name__ + "\n"
          str_ += "--------\n"
  
          for idx, dataset in enumerate(self):
              str_ += f"idx={idx}, id={hex(id(dataset))!r}, name={dataset.name!r}\n"
  
          return str_
  
      def copy(self):
          """A deep copy."""
          return copy.deepcopy(self)
  
      @classmethod
      def read(cls, filedata, filemodel):
          """De-serialize datasets from YAML and FITS files.
  
          Parameters
          ----------
          filedata : str
              filepath to yaml datasets file
          filemodel : str
              filepath to yaml models file
  
          Returns
          -------
          dataset : 'gammapy.modeling.Datasets'
              Datasets
          """
          from .serialize import dict_to_datasets
  
          components = read_yaml(make_path(filemodel))
          data_list = read_yaml(make_path(filedata))
          datasets = dict_to_datasets(data_list, components)
          return cls(datasets)
  
      def write(self, path, prefix="", overwrite=False):
          """Serialize datasets to YAML and FITS files.
  
          Parameters
          ----------
          path : `pathlib.Path`
              path to write files
          prefix : str
              common prefix of file names
          overwrite : bool
              overwrite datasets FITS files
          """
          from .serialize import datasets_to_dict
  
          path = make_path(path)
  
          datasets_dict, components_dict = datasets_to_dict(self, path, prefix, overwrite)
          write_yaml(datasets_dict, path / f"{prefix}_datasets.yaml", sort_keys=False)
          write_yaml(components_dict, path / f"{prefix}_models.yaml", sort_keys=False)
  
      def stack_reduce(self):
          """Reduce the Datasets to a unique Dataset by stacking them together.
  
          This works only if all Dataset are of the same type and if a proper
          in-place stack method exists for the Dataset type.
  
          Returns
          -------
          dataset : ~gammapy.utils.Dataset
              the stacked dataset
          """
          if not self.is_all_same_type:
              raise ValueError(
                  "Stacking impossible: all Datasets contained are not of a unique type."
              )
  
          dataset = self[0].copy()
          for ds in self[1:]:
              dataset.stack(ds)
          return dataset
  
      def info_table(self, cumulative=False):
          """Get info table for datasets.
  
          Parameters
          ----------
          cumulative : bool
              Cumulate info across all observations
  
          Returns
          -------
          info_table : `~astropy.table.Table`
              Info table.
          """
          if not self.is_all_same_type:
              raise ValueError("Info table not supported for mixed dataset type.")
  
          stacked = self[0].copy()
  
          rows = [stacked.info_dict()]
  
          for dataset in self[1:]:
              if cumulative:
                  stacked.stack(dataset)
                  row = stacked.info_dict()
              else:
                  row = dataset.info_dict()
  
              rows.append(row)
  
          return table_from_row_data(rows=rows)
  
      def __getitem__(self, val):
          if isinstance(val, (int, slice)):
              return self._datasets[val]
          elif isinstance(val, str):
              for idx, dataset in enumerate(self._datasets):
                  if val == dataset.name:
                      return self._datasets[idx]
              raise IndexError(f"No dataset: {val!r}")
          else:
              raise TypeError(f"Invalid type: {type(val)!r}")
  
      def __len__(self):
          return len(self._datasets)
  
files: gammapy/modeling/datasets.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import copy
  import astropy.units as u
  from gammapy.utils.scripts import make_name
  from .parameter import Parameter, Parameters
  
  __all__ = ["Model"]
  
  
  class Model:
      """Model base class."""
  
      def __init__(self, **kwargs):
          # Copy default parameters from the class to the instance
          self._parameters = self.__class__.default_parameters.copy()
          for parameter in self._parameters:
              if parameter.name in self.__dict__:
                  raise ValueError(
                      f"Invalid parameter name: {parameter.name!r}."
                      f"Attribute exists already: {getattr(self, parameter.name)!r}"
                  )
  
              setattr(self, parameter.name, parameter)
  
          # Update parameter information from kwargs
          for name, value in kwargs.items():
              if name not in self.parameters.names:
                  raise ValueError(
                      f"Invalid argument: {name!r}. Parameter names are: {self.parameters.names}"
                  )
  
              self._parameters[name].quantity = u.Quantity(value)
  
      def __init_subclass__(cls, **kwargs):
          # Add parameters list on the model sub-class (not instances)
          cls.default_parameters = Parameters(
              [_ for _ in cls.__dict__.values() if isinstance(_, Parameter)]
          )
  
      def _init_from_parameters(self, parameters):
          """Create model from list of parameters.
  
          This should be called for models that generate
          the parameters dynamically in ``__init__``,
          like the ``NaimaSpectralModel``
          """
          # TODO: should we pass through `Parameters` here? Why?
          parameters = Parameters(parameters)
          self._parameters = parameters
          for parameter in parameters:
              setattr(self, parameter.name, parameter)
  
      @property
      def parameters(self):
          """Parameters (`~gammapy.modeling.Parameters`)"""
          return self._parameters
  
      def copy(self, name=None):
          """A deep copy."""
          new = copy.deepcopy(self)
          if name is None:
              new.name = make_name()
          else:
              new.name = name
          return new
  
      def __str__(self):
          return f"{self.__class__.__name__}\n\n{self.parameters.to_table()}"
  
      def to_dict(self):
          """Create dict for YAML serialisation"""
          return {"type": self.tag, "parameters": self.parameters.to_dict()["parameters"]}
  
      @classmethod
      def from_dict(cls, data):
          params = {
              x["name"].split("@")[0]: x["value"] * u.Unit(x["unit"])
              for x in data["parameters"]
          }
  
          # TODO: this is a special case for spatial models, maybe better move to `SpatialModel` base class
          if "frame" in data:
              params["frame"] = data["frame"]
  
          model = cls(**params)
          model._update_from_dict(data)
          return model
  
      # TODO: try to get rid of this
      def _update_from_dict(self, data):
          self._parameters.update_from_dict(data)
          for parameter in self.parameters:
              setattr(self, parameter.name, parameter)
  
      @staticmethod
      def create(tag, *args, **kwargs):
          """Create a model instance.
  
          Examples
          --------
          >>> from gammapy.modeling import Model
          >>> spectral_model = Model.create("PowerLaw2SpectralModel", amplitude="1e-10 cm-2 s-1", index=3)
          >>> type(spectral_model)
          gammapy.modeling.models.spectral.PowerLaw2SpectralModel
          """
          from .models import MODELS
  
          cls = MODELS.get_cls(tag)
          return cls(*args, **kwargs)
  
files: gammapy/modeling/model.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import copy
  import astropy.units as u
  from .parameter import Parameter, Parameters
  
  __all__ = ["Model"]
  
  
  class Model:
      """Model base class."""
  
      def __init__(self, **kwargs):
          # Copy default parameters from the class to the instance
          self._parameters = self.__class__.default_parameters.copy()
          for parameter in self._parameters:
              if parameter.name in self.__dict__:
                  raise ValueError(
                      f"Invalid parameter name: {parameter.name!r}."
                      f"Attribute exists already: {getattr(self, parameter.name)!r}"
                  )
  
              setattr(self, parameter.name, parameter)
  
          # Update parameter information from kwargs
          for name, value in kwargs.items():
              if name not in self.parameters.names:
                  raise ValueError(
                      f"Invalid argument: {name!r}. Parameter names are: {self.parameters.names}"
                  )
  
              self._parameters[name].quantity = u.Quantity(value)
  
      def __init_subclass__(cls, **kwargs):
          # Add parameters list on the model sub-class (not instances)
          cls.default_parameters = Parameters(
              [_ for _ in cls.__dict__.values() if isinstance(_, Parameter)]
          )
  
      def _init_from_parameters(self, parameters):
          """Create model from list of parameters.
  
          This should be called for models that generate
          the parameters dynamically in ``__init__``,
          like the ``NaimaSpectralModel``
          """
          # TODO: should we pass through `Parameters` here? Why?
          parameters = Parameters(parameters)
          self._parameters = parameters
          for parameter in parameters:
              setattr(self, parameter.name, parameter)
  
      @property
      def parameters(self):
          """Parameters (`~gammapy.modeling.Parameters`)"""
          return self._parameters
  
      def copy(self):
          """A deep copy."""
          return copy.deepcopy(self)
  
      def __str__(self):
          return f"{self.__class__.__name__}\n\n{self.parameters.to_table()}"
  
      def to_dict(self):
          """Create dict for YAML serialisation"""
          return {"type": self.tag, "parameters": self.parameters.to_dict()["parameters"]}
  
      @classmethod
      def from_dict(cls, data):
          params = {
              x["name"].split("@")[0]: x["value"] * u.Unit(x["unit"])
              for x in data["parameters"]
          }
  
          # TODO: this is a special case for spatial models, maybe better move to `SpatialModel` base class
          if "frame" in data:
              params["frame"] = data["frame"]
  
          model = cls(**params)
          model._update_from_dict(data)
          return model
  
      # TODO: try to get rid of this
      def _update_from_dict(self, data):
          self._parameters.update_from_dict(data)
          for parameter in self.parameters:
              setattr(self, parameter.name, parameter)
  
      @staticmethod
      def create(tag, *args, **kwargs):
          """Create a model instance.
  
          Examples
          --------
          >>> from gammapy.modeling import Model
          >>> spectral_model = Model.create("PowerLaw2SpectralModel", amplitude="1e-10 cm-2 s-1", index=3)
          >>> type(spectral_model)
          gammapy.modeling.models.spectral.PowerLaw2SpectralModel
          """
          from .models import MODELS
  
          cls = MODELS.get_cls(tag)
          return cls(*args, **kwargs)
  
files: gammapy/modeling/model.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  """Cube models (axes: lon, lat, energy)."""
  import collections.abc
  import copy
  from pathlib import Path
  from warnings import warn
  import numpy as np
  import astropy.units as u
  import yaml
  from gammapy.maps import Map
  from gammapy.modeling import Model, Parameter, Parameters
  from gammapy.utils.scripts import make_name, make_path
  
  
  class SkyModelBase(Model):
      """Sky model base class"""
  
      def __add__(self, other):
          if isinstance(other, (SkyModels, list)):
              return SkyModels([self, *other])
          elif isinstance(other, (SkyModel, SkyDiffuseCube)):
              return SkyModels([self, other])
          else:
              raise TypeError(f"Invalid type: {other!r}")
  
      def __radd__(self, model):
          return self.__add__(model)
  
      def __call__(self, lon, lat, energy):
          return self.evaluate(lon, lat, energy)
  
      def evaluate_geom(self, geom):
          coords = geom.get_coord(frame=self.frame)
          return self(coords.lon, coords.lat, coords["energy"])
  
  
  class SkyModels(collections.abc.Sequence):
      """Sky model collection.
  
      Parameters
      ----------
      skymodels : `SkyModel`, list of `SkyModel` or `SkyModels`
          Sky models
      """
  
      def __init__(self, skymodels):
          if isinstance(skymodels, SkyModels):
              models = skymodels._skymodels
          elif isinstance(skymodels, SkyModel):
              models = [skymodels]
          elif isinstance(skymodels, list):
              models = skymodels
          else:
              raise TypeError(f"Invalid type: {skymodels!r}")
  
          unique_names = []
          for model in models:
              while model.name in unique_names:
                  model.name = make_name()  # replace duplicate
                  warn("SkyModel names must be unique, auto-replaced duplicates")
              unique_names.append(model.name)
  
          self._skymodels = models
  
      @property
      def parameters(self):
          return Parameters.from_stack([_.parameters for _ in self._skymodels])
  
      @classmethod
      def read(cls, filename):
          """Read from YAML file."""
          yaml_str = Path(filename).read_text()
          return cls.from_yaml(yaml_str)
  
      @classmethod
      def from_yaml(cls, yaml_str):
          """Create from YAML string."""
          from gammapy.modeling.serialize import dict_to_models
  
          data = yaml.safe_load(yaml_str)
          skymodels = dict_to_models(data)
          return cls(skymodels)
  
      def write(self, path, overwrite=False):
          """Write to YAML file."""
          path = make_path(path)
          if path.exists() and not overwrite:
              raise IOError(f"File exists already: {path}")
          path.write_text(self.to_yaml())
  
      def to_yaml(self):
          """Convert to YAML string."""
          from gammapy.modeling.serialize import models_to_dict
  
          data = models_to_dict(self._skymodels)
          return yaml.dump(
              data, sort_keys=False, indent=4, width=80, default_flow_style=None
          )
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}\n\n"
  
          for idx, skymodel in enumerate(self):
              str_ += f"Component {idx}: {skymodel}\n\n\t\n\n"
  
          return str_
  
      def __add__(self, other):
          if isinstance(other, (SkyModels, list)):
              return SkyModels([*self, *other])
          elif isinstance(other, (SkyModel, SkyDiffuseCube)):
              return SkyModels([*self, other])
          else:
              raise TypeError(f"Invalid type: {other!r}")
  
      def __getitem__(self, val):
          if isinstance(val, int):
              return self._skymodels[val]
          elif isinstance(val, str):
              for idx, model in enumerate(self._skymodels):
                  if val == model.name:
                      return self._skymodels[idx]
              raise IndexError(f"No model: {val!r}")
          else:
              raise TypeError(f"Invalid type: {type(val)!r}")
  
      def __len__(self):
          return len(self._skymodels)
  
  
  class SkyModel(SkyModelBase):
      """Sky model component.
  
      This model represents a factorised sky model.
      It has `~gammapy.modeling.Parameters`
      combining the spatial and spectral parameters.
  
      TODO: add possibility to have a temporal model component also.
  
      Parameters
      ----------
      spectral_model : `~gammapy.modeling.models.SpectralModel`
          Spectral model
      spatial_model : `~gammapy.modeling.models.SpatialModel`
          Spatial model (must be normalised to integrate to 1)
      name : str
          Model identifier
      """
  
      tag = "SkyModel"
  
      def __init__(self, spectral_model, spatial_model=None, name=None):
          self.spatial_model = spatial_model
          self.spectral_model = spectral_model
          super().__init__()
          # TODO: this hack is needed for compound models to work
          self.__dict__.pop("_parameters")
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
  
      @property
      def parameters(self):
          parameters = []
  
          if self.spatial_model is not None:
              parameters.append(self.spatial_model.parameters)
  
          parameters.append(self.spectral_model.parameters)
          return Parameters.from_stack(parameters)
  
      @property
      def spatial_model(self):
          """`~gammapy.modeling.models.SpatialModel`"""
          return self._spatial_model
  
      @spatial_model.setter
      def spatial_model(self, model):
          from .spatial import SpatialModel
  
          if not (model is None or isinstance(model, SpatialModel)):
              raise TypeError(f"Invalid type: {model!r}")
  
          self._spatial_model = model
  
      @property
      def spectral_model(self):
          """`~gammapy.modeling.models.SpectralModel`"""
          return self._spectral_model
  
      @spectral_model.setter
      def spectral_model(self, model):
          from .spectral import SpectralModel
  
          if not (model is None or isinstance(model, SpectralModel)):
              raise TypeError(f"Invalid type: {model!r}")
          self._spectral_model = model
  
      @property
      def position(self):
          """`~astropy.coordinates.SkyCoord`"""
          return self.spatial_model.position
  
      @property
      def evaluation_radius(self):
          """`~astropy.coordinates.Angle`"""
          return self.spatial_model.evaluation_radius
  
      @property
      def frame(self):
          return self.spatial_model.frame
  
      def __repr__(self):
          return (
              f"{self.__class__.__name__}("
              f"spatial_model={self.spatial_model!r}, "
              f"spectral_model={self.spectral_model!r})"
          )
  
      def evaluate(self, lon, lat, energy):
          """Evaluate the model at given points.
  
          The model evaluation follows numpy broadcasting rules.
  
          Return differential surface brightness cube.
          At the moment in units: ``cm-2 s-1 TeV-1 deg-2``
  
          Parameters
          ----------
          lon, lat : `~astropy.units.Quantity`
              Spatial coordinates
          energy : `~astropy.units.Quantity`
              Energy coordinate
  
          Returns
          -------
          value : `~astropy.units.Quantity`
              Model value at the given point.
          """
          value = self.spectral_model(energy)  # pylint:disable=not-callable
  
          if self.spatial_model is not None:
              value = value * self.spatial_model(lon, lat)  # pylint:disable=not-callable
  
          return value
  
      def evaluate_geom(self, geom):
          """Evaluate model on `~gammapy.maps.Geom`."""
          energy = geom.get_axis_by_name("energy").center[:, np.newaxis, np.newaxis]
          value = self.spectral_model(energy)
  
          if self.spatial_model is not None:
              value = value * self.spatial_model.evaluate_geom(geom.to_image())
  
          return value
  
      def copy(self, **kwargs):
          """Copy SkyModel"""
          if self.spatial_model is not None:
              spatial_model = self.spatial_model.copy()
          else:
              spatial_model = None
  
          kwargs.setdefault("spatial_model", spatial_model)
          kwargs.setdefault("spectral_model", self.spectral_model.copy())
          kwargs.setdefault("name", make_name())
          return self.__class__(**kwargs)
  
      def to_dict(self):
          """Create dict for YAML serilisation"""
          data = {}
          data["name"] = self.name
          data["type"] = self.tag
          data["spectral"] = self.spectral_model.to_dict()
  
          if self.spatial_model is not None:
              data["spatial"] = self.spatial_model.to_dict()
  
          return data
  
      @classmethod
      def from_dict(cls, data):
          """Create SkyModel from dict"""
          from gammapy.modeling.models import SPATIAL_MODELS, SPECTRAL_MODELS
  
          model_class = SPECTRAL_MODELS.get_cls(data["spectral"]["type"])
          spectral_model = model_class.from_dict(data["spectral"])
  
          spatial_data = data.get("spatial")
  
          if spatial_data is not None:
              model_class = SPATIAL_MODELS.get_cls(spatial_data["type"])
              spatial_model = model_class.from_dict(spatial_data)
          else:
              spatial_model = None
  
          return cls(
              name=data["name"],
              spatial_model=spatial_model,
              spectral_model=spectral_model,
          )
  
  
  class SkyDiffuseCube(SkyModelBase):
      """Cube sky map template model (3D).
  
      This is for a 3D map with an energy axis.
      Use `~gammapy.modeling.models.TemplateSpatialModel` for 2D maps.
  
      Parameters
      ----------
      map : `~gammapy.maps.Map`
          Map template
      norm : float
          Norm parameter (multiplied with map values)
      tilt : float
          Additional tilt in the spectrum
      reference : `~astropy.units.Quantity`
          Reference energy of the tilt.
      meta : dict, optional
          Meta information, meta['filename'] will be used for serialization
      interp_kwargs : dict
          Interpolation keyword arguments passed to `gammapy.maps.Map.interp_by_coord`.
          Default arguments are {'interp': 'linear', 'fill_value': 0}.
      """
  
      tag = "SkyDiffuseCube"
      norm = Parameter("norm", 1)
      tilt = Parameter("tilt", 0, unit="", frozen=True)
      reference = Parameter("reference", "1 TeV", frozen=True)
  
      def __init__(
          self,
          map,
          norm=norm.quantity,
          tilt=tilt.quantity,
          reference=reference.quantity,
          meta=None,
          interp_kwargs=None,
          name=None,
          filename=None,
      ):
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
          axis = map.geom.get_axis_by_name("energy")
  
          if axis.node_type != "center":
              raise ValueError('Need a map with energy axis node_type="center"')
  
          self.map = map
          self.meta = {} if meta is None else meta
          self.filename = filename
  
          interp_kwargs = {} if interp_kwargs is None else interp_kwargs
          interp_kwargs.setdefault("interp", "linear")
          interp_kwargs.setdefault("fill_value", 0)
          self._interp_kwargs = interp_kwargs
  
          # TODO: onve we have implement a more general and better model caching
          #  remove this again
          self._cached_value = None
          self._cached_coordinates = (None, None, None)
  
          super().__init__(norm=norm, tilt=tilt, reference=reference)
  
      @classmethod
      def read(cls, filename, **kwargs):
          """Read map from FITS file.
  
          The default unit used if none is found in the file is ``cm-2 s-1 MeV-1 sr-1``.
  
          Parameters
          ----------
          filename : str
              FITS image filename.
          """
          m = Map.read(filename, **kwargs)
          if m.unit == "":
              m.unit = "cm-2 s-1 MeV-1 sr-1"
          name = Path(filename).stem
          return cls(m, name=name, filename=filename)
  
      def _interpolate(self, lon, lat, energy):
          coord = {
              "lon": lon.to_value("deg"),
              "lat": lat.to_value("deg"),
              "energy": energy,
          }
          return self.map.interp_by_coord(coord, **self._interp_kwargs)
  
      def evaluate(self, lon, lat, energy):
          """Evaluate model."""
          is_cached_coord = [
              _ is coord for _, coord in zip((lon, lat, energy), self._cached_coordinates)
          ]
  
          # reset cache
          if not np.all(is_cached_coord):
              self._cached_value = None
  
          if self._cached_value is None:
              self._cached_coordinates = (lon, lat, energy)
              self._cached_value = self._interpolate(lon, lat, energy)
  
          norm = self.parameters["norm"].value
  
          tilt = self.parameters["tilt"].value
          reference = self.parameters["reference"].quantity
          tilt_factor = np.power((energy / reference).to(""), -tilt)
  
          val = norm * self._cached_value * tilt_factor.value
          return u.Quantity(val, self.map.unit, copy=False)
  
      def copy(self):
          """A shallow copy"""
          return copy.copy(self)
  
      @property
      def position(self):
          """`~astropy.coordinates.SkyCoord`"""
          return self.map.geom.center_skydir
  
      @property
      def evaluation_radius(self):
          """`~astropy.coordinates.Angle`"""
          return np.max(self.map.geom.width) / 2.0
  
      @property
      def frame(self):
          return self.position.frame.name
  
      @classmethod
      def from_dict(cls, data):
          model = cls.read(data["filename"])
          model._update_from_dict(data)
          return model
  
      def to_dict(self):
          data = super().to_dict()
          data["name"] = self.name
          data["type"] = data.pop("type")
          data["filename"] = self.filename
  
          # Move parameters at the end
          data["parameters"] = data.pop("parameters")
          return data
  
  
  class BackgroundModel(Model):
      """Background model.
  
      Create a new map by a tilt and normalization on the available map
  
      Parameters
      ----------
      map : `~gammapy.maps.Map`
          Background model map
      norm : float
          Background normalization
      tilt : float
          Additional tilt in the spectrum
      reference : `~astropy.units.Quantity`
          Reference energy of the tilt.
      """
  
      tag = "BackgroundModel"
      norm = Parameter("norm", 1, unit="", min=0)
      tilt = Parameter("tilt", 0, unit="", frozen=True)
      reference = Parameter("reference", "1 TeV", frozen=True)
  
      def __init__(
          self,
          map,
          norm=norm.quantity,
          tilt=tilt.quantity,
          reference=reference.quantity,
          name=None,
          filename=None,
      ):
          axis = map.geom.get_axis_by_name("energy")
          if axis.node_type != "edges":
              raise ValueError('Need an integrated map, energy axis node_type="edges"')
  
          self.map = map
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
          self.filename = filename
  
          super().__init__(norm=norm, tilt=tilt, reference=reference)
  
      @property
      def energy_center(self):
          """True energy axis bin centers (`~astropy.units.Quantity`)"""
          energy_axis = self.map.geom.get_axis_by_name("energy")
          energy = energy_axis.center
          return energy[:, np.newaxis, np.newaxis]
  
      def evaluate(self):
          """Evaluate background model.
  
          Returns
          -------
          background_map : `~gammapy.maps.Map`
              Background evaluated on the Map
          """
          norm = self.parameters["norm"].value
          tilt = self.parameters["tilt"].value
          reference = self.parameters["reference"].quantity
          tilt_factor = np.power((self.energy_center / reference).to(""), -tilt)
          back_values = norm * self.map.data * tilt_factor.value
          return self.map.copy(data=back_values)
  
      def to_dict(self):
          data = {}
          data["name"] = self.name
          data.update(super().to_dict())
          if self.filename is not None:
              data["filename"] = self.filename
          data["parameters"] = data.pop("parameters")
          return data
  
      @classmethod
      def from_dict(cls, data):
          if "filename" in data:
              map = Map.read(data["filename"])
          elif "map" in data:
              map = data["map"]
          else:
              raise ValueError("Requires either filename or `Map` object")
  
          model = cls(map=map, name=data["name"])
          model._update_from_dict(data)
          return model
  
  
  def create_fermi_isotropic_diffuse_model(filename, **kwargs):
      """Read Fermi isotropic diffuse model.
  
      See `LAT Background models <https://fermi.gsfc.nasa.gov/ssc/data/access/lat/BackgroundModels.html>`_
  
      Parameters
      ----------
      filename : str
          filename
      kwargs : dict
          Keyword arguments forwarded to `TemplateSpectralModel`
  
      Returns
      -------
      diffuse_model : `SkyModel`
          Fermi isotropic diffuse sky model.
      """
      from .spectral import TemplateSpectralModel
      from .spatial import ConstantSpatialModel
  
      vals = np.loadtxt(make_path(filename))
      energy = u.Quantity(vals[:, 0], "MeV", copy=False)
      values = u.Quantity(vals[:, 1], "MeV-1 s-1 cm-2", copy=False)
  
      spatial_model = ConstantSpatialModel()
      spectral_model = TemplateSpectralModel(energy=energy, values=values, **kwargs)
      return SkyModel(
          spatial_model=spatial_model,
          spectral_model=spectral_model,
          name="fermi-diffuse-iso",
      )
  
files: gammapy/modeling/models/cube.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  """Cube models (axes: lon, lat, energy)."""
  import collections.abc
  import copy
  from pathlib import Path
  import numpy as np
  import astropy.units as u
  import yaml
  from gammapy.maps import Map
  from gammapy.modeling import Model, Parameter, Parameters
  from gammapy.utils.scripts import make_path
  
  
  class SkyModelBase(Model):
      """Sky model base class"""
  
      def __add__(self, other):
          if isinstance(other, (SkyModels, list)):
              return SkyModels([self, *other])
          elif isinstance(other, (SkyModel, SkyDiffuseCube)):
              return SkyModels([self, other])
          else:
              raise TypeError(f"Invalid type: {other!r}")
  
      def __radd__(self, model):
          return self.__add__(model)
  
      def __call__(self, lon, lat, energy):
          return self.evaluate(lon, lat, energy)
  
      def evaluate_geom(self, geom):
          coords = geom.get_coord(frame=self.frame)
          return self(coords.lon, coords.lat, coords["energy"])
  
  
  class SkyModels(collections.abc.Sequence):
      """Sky model collection.
  
      Parameters
      ----------
      skymodels : `SkyModel`, list of `SkyModel` or `SkyModels`
          Sky models
      """
  
      def __init__(self, skymodels):
          if isinstance(skymodels, SkyModels):
              models = skymodels._skymodels
          elif isinstance(skymodels, SkyModel):
              models = [skymodels]
          elif isinstance(skymodels, list):
              models = skymodels
          else:
              raise TypeError(f"Invalid type: {skymodels!r}")
  
          self._skymodels = models
  
      @property
      def parameters(self):
          return Parameters.from_stack([_.parameters for _ in self._skymodels])
  
      @classmethod
      def read(cls, filename):
          """Read from YAML file."""
          yaml_str = Path(filename).read_text()
          return cls.from_yaml(yaml_str)
  
      @classmethod
      def from_yaml(cls, yaml_str):
          """Create from YAML string."""
          from gammapy.modeling.serialize import dict_to_models
  
          data = yaml.safe_load(yaml_str)
          skymodels = dict_to_models(data)
          return cls(skymodels)
  
      def write(self, path, overwrite=False):
          """Write to YAML file."""
          path = make_path(path)
          if path.exists() and not overwrite:
              raise IOError(f"File exists already: {path}")
          path.write_text(self.to_yaml())
  
      def to_yaml(self):
          """Convert to YAML string."""
          from gammapy.modeling.serialize import models_to_dict
  
          data = models_to_dict(self._skymodels)
          return yaml.dump(
              data, sort_keys=False, indent=4, width=80, default_flow_style=None
          )
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}\n\n"
  
          for idx, skymodel in enumerate(self):
              str_ += f"Component {idx}: {skymodel}\n\n\t\n\n"
  
          return str_
  
      def __add__(self, other):
          if isinstance(other, (SkyModels, list)):
              return SkyModels([*self, *other])
          elif isinstance(other, (SkyModel, SkyDiffuseCube)):
              return SkyModels([*self, other])
          else:
              raise TypeError(f"Invalid type: {other!r}")
  
      def __getitem__(self, val):
          if isinstance(val, int):
              return self._skymodels[val]
          elif isinstance(val, str):
              for idx, model in enumerate(self._skymodels):
                  if val == model.name:
                      return self._skymodels[idx]
              raise IndexError(f"No model: {val!r}")
          else:
              raise TypeError(f"Invalid type: {type(val)!r}")
  
      def __len__(self):
          return len(self._skymodels)
  
  
  class SkyModel(SkyModelBase):
      """Sky model component.
  
      This model represents a factorised sky model.
      It has `~gammapy.modeling.Parameters`
      combining the spatial and spectral parameters.
  
      TODO: add possibility to have a temporal model component also.
  
      Parameters
      ----------
      spectral_model : `~gammapy.modeling.models.SpectralModel`
          Spectral model
      spatial_model : `~gammapy.modeling.models.SpatialModel`
          Spatial model (must be normalised to integrate to 1)
      name : str
          Model identifier
      """
  
      tag = "SkyModel"
  
      def __init__(self, spectral_model, spatial_model=None, name="source"):
          self.name = name
          self.spatial_model = spatial_model
          self.spectral_model = spectral_model
          super().__init__()
          # TODO: this hack is needed for compound models to work
          self.__dict__.pop("_parameters")
  
      @property
      def parameters(self):
          parameters = []
  
          if self.spatial_model is not None:
              parameters.append(self.spatial_model.parameters)
  
          parameters.append(self.spectral_model.parameters)
          return Parameters.from_stack(parameters)
  
      @property
      def spatial_model(self):
          """`~gammapy.modeling.models.SpatialModel`"""
          return self._spatial_model
  
      @spatial_model.setter
      def spatial_model(self, model):
          from .spatial import SpatialModel
  
          if not (model is None or isinstance(model, SpatialModel)):
              raise TypeError(f"Invalid type: {model!r}")
  
          self._spatial_model = model
  
      @property
      def spectral_model(self):
          """`~gammapy.modeling.models.SpectralModel`"""
          return self._spectral_model
  
      @spectral_model.setter
      def spectral_model(self, model):
          from .spectral import SpectralModel
  
          if not (model is None or isinstance(model, SpectralModel)):
              raise TypeError(f"Invalid type: {model!r}")
          self._spectral_model = model
  
      @property
      def position(self):
          """`~astropy.coordinates.SkyCoord`"""
          return self.spatial_model.position
  
      @property
      def evaluation_radius(self):
          """`~astropy.coordinates.Angle`"""
          return self.spatial_model.evaluation_radius
  
      @property
      def frame(self):
          return self.spatial_model.frame
  
      def __repr__(self):
          return (
              f"{self.__class__.__name__}("
              f"spatial_model={self.spatial_model!r}, "
              f"spectral_model={self.spectral_model!r})"
          )
  
      def evaluate(self, lon, lat, energy):
          """Evaluate the model at given points.
  
          The model evaluation follows numpy broadcasting rules.
  
          Return differential surface brightness cube.
          At the moment in units: ``cm-2 s-1 TeV-1 deg-2``
  
          Parameters
          ----------
          lon, lat : `~astropy.units.Quantity`
              Spatial coordinates
          energy : `~astropy.units.Quantity`
              Energy coordinate
  
          Returns
          -------
          value : `~astropy.units.Quantity`
              Model value at the given point.
          """
          value = self.spectral_model(energy)  # pylint:disable=not-callable
  
          if self.spatial_model is not None:
              value = value * self.spatial_model(lon, lat)  # pylint:disable=not-callable
  
          return value
  
      def evaluate_geom(self, geom):
          """Evaluate model on `~gammapy.maps.Geom`."""
          energy = geom.get_axis_by_name("energy").center[:, np.newaxis, np.newaxis]
          value = self.spectral_model(energy)
  
          if self.spatial_model is not None:
              value = value * self.spatial_model.evaluate_geom(geom.to_image())
  
          return value
  
      def copy(self, **kwargs):
          """Copy SkyModel"""
          if self.spatial_model is not None:
              spatial_model = self.spatial_model.copy()
          else:
              spatial_model = None
  
          kwargs.setdefault("spatial_model", spatial_model)
          kwargs.setdefault("spectral_model", self.spectral_model.copy())
          kwargs.setdefault("name", self.name + "-copy")
          return self.__class__(**kwargs)
  
      def to_dict(self):
          """Create dict for YAML serilisation"""
          data = {}
          data["name"] = self.name
          data["type"] = self.tag
          data["spectral"] = self.spectral_model.to_dict()
  
          if self.spatial_model is not None:
              data["spatial"] = self.spatial_model.to_dict()
  
          return data
  
      @classmethod
      def from_dict(cls, data):
          """Create SkyModel from dict"""
          from gammapy.modeling.models import SPATIAL_MODELS, SPECTRAL_MODELS
  
          model_class = SPECTRAL_MODELS.get_cls(data["spectral"]["type"])
          spectral_model = model_class.from_dict(data["spectral"])
  
          spatial_data = data.get("spatial")
  
          if spatial_data is not None:
              model_class = SPATIAL_MODELS.get_cls(spatial_data["type"])
              spatial_model = model_class.from_dict(spatial_data)
          else:
              spatial_model = None
  
          return cls(
              name=data["name"],
              spatial_model=spatial_model,
              spectral_model=spectral_model,
          )
  
  
  class SkyDiffuseCube(SkyModelBase):
      """Cube sky map template model (3D).
  
      This is for a 3D map with an energy axis.
      Use `~gammapy.modeling.models.TemplateSpatialModel` for 2D maps.
  
      Parameters
      ----------
      map : `~gammapy.maps.Map`
          Map template
      norm : float
          Norm parameter (multiplied with map values)
      tilt : float
          Additional tilt in the spectrum
      reference : `~astropy.units.Quantity`
          Reference energy of the tilt.
      meta : dict, optional
          Meta information, meta['filename'] will be used for serialization
      interp_kwargs : dict
          Interpolation keyword arguments passed to `gammapy.maps.Map.interp_by_coord`.
          Default arguments are {'interp': 'linear', 'fill_value': 0}.
      """
  
      tag = "SkyDiffuseCube"
      norm = Parameter("norm", 1)
      tilt = Parameter("tilt", 0, unit="", frozen=True)
      reference = Parameter("reference", "1 TeV", frozen=True)
  
      def __init__(
          self,
          map,
          norm=norm.quantity,
          tilt=tilt.quantity,
          reference=reference.quantity,
          meta=None,
          interp_kwargs=None,
          name="diffuse",
          filename=None,
      ):
          self.name = name
          axis = map.geom.get_axis_by_name("energy")
  
          if axis.node_type != "center":
              raise ValueError('Need a map with energy axis node_type="center"')
  
          self.map = map
          self.meta = {} if meta is None else meta
          self.filename = filename
  
          interp_kwargs = {} if interp_kwargs is None else interp_kwargs
          interp_kwargs.setdefault("interp", "linear")
          interp_kwargs.setdefault("fill_value", 0)
          self._interp_kwargs = interp_kwargs
  
          # TODO: onve we have implement a more general and better model caching
          #  remove this again
          self._cached_value = None
          self._cached_coordinates = (None, None, None)
  
          super().__init__(norm=norm, tilt=tilt, reference=reference)
  
      @classmethod
      def read(cls, filename, **kwargs):
          """Read map from FITS file.
  
          The default unit used if none is found in the file is ``cm-2 s-1 MeV-1 sr-1``.
  
          Parameters
          ----------
          filename : str
              FITS image filename.
          """
          m = Map.read(filename, **kwargs)
          if m.unit == "":
              m.unit = "cm-2 s-1 MeV-1 sr-1"
          name = Path(filename).stem
          return cls(m, name=name, filename=filename)
  
      def _interpolate(self, lon, lat, energy):
          coord = {
              "lon": lon.to_value("deg"),
              "lat": lat.to_value("deg"),
              "energy": energy,
          }
          return self.map.interp_by_coord(coord, **self._interp_kwargs)
  
      def evaluate(self, lon, lat, energy):
          """Evaluate model."""
          is_cached_coord = [
              _ is coord for _, coord in zip((lon, lat, energy), self._cached_coordinates)
          ]
  
          # reset cache
          if not np.all(is_cached_coord):
              self._cached_value = None
  
          if self._cached_value is None:
              self._cached_coordinates = (lon, lat, energy)
              self._cached_value = self._interpolate(lon, lat, energy)
  
          norm = self.parameters["norm"].value
  
          tilt = self.parameters["tilt"].value
          reference = self.parameters["reference"].quantity
          tilt_factor = np.power((energy / reference).to(""), -tilt)
  
          val = norm * self._cached_value * tilt_factor.value
          return u.Quantity(val, self.map.unit, copy=False)
  
      def copy(self):
          """A shallow copy"""
          return copy.copy(self)
  
      @property
      def position(self):
          """`~astropy.coordinates.SkyCoord`"""
          return self.map.geom.center_skydir
  
      @property
      def evaluation_radius(self):
          """`~astropy.coordinates.Angle`"""
          return np.max(self.map.geom.width) / 2.0
  
      @property
      def frame(self):
          return self.position.frame.name
  
      @classmethod
      def from_dict(cls, data):
          model = cls.read(data["filename"])
          model._update_from_dict(data)
          return model
  
      def to_dict(self):
          data = super().to_dict()
          data["name"] = self.name
          data["type"] = data.pop("type")
          data["filename"] = self.filename
  
          # Move parameters at the end
          data["parameters"] = data.pop("parameters")
          return data
  
  
  class BackgroundModel(Model):
      """Background model.
  
      Create a new map by a tilt and normalization on the available map
  
      Parameters
      ----------
      map : `~gammapy.maps.Map`
          Background model map
      norm : float
          Background normalization
      tilt : float
          Additional tilt in the spectrum
      reference : `~astropy.units.Quantity`
          Reference energy of the tilt.
      """
  
      tag = "BackgroundModel"
      norm = Parameter("norm", 1, unit="", min=0)
      tilt = Parameter("tilt", 0, unit="", frozen=True)
      reference = Parameter("reference", "1 TeV", frozen=True)
  
      def __init__(
          self,
          map,
          norm=norm.quantity,
          tilt=tilt.quantity,
          reference=reference.quantity,
          name="background",
          filename=None,
      ):
          axis = map.geom.get_axis_by_name("energy")
          if axis.node_type != "edges":
              raise ValueError('Need an integrated map, energy axis node_type="edges"')
  
          self.map = map
          self.name = name
          self.filename = filename
          super().__init__(norm=norm, tilt=tilt, reference=reference)
  
      @property
      def energy_center(self):
          """True energy axis bin centers (`~astropy.units.Quantity`)"""
          energy_axis = self.map.geom.get_axis_by_name("energy")
          energy = energy_axis.center
          return energy[:, np.newaxis, np.newaxis]
  
      def evaluate(self):
          """Evaluate background model.
  
          Returns
          -------
          background_map : `~gammapy.maps.Map`
              Background evaluated on the Map
          """
          norm = self.parameters["norm"].value
          tilt = self.parameters["tilt"].value
          reference = self.parameters["reference"].quantity
          tilt_factor = np.power((self.energy_center / reference).to(""), -tilt)
          back_values = norm * self.map.data * tilt_factor.value
          return self.map.copy(data=back_values)
  
      def to_dict(self):
          data = {}
          data["name"] = self.name
          data.update(super().to_dict())
          if self.filename is not None:
              data["filename"] = self.filename
          data["parameters"] = data.pop("parameters")
          return data
  
      @classmethod
      def from_dict(cls, data):
          if "filename" in data:
              map = Map.read(data["filename"])
          elif "map" in data:
              map = data["map"]
          else:
              raise ValueError("Requires either filename or `Map` object")
  
          model = cls(map=map, name=data["name"])
          model._update_from_dict(data)
          return model
  
  
  def create_fermi_isotropic_diffuse_model(filename, **kwargs):
      """Read Fermi isotropic diffuse model.
  
      See `LAT Background models <https://fermi.gsfc.nasa.gov/ssc/data/access/lat/BackgroundModels.html>`_
  
      Parameters
      ----------
      filename : str
          filename
      kwargs : dict
          Keyword arguments forwarded to `TemplateSpectralModel`
  
      Returns
      -------
      diffuse_model : `SkyModel`
          Fermi isotropic diffuse sky model.
      """
      from .spectral import TemplateSpectralModel
      from .spatial import ConstantSpatialModel
  
      vals = np.loadtxt(make_path(filename))
      energy = u.Quantity(vals[:, 0], "MeV", copy=False)
      values = u.Quantity(vals[:, 1], "MeV-1 s-1 cm-2", copy=False)
  
      spatial_model = ConstantSpatialModel()
      spectral_model = TemplateSpectralModel(energy=energy, values=values, **kwargs)
      return SkyModel(
          spatial_model=spatial_model,
          spectral_model=spectral_model,
          name="fermi-diffuse-iso",
      )
  
files: gammapy/modeling/models/cube.py
files: """Create example model YAML files programmatically.
  
  (some will be also written manually)
  """
  from pathlib import Path
  import numpy as np
  import astropy.units as u
  from gammapy.cube import MapDataset, MapDatasetMaker
  from gammapy.data import DataStore
  from gammapy.maps import MapAxis, WcsGeom
  from gammapy.modeling import Datasets
  from gammapy.modeling.models import (
      ExpCutoffPowerLawSpectralModel,
      GaussianSpatialModel,
      PointSpatialModel,
      PowerLawSpectralModel,
      SkyDiffuseCube,
      SkyModel,
      SkyModels,
  )
  
  DATA_PATH = Path("./")
  
  
  def make_example_2():
      spatial = GaussianSpatialModel(lon_0="0 deg", lat_0="0 deg", sigma="1 deg")
      model = SkyModel(PowerLawSpectralModel(), spatial)
      models = SkyModels([model])
      models.write(DATA_PATH / "example2.yaml")
  
  
  def make_datasets_example():
      # Define which data to use and print some information
  
      energy_axis = MapAxis.from_edges(
          np.logspace(-1.0, 1.0, 4), unit="TeV", name="energy", interp="log"
      )
      geom0 = WcsGeom.create(
          skydir=(0, 0),
          binsz=0.1,
          width=(1, 1),
          frame="galactic",
          proj="CAR",
          axes=[energy_axis],
      )
      geom1 = WcsGeom.create(
          skydir=(1, 0),
          binsz=0.1,
          width=(1, 1),
          frame="galactic",
          proj="CAR",
          axes=[energy_axis],
      )
      geoms = [geom0, geom1]
  
      sources_coords = [(0, 0), (0.9, 0.1)]
      names = ["gc", "g09"]
      models = []
  
      for idx, (lon, lat) in enumerate(sources_coords):
          spatial_model = PointSpatialModel(
              lon_0=lon * u.deg, lat_0=lat * u.deg, frame="galactic"
          )
          spectral_model = ExpCutoffPowerLawSpectralModel(
              index=2 * u.Unit(""),
              amplitude=3e-12 * u.Unit("cm-2 s-1 TeV-1"),
              reference=1.0 * u.TeV,
              lambda_=0.1 / u.TeV,
          )
          model_ecpl = SkyModel(
              spatial_model=spatial_model, spectral_model=spectral_model, name=names[idx]
          )
          models.append(model_ecpl)
  
      # test to link a spectral parameter
      params0 = models[0].spectral_model.parameters
      params1 = models[1].spectral_model.parameters
      params0.link("reference", params1["reference"])
      # update the sky model
      models[0].parameters.link("reference", params1["reference"])
  
      obs_ids = [110380, 111140, 111159]
      data_store = DataStore.from_dir("$GAMMAPY_DATA/cta-1dc/index/gps/")
  
      diffuse_model = SkyDiffuseCube.read(
          "$GAMMAPY_DATA/fermi_3fhl/gll_iem_v06_cutout.fits"
      )
  
      datasets_list = []
      for idx, geom in enumerate(geoms):
          observations = data_store.get_observations(obs_ids)
  
          stacked = MapDataset.create(geom=geom)
          stacked.background_model.name = "background_irf_" + names[idx]
  
          maker = MapDatasetMaker(offset_max=4.0 * u.deg)
  
          for obs in observations:
              dataset = maker.run(stacked, obs)
              stacked.stack(dataset)
  
          stacked.psf = stacked.psf.get_psf_kernel(
              position=geom.center_skydir, geom=geom, max_radius="0.3 deg"
          )
  
          stacked.name = names[idx]
          stacked.models = models[idx] + diffuse_model
          datasets_list.append(stacked)
  
      datasets = Datasets(datasets_list)
  
      dataset0 = datasets[0]
      print("dataset0")
      print("counts sum : ", dataset0.counts.data.sum())
      print("expo sum : ", dataset0.exposure.data.sum())
      print("bkg0 sum : ", dataset0.background_model.evaluate().data.sum())
  
      datasets.write("$GAMMAPY_DATA/tests/models", prefix="gc_example_", overwrite=True)
  
  
  if __name__ == "__main__":
      make_example_2()
      make_datasets_example()
  
files: gammapy/modeling/tests/data/make.py
files: """Create example model YAML files programmatically.
  
  (some will be also written manually)
  """
  from pathlib import Path
  import numpy as np
  import astropy.units as u
  from gammapy.cube import MapDataset, MapDatasetMaker
  from gammapy.data import DataStore
  from gammapy.maps import MapAxis, WcsGeom
  from gammapy.modeling import Datasets
  from gammapy.modeling.models import (
      ExpCutoffPowerLawSpectralModel,
      GaussianSpatialModel,
      PointSpatialModel,
      PowerLawSpectralModel,
      SkyDiffuseCube,
      SkyModel,
      SkyModels,
  )
  
  DATA_PATH = Path("./")
  
  
  def make_example_2():
      spatial = GaussianSpatialModel(lon_0="0 deg", lat_0="0 deg", sigma="1 deg")
      model = SkyModel(spatial, PowerLawSpectralModel())
      models = SkyModels([model])
      models.write(DATA_PATH / "example2.yaml")
  
  
  def make_datasets_example():
      # Define which data to use and print some information
  
      energy_axis = MapAxis.from_edges(
          np.logspace(-1.0, 1.0, 4), unit="TeV", name="energy", interp="log"
      )
      geom0 = WcsGeom.create(
          skydir=(0, 0),
          binsz=0.1,
          width=(1, 1),
          frame="galactic",
          proj="CAR",
          axes=[energy_axis],
      )
      geom1 = WcsGeom.create(
          skydir=(1, 0),
          binsz=0.1,
          width=(1, 1),
          frame="galactic",
          proj="CAR",
          axes=[energy_axis],
      )
      geoms = [geom0, geom1]
  
      sources_coords = [(0, 0), (0.9, 0.1)]
      names = ["gc", "g09"]
      models = []
  
      for idx, (lon, lat) in enumerate(sources_coords):
          spatial_model = PointSpatialModel(
              lon_0=lon * u.deg, lat_0=lat * u.deg, frame="galactic"
          )
          spectral_model = ExpCutoffPowerLawSpectralModel(
              index=2 * u.Unit(""),
              amplitude=3e-12 * u.Unit("cm-2 s-1 TeV-1"),
              reference=1.0 * u.TeV,
              lambda_=0.1 / u.TeV,
          )
          model_ecpl = SkyModel(
              spatial_model=spatial_model, spectral_model=spectral_model, name=names[idx]
          )
          models.append(model_ecpl)
  
      # test to link a spectral parameter
      params0 = models[0].spectral_model.parameters
      params1 = models[1].spectral_model.parameters
      params0.link("reference", params1["reference"])
      # update the sky model
      models[0].parameters.link("reference", params1["reference"])
  
      obs_ids = [110380, 111140, 111159]
      data_store = DataStore.from_dir("$GAMMAPY_DATA/cta-1dc/index/gps/")
  
      diffuse_model = SkyDiffuseCube.read(
          "$GAMMAPY_DATA/fermi_3fhl/gll_iem_v06_cutout.fits"
      )
  
      datasets_list = []
      for idx, geom in enumerate(geoms):
          observations = data_store.get_observations(obs_ids)
  
          stacked = MapDataset.create(geom=geom)
          stacked.background_model.name = "background_irf_" + names[idx]
  
          maker = MapDatasetMaker(offset_max=4.0 * u.deg)
  
          for obs in observations:
              dataset = maker.run(stacked, obs)
              stacked.stack(dataset)
  
          stacked.psf = stacked.psf.get_psf_kernel(
              position=geom.center_skydir, geom=geom, max_radius="0.3 deg"
          )
  
          stacked.name = names[idx]
          stacked.models = models[idx] + diffuse_model
          datasets_list.append(stacked)
  
      datasets = Datasets(datasets_list)
  
      dataset0 = datasets[0]
      print("dataset0")
      print("counts sum : ", dataset0.counts.data.sum())
      print("expo sum : ", dataset0.exposure.data.sum())
      print("bkg0 sum : ", dataset0.background_model.evaluate().data.sum())
  
      datasets.write("$GAMMAPY_DATA/tests/models", prefix="gc_example_", overwrite=True)
  
  
  if __name__ == "__main__":
      make_example_2()
      make_datasets_example()
  
files: gammapy/modeling/tests/data/make.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  from pathlib import Path
  import numpy as np
  from astropy import units as u
  from astropy.io import fits
  from astropy.table import Table
  from gammapy.data import GTI
  from gammapy.irf import EDispKernel, EffectiveAreaTable, IRFStacker
  from gammapy.modeling import Dataset, Parameters
  from gammapy.modeling.models import SkyModel, SkyModels
  from gammapy.stats import cash, significance_on_off, significance, wstat
  from gammapy.utils.fits import energy_axis_to_ebounds
  from gammapy.utils.random import get_random_state
  from gammapy.utils.scripts import make_name, make_path
  from .core import CountsSpectrum, SpectrumEvaluator
  
  __all__ = [
      "SpectrumDatasetOnOff",
      "SpectrumDataset",
      "plot_spectrum_datasets_off_regions",
  ]
  
  
  class SpectrumDataset(Dataset):
      """Spectrum dataset for likelihood fitting.
  
      The spectrum dataset bundles reduced counts data, with a spectral model,
      background model and instrument response function to compute the fit-statistic
      given the current model and data.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Fit model
      counts : `~gammapy.spectrum.CountsSpectrum`
          Counts spectrum
      livetime : `~astropy.units.Quantity`
          Livetime
      aeff : `~gammapy.irf.EffectiveAreaTable`
          Effective area
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      background : `~gammapy.spectrum.CountsSpectrum`
          Background to use for the fit.
      mask_safe : `~numpy.ndarray`
          Mask defining the safe data range.
      mask_fit : `~numpy.ndarray`
          Mask to apply to the likelihood for fitting.
      name : str
          Dataset name.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
  
      See Also
      --------
      SpectrumDatasetOnOff, FluxPointsDataset, gammapy.cube.MapDataset
      """
  
      stat_type = "cash"
      tag = "SpectrumDataset"
  
      def __init__(
          self,
          models=None,
          counts=None,
          livetime=None,
          aeff=None,
          edisp=None,
          background=None,
          mask_safe=None,
          mask_fit=None,
          name=None,
          gti=None,
      ):
  
          if mask_fit is not None and mask_fit.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.counts = counts
  
          if livetime is not None:
              livetime = u.Quantity(livetime)
  
          self.livetime = livetime
          self.mask_fit = mask_fit
          self.aeff = aeff
          self.edisp = edisp
          self.background = background
          self.models = models
          self.mask_safe = mask_safe
          self.gti = gti
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
  
      def __str__(self):
          str_ = self.__class__.__name__
          str_ += "\n\n"
  
          str_ += "\t{:32}: {} \n\n".format("Name", self.name)
  
          counts = np.nan
          if self.counts is not None:
              counts = np.sum(self.counts.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts", counts)
  
          npred = np.nan
          if self.models is not None:
              npred = np.sum(self.npred().data)
          str_ += "\t{:32}: {:.2f}\n".format("Total predicted counts", npred)
  
          counts_off = np.nan
          if getattr(self, "counts_off", None) is not None:
              counts_off = np.sum(self.counts_off.data)
              str_ += "\t{:32}: {:.2f}\n\n".format("Total off counts", counts_off)
  
          background = np.nan
          if getattr(self, "background", None) is not None:
              background = np.sum(self.background.data)
              str_ += "\t{:32}: {:.2f}\n\n".format("Total background counts", background)
  
          aeff_min, aeff_max, aeff_unit = np.nan, np.nan, ""
          if self.aeff is not None:
              aeff_min = np.min(self.aeff.data.data.value[self.aeff.data.data.value > 0])
              aeff_max = np.max(self.aeff.data.data.value)
              aeff_unit = self.aeff.data.data.unit
  
          str_ += "\t{:32}: {:.2e} {}\n".format("Effective area min", aeff_min, aeff_unit)
          str_ += "\t{:32}: {:.2e} {}\n\n".format(
              "Effective area max", aeff_max, aeff_unit
          )
  
          livetime = np.nan
          if self.livetime is not None:
              livetime = self.livetime
          str_ += "\t{:32}: {:.2e}\n\n".format("Livetime", livetime)
  
          # data section
          n_bins = 0
          if self.counts is not None:
              n_bins = self.counts.data.size
          str_ += "\t{:32}: {} \n".format("Number of total bins", n_bins)
  
          n_fit_bins = 0
          if self.mask is not None:
              n_fit_bins = np.sum(self.mask)
          str_ += "\t{:32}: {} \n\n".format("Number of fit bins", n_fit_bins)
  
          # likelihood section
          str_ += "\t{:32}: {}\n".format("Fit statistic type", self.stat_type)
  
          stat = np.nan
          if self.models is not None and self.counts is not None:
              stat = self.stat_sum()
          str_ += "\t{:32}: {:.2f}\n\n".format("Fit statistic value (-2 log(L))", stat)
  
          n_pars, n_free_pars = 0, 0
          if self.models is not None:
              n_pars = len(self.models.parameters)
              n_free_pars = len(self.parameters.free_parameters)
  
          str_ += "\t{:32}: {}\n".format("Number of parameters", n_pars)
          str_ += "\t{:32}: {}\n\n".format("Number of free parameters", n_free_pars)
  
          if self.models is not None:
              str_ += "\t{:32}: {}\n".format("Model type", self.models.__class__.__name__)
              info = str(self.models.parameters)
              lines = info.split("\n")
              for line in lines[2:-1]:
                  str_ += "\t" + line.replace(":", "\t:") + "\n"
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def models(self):
          """Models (`gammapy.modeling.models.SkyModels`)."""
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
          evaluators = []
          if self.models is not None:
              for model in self.models:
                  evaluator = SpectrumEvaluator(
                      model=model,
                      livetime=self.livetime,
                      aeff=self.aeff,
                      edisp=self.edisp,
                  )
                  evaluators.append(evaluator)
  
          self._evaluators = evaluators
  
      @property
      def mask_safe(self):
          if self._mask_safe is None:
              return np.ones(self.data_shape, bool)
          else:
              return self._mask_safe
  
      @mask_safe.setter
      def mask_safe(self, mask):
          self._mask_safe = mask
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          for component in self.models:
              parameters.append(component.spectral_model.parameters)
  
          return Parameters.from_stack(parameters)
  
      @property
      def _energy_axis(self):
          if self.counts is not None:
              e_axis = self.counts.energy
          elif self.edisp is not None:
              e_axis = self.edisp.data.axis("e_reco")
          elif self.aeff is not None:
              # assume e_reco = e_true
              e_axis = self.aeff.data.axis("energy")
          return e_axis
  
      @property
      def data_shape(self):
          """Shape of the counts data"""
          return (self._energy_axis.nbin,)
  
      def npred_sig(self):
          """Predicted counts from source model (`CountsSpectrum`)."""
          data = np.zeros(self.data_shape)
          npred = self._as_counts_spectrum(data)
  
          for evaluator in self._evaluators:
              npred += evaluator.compute_npred()
  
          return npred
  
      def npred(self):
          """Return npred map (model + background)"""
          npred = self.npred_sig()
  
          if self.background:
              npred += self.background
  
          return npred
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          return cash(n_on=self.counts.data, mu_on=self.npred().data)
  
      def _as_counts_spectrum(self, data):
          energy = self._energy_axis.edges
          return CountsSpectrum(data=data, energy_lo=energy[:-1], energy_hi=energy[1:])
  
      @property
      def excess(self):
          """Excess (counts - alpha * counts_off)"""
          excess = self.counts.data - self.background.data
          return self._as_counts_spectrum(excess)
  
      def fake(self, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced irfs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
              Defines random number generator initialisation.
              Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
          self.counts = npred
  
      @property
      def energy_range(self):
          """Energy range defined by the safe mask"""
          energy = self._energy_axis.edges
          e_min, e_max = energy[:-1], energy[1:]
  
          if self.mask_safe is not None:
              if self.mask_safe.any():
                  e_min = e_min[self.mask_safe]
                  e_max = e_max[self.mask_safe]
              else:
                  return None, None
  
          return u.Quantity([e_min.min(), e_max.max()])
  
      def plot_fit(self):
          """Plot counts and residuals in two panels.
  
          Calls ``plot_counts`` and ``plot_residuals``.
          """
          from matplotlib.gridspec import GridSpec
          import matplotlib.pyplot as plt
  
          gs = GridSpec(7, 1)
  
          ax_spectrum = plt.subplot(gs[:5, :])
          self.plot_counts(ax=ax_spectrum)
  
          ax_spectrum.set_xticks([])
  
          ax_residuals = plt.subplot(gs[5:, :])
          self.plot_residuals(ax=ax_residuals)
          return ax_spectrum, ax_residuals
  
      @property
      def _e_unit(self):
          return self.counts.energy.unit
  
      def plot_counts(self, ax=None):
          """Plot predicted and detected counts.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          self.npred_sig().plot(ax=ax, label="mu_src", energy_unit=self._e_unit)
          self.excess.plot(ax=ax, label="Excess", fmt=".", energy_unit=self._e_unit)
  
          e_min, e_max = self.energy_range
          kwargs = {"color": "black", "linestyle": "dashed"}
          ax.axvline(e_min.to_value(self._e_unit), label="fit range", **kwargs)
          ax.axvline(e_max.to_value(self._e_unit), **kwargs)
  
          ax.legend(numpoints=1)
          ax.set_title("")
          return ax
  
      def residuals(self, method="diff"):
          """Compute the spectral residuals.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - ``diff`` (default): data - model
                  - ``diff/model``: (data - model) / model
                  - ``diff/sqrt(model)``: (data - model) / sqrt(model)
  
          Returns
          -------
          residuals : `CountsSpectrum`
              Residual spectrum
          """
          residuals = self._compute_residuals(self.counts, self.npred(), method)
          return residuals
  
      def plot_residuals(self, method="diff", ax=None, **kwargs):
          """Plot residuals.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Normalization used to compute the residuals, see `SpectrumDataset.residuals()`
          **kwargs : dict
              Keywords passed to `CountsSpectrum.plot()`
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          residuals = self.residuals(method=method)
          label = self._residuals_labels[method]
  
          residuals.plot(
              ax=ax, ecolor="black", fmt="none", energy_unit=self._e_unit, **kwargs
          )
          ax.axhline(0, color="black", lw=0.5)
  
          ymax = 1.2 * np.nanmax(residuals.data)
          ax.set_ylim(-ymax, ymax)
  
          ax.set_xlabel(f"Energy [{self._e_unit}]")
          ax.set_ylabel(f"Residuals ({label})")
          return ax
  
      @classmethod
      def create(cls, e_reco, e_true=None, region=None, reference_time="2000-01-01"):
          """Creates empty spectrum dataset.
  
          Empty containers are created with the correct geometry.
          counts, background and aeff are zero and edisp is diagonal.
  
          The safe_mask is set to False in every bin.
  
          Parameters
          ----------
          e_reco : `~astropy.units.Quantity`
              edges of counts vector
          e_true : `~astropy.units.Quantity`
              edges of effective area table. If not set use reco energy values. Default : None
          region : `~regions.SkyRegion`
              Region to define the dataset for.
          reference_time : `~astropy.time.Time`
              reference time of the dataset, Default is "2000-01-01"
          """
          if e_true is None:
              e_true = e_reco
  
          counts = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          background = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          aeff = EffectiveAreaTable(
              e_true[:-1], e_true[1:], np.zeros(e_true[:-1].shape) * u.m ** 2
          )
          edisp = EDispKernel.from_diagonal_response(e_true, e_reco)
          mask_safe = np.zeros_like(counts.data, "bool")
          gti = GTI.create(u.Quantity([], "s"), u.Quantity([], "s"), reference_time)
          livetime = gti.time_sum
  
          return SpectrumDataset(
              counts=counts,
              aeff=aeff,
              edisp=edisp,
              mask_safe=mask_safe,
              background=background,
              livetime=livetime,
              gti=gti,
          )
  
      def stack(self, other):
          r"""Stack this dataset with another one.
  
          Safe mask is applied to compute the stacked counts vector.
          Counts outside each dataset safe mask are lost.
  
          Stacking is performed in-place.
  
          The stacking of 2 datasets is implemented as follows.
          Here, :math:`k` denotes a bin in reconstructed energy and :math:`j = {1,2}` is the dataset number
  
          The ``mask_safe`` of each dataset is defined as:
  
          .. math::
              \epsilon_{jk} =\left\{\begin{array}{cl} 1, &
              \mbox{if bin k is inside the energy thresholds}\\ 0, &
              \mbox{otherwise} \end{array}\right.
  
          Then the total ``counts`` and model background ``bkg`` are computed according to:
  
          .. math::
              \overline{\mathrm{n_{on}}}_k =  \mathrm{n_{on}}_{1k} \cdot \epsilon_{1k} +
               \mathrm{n_{on}}_{2k} \cdot \epsilon_{2k}
  
              \overline{bkg}_k = bkg_{1k} \cdot \epsilon_{1k} +
               bkg_{2k} \cdot \epsilon_{2k}
  
          The stacked ``safe_mask`` is then:
  
          .. math::
              \overline{\epsilon_k} = \epsilon_{1k} OR \epsilon_{2k}
  
          Please refer to the `~gammapy.irf.IRFStacker` for the description
          of how the IRFs are stacked.
  
          Parameters
          ----------
          other : `~gammapy.spectrum.SpectrumDataset`
              the dataset to stack to the current one
          """
          if not isinstance(other, SpectrumDataset):
              raise TypeError("Incompatible types for SpectrumDataset stacking")
  
          if self.counts is not None:
              self.counts.data[~self.mask_safe] = 0
              self.counts.data[other.mask_safe] += other.counts.data[other.mask_safe]
  
          if self.background is not None:
              self.background.data[~self.mask_safe] = 0
              self.background.data[other.mask_safe] += other.background.data[
                  other.mask_safe
              ]
  
          if self.aeff is not None:
              if self.livetime is None or other.livetime is None:
                  raise ValueError("IRF stacking requires livetime for both datasets.")
  
              irf_stacker = IRFStacker(
                  list_aeff=[self.aeff, other.aeff],
                  list_livetime=[self.livetime, other.livetime],
                  list_edisp=[self.edisp, other.edisp],
                  list_low_threshold=[self.energy_range[0], other.energy_range[0]],
                  list_high_threshold=[self.energy_range[1], other.energy_range[1]],
              )
              irf_stacker.stack_aeff()
              if self.edisp is not None:
                  irf_stacker.stack_edisp()
                  self.edisp = irf_stacker.stacked_edisp
              self.aeff = irf_stacker.stacked_aeff
  
          self.mask_safe = np.logical_or(self.mask_safe, other.mask_safe)
  
          if self.gti is not None:
              self.gti = self.gti.stack(other.gti).union()
  
          # TODO: for the moment, since dead time is not accounted for, livetime cannot be the sum of GTIs
          if self.livetime is not None:
              self.livetime += other.livetime
  
      def peek(self, figsize=(16, 4)):
          """Quick-look summary plots."""
          import matplotlib.pyplot as plt
  
          e_min, e_max = self.energy_range
  
          _, (ax1, ax2, ax3) = plt.subplots(nrows=1, ncols=3, figsize=figsize)
  
          ax1.set_title("Counts")
          energy_unit = "TeV"
  
          if isinstance(self, SpectrumDatasetOnOff) and self.counts_off is not None:
              self.background.plot_hist(
                  ax=ax1, label="alpha * N_off", color="darkblue", energy_unit=energy_unit
              )
          elif self.background is not None:
              self.background.plot_hist(
                  ax=ax1, label="background", color="darkblue", energy_unit=energy_unit
              )
  
          self.counts.plot_hist(
              ax=ax1,
              label="n_on",
              color="darkred",
              energy_unit=energy_unit,
              show_energy=(e_min, e_max),
          )
  
          ax1.set_xlim(
              0.7 * e_min.to_value(energy_unit), 1.3 * e_max.to_value(energy_unit)
          )
          ax1.legend(numpoints=1)
  
          ax2.set_title("Effective Area")
          e_unit = self.aeff.energy.unit
          self.aeff.plot(ax=ax2, show_energy=(e_min, e_max))
          ax2.set_xlim(0.7 * e_min.to_value(e_unit), 1.3 * e_max.to_value(e_unit))
  
          ax3.set_title("Energy Dispersion")
          if self.edisp is not None:
              self.edisp.plot_matrix(ax=ax3)
  
          # TODO: optimize layout
          plt.subplots_adjust(wspace=0.3)
  
      def info_dict(self, in_safe_energy_range=True):
          """Info dict with summary statistics, summed over energy
  
          Parameters
          ----------
          in_safe_energy_range : bool
              Whether to sum only in the safe energy range
  
          Returns
          -------
          info_dict : dict
              Dictionary with summary info.
          """
          info = dict()
          mask = self.mask_safe if in_safe_energy_range else slice(None)
  
          info["name"] = self.name
          info["livetime"] = self.livetime.copy()
  
          info["n_on"] = self.counts.data[mask].sum()
  
          info["background"] = self.background.data[mask].sum()
          info["excess"] = self.excess.data[mask].sum()
          info["significance"] = significance(
              self.counts.data[mask].sum(), self.background.data[mask].sum(),
          )
  
          info["background_rate"] = info["background"] / info["livetime"]
          info["gamma_rate"] = info["excess"] / info["livetime"]
          return info
  
  
  class SpectrumDatasetOnOff(SpectrumDataset):
      """Spectrum dataset for on-off likelihood fitting.
  
      The on-off spectrum dataset bundles reduced counts data, off counts data,
      with a spectral model, relative background efficiency and instrument
      response functions to compute the fit-statistic given the current model
      and data.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Fit model
      counts : `~gammapy.spectrum.CountsSpectrum`
          ON Counts spectrum
      counts_off : `~gammapy.spectrum.CountsSpectrum`
          OFF Counts spectrum
      livetime : `~astropy.units.Quantity`
          Livetime
      aeff : `~gammapy.irf.EffectiveAreaTable`
          Effective area
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      mask_safe : `~numpy.array`
          Mask defining the safe data range.
      mask_fit : `~numpy.array`
          Mask to apply to the likelihood for fitting.
      acceptance : `~numpy.array` or float
          Relative background efficiency in the on region.
      acceptance_off : `~numpy.array` or float
          Relative background efficiency in the off region.
      name : str
          Name of the dataset.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
  
      See Also
      --------
      SpectrumDataset, FluxPointsDataset, MapDataset
      """
  
      stat_type = "wstat"
      tag = "SpectrumDatasetOnOff"
  
      def __init__(
          self,
          models=None,
          counts=None,
          counts_off=None,
          livetime=None,
          aeff=None,
          edisp=None,
          mask_safe=None,
          mask_fit=None,
          acceptance=None,
          acceptance_off=None,
          name="",
          gti=None,
      ):
  
          self.counts = counts
          self.counts_off = counts_off
  
          if livetime is not None:
              livetime = u.Quantity(livetime)
  
          self.livetime = livetime
          self.mask_fit = mask_fit
          self.aeff = aeff
          self.edisp = edisp
          self.models = models
          self.mask_safe = mask_safe
  
          if np.isscalar(acceptance):
              acceptance = np.ones(self.data_shape) * acceptance
  
          if np.isscalar(acceptance_off):
              acceptance_off = np.ones(self.data_shape) * acceptance_off
  
          self.acceptance = acceptance
          self.acceptance_off = acceptance_off
          self.name = name
          self.gti = gti
  
      def __str__(self):
          str_ = super().__str__()
  
          acceptance = np.nan
          if self.acceptance is not None:
              acceptance = np.mean(self.acceptance)
  
          str_ += "\t{:32}: {}\n".format("Acceptance mean:", acceptance)
          return str_.expandtabs(tabsize=4)
  
      @property
      def background(self):
          """"""
          background = self.alpha * self.counts_off.data
          return self._as_counts_spectrum(background)
  
      @property
      def alpha(self):
          """Exposure ratio between signal and background regions"""
          return self.acceptance / self.acceptance_off
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          mu_sig = self.npred_sig().data
          on_stat_ = wstat(
              n_on=self.counts.data,
              n_off=self.counts_off.data,
              alpha=self.alpha,
              mu_sig=mu_sig,
          )
          return np.nan_to_num(on_stat_)
  
      def fake(self, background_model, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced irfs.
  
          This method overwrites the counts and off counts defined on the dataset object.
  
          Parameters
          ----------
          background_model : `~gammapy.spectrum.CountsSpectrum`
              BackgroundModel. In the future will be part of the SpectrumDataset Class.
              For the moment, a CountSpectrum.
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
              Defines random number generator initialisation.
              Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
  
          npred_sig = self.npred_sig()
          npred_sig.data = random_state.poisson(npred_sig.data)
  
          npred_bkg = background_model.copy()
          npred_bkg.data = random_state.poisson(npred_bkg.data)
  
          self.counts = npred_sig + npred_bkg
  
          npred_off = background_model / self.alpha
          npred_off.data = random_state.poisson(npred_off.data)
          self.counts_off = npred_off
  
      @classmethod
      def create(cls, e_reco, e_true=None, region=None, reference_time="2000-01-01"):
          """Create empty SpectrumDatasetOnOff.
  
          Empty containers are created with the correct geometry.
          counts, counts_off and aeff are zero and edisp is diagonal.
  
          The safe_mask is set to False in every bin.
  
          Parameters
          ----------
          e_reco : `~astropy.units.Quantity`
              edges of counts vector
          e_true : `~astropy.units.Quantity`
              edges of effective area table. If not set use reco energy values. Default : None
          region : `~regions.SkyRegion`
              Region to define the dataset for.
          reference_time : `~astropy.time.Time`
              reference time of the dataset, Default is "2000-01-01"
          """
          if e_true is None:
              e_true = e_reco
  
          counts = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          counts_off = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          aeff = EffectiveAreaTable(
              e_true[:-1], e_true[1:], np.zeros(e_true[:-1].shape) * u.m ** 2
          )
          edisp = EDispKernel.from_diagonal_response(e_true, e_reco)
          mask_safe = np.zeros_like(counts.data, "bool")
          gti = GTI.create(u.Quantity([], "s"), u.Quantity([], "s"), reference_time)
          livetime = gti.time_sum
          acceptance = np.ones_like(counts.data, int)
          acceptance_off = np.ones_like(counts.data, int)
  
          return SpectrumDatasetOnOff(
              counts=counts,
              counts_off=counts_off,
              aeff=aeff,
              edisp=edisp,
              mask_safe=mask_safe,
              acceptance=acceptance,
              acceptance_off=acceptance_off,
              livetime=livetime,
              gti=gti,
          )
  
      @classmethod
      def read(cls, filename):
          """Read from file
  
          For now, filename is assumed to the name of a PHA file where BKG file, ARF, and RMF names
          must be set in the PHA header and be present in the same folder
  
          Parameters
          ----------
          filename : str
              OGIP PHA file to read
          """
          raise NotImplementedError(
              "To read from an OGIP fits file use SpectrumDatasetOnOff.from_ogip_files."
          )
  
      def _is_stackable(self):
          """Check if the Dataset contains enough information to be stacked"""
          if (
              self.acceptance_off is None
              or self.acceptance is None
              or self.counts_off is None
          ):
              return False
          else:
              return True
  
      def stack(self, other):
          r"""Stack this dataset with another one.
  
          Safe mask is applied to compute the stacked counts vector.
          Counts outside each dataset safe mask are lost.
  
          Stacking is performed in-place.
  
          The stacking of 2 datasets is implemented as follows.
          Here, :math:`k`  denotes a bin in reconstructed energy and :math:`j = {1,2}` is the dataset number
  
          The ``mask_safe`` of each dataset is defined as:
  
          .. math::
              \epsilon_{jk} =\left\{\begin{array}{cl} 1, &
              \mbox{if k is inside the energy thresholds}\\ 0, &
              \mbox{otherwise} \end{array}\right.
  
          Then the total ``counts`` and ``counts_off`` are computed according to:
  
          .. math::
              \overline{\mathrm{n_{on}}}_k =  \mathrm{n_{on}}_{1k} \cdot \epsilon_{1k} +
              \mathrm{n_{on}}_{2k} \cdot \epsilon_{2k}
  
              \overline{\mathrm{n_{off}}}_k = \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} +
              \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}
  
          The stacked ``safe_mask`` is then:
  
          .. math::
              \overline{\epsilon_k} = \epsilon_{1k} OR \epsilon_{2k}
  
          In each energy bin :math:`k`, the count excess is computed taking into account the ON ``acceptance``,
          :math:`a_{on}_k` and the OFF one: ``acceptance_off``, :math:`a_{off}_k`. They define
          the :math:`\alpha_k=a_{on}_k/a_{off}_k` factors such that :math:`n_{ex}_k = n_{on}_k - \alpha_k n_{off}_k`.
          We define the stacked value of :math:`\overline{{a}_{on}}_k = 1` so that:
  
          .. math::
              \overline{{a}_{off}}_k = \frac{\overline{\mathrm {n_{off}}}}{\alpha_{1k} \cdot
              \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} + \alpha_{2k} \cdot \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}}
  
          Please refer to the `~gammapy.irf.IRFStacker` for the description
          of how the IRFs are stacked.
  
          Parameters
          ----------
          other : `~gammapy.spectrum.SpectrumDatasetOnOff`
              the dataset to stack to the current one
  
          Examples
          --------
          >>> from gammapy.spectrum import SpectrumDatasetOnOff
          >>> obs_ids = [23523, 23526, 23559, 23592]
          >>> datasets = []
          >>> for obs in obs_ids:
          >>>     filename = "$GAMMAPY_DATA/joint-crab/spectra/hess/pha_obs{}.fits"
          >>>     ds = SpectrumDatasetOnOff.from_ogip_files(filename.format(obs))
          >>>     datasets.append(ds)
          >>> stacked = datasets[0]
          >>> for ds in datasets[1:]:
          >>>     stacked.stack(ds)
          >>> print(stacked.livetime)
          6313.8116406202325 s
          """
          if not isinstance(other, SpectrumDatasetOnOff):
              raise TypeError("Incompatible types for SpectrumDatasetOnOff stacking")
  
          # We assume here that counts_off, acceptance and acceptance_off are well defined.
          if not self._is_stackable() or not other._is_stackable():
              raise ValueError("Cannot stack incomplete SpectrumDatsetOnOff.")
  
          total_off = np.zeros_like(self.counts_off.data, dtype=float)
          total_alpha = np.zeros_like(self.counts_off.data, dtype=float)
  
          total_off[self.mask_safe] += self.counts_off.data[self.mask_safe]
          total_off[other.mask_safe] += other.counts_off.data[other.mask_safe]
          total_alpha[self.mask_safe] += (self.alpha * self.counts_off)[self.mask_safe]
          total_alpha[other.mask_safe] += (other.alpha * other.counts_off)[
              other.mask_safe
          ]
  
          with np.errstate(divide="ignore", invalid="ignore"):
              acceptance_off = total_off / total_alpha
              average_alpha = total_alpha.sum() / total_off.sum()
  
          # For the bins where the stacked OFF counts equal 0, the alpha value is performed by weighting on the total
          # OFF counts of each run
          is_zero = total_off == 0
          acceptance_off[is_zero] = 1 / average_alpha
  
          self.acceptance = np.ones_like(self.counts_off.data, dtype=float)
          self.acceptance_off = acceptance_off
  
          if self.counts_off is not None:
              self.counts_off.data[~self.mask_safe] = 0
              self.counts_off.data[other.mask_safe] += other.counts_off.data[
                  other.mask_safe
              ]
  
          super().stack(other)
  
      def to_ogip_files(self, outdir=None, use_sherpa=False, overwrite=False):
          """Write OGIP files.
  
          If you want to use the written files with Sherpa you have to set the
          ``use_sherpa`` flag. Then all files will be written in units 'keV' and
          'cm2'.
  
          The naming scheme is fixed, with {name} the dataset name:
  
          * PHA file is named pha_obs{name}.fits
          * BKG file is named bkg_obs{name}.fits
          * ARF file is named arf_obs{name}.fits
          * RMF file is named rmf_obs{name}.fits
  
          Parameters
          ----------
          outdir : `pathlib.Path`
              output directory, default: pwd
          use_sherpa : bool, optional
              Write Sherpa compliant files, default: False
          overwrite : bool
              Overwrite existing files?
          """
          # TODO: refactor and reduce amount of code duplication
          outdir = Path.cwd() if outdir is None else make_path(outdir)
          outdir.mkdir(exist_ok=True, parents=True)
  
          phafile = f"pha_obs{self.name}.fits"
  
          bkgfile = phafile.replace("pha", "bkg")
          arffile = phafile.replace("pha", "arf")
          rmffile = phafile.replace("pha", "rmf")
  
          counts_table = self.counts.to_table()
          counts_table["QUALITY"] = np.logical_not(self.mask_safe)
          counts_table["BACKSCAL"] = self.acceptance
          counts_table["AREASCAL"] = np.ones(self.acceptance.size)
          meta = self._ogip_meta()
  
          meta["respfile"] = rmffile
          meta["backfile"] = bkgfile
          meta["ancrfile"] = arffile
          meta["hduclas2"] = "TOTAL"
          counts_table.meta = meta
  
          name = counts_table.meta["name"]
          hdu = fits.BinTableHDU(counts_table, name=name)
          hdulist = fits.HDUList([fits.PrimaryHDU(), hdu, self._ebounds_hdu(use_sherpa)])
  
          if self.gti is not None:
              hdu = fits.BinTableHDU(self.gti.table, name="GTI")
              hdulist.append(hdu)
  
          hdulist.writeto(outdir / phafile, overwrite=overwrite)
  
          self.aeff.write(outdir / arffile, overwrite=overwrite, use_sherpa=use_sherpa)
  
          if self.counts_off is not None:
              counts_off_table = self.counts_off.to_table()
              counts_off_table["QUALITY"] = np.logical_not(self.mask_safe)
              counts_off_table["BACKSCAL"] = self.acceptance_off
              counts_off_table["AREASCAL"] = np.ones(self.acceptance.size)
              meta = self._ogip_meta()
              meta["hduclas2"] = "BKG"
  
              counts_off_table.meta = meta
              name = counts_off_table.meta["name"]
              hdu = fits.BinTableHDU(counts_off_table, name=name)
              hdulist = fits.HDUList(
                  [fits.PrimaryHDU(), hdu, self._ebounds_hdu(use_sherpa)]
              )
              hdulist.writeto(outdir / bkgfile, overwrite=overwrite)
  
          if self.edisp is not None:
              self.edisp.write(
                  outdir / rmffile, overwrite=overwrite, use_sherpa=use_sherpa
              )
  
      def _ebounds_hdu(self, use_sherpa):
          energy = self.counts.energy.edges
  
          if use_sherpa:
              energy = energy.to("keV")
  
          return energy_axis_to_ebounds(energy)
  
      def _ogip_meta(self):
          """Meta info for the OGIP data format"""
          return {
              "name": "SPECTRUM",
              "hduclass": "OGIP",
              "hduclas1": "SPECTRUM",
              "corrscal": "",
              "chantype": "PHA",
              "detchans": self.counts.energy.nbin,
              "filter": "None",
              "corrfile": "",
              "poisserr": True,
              "hduclas3": "COUNT",
              "hduclas4": "TYPE:1",
              "lo_thres": self.energy_range[0].to_value("TeV"),
              "hi_thres": self.energy_range[1].to_value("TeV"),
              "exposure": self.livetime.to_value("s"),
              "obs_id": self.name,
          }
  
      @classmethod
      def from_ogip_files(cls, filename):
          """Read `~gammapy.spectrum.SpectrumDatasetOnOff` from OGIP files.
  
          BKG file, ARF, and RMF must be set in the PHA header and be present in
          the same folder.
  
          The naming scheme is fixed to the following scheme:
  
          * PHA file is named ``pha_obs{name}.fits``
          * BKG file is named ``bkg_obs{name}.fits``
          * ARF file is named ``arf_obs{name}.fits``
          * RMF file is named ``rmf_obs{name}.fits``
            with ``{name}`` the dataset name.
  
          Parameters
          ----------
          filename : str
              OGIP PHA file to read
          """
          filename = make_path(filename)
          dirname = filename.parent
  
          with fits.open(filename, memmap=False) as hdulist:
              data = _read_ogip_hdulist(hdulist)
  
          counts = CountsSpectrum(
              energy_hi=data["energy_hi"], energy_lo=data["energy_lo"], data=data["data"]
          )
  
          phafile = filename.name
  
          try:
              rmffile = phafile.replace("pha", "rmf")
              energy_dispersion = EDispKernel.read(dirname / rmffile)
          except OSError:
              # TODO : Add logger and echo warning
              energy_dispersion = None
  
          try:
              bkgfile = phafile.replace("pha", "bkg")
              with fits.open(dirname / bkgfile, memmap=False) as hdulist:
                  data_bkg = _read_ogip_hdulist(hdulist)
                  counts_off = CountsSpectrum(
                      energy_hi=data_bkg["energy_hi"],
                      energy_lo=data_bkg["energy_lo"],
                      data=data_bkg["data"],
                  )
  
                  acceptance_off = data_bkg["backscal"]
          except OSError:
              # TODO : Add logger and echo warning
              counts_off, acceptance_off = None, None
  
          arffile = phafile.replace("pha", "arf")
          aeff = EffectiveAreaTable.read(dirname / arffile)
  
          mask_safe = np.logical_not(data["quality"])
  
          return cls(
              counts=counts,
              aeff=aeff,
              counts_off=counts_off,
              edisp=energy_dispersion,
              livetime=data["livetime"],
              mask_safe=mask_safe,
              acceptance=data["backscal"],
              acceptance_off=acceptance_off,
              name=str(data["obs_id"]),
              gti=data["gti"],
          )
  
      def info_dict(self, in_safe_energy_range=True):
          """Info dict with summary statistics, summed over energy
  
          Parameters
          ----------
          in_safe_energy_range : bool
              Whether to sum only in the safe energy range
  
          Returns
          -------
          info_dict : dict
              Dictionary with summary info.
          """
          info = super().info_dict(in_safe_energy_range)
          mask = self.mask_safe if in_safe_energy_range else slice(None)
  
          # TODO: handle energy dependent a_on / a_off
          info["a_on"] = self.acceptance[0].copy()
  
          if self.counts_off is not None:
              info["n_off"] = self.counts_off.data[mask].sum()
              info["a_off"] = self.acceptance_off[0].copy()
          else:
              info["n_off"] = 0
              info["a_off"] = 1
  
          info["alpha"] = self.alpha[0].copy()
          info["significance"] = significance_on_off(
              self.counts.data[mask].sum(),
              self.counts_off.data[mask].sum(),
              self.alpha[0],
          )
  
          return info
  
      def to_dict(self, filename, *args, **kwargs):
          """Convert to dict for YAML serialization."""
          outdir = Path(filename).parent
          filename = str(outdir / f"pha_obs{self.name}.fits")
  
          if self.models is None:
              models = []
          else:
              models = [_.name for _ in self.models]
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "filename": filename,
          }
  
      def write(self, filename, overwrite):
          """Write spectrum dataset on off to file.
  
          Currently only the OGIP format is supported
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite existing file.
          """
          outdir = Path(filename).parent
          self.to_ogip_files(outdir=outdir, overwrite=overwrite)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create flux point dataset from dict.
  
          Parameters
          ----------
          data : dict
              Dict containing data to create dataset from.
          components : list of dict
              Not used.
          models : list of `SkyModel`
              List of model components.
  
          Returns
          -------
          dataset : `SpectrumDatasetOnOff`
              Spectrum dataset on off.
  
          """
          models = [model for model in models if model.name in data["models"]]
  
          # TODO: assumes that the model is a skymodel
          # so this will work only when this change will be effective
          filename = data["filename"]
  
          dataset = cls.from_ogip_files(filename=filename)
          dataset.mask_fit = None
          dataset.models = models
          return dataset
  
      @classmethod
      def from_spectrum_dataset(
          cls, dataset, acceptance, acceptance_off, counts_off=None
      ):
          """Create spectrum dataseton off from another dataset.
  
          Parameters
          ----------
          dataset : `SpectrumDataset`
              Spectrum dataset defining counts, edisp, aeff, livetime etc.
          acceptance : `~numpy.array` or float
              Relative background efficiency in the on region.
          acceptance_off : `~numpy.array` or float
              Relative background efficiency in the off region.
          counts_off : `~gammapy.spectrum.CountsSpectrum`
              Off counts spectrum . If the dataset provides a background model,
              and no off counts are defined. The off counts are deferred from
              counts_off / alpha.
  
          Returns
          -------
          dataset : `SpectrumDatasetOnOff`
              Spectrum dataset on off.
  
          """
          if counts_off is None and dataset.background is not None:
              alpha = acceptance / acceptance_off
              counts_off = dataset.background / alpha
  
          return cls(
              counts=dataset.counts,
              aeff=dataset.aeff,
              counts_off=counts_off,
              edisp=dataset.edisp,
              livetime=dataset.livetime,
              mask_safe=dataset.mask_safe,
              mask_fit=dataset.mask_fit,
              acceptance=acceptance,
              acceptance_off=acceptance_off,
              gti=dataset.gti,
              name=dataset.name,
          )
  
  
  def _read_ogip_hdulist(hdulist, hdu1="SPECTRUM", hdu2="EBOUNDS", hdu3="GTI"):
      """Create from `~astropy.io.fits.HDUList`."""
      counts_table = Table.read(hdulist[hdu1])
      ebounds = Table.read(hdulist[hdu2])
      emin = ebounds["E_MIN"].quantity
      emax = ebounds["E_MAX"].quantity
  
      if hdu3 in hdulist:
          gti = GTI(Table.read(hdulist[hdu3]))
      else:
          gti = None
  
      # Check if column are present in the header
      quality = None
      areascal = None
      backscal = None
  
      if "QUALITY" in counts_table.colnames:
          quality = counts_table["QUALITY"].data
      if "AREASCAL" in counts_table.colnames:
          areascal = counts_table["AREASCAL"].data
      if "BACKSCAL" in counts_table.colnames:
          backscal = counts_table["BACKSCAL"].data
  
      return dict(
          data=counts_table["COUNTS"],
          backscal=backscal,
          energy_lo=emin,
          energy_hi=emax,
          quality=quality,
          areascal=areascal,
          livetime=counts_table.meta["EXPOSURE"] * u.s,
          obs_id=counts_table.meta["OBS_ID"],
          is_bkg=False,
          gti=gti,
      )
  
  
  def plot_spectrum_datasets_off_regions(datasets, ax=None):
      """Plot spectrum datasets of regions.
  
      Parameters
      ----------
      datasets : list of `SpectrumDatasetOnOff`
          List of spectrum on-off datasets
      """
      import matplotlib.pyplot as plt
      import matplotlib.patches as mpatches
  
      ax = plt.gca() or ax
  
      color_cycle = plt.rcParams["axes.prop_cycle"]
      colors = color_cycle.by_key()["color"]
      handles = []
  
      for color, dataset in zip(colors, datasets):
          kwargs = {"edgecolor": color, "facecolor": "none"}
          dataset.counts_off.plot_region(ax=ax, **kwargs)
  
          # create proxy artist for the custom legend
          handle = mpatches.Patch(label=dataset.name, **kwargs)
          handles.append(handle)
  
      plt.legend(handles=handles)
  
files: gammapy/spectrum/dataset.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  from pathlib import Path
  import numpy as np
  from astropy import units as u
  from astropy.io import fits
  from astropy.table import Table
  from gammapy.data import GTI
  from gammapy.irf import EffectiveAreaTable, EDispKernel, IRFStacker
  from gammapy.modeling import Dataset, Parameters
  from gammapy.modeling.models import SkyModel, SkyModels
  from gammapy.stats import cash, significance_on_off, significance, wstat
  from gammapy.utils.fits import energy_axis_to_ebounds
  from gammapy.utils.random import get_random_state
  from gammapy.utils.scripts import make_path
  from .core import CountsSpectrum, SpectrumEvaluator
  
  __all__ = [
      "SpectrumDatasetOnOff",
      "SpectrumDataset",
      "plot_spectrum_datasets_off_regions",
  ]
  
  
  class SpectrumDataset(Dataset):
      """Spectrum dataset for likelihood fitting.
  
      The spectrum dataset bundles reduced counts data, with a spectral model,
      background model and instrument response function to compute the fit-statistic
      given the current model and data.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Fit model
      counts : `~gammapy.spectrum.CountsSpectrum`
          Counts spectrum
      livetime : `~astropy.units.Quantity`
          Livetime
      aeff : `~gammapy.irf.EffectiveAreaTable`
          Effective area
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      background : `~gammapy.spectrum.CountsSpectrum`
          Background to use for the fit.
      mask_safe : `~numpy.ndarray`
          Mask defining the safe data range.
      mask_fit : `~numpy.ndarray`
          Mask to apply to the likelihood for fitting.
      name : str
          Dataset name.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
  
      See Also
      --------
      SpectrumDatasetOnOff, FluxPointsDataset, gammapy.cube.MapDataset
      """
  
      stat_type = "cash"
      tag = "SpectrumDataset"
  
      def __init__(
          self,
          models=None,
          counts=None,
          livetime=None,
          aeff=None,
          edisp=None,
          background=None,
          mask_safe=None,
          mask_fit=None,
          name="",
          gti=None,
      ):
  
          if mask_fit is not None and mask_fit.dtype != np.dtype("bool"):
              raise ValueError("mask data must have dtype bool")
  
          self.counts = counts
  
          if livetime is not None:
              livetime = u.Quantity(livetime)
  
          self.livetime = livetime
          self.mask_fit = mask_fit
          self.aeff = aeff
          self.edisp = edisp
          self.background = background
          self.models = models
          self.mask_safe = mask_safe
          self.name = name
          self.gti = gti
  
      def __str__(self):
          str_ = self.__class__.__name__
          str_ += "\n\n"
  
          str_ += "\t{:32}: {} \n\n".format("Name", self.name)
  
          counts = np.nan
          if self.counts is not None:
              counts = np.sum(self.counts.data)
          str_ += "\t{:32}: {:.0f} \n".format("Total counts", counts)
  
          npred = np.nan
          if self.models is not None:
              npred = np.sum(self.npred().data)
          str_ += "\t{:32}: {:.2f}\n".format("Total predicted counts", npred)
  
          counts_off = np.nan
          if getattr(self, "counts_off", None) is not None:
              counts_off = np.sum(self.counts_off.data)
              str_ += "\t{:32}: {:.2f}\n\n".format("Total off counts", counts_off)
  
          background = np.nan
          if getattr(self, "background", None) is not None:
              background = np.sum(self.background.data)
              str_ += "\t{:32}: {:.2f}\n\n".format("Total background counts", background)
  
          aeff_min, aeff_max, aeff_unit = np.nan, np.nan, ""
          if self.aeff is not None:
              aeff_min = np.min(self.aeff.data.data.value[self.aeff.data.data.value > 0])
              aeff_max = np.max(self.aeff.data.data.value)
              aeff_unit = self.aeff.data.data.unit
  
          str_ += "\t{:32}: {:.2e} {}\n".format("Effective area min", aeff_min, aeff_unit)
          str_ += "\t{:32}: {:.2e} {}\n\n".format(
              "Effective area max", aeff_max, aeff_unit
          )
  
          livetime = np.nan
          if self.livetime is not None:
              livetime = self.livetime
          str_ += "\t{:32}: {:.2e}\n\n".format("Livetime", livetime)
  
          # data section
          n_bins = 0
          if self.counts is not None:
              n_bins = self.counts.data.size
          str_ += "\t{:32}: {} \n".format("Number of total bins", n_bins)
  
          n_fit_bins = 0
          if self.mask is not None:
              n_fit_bins = np.sum(self.mask)
          str_ += "\t{:32}: {} \n\n".format("Number of fit bins", n_fit_bins)
  
          # likelihood section
          str_ += "\t{:32}: {}\n".format("Fit statistic type", self.stat_type)
  
          stat = np.nan
          if self.models is not None and self.counts is not None:
              stat = self.stat_sum()
          str_ += "\t{:32}: {:.2f}\n\n".format("Fit statistic value (-2 log(L))", stat)
  
          n_pars, n_free_pars = 0, 0
          if self.models is not None:
              n_pars = len(self.models.parameters)
              n_free_pars = len(self.parameters.free_parameters)
  
          str_ += "\t{:32}: {}\n".format("Number of parameters", n_pars)
          str_ += "\t{:32}: {}\n\n".format("Number of free parameters", n_free_pars)
  
          if self.models is not None:
              str_ += "\t{:32}: {}\n".format("Model type", self.models.__class__.__name__)
              info = str(self.models.parameters)
              lines = info.split("\n")
              for line in lines[2:-1]:
                  str_ += "\t" + line.replace(":", "\t:") + "\n"
  
          return str_.expandtabs(tabsize=4)
  
      @property
      def models(self):
          """Models (`gammapy.modeling.models.SkyModels`)."""
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
          evaluators = []
          if self.models is not None:
              for model in self.models:
                  evaluator = SpectrumEvaluator(
                      model=model,
                      livetime=self.livetime,
                      aeff=self.aeff,
                      edisp=self.edisp,
                  )
                  evaluators.append(evaluator)
  
          self._evaluators = evaluators
  
      @property
      def mask_safe(self):
          if self._mask_safe is None:
              return np.ones(self.data_shape, bool)
          else:
              return self._mask_safe
  
      @mask_safe.setter
      def mask_safe(self, mask):
          self._mask_safe = mask
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          for component in self.models:
              parameters.append(component.spectral_model.parameters)
  
          return Parameters.from_stack(parameters)
  
      @property
      def _energy_axis(self):
          if self.counts is not None:
              e_axis = self.counts.energy
          elif self.edisp is not None:
              e_axis = self.edisp.data.axis("e_reco")
          elif self.aeff is not None:
              # assume e_reco = e_true
              e_axis = self.aeff.data.axis("energy")
          return e_axis
  
      @property
      def data_shape(self):
          """Shape of the counts data"""
          return (self._energy_axis.nbin,)
  
      def npred_sig(self):
          """Predicted counts from source model (`CountsSpectrum`)."""
          data = np.zeros(self.data_shape)
          npred = self._as_counts_spectrum(data)
  
          for evaluator in self._evaluators:
              npred += evaluator.compute_npred()
  
          return npred
  
      def npred(self):
          """Return npred map (model + background)"""
          npred = self.npred_sig()
  
          if self.background:
              npred += self.background
  
          return npred
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          return cash(n_on=self.counts.data, mu_on=self.npred().data)
  
      def _as_counts_spectrum(self, data):
          energy = self._energy_axis.edges
          return CountsSpectrum(data=data, energy_lo=energy[:-1], energy_hi=energy[1:])
  
      @property
      def excess(self):
          """Excess (counts - alpha * counts_off)"""
          excess = self.counts.data - self.background.data
          return self._as_counts_spectrum(excess)
  
      def fake(self, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced irfs.
  
          This method overwrites the counts defined on the dataset object.
  
          Parameters
          ----------
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
              Defines random number generator initialisation.
              Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
          npred = self.npred()
          npred.data = random_state.poisson(npred.data)
          self.counts = npred
  
      @property
      def energy_range(self):
          """Energy range defined by the safe mask"""
          energy = self._energy_axis.edges
          e_min, e_max = energy[:-1], energy[1:]
  
          if self.mask_safe is not None:
              if self.mask_safe.any():
                  e_min = e_min[self.mask_safe]
                  e_max = e_max[self.mask_safe]
              else:
                  return None, None
  
          return u.Quantity([e_min.min(), e_max.max()])
  
      def plot_fit(self):
          """Plot counts and residuals in two panels.
  
          Calls ``plot_counts`` and ``plot_residuals``.
          """
          from matplotlib.gridspec import GridSpec
          import matplotlib.pyplot as plt
  
          gs = GridSpec(7, 1)
  
          ax_spectrum = plt.subplot(gs[:5, :])
          self.plot_counts(ax=ax_spectrum)
  
          ax_spectrum.set_xticks([])
  
          ax_residuals = plt.subplot(gs[5:, :])
          self.plot_residuals(ax=ax_residuals)
          return ax_spectrum, ax_residuals
  
      @property
      def _e_unit(self):
          return self.counts.energy.unit
  
      def plot_counts(self, ax=None):
          """Plot predicted and detected counts.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          self.npred_sig().plot(ax=ax, label="mu_src", energy_unit=self._e_unit)
          self.excess.plot(ax=ax, label="Excess", fmt=".", energy_unit=self._e_unit)
  
          e_min, e_max = self.energy_range
          kwargs = {"color": "black", "linestyle": "dashed"}
          ax.axvline(e_min.to_value(self._e_unit), label="fit range", **kwargs)
          ax.axvline(e_max.to_value(self._e_unit), **kwargs)
  
          ax.legend(numpoints=1)
          ax.set_title("")
          return ax
  
      def residuals(self, method="diff"):
          """Compute the spectral residuals.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - ``diff`` (default): data - model
                  - ``diff/model``: (data - model) / model
                  - ``diff/sqrt(model)``: (data - model) / sqrt(model)
  
          Returns
          -------
          residuals : `CountsSpectrum`
              Residual spectrum
          """
          residuals = self._compute_residuals(self.counts, self.npred(), method)
          return residuals
  
      def plot_residuals(self, method="diff", ax=None, **kwargs):
          """Plot residuals.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Normalization used to compute the residuals, see `SpectrumDataset.residuals()`
          **kwargs : dict
              Keywords passed to `CountsSpectrum.plot()`
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          residuals = self.residuals(method=method)
          label = self._residuals_labels[method]
  
          residuals.plot(
              ax=ax, ecolor="black", fmt="none", energy_unit=self._e_unit, **kwargs
          )
          ax.axhline(0, color="black", lw=0.5)
  
          ymax = 1.2 * np.nanmax(residuals.data)
          ax.set_ylim(-ymax, ymax)
  
          ax.set_xlabel(f"Energy [{self._e_unit}]")
          ax.set_ylabel(f"Residuals ({label})")
          return ax
  
      @classmethod
      def create(cls, e_reco, e_true=None, region=None, reference_time="2000-01-01"):
          """Creates empty spectrum dataset.
  
          Empty containers are created with the correct geometry.
          counts, background and aeff are zero and edisp is diagonal.
  
          The safe_mask is set to False in every bin.
  
          Parameters
          ----------
          e_reco : `~astropy.units.Quantity`
              edges of counts vector
          e_true : `~astropy.units.Quantity`
              edges of effective area table. If not set use reco energy values. Default : None
          region : `~regions.SkyRegion`
              Region to define the dataset for.
          reference_time : `~astropy.time.Time`
              reference time of the dataset, Default is "2000-01-01"
          """
          if e_true is None:
              e_true = e_reco
  
          counts = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          background = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          aeff = EffectiveAreaTable(
              e_true[:-1], e_true[1:], np.zeros(e_true[:-1].shape) * u.m ** 2
          )
          edisp = EDispKernel.from_diagonal_response(e_true, e_reco)
          mask_safe = np.zeros_like(counts.data, "bool")
          gti = GTI.create(u.Quantity([], "s"), u.Quantity([], "s"), reference_time)
          livetime = gti.time_sum
  
          return SpectrumDataset(
              counts=counts,
              aeff=aeff,
              edisp=edisp,
              mask_safe=mask_safe,
              background=background,
              livetime=livetime,
              gti=gti,
          )
  
      def stack(self, other):
          r"""Stack this dataset with another one.
  
          Safe mask is applied to compute the stacked counts vector.
          Counts outside each dataset safe mask are lost.
  
          Stacking is performed in-place.
  
          The stacking of 2 datasets is implemented as follows.
          Here, :math:`k` denotes a bin in reconstructed energy and :math:`j = {1,2}` is the dataset number
  
          The ``mask_safe`` of each dataset is defined as:
  
          .. math::
              \epsilon_{jk} =\left\{\begin{array}{cl} 1, &
              \mbox{if bin k is inside the energy thresholds}\\ 0, &
              \mbox{otherwise} \end{array}\right.
  
          Then the total ``counts`` and model background ``bkg`` are computed according to:
  
          .. math::
              \overline{\mathrm{n_{on}}}_k =  \mathrm{n_{on}}_{1k} \cdot \epsilon_{1k} +
               \mathrm{n_{on}}_{2k} \cdot \epsilon_{2k}
  
              \overline{bkg}_k = bkg_{1k} \cdot \epsilon_{1k} +
               bkg_{2k} \cdot \epsilon_{2k}
  
          The stacked ``safe_mask`` is then:
  
          .. math::
              \overline{\epsilon_k} = \epsilon_{1k} OR \epsilon_{2k}
  
          Please refer to the `~gammapy.irf.IRFStacker` for the description
          of how the IRFs are stacked.
  
          Parameters
          ----------
          other : `~gammapy.spectrum.SpectrumDataset`
              the dataset to stack to the current one
          """
          if not isinstance(other, SpectrumDataset):
              raise TypeError("Incompatible types for SpectrumDataset stacking")
  
          if self.counts is not None:
              self.counts.data[~self.mask_safe] = 0
              self.counts.data[other.mask_safe] += other.counts.data[other.mask_safe]
  
          if self.background is not None:
              self.background.data[~self.mask_safe] = 0
              self.background.data[other.mask_safe] += other.background.data[
                  other.mask_safe
              ]
  
          if self.aeff is not None:
              if self.livetime is None or other.livetime is None:
                  raise ValueError("IRF stacking requires livetime for both datasets.")
  
              irf_stacker = IRFStacker(
                  list_aeff=[self.aeff, other.aeff],
                  list_livetime=[self.livetime, other.livetime],
                  list_edisp=[self.edisp, other.edisp],
                  list_low_threshold=[self.energy_range[0], other.energy_range[0]],
                  list_high_threshold=[self.energy_range[1], other.energy_range[1]],
              )
              irf_stacker.stack_aeff()
              if self.edisp is not None:
                  irf_stacker.stack_edisp()
                  self.edisp = irf_stacker.stacked_edisp
              self.aeff = irf_stacker.stacked_aeff
  
          self.mask_safe = np.logical_or(self.mask_safe, other.mask_safe)
  
          if self.gti is not None:
              self.gti = self.gti.stack(other.gti).union()
  
          # TODO: for the moment, since dead time is not accounted for, livetime cannot be the sum of GTIs
          if self.livetime is not None:
              self.livetime += other.livetime
  
      def peek(self, figsize=(16, 4)):
          """Quick-look summary plots."""
          import matplotlib.pyplot as plt
  
          e_min, e_max = self.energy_range
  
          _, (ax1, ax2, ax3) = plt.subplots(nrows=1, ncols=3, figsize=figsize)
  
          ax1.set_title("Counts")
          energy_unit = "TeV"
  
          if isinstance(self, SpectrumDatasetOnOff) and self.counts_off is not None:
              self.background.plot_hist(
                  ax=ax1, label="alpha * N_off", color="darkblue", energy_unit=energy_unit
              )
          elif self.background is not None:
              self.background.plot_hist(
                  ax=ax1, label="background", color="darkblue", energy_unit=energy_unit
              )
  
          self.counts.plot_hist(
              ax=ax1,
              label="n_on",
              color="darkred",
              energy_unit=energy_unit,
              show_energy=(e_min, e_max),
          )
  
          ax1.set_xlim(
              0.7 * e_min.to_value(energy_unit), 1.3 * e_max.to_value(energy_unit)
          )
          ax1.legend(numpoints=1)
  
          ax2.set_title("Effective Area")
          e_unit = self.aeff.energy.unit
          self.aeff.plot(ax=ax2, show_energy=(e_min, e_max))
          ax2.set_xlim(0.7 * e_min.to_value(e_unit), 1.3 * e_max.to_value(e_unit))
  
          ax3.set_title("Energy Dispersion")
          if self.edisp is not None:
              self.edisp.plot_matrix(ax=ax3)
  
          # TODO: optimize layout
          plt.subplots_adjust(wspace=0.3)
  
      def info_dict(self, in_safe_energy_range=True):
          """Info dict with summary statistics, summed over energy
  
          Parameters
          ----------
          in_safe_energy_range : bool
              Whether to sum only in the safe energy range
  
          Returns
          -------
          info_dict : dict
              Dictionary with summary info.
          """
          info = dict()
          mask = self.mask_safe if in_safe_energy_range else slice(None)
  
          info["name"] = self.name
          info["livetime"] = self.livetime.copy()
  
          info["n_on"] = self.counts.data[mask].sum()
  
          info["background"] = self.background.data[mask].sum()
          info["excess"] = self.excess.data[mask].sum()
          info["significance"] = significance(
              self.counts.data[mask].sum(), self.background.data[mask].sum(),
          )
  
          info["background_rate"] = info["background"] / info["livetime"]
          info["gamma_rate"] = info["excess"] / info["livetime"]
          return info
  
  
  class SpectrumDatasetOnOff(SpectrumDataset):
      """Spectrum dataset for on-off likelihood fitting.
  
      The on-off spectrum dataset bundles reduced counts data, off counts data,
      with a spectral model, relative background efficiency and instrument
      response functions to compute the fit-statistic given the current model
      and data.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Fit model
      counts : `~gammapy.spectrum.CountsSpectrum`
          ON Counts spectrum
      counts_off : `~gammapy.spectrum.CountsSpectrum`
          OFF Counts spectrum
      livetime : `~astropy.units.Quantity`
          Livetime
      aeff : `~gammapy.irf.EffectiveAreaTable`
          Effective area
      edisp : `~gammapy.irf.EDispKernel`
          Energy dispersion
      mask_safe : `~numpy.array`
          Mask defining the safe data range.
      mask_fit : `~numpy.array`
          Mask to apply to the likelihood for fitting.
      acceptance : `~numpy.array` or float
          Relative background efficiency in the on region.
      acceptance_off : `~numpy.array` or float
          Relative background efficiency in the off region.
      name : str
          Name of the dataset.
      gti : `~gammapy.data.GTI`
          GTI of the observation or union of GTI if it is a stacked observation
  
      See Also
      --------
      SpectrumDataset, FluxPointsDataset, MapDataset
      """
  
      stat_type = "wstat"
      tag = "SpectrumDatasetOnOff"
  
      def __init__(
          self,
          models=None,
          counts=None,
          counts_off=None,
          livetime=None,
          aeff=None,
          edisp=None,
          mask_safe=None,
          mask_fit=None,
          acceptance=None,
          acceptance_off=None,
          name="",
          gti=None,
      ):
  
          self.counts = counts
          self.counts_off = counts_off
  
          if livetime is not None:
              livetime = u.Quantity(livetime)
  
          self.livetime = livetime
          self.mask_fit = mask_fit
          self.aeff = aeff
          self.edisp = edisp
          self.models = models
          self.mask_safe = mask_safe
  
          if np.isscalar(acceptance):
              acceptance = np.ones(self.data_shape) * acceptance
  
          if np.isscalar(acceptance_off):
              acceptance_off = np.ones(self.data_shape) * acceptance_off
  
          self.acceptance = acceptance
          self.acceptance_off = acceptance_off
          self.name = name
          self.gti = gti
  
      def __str__(self):
          str_ = super().__str__()
  
          acceptance = np.nan
          if self.acceptance is not None:
              acceptance = np.mean(self.acceptance)
  
          str_ += "\t{:32}: {}\n".format("Acceptance mean:", acceptance)
          return str_.expandtabs(tabsize=4)
  
      @property
      def background(self):
          """"""
          background = self.alpha * self.counts_off.data
          return self._as_counts_spectrum(background)
  
      @property
      def alpha(self):
          """Exposure ratio between signal and background regions"""
          return self.acceptance / self.acceptance_off
  
      def stat_array(self):
          """Likelihood per bin given the current model parameters"""
          mu_sig = self.npred_sig().data
          on_stat_ = wstat(
              n_on=self.counts.data,
              n_off=self.counts_off.data,
              alpha=self.alpha,
              mu_sig=mu_sig,
          )
          return np.nan_to_num(on_stat_)
  
      def fake(self, background_model, random_state="random-seed"):
          """Simulate fake counts for the current model and reduced irfs.
  
          This method overwrites the counts and off counts defined on the dataset object.
  
          Parameters
          ----------
          background_model : `~gammapy.spectrum.CountsSpectrum`
              BackgroundModel. In the future will be part of the SpectrumDataset Class.
              For the moment, a CountSpectrum.
          random_state : {int, 'random-seed', 'global-rng', `~numpy.random.RandomState`}
              Defines random number generator initialisation.
              Passed to `~gammapy.utils.random.get_random_state`.
          """
          random_state = get_random_state(random_state)
  
          npred_sig = self.npred_sig()
          npred_sig.data = random_state.poisson(npred_sig.data)
  
          npred_bkg = background_model.copy()
          npred_bkg.data = random_state.poisson(npred_bkg.data)
  
          self.counts = npred_sig + npred_bkg
  
          npred_off = background_model / self.alpha
          npred_off.data = random_state.poisson(npred_off.data)
          self.counts_off = npred_off
  
      @classmethod
      def create(cls, e_reco, e_true=None, region=None, reference_time="2000-01-01"):
          """Create empty SpectrumDatasetOnOff.
  
          Empty containers are created with the correct geometry.
          counts, counts_off and aeff are zero and edisp is diagonal.
  
          The safe_mask is set to False in every bin.
  
          Parameters
          ----------
          e_reco : `~astropy.units.Quantity`
              edges of counts vector
          e_true : `~astropy.units.Quantity`
              edges of effective area table. If not set use reco energy values. Default : None
          region : `~regions.SkyRegion`
              Region to define the dataset for.
          reference_time : `~astropy.time.Time`
              reference time of the dataset, Default is "2000-01-01"
          """
          if e_true is None:
              e_true = e_reco
  
          counts = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          counts_off = CountsSpectrum(e_reco[:-1], e_reco[1:], region=region)
          aeff = EffectiveAreaTable(
              e_true[:-1], e_true[1:], np.zeros(e_true[:-1].shape) * u.m ** 2
          )
          edisp = EDispKernel.from_diagonal_response(e_true, e_reco)
          mask_safe = np.zeros_like(counts.data, "bool")
          gti = GTI.create(u.Quantity([], "s"), u.Quantity([], "s"), reference_time)
          livetime = gti.time_sum
          acceptance = np.ones_like(counts.data, int)
          acceptance_off = np.ones_like(counts.data, int)
  
          return SpectrumDatasetOnOff(
              counts=counts,
              counts_off=counts_off,
              aeff=aeff,
              edisp=edisp,
              mask_safe=mask_safe,
              acceptance=acceptance,
              acceptance_off=acceptance_off,
              livetime=livetime,
              gti=gti,
          )
  
      @classmethod
      def read(cls, filename):
          """Read from file
  
          For now, filename is assumed to the name of a PHA file where BKG file, ARF, and RMF names
          must be set in the PHA header and be present in the same folder
  
          Parameters
          ----------
          filename : str
              OGIP PHA file to read
          """
          raise NotImplementedError(
              "To read from an OGIP fits file use SpectrumDatasetOnOff.from_ogip_files."
          )
  
      def _is_stackable(self):
          """Check if the Dataset contains enough information to be stacked"""
          if (
              self.acceptance_off is None
              or self.acceptance is None
              or self.counts_off is None
          ):
              return False
          else:
              return True
  
      def stack(self, other):
          r"""Stack this dataset with another one.
  
          Safe mask is applied to compute the stacked counts vector.
          Counts outside each dataset safe mask are lost.
  
          Stacking is performed in-place.
  
          The stacking of 2 datasets is implemented as follows.
          Here, :math:`k`  denotes a bin in reconstructed energy and :math:`j = {1,2}` is the dataset number
  
          The ``mask_safe`` of each dataset is defined as:
  
          .. math::
              \epsilon_{jk} =\left\{\begin{array}{cl} 1, &
              \mbox{if k is inside the energy thresholds}\\ 0, &
              \mbox{otherwise} \end{array}\right.
  
          Then the total ``counts`` and ``counts_off`` are computed according to:
  
          .. math::
              \overline{\mathrm{n_{on}}}_k =  \mathrm{n_{on}}_{1k} \cdot \epsilon_{1k} +
              \mathrm{n_{on}}_{2k} \cdot \epsilon_{2k}
  
              \overline{\mathrm{n_{off}}}_k = \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} +
              \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}
  
          The stacked ``safe_mask`` is then:
  
          .. math::
              \overline{\epsilon_k} = \epsilon_{1k} OR \epsilon_{2k}
  
          In each energy bin :math:`k`, the count excess is computed taking into account the ON ``acceptance``,
          :math:`a_{on}_k` and the OFF one: ``acceptance_off``, :math:`a_{off}_k`. They define
          the :math:`\alpha_k=a_{on}_k/a_{off}_k` factors such that :math:`n_{ex}_k = n_{on}_k - \alpha_k n_{off}_k`.
          We define the stacked value of :math:`\overline{{a}_{on}}_k = 1` so that:
  
          .. math::
              \overline{{a}_{off}}_k = \frac{\overline{\mathrm {n_{off}}}}{\alpha_{1k} \cdot
              \mathrm{n_{off}}_{1k} \cdot \epsilon_{1k} + \alpha_{2k} \cdot \mathrm{n_{off}}_{2k} \cdot \epsilon_{2k}}
  
          Please refer to the `~gammapy.irf.IRFStacker` for the description
          of how the IRFs are stacked.
  
          Parameters
          ----------
          other : `~gammapy.spectrum.SpectrumDatasetOnOff`
              the dataset to stack to the current one
  
          Examples
          --------
          >>> from gammapy.spectrum import SpectrumDatasetOnOff
          >>> obs_ids = [23523, 23526, 23559, 23592]
          >>> datasets = []
          >>> for obs in obs_ids:
          >>>     filename = "$GAMMAPY_DATA/joint-crab/spectra/hess/pha_obs{}.fits"
          >>>     ds = SpectrumDatasetOnOff.from_ogip_files(filename.format(obs))
          >>>     datasets.append(ds)
          >>> stacked = datasets[0]
          >>> for ds in datasets[1:]:
          >>>     stacked.stack(ds)
          >>> print(stacked.livetime)
          6313.8116406202325 s
          """
          if not isinstance(other, SpectrumDatasetOnOff):
              raise TypeError("Incompatible types for SpectrumDatasetOnOff stacking")
  
          # We assume here that counts_off, acceptance and acceptance_off are well defined.
          if not self._is_stackable() or not other._is_stackable():
              raise ValueError("Cannot stack incomplete SpectrumDatsetOnOff.")
  
          total_off = np.zeros_like(self.counts_off.data, dtype=float)
          total_alpha = np.zeros_like(self.counts_off.data, dtype=float)
  
          total_off[self.mask_safe] += self.counts_off.data[self.mask_safe]
          total_off[other.mask_safe] += other.counts_off.data[other.mask_safe]
          total_alpha[self.mask_safe] += (self.alpha * self.counts_off)[self.mask_safe]
          total_alpha[other.mask_safe] += (other.alpha * other.counts_off)[
              other.mask_safe
          ]
  
          with np.errstate(divide="ignore", invalid="ignore"):
              acceptance_off = total_off / total_alpha
              average_alpha = total_alpha.sum() / total_off.sum()
  
          # For the bins where the stacked OFF counts equal 0, the alpha value is performed by weighting on the total
          # OFF counts of each run
          is_zero = total_off == 0
          acceptance_off[is_zero] = 1 / average_alpha
  
          self.acceptance = np.ones_like(self.counts_off.data, dtype=float)
          self.acceptance_off = acceptance_off
  
          if self.counts_off is not None:
              self.counts_off.data[~self.mask_safe] = 0
              self.counts_off.data[other.mask_safe] += other.counts_off.data[
                  other.mask_safe
              ]
  
          super().stack(other)
  
      def to_ogip_files(self, outdir=None, use_sherpa=False, overwrite=False):
          """Write OGIP files.
  
          If you want to use the written files with Sherpa you have to set the
          ``use_sherpa`` flag. Then all files will be written in units 'keV' and
          'cm2'.
  
          The naming scheme is fixed, with {name} the dataset name:
  
          * PHA file is named pha_obs{name}.fits
          * BKG file is named bkg_obs{name}.fits
          * ARF file is named arf_obs{name}.fits
          * RMF file is named rmf_obs{name}.fits
  
          Parameters
          ----------
          outdir : `pathlib.Path`
              output directory, default: pwd
          use_sherpa : bool, optional
              Write Sherpa compliant files, default: False
          overwrite : bool
              Overwrite existing files?
          """
          # TODO: refactor and reduce amount of code duplication
          outdir = Path.cwd() if outdir is None else make_path(outdir)
          outdir.mkdir(exist_ok=True, parents=True)
  
          phafile = f"pha_obs{self.name}.fits"
  
          bkgfile = phafile.replace("pha", "bkg")
          arffile = phafile.replace("pha", "arf")
          rmffile = phafile.replace("pha", "rmf")
  
          counts_table = self.counts.to_table()
          counts_table["QUALITY"] = np.logical_not(self.mask_safe)
          counts_table["BACKSCAL"] = self.acceptance
          counts_table["AREASCAL"] = np.ones(self.acceptance.size)
          meta = self._ogip_meta()
  
          meta["respfile"] = rmffile
          meta["backfile"] = bkgfile
          meta["ancrfile"] = arffile
          meta["hduclas2"] = "TOTAL"
          counts_table.meta = meta
  
          name = counts_table.meta["name"]
          hdu = fits.BinTableHDU(counts_table, name=name)
          hdulist = fits.HDUList([fits.PrimaryHDU(), hdu, self._ebounds_hdu(use_sherpa)])
  
          if self.gti is not None:
              hdu = fits.BinTableHDU(self.gti.table, name="GTI")
              hdulist.append(hdu)
  
          hdulist.writeto(outdir / phafile, overwrite=overwrite)
  
          self.aeff.write(outdir / arffile, overwrite=overwrite, use_sherpa=use_sherpa)
  
          if self.counts_off is not None:
              counts_off_table = self.counts_off.to_table()
              counts_off_table["QUALITY"] = np.logical_not(self.mask_safe)
              counts_off_table["BACKSCAL"] = self.acceptance_off
              counts_off_table["AREASCAL"] = np.ones(self.acceptance.size)
              meta = self._ogip_meta()
              meta["hduclas2"] = "BKG"
  
              counts_off_table.meta = meta
              name = counts_off_table.meta["name"]
              hdu = fits.BinTableHDU(counts_off_table, name=name)
              hdulist = fits.HDUList(
                  [fits.PrimaryHDU(), hdu, self._ebounds_hdu(use_sherpa)]
              )
              hdulist.writeto(outdir / bkgfile, overwrite=overwrite)
  
          if self.edisp is not None:
              self.edisp.write(
                  outdir / rmffile, overwrite=overwrite, use_sherpa=use_sherpa
              )
  
      def _ebounds_hdu(self, use_sherpa):
          energy = self.counts.energy.edges
  
          if use_sherpa:
              energy = energy.to("keV")
  
          return energy_axis_to_ebounds(energy)
  
      def _ogip_meta(self):
          """Meta info for the OGIP data format"""
          return {
              "name": "SPECTRUM",
              "hduclass": "OGIP",
              "hduclas1": "SPECTRUM",
              "corrscal": "",
              "chantype": "PHA",
              "detchans": self.counts.energy.nbin,
              "filter": "None",
              "corrfile": "",
              "poisserr": True,
              "hduclas3": "COUNT",
              "hduclas4": "TYPE:1",
              "lo_thres": self.energy_range[0].to_value("TeV"),
              "hi_thres": self.energy_range[1].to_value("TeV"),
              "exposure": self.livetime.to_value("s"),
              "obs_id": self.name,
          }
  
      @classmethod
      def from_ogip_files(cls, filename):
          """Read `~gammapy.spectrum.SpectrumDatasetOnOff` from OGIP files.
  
          BKG file, ARF, and RMF must be set in the PHA header and be present in
          the same folder.
  
          The naming scheme is fixed to the following scheme:
  
          * PHA file is named ``pha_obs{name}.fits``
          * BKG file is named ``bkg_obs{name}.fits``
          * ARF file is named ``arf_obs{name}.fits``
          * RMF file is named ``rmf_obs{name}.fits``
            with ``{name}`` the dataset name.
  
          Parameters
          ----------
          filename : str
              OGIP PHA file to read
          """
          filename = make_path(filename)
          dirname = filename.parent
  
          with fits.open(filename, memmap=False) as hdulist:
              data = _read_ogip_hdulist(hdulist)
  
          counts = CountsSpectrum(
              energy_hi=data["energy_hi"], energy_lo=data["energy_lo"], data=data["data"]
          )
  
          phafile = filename.name
  
          try:
              rmffile = phafile.replace("pha", "rmf")
              energy_dispersion = EDispKernel.read(dirname / rmffile)
          except OSError:
              # TODO : Add logger and echo warning
              energy_dispersion = None
  
          try:
              bkgfile = phafile.replace("pha", "bkg")
              with fits.open(dirname / bkgfile, memmap=False) as hdulist:
                  data_bkg = _read_ogip_hdulist(hdulist)
                  counts_off = CountsSpectrum(
                      energy_hi=data_bkg["energy_hi"],
                      energy_lo=data_bkg["energy_lo"],
                      data=data_bkg["data"],
                  )
  
                  acceptance_off = data_bkg["backscal"]
          except OSError:
              # TODO : Add logger and echo warning
              counts_off, acceptance_off = None, None
  
          arffile = phafile.replace("pha", "arf")
          aeff = EffectiveAreaTable.read(dirname / arffile)
  
          mask_safe = np.logical_not(data["quality"])
  
          return cls(
              counts=counts,
              aeff=aeff,
              counts_off=counts_off,
              edisp=energy_dispersion,
              livetime=data["livetime"],
              mask_safe=mask_safe,
              acceptance=data["backscal"],
              acceptance_off=acceptance_off,
              name=str(data["obs_id"]),
              gti=data["gti"],
          )
  
      def info_dict(self, in_safe_energy_range=True):
          """Info dict with summary statistics, summed over energy
  
          Parameters
          ----------
          in_safe_energy_range : bool
              Whether to sum only in the safe energy range
  
          Returns
          -------
          info_dict : dict
              Dictionary with summary info.
          """
          info = super().info_dict(in_safe_energy_range)
          mask = self.mask_safe if in_safe_energy_range else slice(None)
  
          # TODO: handle energy dependent a_on / a_off
          info["a_on"] = self.acceptance[0].copy()
  
          if self.counts_off is not None:
              info["n_off"] = self.counts_off.data[mask].sum()
              info["a_off"] = self.acceptance_off[0].copy()
          else:
              info["n_off"] = 0
              info["a_off"] = 1
  
          info["alpha"] = self.alpha[0].copy()
          info["significance"] = significance_on_off(
              self.counts.data[mask].sum(),
              self.counts_off.data[mask].sum(),
              self.alpha[0],
          )
  
          return info
  
      def to_dict(self, filename, *args, **kwargs):
          """Convert to dict for YAML serialization."""
          outdir = Path(filename).parent
          filename = str(outdir / f"pha_obs{self.name}.fits")
  
          if self.models is None:
              models = []
          else:
              models = [_.name for _ in self.models]
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "filename": filename,
          }
  
      def write(self, filename, overwrite):
          """Write spectrum dataset on off to file.
  
          Currently only the OGIP format is supported
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite existing file.
          """
          outdir = Path(filename).parent
          self.to_ogip_files(outdir=outdir, overwrite=overwrite)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create flux point dataset from dict.
  
          Parameters
          ----------
          data : dict
              Dict containing data to create dataset from.
          components : list of dict
              Not used.
          models : list of `SkyModel`
              List of model components.
  
          Returns
          -------
          dataset : `SpectrumDatasetOnOff`
              Spectrum dataset on off.
  
          """
          models = [model for model in models if model.name in data["models"]]
  
          # TODO: assumes that the model is a skymodel
          # so this will work only when this change will be effective
          filename = data["filename"]
  
          dataset = cls.from_ogip_files(filename=filename)
          dataset.mask_fit = None
          dataset.models = models
          return dataset
  
      @classmethod
      def from_spectrum_dataset(
          cls, dataset, acceptance, acceptance_off, counts_off=None
      ):
          """Create spectrum dataseton off from another dataset.
  
          Parameters
          ----------
          dataset : `SpectrumDataset`
              Spectrum dataset defining counts, edisp, aeff, livetime etc.
          acceptance : `~numpy.array` or float
              Relative background efficiency in the on region.
          acceptance_off : `~numpy.array` or float
              Relative background efficiency in the off region.
          counts_off : `~gammapy.spectrum.CountsSpectrum`
              Off counts spectrum . If the dataset provides a background model,
              and no off counts are defined. The off counts are deferred from
              counts_off / alpha.
  
          Returns
          -------
          dataset : `SpectrumDatasetOnOff`
              Spectrum dataset on off.
  
          """
          if counts_off is None and dataset.background is not None:
              alpha = acceptance / acceptance_off
              counts_off = dataset.background / alpha
  
          return cls(
              counts=dataset.counts,
              aeff=dataset.aeff,
              counts_off=counts_off,
              edisp=dataset.edisp,
              livetime=dataset.livetime,
              mask_safe=dataset.mask_safe,
              mask_fit=dataset.mask_fit,
              acceptance=acceptance,
              acceptance_off=acceptance_off,
              gti=dataset.gti,
              name=dataset.name,
          )
  
  
  def _read_ogip_hdulist(hdulist, hdu1="SPECTRUM", hdu2="EBOUNDS", hdu3="GTI"):
      """Create from `~astropy.io.fits.HDUList`."""
      counts_table = Table.read(hdulist[hdu1])
      ebounds = Table.read(hdulist[hdu2])
      emin = ebounds["E_MIN"].quantity
      emax = ebounds["E_MAX"].quantity
  
      if hdu3 in hdulist:
          gti = GTI(Table.read(hdulist[hdu3]))
      else:
          gti = None
  
      # Check if column are present in the header
      quality = None
      areascal = None
      backscal = None
  
      if "QUALITY" in counts_table.colnames:
          quality = counts_table["QUALITY"].data
      if "AREASCAL" in counts_table.colnames:
          areascal = counts_table["AREASCAL"].data
      if "BACKSCAL" in counts_table.colnames:
          backscal = counts_table["BACKSCAL"].data
  
      return dict(
          data=counts_table["COUNTS"],
          backscal=backscal,
          energy_lo=emin,
          energy_hi=emax,
          quality=quality,
          areascal=areascal,
          livetime=counts_table.meta["EXPOSURE"] * u.s,
          obs_id=counts_table.meta["OBS_ID"],
          is_bkg=False,
          gti=gti,
      )
  
  
  def plot_spectrum_datasets_off_regions(datasets, ax=None):
      """Plot spectrum datasets of regions.
  
      Parameters
      ----------
      datasets : list of `SpectrumDatasetOnOff`
          List of spectrum on-off datasets
      """
      import matplotlib.pyplot as plt
      import matplotlib.patches as mpatches
  
      ax = plt.gca() or ax
  
      color_cycle = plt.rcParams["axes.prop_cycle"]
      colors = color_cycle.by_key()["color"]
      handles = []
  
      for color, dataset in zip(colors, datasets):
          kwargs = {"edgecolor": color, "facecolor": "none"}
          dataset.counts_off.plot_region(ax=ax, **kwargs)
  
          # create proxy artist for the custom legend
          handle = mpatches.Patch(label=dataset.name, **kwargs)
          handles.append(handle)
  
      plt.legend(handles=handles)
  
files: gammapy/spectrum/dataset.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import logging
  import numpy as np
  from astropy import units as u
  from astropy.io.registry import IORegistryError
  from astropy.table import Table, vstack
  from gammapy.modeling import Dataset, Datasets, Fit, Parameters
  from gammapy.modeling.models import (
      PowerLawSpectralModel,
      ScaleSpectralModel,
      SkyModel,
      SkyModels,
  )
  from gammapy.utils.interpolation import interpolate_profile
  from gammapy.utils.scripts import make_name, make_path
  from gammapy.utils.table import table_from_row_data, table_standardise_units_copy
  from .dataset import SpectrumDatasetOnOff
  
  __all__ = ["FluxPoints", "FluxPointsEstimator", "FluxPointsDataset"]
  
  log = logging.getLogger(__name__)
  
  REQUIRED_COLUMNS = {
      "dnde": ["e_ref", "dnde"],
      "e2dnde": ["e_ref", "e2dnde"],
      "flux": ["e_min", "e_max", "flux"],
      "eflux": ["e_min", "e_max", "eflux"],
      # TODO: extend required columns
      "likelihood": [
          "e_min",
          "e_max",
          "e_ref",
          "ref_dnde",
          "norm",
          "norm_scan",
          "stat_scan",
      ],
  }
  
  OPTIONAL_COLUMNS = {
      "dnde": ["dnde_err", "dnde_errp", "dnde_errn", "dnde_ul", "is_ul"],
      "e2dnde": ["e2dnde_err", "e2dnde_errp", "e2dnde_errn", "e2dnde_ul", "is_ul"],
      "flux": ["flux_err", "flux_errp", "flux_errn", "flux_ul", "is_ul"],
      "eflux": ["eflux_err", "eflux_errp", "eflux_errn", "eflux_ul", "is_ul"],
  }
  
  DEFAULT_UNIT = {
      "dnde": u.Unit("cm-2 s-1 TeV-1"),
      "e2dnde": u.Unit("erg cm-2 s-1"),
      "flux": u.Unit("cm-2 s-1"),
      "eflux": u.Unit("erg cm-2 s-1"),
  }
  
  
  class FluxPoints:
      """Flux points container.
  
      The supported formats are described here: :ref:`gadf:flux-points`
  
      In summary, the following formats and minimum required columns are:
  
      * Format ``dnde``: columns ``e_ref`` and ``dnde``
      * Format ``e2dnde``: columns ``e_ref``, ``e2dnde``
      * Format ``flux``: columns ``e_min``, ``e_max``, ``flux``
      * Format ``eflux``: columns ``e_min``, ``e_max``, ``eflux``
  
      Parameters
      ----------
      table : `~astropy.table.Table`
          Table with flux point data
  
      Attributes
      ----------
      table : `~astropy.table.Table`
          Table with flux point data
  
      Examples
      --------
      The `FluxPoints` object is most easily created by reading a file with
      flux points given in one of the formats documented above::
  
          from gammapy.spectrum import FluxPoints
          filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          flux_points = FluxPoints.read(filename)
          flux_points.plot()
  
      An instance of `FluxPoints` can also be created by passing an instance of
      `astropy.table.Table`, which contains the required columns, such as `'e_ref'`
      and `'dnde'`. The corresponding `sed_type` has to be defined in the meta data
      of the table::
  
          from astropy import units as u
          from astropy.table import Table
          from gammapy.spectrum import FluxPoints
          from gammapy.modeling.models import PowerLawSpectralModel
  
          table = Table()
          pwl = PowerLawSpectralModel()
          e_ref = np.logspace(0, 2, 7) * u.TeV
          table['e_ref'] = e_ref
          table['dnde'] = pwl(e_ref)
          table.meta['SED_TYPE'] = 'dnde'
  
          flux_points = FluxPoints(table)
          flux_points.plot()
  
      If you have flux points in a different data format, the format can be changed
      by renaming the table columns and adding meta data::
  
  
          from astropy import units as u
          from astropy.table import Table
          from gammapy.spectrum import FluxPoints
  
          table = Table.read('$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points_ctb_37b.txt',
                             format='ascii.csv', delimiter=' ', comment='#')
          table.meta['SED_TYPE'] = 'dnde'
          table.rename_column('Differential_Flux', 'dnde')
          table['dnde'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('lower_error', 'dnde_errn')
          table['dnde_errn'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('upper_error', 'dnde_errp')
          table['dnde_errp'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('E', 'e_ref')
          table['e_ref'].unit = 'TeV'
  
          flux_points = FluxPoints(table)
          flux_points.plot()
  
      """
  
      def __init__(self, table):
          self.table = table_standardise_units_copy(table)
          # validate that the table is a valid representation
          # of the given flux point sed type
          self._validate_table(self.table, table.meta["SED_TYPE"])
  
      def __repr__(self):
          return f"{self.__class__.__name__}(sed_type={self.sed_type!r}, n_points={len(self.table)})"
  
      @property
      def table_formatted(self):
          """Return formatted version of the flux points table. Used for pretty printing"""
          table = self.table.copy()
  
          for column in table.colnames:
              if column.startswith(("dnde", "eflux", "flux", "e2dnde", "ref")):
                  table[column].format = ".3e"
              elif column.startswith(
                  ("e_min", "e_max", "e_ref", "sqrt_ts", "norm", "ts", "stat")
              ):
                  table[column].format = ".3f"
  
          return table
  
      @classmethod
      def read(cls, filename, **kwargs):
          """Read flux points.
  
          Parameters
          ----------
          filename : str
              Filename
          kwargs : dict
              Keyword arguments passed to `astropy.table.Table.read`.
          """
          filename = make_path(filename)
          try:
              table = Table.read(filename, **kwargs)
          except IORegistryError:
              kwargs.setdefault("format", "ascii.ecsv")
              table = Table.read(filename, **kwargs)
  
          if "SED_TYPE" not in table.meta.keys():
              sed_type = cls._guess_sed_type(table)
              table.meta["SED_TYPE"] = sed_type
  
          # TODO: check sign and factor 2 here
          # https://github.com/gammapy/gammapy/pull/2546#issuecomment-554274318
          # The idea below is to support the format here:
          # https://gamma-astro-data-formats.readthedocs.io/en/latest/spectra/flux_points/index.html#likelihood-columns
          # but internally to go to the uniform "stat"
  
          if "loglike" in table.colnames and "stat" not in table.colnames:
              table["stat"] = 2 * table["loglike"]
  
          if "loglike_null" in table.colnames and "stat_null" not in table.colnames:
              table["stat_null"] = 2 * table["loglike_null"]
  
          if "dloglike_scan" in table.colnames and "stat_scan" not in table.colnames:
              table["stat_scan"] = 2 * table["dloglike_scan"]
  
          return cls(table=table)
  
      def write(self, filename, **kwargs):
          """Write flux points.
  
          Parameters
          ----------
          filename : str
              Filename
          kwargs : dict
              Keyword arguments passed to `astropy.table.Table.write`.
          """
          filename = make_path(filename)
          try:
              self.table.write(filename, **kwargs)
          except IORegistryError:
              kwargs.setdefault("format", "ascii.ecsv")
              self.table.write(filename, **kwargs)
  
      @classmethod
      def stack(cls, flux_points):
          """Create flux points by stacking list of flux points.
  
          The first `FluxPoints` object in the list is taken as a reference to infer
          column names and units for the stacked object.
  
          Parameters
          ----------
          flux_points : list of `FluxPoints`
              List of flux points to stack.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points without upper limit points.
          """
          reference = flux_points[0].table
  
          tables = []
          for _ in flux_points:
              table = _.table
              for colname in reference.colnames:
                  column = reference[colname]
                  if column.unit:
                      table[colname] = table[colname].quantity.to(column.unit)
              tables.append(table[reference.colnames])
  
          table_stacked = vstack(tables)
          table_stacked.meta["SED_TYPE"] = reference.meta["SED_TYPE"]
  
          return cls(table_stacked)
  
      def drop_ul(self):
          """Drop upper limit flux points.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points with upper limit points removed.
  
          Examples
          --------
          >>> from gammapy.spectrum import FluxPoints
          >>> filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          >>> flux_points = FluxPoints.read(filename)
          >>> print(flux_points)
          FluxPoints(sed_type="flux", n_points=24)
          >>> print(flux_points.drop_ul())
          FluxPoints(sed_type="flux", n_points=19)
          """
          table_drop_ul = self.table[~self.is_ul]
          return self.__class__(table_drop_ul)
  
      def _flux_to_dnde(self, e_ref, table, model, pwl_approx):
          if model is None:
              model = PowerLawSpectralModel()
  
          e_min, e_max = self.e_min, self.e_max
  
          flux = table["flux"].quantity
          dnde = self._dnde_from_flux(flux, model, e_ref, e_min, e_max, pwl_approx)
  
          # Add to result table
          table["e_ref"] = e_ref
          table["dnde"] = dnde
  
          if "flux_err" in table.colnames:
              table["dnde_err"] = dnde * table["flux_err"].quantity / flux
  
          if "flux_errn" in table.colnames:
              table["dnde_errn"] = dnde * table["flux_errn"].quantity / flux
              table["dnde_errp"] = dnde * table["flux_errp"].quantity / flux
  
          if "flux_ul" in table.colnames:
              flux_ul = table["flux_ul"].quantity
              dnde_ul = self._dnde_from_flux(
                  flux_ul, model, e_ref, e_min, e_max, pwl_approx
              )
              table["dnde_ul"] = dnde_ul
  
          return table
  
      @staticmethod
      def _dnde_to_e2dnde(e_ref, table):
          for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
              try:
                  data = table["dnde" + suffix].quantity
                  table["e2dnde" + suffix] = (e_ref ** 2 * data).to(
                      DEFAULT_UNIT["e2dnde"]
                  )
              except KeyError:
                  continue
  
          return table
  
      @staticmethod
      def _e2dnde_to_dnde(e_ref, table):
          for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
              try:
                  data = table["e2dnde" + suffix].quantity
                  table["dnde" + suffix] = (data / e_ref ** 2).to(DEFAULT_UNIT["dnde"])
              except KeyError:
                  continue
  
          return table
  
      def to_sed_type(self, sed_type, method="log_center", model=None, pwl_approx=False):
          """Convert to a different SED type (return new `FluxPoints`).
  
          See: https://ui.adsabs.harvard.edu/abs/1995NIMPA.355..541L for details
          on the `'lafferty'` method.
  
          Parameters
          ----------
          sed_type : {'dnde'}
               SED type to convert to.
          model : `~gammapy.modeling.models.SpectralModel`
              Spectral model assumption.  Note that the value of the amplitude parameter
              does not matter. Still it is recommended to use something with the right
              scale and units. E.g. `amplitude = 1e-12 * u.Unit('cm-2 s-1 TeV-1')`
          method : {'lafferty', 'log_center', 'table'}
              Flux points `e_ref` estimation method:
  
                  * `'laferty'` Lafferty & Wyatt model-based e_ref
                  * `'log_center'` log bin center e_ref
                  * `'table'` using column 'e_ref' from input flux_points
          pwl_approx : bool
              Use local power law appoximation at e_ref to compute differential flux
              from the integral flux. This method is used by the Fermi-LAT catalogs.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points including differential quantity columns `dnde`
              and `dnde_err` (optional), `dnde_ul` (optional).
  
          Examples
          --------
          >>> from gammapy.spectrum import FluxPoints
          >>> from gammapy.modeling.models import PowerLawSpectralModel
          >>> filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          >>> flux_points = FluxPoints.read(filename)
          >>> model = PowerLawSpectralModel(index=2.2)
          >>> flux_points_dnde = flux_points.to_sed_type('dnde', model=model)
          """
          # TODO: implement other directions.
          table = self.table.copy()
  
          if self.sed_type == "flux" and sed_type == "dnde":
              # Compute e_ref
              if method == "table":
                  e_ref = table["e_ref"].quantity
              elif method == "log_center":
                  e_ref = np.sqrt(self.e_min * self.e_max)
              elif method == "lafferty":
                  # set e_ref that it represents the mean dnde in the given energy bin
                  e_ref = self._e_ref_lafferty(model, self.e_min, self.e_max)
              else:
                  raise ValueError(f"Invalid method: {method}")
              table = self._flux_to_dnde(e_ref, table, model, pwl_approx)
  
          elif self.sed_type == "dnde" and sed_type == "e2dnde":
              table = self._dnde_to_e2dnde(self.e_ref, table)
  
          elif self.sed_type == "e2dnde" and sed_type == "dnde":
              table = self._e2dnde_to_dnde(self.e_ref, table)
  
          elif self.sed_type == "likelihood" and sed_type in ["dnde", "flux", "eflux"]:
              for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
                  try:
                      table[sed_type + suffix] = (
                          table["ref_" + sed_type] * table["norm" + suffix]
                      )
                  except KeyError:
                      continue
          else:
              raise NotImplementedError
  
          table.meta["SED_TYPE"] = sed_type
          return FluxPoints(table)
  
      @staticmethod
      def _e_ref_lafferty(model, e_min, e_max):
          """Helper for `to_sed_type`.
  
          Compute e_ref that the value at e_ref corresponds
          to the mean value between e_min and e_max.
          """
          flux = model.integral(e_min, e_max)
          dnde_mean = flux / (e_max - e_min)
          return model.inverse(dnde_mean)
  
      @staticmethod
      def _dnde_from_flux(flux, model, e_ref, e_min, e_max, pwl_approx):
          """Helper for `to_sed_type`.
  
          Compute dnde under the assumption that flux equals expected
          flux from model.
          """
          dnde_model = model(e_ref)
  
          if pwl_approx:
              index = model.spectral_index(e_ref)
              flux_model = PowerLawSpectralModel.evaluate_integral(
                  emin=e_min,
                  emax=e_max,
                  index=index,
                  reference=e_ref,
                  amplitude=dnde_model,
              )
          else:
              flux_model = model.integral(e_min, e_max, intervals=True)
  
          return dnde_model * (flux / flux_model)
  
      @property
      def sed_type(self):
          """SED type (str).
  
          One of: {'dnde', 'e2dnde', 'flux', 'eflux'}
          """
          return self.table.meta["SED_TYPE"]
  
      @staticmethod
      def _guess_sed_type(table):
          """Guess SED type from table content."""
          valid_sed_types = list(REQUIRED_COLUMNS.keys())
          for sed_type in valid_sed_types:
              required = set(REQUIRED_COLUMNS[sed_type])
              if required.issubset(table.colnames):
                  return sed_type
  
      @staticmethod
      def _guess_sed_type_from_unit(unit):
          """Guess SED type from unit."""
          for sed_type, default_unit in DEFAULT_UNIT.items():
              if unit.is_equivalent(default_unit):
                  return sed_type
  
      @staticmethod
      def _validate_table(table, sed_type):
          """Validate input table."""
          required = set(REQUIRED_COLUMNS[sed_type])
  
          if not required.issubset(table.colnames):
              missing = required.difference(table.colnames)
              raise ValueError(
                  "Missing columns for sed type '{}':" " {}".format(sed_type, missing)
              )
  
      @staticmethod
      def _get_y_energy_unit(y_unit):
          """Get energy part of the given y unit."""
          try:
              return [_ for _ in y_unit.bases if _.physical_type == "energy"][0]
          except IndexError:
              return u.Unit("TeV")
  
      def _plot_get_energy_err(self):
          """Compute energy error for given sed type"""
          try:
              e_min = self.table["e_min"].quantity
              e_max = self.table["e_max"].quantity
              e_ref = self.e_ref
              x_err = ((e_ref - e_min), (e_max - e_ref))
          except KeyError:
              x_err = None
          return x_err
  
      def _plot_get_flux_err(self, sed_type=None):
          """Compute flux error for given sed type"""
          try:
              # asymmetric error
              y_errn = self.table[sed_type + "_errn"].quantity
              y_errp = self.table[sed_type + "_errp"].quantity
              y_err = (y_errn, y_errp)
          except KeyError:
              try:
                  # symmetric error
                  y_err = self.table[sed_type + "_err"].quantity
                  y_err = (y_err, y_err)
              except KeyError:
                  # no error at all
                  y_err = None
          return y_err
  
      @property
      def is_ul(self):
          try:
              return self.table["is_ul"].data.astype("bool")
          except KeyError:
              return np.isnan(self.table[self.sed_type])
  
      @property
      def e_ref(self):
          """Reference energy.
  
          Defined by `e_ref` column in `FluxPoints.table` or computed as log
          center, if `e_min` and `e_max` columns are present in `FluxPoints.table`.
  
          Returns
          -------
          e_ref : `~astropy.units.Quantity`
              Reference energy.
          """
          try:
              return self.table["e_ref"].quantity
          except KeyError:
              return np.sqrt(self.e_min * self.e_max)
  
      @property
      def e_edges(self):
          """Edges of the energy bin.
  
          Returns
          -------
          e_edges : `~astropy.units.Quantity`
              Energy edges.
          """
          e_edges = list(self.e_min)
          e_edges += [self.e_max[-1]]
          return u.Quantity(e_edges, self.e_min.unit, copy=False)
  
      @property
      def e_min(self):
          """Lower bound of energy bin.
  
          Defined by `e_min` column in `FluxPoints.table`.
  
          Returns
          -------
          e_min : `~astropy.units.Quantity`
              Lower bound of energy bin.
          """
          return self.table["e_min"].quantity
  
      @property
      def e_max(self):
          """Upper bound of energy bin.
  
          Defined by ``e_max`` column in ``table``.
  
          Returns
          -------
          e_max : `~astropy.units.Quantity`
              Upper bound of energy bin.
          """
          return self.table["e_max"].quantity
  
      def plot(
          self, ax=None, energy_unit="TeV", flux_unit=None, energy_power=0, **kwargs
      ):
          """Plot flux points.
  
          Parameters
          ----------
          ax : `~matplotlib.axes.Axes`
              Axis object to plot on.
          energy_unit : str, `~astropy.units.Unit`, optional
              Unit of the energy axis
          flux_unit : str, `~astropy.units.Unit`, optional
              Unit of the flux axis
          energy_power : int
              Power of energy to multiply y axis with
          kwargs : dict
              Keyword arguments passed to :func:`matplotlib.pyplot.errorbar`
  
          Returns
          -------
          ax : `~matplotlib.axes.Axes`
              Axis object
          """
          import matplotlib.pyplot as plt
  
          if ax is None:
              ax = plt.gca()
  
          sed_type = self.sed_type
          y_unit = u.Unit(flux_unit or DEFAULT_UNIT[sed_type])
  
          y = self.table[sed_type].quantity.to(y_unit)
          x = self.e_ref.to(energy_unit)
  
          # get errors and ul
          is_ul = self.is_ul
          x_err_all = self._plot_get_energy_err()
          y_err_all = self._plot_get_flux_err(sed_type)
  
          # handle energy power
          e_unit = self._get_y_energy_unit(y_unit)
          y_unit = y.unit * e_unit ** energy_power
          y = (y * np.power(x, energy_power)).to(y_unit)
  
          y_err, x_err = None, None
  
          if y_err_all:
              y_errn = (y_err_all[0] * np.power(x, energy_power)).to(y_unit)
              y_errp = (y_err_all[1] * np.power(x, energy_power)).to(y_unit)
              y_err = (y_errn[~is_ul].to_value(y_unit), y_errp[~is_ul].to_value(y_unit))
  
          if x_err_all:
              x_errn, x_errp = x_err_all
              x_err = (
                  x_errn[~is_ul].to_value(energy_unit),
                  x_errp[~is_ul].to_value(energy_unit),
              )
  
          # set flux points plotting defaults
          kwargs.setdefault("marker", "+")
          kwargs.setdefault("ls", "None")
  
          ebar = ax.errorbar(
              x[~is_ul].value, y[~is_ul].value, yerr=y_err, xerr=x_err, **kwargs
          )
  
          if is_ul.any():
              if x_err_all:
                  x_errn, x_errp = x_err_all
                  x_err = (
                      x_errn[is_ul].to_value(energy_unit),
                      x_errp[is_ul].to_value(energy_unit),
                  )
  
              y_ul = self.table[sed_type + "_ul"].quantity
              y_ul = (y_ul * np.power(x, energy_power)).to(y_unit)
  
              y_err = (0.5 * y_ul[is_ul].value, np.zeros_like(y_ul[is_ul].value))
  
              kwargs.setdefault("color", ebar[0].get_color())
  
              # pop label keyword to avoid that it appears twice in the legend
              kwargs.pop("label", None)
              ax.errorbar(
                  x[is_ul].value,
                  y_ul[is_ul].value,
                  xerr=x_err,
                  yerr=y_err,
                  uplims=True,
                  **kwargs,
              )
  
          ax.set_xscale("log", nonposx="clip")
          ax.set_yscale("log", nonposy="clip")
          ax.set_xlabel(f"Energy ({energy_unit})")
          ax.set_ylabel(f"{self.sed_type} ({y_unit})")
          return ax
  
      def plot_ts_profiles(
          self,
          ax=None,
          energy_unit="TeV",
          add_cbar=True,
          y_values=None,
          y_unit=None,
          **kwargs,
      ):
          """Plot fit statistic SED profiles as a density plot.
  
          Parameters
          ----------
          ax : `~matplotlib.axes.Axes`
              Axis object to plot on.
          energy_unit : str, `~astropy.units.Unit`, optional
              Unit of the energy axis
          y_values : `astropy.units.Quantity`
              Array of y-values to use for the fit statistic profile evaluation.
          y_unit : str or `astropy.units.Unit`
              Unit to use for the y-axis.
          add_cbar : bool
              Whether to add a colorbar to the plot.
          kwargs : dict
              Keyword arguments passed to :func:`matplotlib.pyplot.pcolormesh`
  
          Returns
          -------
          ax : `~matplotlib.axes.Axes`
              Axis object
          """
          import matplotlib.pyplot as plt
  
          if ax is None:
              ax = plt.gca()
  
          self._validate_table(self.table, "likelihood")
          y_unit = u.Unit(y_unit or DEFAULT_UNIT[self.sed_type])
  
          if y_values is None:
              ref_values = self.table["ref_" + self.sed_type].quantity
              y_values = np.logspace(
                  np.log10(0.2 * ref_values.value.min()),
                  np.log10(5 * ref_values.value.max()),
                  500,
              )
              y_values = u.Quantity(y_values, y_unit, copy=False)
  
          x = self.e_edges.to(energy_unit)
  
          # Compute fit statistic "image" one energy bin at a time
          # by interpolating e2dnde at the log bin centers
          z = np.empty((len(self.table), len(y_values)))
          for idx, row in enumerate(self.table):
              y_ref = self.table["ref_" + self.sed_type].quantity[idx]
              norm = (y_values / y_ref).to_value("")
              norm_scan = row["norm_scan"]
              ts_scan = row["stat_scan"] - row["stat"]
              interp = interpolate_profile(norm_scan, ts_scan)
              z[idx] = interp((norm,))
  
          kwargs.setdefault("vmax", 0)
          kwargs.setdefault("vmin", -4)
          kwargs.setdefault("zorder", 0)
          kwargs.setdefault("cmap", "Blues")
          kwargs.setdefault("linewidths", 0)
  
          # clipped values are set to NaN so that they appear white on the plot
          z[-z < kwargs["vmin"]] = np.nan
          caxes = ax.pcolormesh(x.value, y_values.value, -z.T, **kwargs)
          ax.set_xscale("log", nonposx="clip")
          ax.set_yscale("log", nonposy="clip")
          ax.set_xlabel(f"Energy ({energy_unit})")
          ax.set_ylabel(f"{self.sed_type} ({y_values.unit})")
  
          if add_cbar:
              label = "fit statistic difference"
              ax.figure.colorbar(caxes, ax=ax, label=label)
  
          return ax
  
  
  class FluxPointsEstimator:
      """Flux points estimator.
  
      Estimates flux points for a given list of spectral datasets, energies and
      spectral model.
  
      To estimate the flux point the amplitude of the reference spectral model is
      fitted within the energy range defined by the energy group. This is done for
      each group independently. The amplitude is re-normalized using the "norm" parameter,
      which specifies the deviation of the flux from the reference model in this
      energy group. See https://gamma-astro-data-formats.readthedocs.io/en/latest/spectra/binned_likelihoods/index.html
      for details.
  
      The method is also described in the Fermi-LAT catalog paper
      https://ui.adsabs.harvard.edu/#abs/2015ApJS..218...23A
      or the HESS Galactic Plane Survey paper
      https://ui.adsabs.harvard.edu/#abs/2018A%26A...612A...1H
  
      Parameters
      ----------
      datasets : list of `~gammapy.spectrum.SpectrumDataset`
          Spectrum datasets.
      e_edges : `~astropy.units.Quantity`
          Energy edges of the flux point bins.
      source : str
          For which source in the model to compute the flux points.
      norm_min : float
          Minimum value for the norm used for the fit statistic profile evaluation.
      norm_max : float
          Maximum value for the norm used for the fit statistic profile evaluation.
      norm_n_values : int
          Number of norm values used for the fit statistic profile.
      norm_values : `numpy.ndarray`
          Array of norm values to be used for the fit statistic profile.
      sigma : int
          Sigma to use for asymmetric error computation.
      sigma_ul : int
          Sigma to use for upper limit computation.
      reoptimize : bool
          Re-optimize other free model parameters.
      """
  
      def __init__(
          self,
          datasets,
          e_edges,
          source="",
          norm_min=0.2,
          norm_max=5,
          norm_n_values=11,
          norm_values=None,
          sigma=1,
          sigma_ul=2,
          reoptimize=False,
      ):
          # make a copy to not modify the input datasets
          if not isinstance(datasets, Datasets):
              datasets = Datasets(datasets)
  
          if not datasets.is_all_same_type and datasets.is_all_same_shape:
              raise ValueError(
                  "Flux point estimation requires a list of datasets"
                  " of the same type and data shape."
              )
  
          self.datasets = datasets.copy()
          self.e_edges = e_edges
  
          dataset = self.datasets[0]
  
          # TODO: this is complex and non-obvious behaviour. Simlify!
          if len(dataset.models) > 1:
              model = dataset.models[source].spectral_model
          else:
              model = dataset.models[0].spectral_model
  
          self.model = ScaleSpectralModel(model)
          self.model.norm.min = 0
          self.model.norm.max = 1e3
  
          if norm_values is None:
              norm_values = np.logspace(
                  np.log10(norm_min), np.log10(norm_max), norm_n_values
              )
  
          self.norm_values = norm_values
          self.sigma = sigma
          self.sigma_ul = sigma_ul
          self.reoptimize = reoptimize
          self.source = source
          self.fit = Fit(self.datasets)
  
          self._set_scale_model()
          self._contribute_to_stat = False
  
      def _freeze_parameters(self):
          # freeze other parameters
          for par in self.datasets.parameters:
              if par is not self.model.norm:
                  par.frozen = True
  
      def _freeze_empty_background(self):
          from gammapy.cube import MapDataset
  
          counts_all = self.estimate_counts()["counts"]
  
          for counts, dataset in zip(counts_all, self.datasets):
              if isinstance(dataset, MapDataset) and counts == 0:
                  if dataset.background_model is not None:
                      dataset.background_model.parameters.freeze_all()
  
      def _set_scale_model(self):
          # set the model on all datasets
          for dataset in self.datasets:
              if len(dataset.models) > 1:
                  dataset.models[self.source].spectral_model = self.model
              else:
                  dataset.models[0].spectral_model = self.model
  
      @property
      def ref_model(self):
          return self.model.model
  
      @property
      def e_groups(self):
          """Energy grouping table `~astropy.table.Table`"""
          dataset = self.datasets[0]
          if isinstance(dataset, SpectrumDatasetOnOff):
              energy_axis = dataset.counts.energy
          else:
              energy_axis = dataset.counts.geom.get_axis_by_name("energy")
          return energy_axis.group_table(self.e_edges)
  
      def __str__(self):
          s = f"{self.__class__.__name__}:\n"
          s += str(self.datasets) + "\n"
          s += str(self.e_edges) + "\n"
          s += str(self.model) + "\n"
          return s
  
      def run(self, steps="all"):
          """Run the flux point estimator for all energy groups.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Estimated flux points.
          steps : list of str
              Which steps to execute. See `estimate_flux_point` for details
              and available options.
          """
          rows = []
          for e_group in self.e_groups:
              if e_group["bin_type"].strip() != "normal":
                  log.debug("Skipping under-/ overflow bin in flux point estimation.")
                  continue
  
              row = self.estimate_flux_point(e_group, steps=steps)
              rows.append(row)
  
          table = table_from_row_data(rows=rows, meta={"SED_TYPE": "likelihood"})
          return FluxPoints(table).to_sed_type("dnde")
  
      def _energy_mask(self, e_group, dataset):
          energy_mask = np.zeros(dataset.data_shape)
          energy_mask[e_group["idx_min"] : e_group["idx_max"] + 1] = 1
          return energy_mask.astype(bool)
  
      def estimate_flux_point(self, e_group, steps="all"):
          """Estimate flux point for a single energy group.
  
          Parameters
          ----------
          e_group : `~astropy.table.Row`
              Energy group to compute the flux point for.
          steps : list of str
              Which steps to execute. Available options are:
  
                  * "err": estimate symmetric error.
                  * "errn-errp": estimate asymmetric errors.
                  * "ul": estimate upper limits.
                  * "ts": estimate ts and sqrt(ts) values.
                  * "norm-scan": estimate fit statistic profiles.
  
              By default all steps are executed.
  
          Returns
          -------
          result : dict
              Dict with results for the flux point.
          """
          e_min, e_max = e_group["energy_min"], e_group["energy_max"]
          # Put at log center of the bin
          e_ref = np.sqrt(e_min * e_max)
  
          result = {
              "e_ref": e_ref,
              "e_min": e_min,
              "e_max": e_max,
              "ref_dnde": self.ref_model(e_ref),
              "ref_flux": self.ref_model.integral(e_min, e_max),
              "ref_eflux": self.ref_model.energy_flux(e_min, e_max),
              "ref_e2dnde": self.ref_model(e_ref) * e_ref ** 2,
          }
  
          for dataset in self.datasets:
              dataset.mask_fit = self._energy_mask(e_group=e_group, dataset=dataset)
              mask = dataset.mask_fit
  
              if dataset.mask_safe is not None:
                  mask &= dataset.mask_safe
  
              self._contribute_to_stat |= mask.any()
  
          with self.datasets.parameters.restore_values:
  
              self._freeze_empty_background()
  
              if not self.reoptimize:
                  self._freeze_parameters()
  
              result.update(self.estimate_norm())
  
              if not result.pop("success"):
                  log.warning(
                      "Fit failed for flux point between {e_min:.3f} and {e_max:.3f},"
                      " setting NaN.".format(e_min=e_min, e_max=e_max)
                  )
  
              if steps == "all":
                  steps = ["err", "counts", "errp-errn", "ul", "ts", "norm-scan"]
  
              if "err" in steps:
                  result.update(self.estimate_norm_err())
  
              if "counts" in steps:
                  result.update(self.estimate_counts())
  
              if "errp-errn" in steps:
                  result.update(self.estimate_norm_errn_errp())
  
              if "ul" in steps:
                  result.update(self.estimate_norm_ul())
  
              if "ts" in steps:
                  result.update(self.estimate_norm_ts())
  
              if "norm-scan" in steps:
                  result.update(self.estimate_norm_scan())
  
          return result
  
      def estimate_norm_errn_errp(self):
          """Estimate asymmetric errors for a flux point.
  
          Returns
          -------
          result : dict
              Dict with asymmetric errors for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_errp": np.nan, "norm_errn": np.nan}
  
          result = self.fit.confidence(parameter=self.model.norm, sigma=self.sigma)
          return {"norm_errp": result["errp"], "norm_errn": result["errn"]}
  
      def estimate_norm_err(self):
          """Estimate covariance errors for a flux point.
  
          Returns
          -------
          result : dict
              Dict with symmetric error for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_err": np.nan}
  
          result = self.fit.covariance()
          norm_err = result.parameters.error(self.model.norm)
          return {"norm_err": norm_err}
  
      def estimate_counts(self):
          """Estimate counts for the flux point.
  
          Returns
          -------
          result : dict
              Dict with an array with one entry per dataset with counts for the flux point.
          """
          if not self._contribute_to_stat:
              return {"counts": np.zeros(len(self.datasets))}
  
          counts = []
          for dataset in self.datasets:
              mask = dataset.mask_fit
              if dataset.mask_safe is not None:
                  mask &= dataset.mask_safe
  
              counts.append(dataset.counts.data[mask].sum())
  
          return {"counts": np.array(counts, dtype=int)}
  
      def estimate_norm_ul(self):
          """Estimate upper limit for a flux point.
  
          Returns
          -------
          result : dict
              Dict with upper limit for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_ul": np.nan}
  
          norm = self.model.norm
  
          # TODO: the minuit backend has convergence problems when the fit statistic is not
          #  of parabolic shape, which is the case, when there are zero counts in the
          #  energy bin. For this case we change to the scipy backend.
          counts = self.estimate_counts()["counts"]
  
          if np.all(counts == 0):
              result = self.fit.confidence(
                  parameter=norm,
                  sigma=self.sigma_ul,
                  backend="scipy",
                  reoptimize=self.reoptimize,
              )
          else:
              result = self.fit.confidence(parameter=norm, sigma=self.sigma_ul)
  
          return {"norm_ul": result["errp"] + norm.value}
  
      def estimate_norm_ts(self):
          """Estimate ts and sqrt(ts) for the flux point.
  
          Returns
          -------
          result : dict
              Dict with ts and sqrt(ts) for the flux point.
          """
          if not self._contribute_to_stat:
              return {"sqrt_ts": np.nan, "ts": np.nan}
  
          stat = self.datasets.stat_sum()
  
          # store best fit amplitude, set amplitude of fit model to zero
          self.model.norm.value = 0
          self.model.norm.frozen = True
  
          if self.reoptimize:
              _ = self.fit.optimize()
  
          stat_null = self.datasets.stat_sum()
  
          # compute sqrt TS
          ts = np.abs(stat_null - stat)
          sqrt_ts = np.sqrt(ts)
          return {"sqrt_ts": sqrt_ts, "ts": ts}
  
      def estimate_norm_scan(self):
          """Estimate fit statistic profile for the norm parameter.
  
          Returns
          -------
          result : dict
              Keys: "norm_scan", "stat_scan"
          """
          if not self._contribute_to_stat:
              nans = np.nan * np.empty_like(self.norm_values)
              return {"norm_scan": nans, "stat_scan": nans}
  
          result = self.fit.stat_profile(
              self.model.norm, values=self.norm_values, reoptimize=self.reoptimize
          )
          return {"norm_scan": result["values"], "stat_scan": result["stat"]}
  
      def estimate_norm(self):
          """Fit norm of the flux point.
  
          Returns
          -------
          result : dict
              Dict with "norm" and "stat" for the flux point.
          """
          if not self._contribute_to_stat:
              return {"norm": np.nan, "stat": np.nan, "success": False}
  
          # start optimization with norm=1
          self.model.norm.value = 1.0
          self.model.norm.frozen = False
  
          result = self.fit.optimize()
  
          if result.success:
              norm = self.model.norm.value
          else:
              norm = np.nan
  
          return {"norm": norm, "stat": result.total_stat, "success": result.success}
  
  
  class FluxPointsDataset(Dataset):
      """
      Fit a set of flux points with a parametric model.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Models (only spectral part needs to be set)
      data : `~gammapy.spectrum.FluxPoints`
          Flux points.
      mask_fit : `numpy.ndarray`
          Mask to apply for fitting
      mask_safe : `numpy.ndarray`
          Mask defining the safe data range.
  
      Examples
      --------
      Load flux points from file and fit with a power-law model::
  
          from gammapy.modeling import Fit
          from gammapy.modeling.models import PowerLawSpectralModel, SkyModel
          from gammapy.spectrum import FluxPoints, FluxPointsDataset
  
          filename = "$GAMMAPY_DATA/tests/spectrum/flux_points/diff_flux_points.fits"
          flux_points = FluxPoints.read(filename)
  
          model = SkyModel(spectral_model=PowerLawSpectralModel())
  
          dataset = FluxPointsDataset(model, flux_points)
          fit = Fit([dataset])
          result = fit.run()
          print(result)
          print(result.parameters.to_table())
      """
  
      stat_type = "chi2"
      tag = "FluxPointsDataset"
  
      def __init__(self, models, data, mask_fit=None, mask_safe=None, name=None):
          self.data = data
          self.mask_fit = mask_fit
          self.models = models
  
          if name is None:
              self.name = make_name()
          else:
              self.name = name
  
          if data.sed_type != "dnde":
              raise ValueError("Currently only flux points of type 'dnde' are supported.")
  
          if mask_safe is None:
              mask_safe = np.isfinite(data.table["dnde"])
  
          self.mask_safe = mask_safe
  
      @property
      def models(self):
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          for component in self.models:
              parameters.append(component.spectral_model.parameters)
  
          return Parameters.from_stack(parameters)
  
      def write(self, filename, overwrite=True, **kwargs):
          """Write flux point dataset to file.
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite existing file.
          **kwargs : dict
               Keyword arguments passed to `~astropy.table.Table.write`.
          """
          table = self.data.table.copy()
          if self.mask_fit is None:
              mask_fit = self.mask_safe
          else:
              mask_fit = self.mask_fit
  
          table["mask_fit"] = mask_fit
          table["mask_safe"] = self.mask_safe
          table.write(filename, overwrite=overwrite, **kwargs)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create flux point dataset from dict.
  
          Parameters
          ----------
          data : dict
              Dict containing data to create dataset from.
          components : list of dict
              Not used.
          models : list of `SkyModel`
              List of model components.
  
          Returns
          -------
          dataset : `FluxPointsDataset`
              Flux point datasets.
          """
          models = [model for model in models if model.name in data["models"]]
          # TODO: assumes that the model is a skymodel
          # so this will work only when this change will be effective
          table = Table.read(data["filename"])
          mask_fit = table["mask_fit"].data.astype("bool")
          mask_safe = table["mask_safe"].data.astype("bool")
          table.remove_columns(["mask_fit", "mask_safe"])
          return cls(
              models=models,
              name=data["name"],
              data=FluxPoints(table),
              mask_fit=mask_fit,
              mask_safe=mask_safe,
          )
  
      def to_dict(self, filename=""):
          """Convert to dict for YAML serialization."""
          if self.models is not None:
              models = [_.name for _ in self.models]
          else:
              models = []
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "filename": str(filename),
          }
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}: \n"
          str_ += "\n"
          if self.models is None:
              str_ += "\t{:32}:   {} \n".format("Model Name", "No Model")
          else:
              str_ += "\t{:32}:   {} \n".format("Total flux points", len(self.data.table))
              str_ += "\t{:32}:   {} \n".format(
                  "Points used for the fit", self.mask.sum()
              )
              str_ += "\t{:32}:   {} \n".format(
                  "Excluded for safe energy range", (~self.mask_safe).sum()
              )
              if self.mask_fit is None:
                  str_ += "\t{:32}:   {} \n".format("Excluded by user", "0")
              else:
                  str_ += "\t{:32}:   {} \n".format(
                      "Excluded by user", (~self.mask_fit).sum()
                  )
              str_ += "\t{:32}:   {}\n".format(
                  "Model Name", self.models.__class__.__name__
              )
              str_ += "\t{:32}:   {}\n".format("N parameters", len(self.parameters))
              str_ += "\t{:32}:   {}\n".format(
                  "N free parameters", len(self.parameters.free_parameters)
              )
              str_ += "\tList of parameters\n"
              for par in self.parameters:
                  if par.frozen:
                      if par.name == "amplitude":
                          str_ += "\t \t {:14} (Frozen):   {:.2e} {} \n".format(
                              par.name, par.value, par.unit
                          )
                      else:
                          str_ += "\t \t {:14} (Frozen):   {:.2f} {} \n".format(
                              par.name, par.value, par.unit
                          )
                  else:
                      if par.name == "amplitude":
                          str_ += "\t \t {:23}:   {:.2e} {} \n".format(
                              par.name, par.value, par.unit
                          )
                      else:
                          str_ += "\t \t {:23}:   {:.2f} {} \n".format(
                              par.name, par.value, par.unit
                          )
              str_ += "\t{:32}:   {:.2f}\n".format("Likelihood value", self.stat_sum())
          return str_
  
      def data_shape(self):
          """Shape of the flux points data (tuple)."""
          return self.data.e_ref.shape
  
      def flux_pred(self):
          """Compute predicted flux."""
          flux = 0.0
          for component in self.models:
              flux += component.spectral_model(self.data.e_ref)
          return flux
  
      def stat_array(self):
          """Fit statistic array."""
          model = self.flux_pred()
          data = self.data.table["dnde"].quantity
          sigma = self.data.table["dnde_err"].quantity
          return ((data - model) / sigma).to_value("") ** 2
  
      def residuals(self, method="diff"):
          """Compute the flux point residuals ().
  
          Parameters
          ----------
          method: {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - `diff` (default): data - model
                  - `diff/model`: (data - model) / model
                  - `diff/sqrt(model)`: (data - model) / sqrt(model)
                  - `norm='sqrt_model'` for: (flux points - model)/sqrt(model)
  
  
          Returns
          -------
          residuals : `~numpy.ndarray`
              Residuals array.
          """
          fp = self.data
          data = fp.table[fp.sed_type]
  
          model = self.flux_pred()
  
          residuals = self._compute_residuals(data, model, method)
          # Remove residuals for upper_limits
          residuals[fp.is_ul] = np.nan
          return residuals
  
      def peek(self, method="diff/model", **kwargs):
          """Plot flux points, best fit model and residuals.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          """
          from matplotlib.gridspec import GridSpec
          import matplotlib.pyplot as plt
  
          gs = GridSpec(7, 1)
  
          ax_spectrum = plt.subplot(gs[:5, :])
          self.plot_spectrum(ax=ax_spectrum, **kwargs)
  
          ax_spectrum.set_xticks([])
  
          ax_residuals = plt.subplot(gs[5:, :])
          self.plot_residuals(ax=ax_residuals, method=method)
          return ax_spectrum, ax_residuals
  
      @property
      def _e_range(self):
          try:
              return u.Quantity([self.data.e_min.min(), self.data.e_max.max()])
          except KeyError:
              return u.Quantity([self.data.e_ref.min(), self.data.e_ref.max()])
  
      @property
      def _e_unit(self):
          return self.data.e_ref.unit
  
      def plot_residuals(self, ax=None, method="diff", **kwargs):
          """Plot flux point residuals.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          **kwargs : dict
              Keyword arguments passed to `~matplotlib.pyplot.errorbar`.
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          residuals = self.residuals(method=method)
  
          fp = self.data
  
          xerr = fp._plot_get_energy_err()
          if xerr is not None:
              xerr = xerr[0].to_value(self._e_unit), xerr[1].to_value(self._e_unit)
  
          model = self.flux_pred()
          yerr = fp._plot_get_flux_err(fp.sed_type)
  
          if method == "diff":
              unit = yerr[0].unit
              yerr = yerr[0].to_value(unit), yerr[1].to_value(unit)
          elif method == "diff/model":
              unit = ""
              yerr = (yerr[0] / model).to_value(""), (yerr[1] / model).to_value(unit)
          else:
              raise ValueError("Invalid method, choose between 'diff' and 'diff/model'")
  
          kwargs.setdefault("marker", "+")
          kwargs.setdefault("ls", "None")
          kwargs.setdefault("color", "black")
  
          ax.errorbar(
              self.data.e_ref.value, residuals.value, xerr=xerr, yerr=yerr, **kwargs
          )
  
          # format axes
          ax.axhline(0, color="black", lw=0.5)
          ax.set_ylabel("Residuals {}".format(unit.__str__()))
          ax.set_xlabel(f"Energy ({self._e_unit})")
          ax.set_xscale("log")
          ax.set_xlim(self._e_range.to_value(self._e_unit))
          y_max = 2 * np.nanmax(residuals).value
          ax.set_ylim(-y_max, y_max)
          return ax
  
      def plot_spectrum(self, ax=None, fp_kwargs=None, model_kwargs=None):
          """
          Plot spectrum including flux points and model.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          fp_kwargs : dict
              Keyword arguments passed to `FluxPoints.plot`.
          model_kwargs : dict
              Keywords passed to `SpectralModel.plot` and `SpectralModel.plot_error`
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
          fp_kwargs = {} if fp_kwargs is None else fp_kwargs
          model_kwargs = {} if model_kwargs is None else model_kwargs
  
          kwargs = {
              "flux_unit": "erg-1 cm-2 s-1",
              "energy_unit": "TeV",
              "energy_power": 2,
          }
  
          # plot flux points
          plot_kwargs = kwargs.copy()
          plot_kwargs.update(fp_kwargs)
          plot_kwargs.setdefault("label", "Flux points")
          ax = self.data.plot(ax=ax, **plot_kwargs)
  
          plot_kwargs = kwargs.copy()
          plot_kwargs.setdefault("energy_range", self._e_range)
          plot_kwargs.setdefault("zorder", 10)
          plot_kwargs.update(model_kwargs)
          plot_kwargs.setdefault("label", "Best fit model")
          for _ in self.models:
              _.spectral_model.plot(ax=ax, **plot_kwargs)
  
          plot_kwargs.setdefault("color", ax.lines[-1].get_color())
          del plot_kwargs["label"]
  
          if self.models.parameters.covariance is not None:
              try:
                  self.models.plot_error(ax=ax, **plot_kwargs)
              except AttributeError:
                  log.debug("Model does not support evaluation of errors")
  
          # format axes
          ax.set_xlim(self._e_range.to_value(self._e_unit))
          return ax
  
files: gammapy/spectrum/flux_point.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  import logging
  import numpy as np
  from astropy import units as u
  from astropy.io.registry import IORegistryError
  from astropy.table import Table, vstack
  from gammapy.modeling import Dataset, Datasets, Fit, Parameters
  from gammapy.modeling.models import (
      PowerLawSpectralModel,
      ScaleSpectralModel,
      SkyModel,
      SkyModels,
  )
  from gammapy.utils.interpolation import interpolate_profile
  from gammapy.utils.scripts import make_path
  from gammapy.utils.table import table_from_row_data, table_standardise_units_copy
  from .dataset import SpectrumDatasetOnOff
  
  __all__ = ["FluxPoints", "FluxPointsEstimator", "FluxPointsDataset"]
  
  log = logging.getLogger(__name__)
  
  REQUIRED_COLUMNS = {
      "dnde": ["e_ref", "dnde"],
      "e2dnde": ["e_ref", "e2dnde"],
      "flux": ["e_min", "e_max", "flux"],
      "eflux": ["e_min", "e_max", "eflux"],
      # TODO: extend required columns
      "likelihood": [
          "e_min",
          "e_max",
          "e_ref",
          "ref_dnde",
          "norm",
          "norm_scan",
          "stat_scan",
      ],
  }
  
  OPTIONAL_COLUMNS = {
      "dnde": ["dnde_err", "dnde_errp", "dnde_errn", "dnde_ul", "is_ul"],
      "e2dnde": ["e2dnde_err", "e2dnde_errp", "e2dnde_errn", "e2dnde_ul", "is_ul"],
      "flux": ["flux_err", "flux_errp", "flux_errn", "flux_ul", "is_ul"],
      "eflux": ["eflux_err", "eflux_errp", "eflux_errn", "eflux_ul", "is_ul"],
  }
  
  DEFAULT_UNIT = {
      "dnde": u.Unit("cm-2 s-1 TeV-1"),
      "e2dnde": u.Unit("erg cm-2 s-1"),
      "flux": u.Unit("cm-2 s-1"),
      "eflux": u.Unit("erg cm-2 s-1"),
  }
  
  
  class FluxPoints:
      """Flux points container.
  
      The supported formats are described here: :ref:`gadf:flux-points`
  
      In summary, the following formats and minimum required columns are:
  
      * Format ``dnde``: columns ``e_ref`` and ``dnde``
      * Format ``e2dnde``: columns ``e_ref``, ``e2dnde``
      * Format ``flux``: columns ``e_min``, ``e_max``, ``flux``
      * Format ``eflux``: columns ``e_min``, ``e_max``, ``eflux``
  
      Parameters
      ----------
      table : `~astropy.table.Table`
          Table with flux point data
  
      Attributes
      ----------
      table : `~astropy.table.Table`
          Table with flux point data
  
      Examples
      --------
      The `FluxPoints` object is most easily created by reading a file with
      flux points given in one of the formats documented above::
  
          from gammapy.spectrum import FluxPoints
          filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          flux_points = FluxPoints.read(filename)
          flux_points.plot()
  
      An instance of `FluxPoints` can also be created by passing an instance of
      `astropy.table.Table`, which contains the required columns, such as `'e_ref'`
      and `'dnde'`. The corresponding `sed_type` has to be defined in the meta data
      of the table::
  
          from astropy import units as u
          from astropy.table import Table
          from gammapy.spectrum import FluxPoints
          from gammapy.modeling.models import PowerLawSpectralModel
  
          table = Table()
          pwl = PowerLawSpectralModel()
          e_ref = np.logspace(0, 2, 7) * u.TeV
          table['e_ref'] = e_ref
          table['dnde'] = pwl(e_ref)
          table.meta['SED_TYPE'] = 'dnde'
  
          flux_points = FluxPoints(table)
          flux_points.plot()
  
      If you have flux points in a different data format, the format can be changed
      by renaming the table columns and adding meta data::
  
  
          from astropy import units as u
          from astropy.table import Table
          from gammapy.spectrum import FluxPoints
  
          table = Table.read('$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points_ctb_37b.txt',
                             format='ascii.csv', delimiter=' ', comment='#')
          table.meta['SED_TYPE'] = 'dnde'
          table.rename_column('Differential_Flux', 'dnde')
          table['dnde'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('lower_error', 'dnde_errn')
          table['dnde_errn'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('upper_error', 'dnde_errp')
          table['dnde_errp'].unit = 'cm-2 s-1 TeV-1'
  
          table.rename_column('E', 'e_ref')
          table['e_ref'].unit = 'TeV'
  
          flux_points = FluxPoints(table)
          flux_points.plot()
  
      """
  
      def __init__(self, table):
          self.table = table_standardise_units_copy(table)
          # validate that the table is a valid representation
          # of the given flux point sed type
          self._validate_table(self.table, table.meta["SED_TYPE"])
  
      def __repr__(self):
          return f"{self.__class__.__name__}(sed_type={self.sed_type!r}, n_points={len(self.table)})"
  
      @property
      def table_formatted(self):
          """Return formatted version of the flux points table. Used for pretty printing"""
          table = self.table.copy()
  
          for column in table.colnames:
              if column.startswith(("dnde", "eflux", "flux", "e2dnde", "ref")):
                  table[column].format = ".3e"
              elif column.startswith(
                  ("e_min", "e_max", "e_ref", "sqrt_ts", "norm", "ts", "stat")
              ):
                  table[column].format = ".3f"
  
          return table
  
      @classmethod
      def read(cls, filename, **kwargs):
          """Read flux points.
  
          Parameters
          ----------
          filename : str
              Filename
          kwargs : dict
              Keyword arguments passed to `astropy.table.Table.read`.
          """
          filename = make_path(filename)
          try:
              table = Table.read(filename, **kwargs)
          except IORegistryError:
              kwargs.setdefault("format", "ascii.ecsv")
              table = Table.read(filename, **kwargs)
  
          if "SED_TYPE" not in table.meta.keys():
              sed_type = cls._guess_sed_type(table)
              table.meta["SED_TYPE"] = sed_type
  
          # TODO: check sign and factor 2 here
          # https://github.com/gammapy/gammapy/pull/2546#issuecomment-554274318
          # The idea below is to support the format here:
          # https://gamma-astro-data-formats.readthedocs.io/en/latest/spectra/flux_points/index.html#likelihood-columns
          # but internally to go to the uniform "stat"
  
          if "loglike" in table.colnames and "stat" not in table.colnames:
              table["stat"] = 2 * table["loglike"]
  
          if "loglike_null" in table.colnames and "stat_null" not in table.colnames:
              table["stat_null"] = 2 * table["loglike_null"]
  
          if "dloglike_scan" in table.colnames and "stat_scan" not in table.colnames:
              table["stat_scan"] = 2 * table["dloglike_scan"]
  
          return cls(table=table)
  
      def write(self, filename, **kwargs):
          """Write flux points.
  
          Parameters
          ----------
          filename : str
              Filename
          kwargs : dict
              Keyword arguments passed to `astropy.table.Table.write`.
          """
          filename = make_path(filename)
          try:
              self.table.write(filename, **kwargs)
          except IORegistryError:
              kwargs.setdefault("format", "ascii.ecsv")
              self.table.write(filename, **kwargs)
  
      @classmethod
      def stack(cls, flux_points):
          """Create flux points by stacking list of flux points.
  
          The first `FluxPoints` object in the list is taken as a reference to infer
          column names and units for the stacked object.
  
          Parameters
          ----------
          flux_points : list of `FluxPoints`
              List of flux points to stack.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points without upper limit points.
          """
          reference = flux_points[0].table
  
          tables = []
          for _ in flux_points:
              table = _.table
              for colname in reference.colnames:
                  column = reference[colname]
                  if column.unit:
                      table[colname] = table[colname].quantity.to(column.unit)
              tables.append(table[reference.colnames])
  
          table_stacked = vstack(tables)
          table_stacked.meta["SED_TYPE"] = reference.meta["SED_TYPE"]
  
          return cls(table_stacked)
  
      def drop_ul(self):
          """Drop upper limit flux points.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points with upper limit points removed.
  
          Examples
          --------
          >>> from gammapy.spectrum import FluxPoints
          >>> filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          >>> flux_points = FluxPoints.read(filename)
          >>> print(flux_points)
          FluxPoints(sed_type="flux", n_points=24)
          >>> print(flux_points.drop_ul())
          FluxPoints(sed_type="flux", n_points=19)
          """
          table_drop_ul = self.table[~self.is_ul]
          return self.__class__(table_drop_ul)
  
      def _flux_to_dnde(self, e_ref, table, model, pwl_approx):
          if model is None:
              model = PowerLawSpectralModel()
  
          e_min, e_max = self.e_min, self.e_max
  
          flux = table["flux"].quantity
          dnde = self._dnde_from_flux(flux, model, e_ref, e_min, e_max, pwl_approx)
  
          # Add to result table
          table["e_ref"] = e_ref
          table["dnde"] = dnde
  
          if "flux_err" in table.colnames:
              table["dnde_err"] = dnde * table["flux_err"].quantity / flux
  
          if "flux_errn" in table.colnames:
              table["dnde_errn"] = dnde * table["flux_errn"].quantity / flux
              table["dnde_errp"] = dnde * table["flux_errp"].quantity / flux
  
          if "flux_ul" in table.colnames:
              flux_ul = table["flux_ul"].quantity
              dnde_ul = self._dnde_from_flux(
                  flux_ul, model, e_ref, e_min, e_max, pwl_approx
              )
              table["dnde_ul"] = dnde_ul
  
          return table
  
      @staticmethod
      def _dnde_to_e2dnde(e_ref, table):
          for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
              try:
                  data = table["dnde" + suffix].quantity
                  table["e2dnde" + suffix] = (e_ref ** 2 * data).to(
                      DEFAULT_UNIT["e2dnde"]
                  )
              except KeyError:
                  continue
  
          return table
  
      @staticmethod
      def _e2dnde_to_dnde(e_ref, table):
          for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
              try:
                  data = table["e2dnde" + suffix].quantity
                  table["dnde" + suffix] = (data / e_ref ** 2).to(DEFAULT_UNIT["dnde"])
              except KeyError:
                  continue
  
          return table
  
      def to_sed_type(self, sed_type, method="log_center", model=None, pwl_approx=False):
          """Convert to a different SED type (return new `FluxPoints`).
  
          See: https://ui.adsabs.harvard.edu/abs/1995NIMPA.355..541L for details
          on the `'lafferty'` method.
  
          Parameters
          ----------
          sed_type : {'dnde'}
               SED type to convert to.
          model : `~gammapy.modeling.models.SpectralModel`
              Spectral model assumption.  Note that the value of the amplitude parameter
              does not matter. Still it is recommended to use something with the right
              scale and units. E.g. `amplitude = 1e-12 * u.Unit('cm-2 s-1 TeV-1')`
          method : {'lafferty', 'log_center', 'table'}
              Flux points `e_ref` estimation method:
  
                  * `'laferty'` Lafferty & Wyatt model-based e_ref
                  * `'log_center'` log bin center e_ref
                  * `'table'` using column 'e_ref' from input flux_points
          pwl_approx : bool
              Use local power law appoximation at e_ref to compute differential flux
              from the integral flux. This method is used by the Fermi-LAT catalogs.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Flux points including differential quantity columns `dnde`
              and `dnde_err` (optional), `dnde_ul` (optional).
  
          Examples
          --------
          >>> from gammapy.spectrum import FluxPoints
          >>> from gammapy.modeling.models import PowerLawSpectralModel
          >>> filename = '$GAMMAPY_DATA/tests/spectrum/flux_points/flux_points.fits'
          >>> flux_points = FluxPoints.read(filename)
          >>> model = PowerLawSpectralModel(index=2.2)
          >>> flux_points_dnde = flux_points.to_sed_type('dnde', model=model)
          """
          # TODO: implement other directions.
          table = self.table.copy()
  
          if self.sed_type == "flux" and sed_type == "dnde":
              # Compute e_ref
              if method == "table":
                  e_ref = table["e_ref"].quantity
              elif method == "log_center":
                  e_ref = np.sqrt(self.e_min * self.e_max)
              elif method == "lafferty":
                  # set e_ref that it represents the mean dnde in the given energy bin
                  e_ref = self._e_ref_lafferty(model, self.e_min, self.e_max)
              else:
                  raise ValueError(f"Invalid method: {method}")
              table = self._flux_to_dnde(e_ref, table, model, pwl_approx)
  
          elif self.sed_type == "dnde" and sed_type == "e2dnde":
              table = self._dnde_to_e2dnde(self.e_ref, table)
  
          elif self.sed_type == "e2dnde" and sed_type == "dnde":
              table = self._e2dnde_to_dnde(self.e_ref, table)
  
          elif self.sed_type == "likelihood" and sed_type in ["dnde", "flux", "eflux"]:
              for suffix in ["", "_ul", "_err", "_errp", "_errn"]:
                  try:
                      table[sed_type + suffix] = (
                          table["ref_" + sed_type] * table["norm" + suffix]
                      )
                  except KeyError:
                      continue
          else:
              raise NotImplementedError
  
          table.meta["SED_TYPE"] = sed_type
          return FluxPoints(table)
  
      @staticmethod
      def _e_ref_lafferty(model, e_min, e_max):
          """Helper for `to_sed_type`.
  
          Compute e_ref that the value at e_ref corresponds
          to the mean value between e_min and e_max.
          """
          flux = model.integral(e_min, e_max)
          dnde_mean = flux / (e_max - e_min)
          return model.inverse(dnde_mean)
  
      @staticmethod
      def _dnde_from_flux(flux, model, e_ref, e_min, e_max, pwl_approx):
          """Helper for `to_sed_type`.
  
          Compute dnde under the assumption that flux equals expected
          flux from model.
          """
          dnde_model = model(e_ref)
  
          if pwl_approx:
              index = model.spectral_index(e_ref)
              flux_model = PowerLawSpectralModel.evaluate_integral(
                  emin=e_min,
                  emax=e_max,
                  index=index,
                  reference=e_ref,
                  amplitude=dnde_model,
              )
          else:
              flux_model = model.integral(e_min, e_max, intervals=True)
  
          return dnde_model * (flux / flux_model)
  
      @property
      def sed_type(self):
          """SED type (str).
  
          One of: {'dnde', 'e2dnde', 'flux', 'eflux'}
          """
          return self.table.meta["SED_TYPE"]
  
      @staticmethod
      def _guess_sed_type(table):
          """Guess SED type from table content."""
          valid_sed_types = list(REQUIRED_COLUMNS.keys())
          for sed_type in valid_sed_types:
              required = set(REQUIRED_COLUMNS[sed_type])
              if required.issubset(table.colnames):
                  return sed_type
  
      @staticmethod
      def _guess_sed_type_from_unit(unit):
          """Guess SED type from unit."""
          for sed_type, default_unit in DEFAULT_UNIT.items():
              if unit.is_equivalent(default_unit):
                  return sed_type
  
      @staticmethod
      def _validate_table(table, sed_type):
          """Validate input table."""
          required = set(REQUIRED_COLUMNS[sed_type])
  
          if not required.issubset(table.colnames):
              missing = required.difference(table.colnames)
              raise ValueError(
                  "Missing columns for sed type '{}':" " {}".format(sed_type, missing)
              )
  
      @staticmethod
      def _get_y_energy_unit(y_unit):
          """Get energy part of the given y unit."""
          try:
              return [_ for _ in y_unit.bases if _.physical_type == "energy"][0]
          except IndexError:
              return u.Unit("TeV")
  
      def _plot_get_energy_err(self):
          """Compute energy error for given sed type"""
          try:
              e_min = self.table["e_min"].quantity
              e_max = self.table["e_max"].quantity
              e_ref = self.e_ref
              x_err = ((e_ref - e_min), (e_max - e_ref))
          except KeyError:
              x_err = None
          return x_err
  
      def _plot_get_flux_err(self, sed_type=None):
          """Compute flux error for given sed type"""
          try:
              # asymmetric error
              y_errn = self.table[sed_type + "_errn"].quantity
              y_errp = self.table[sed_type + "_errp"].quantity
              y_err = (y_errn, y_errp)
          except KeyError:
              try:
                  # symmetric error
                  y_err = self.table[sed_type + "_err"].quantity
                  y_err = (y_err, y_err)
              except KeyError:
                  # no error at all
                  y_err = None
          return y_err
  
      @property
      def is_ul(self):
          try:
              return self.table["is_ul"].data.astype("bool")
          except KeyError:
              return np.isnan(self.table[self.sed_type])
  
      @property
      def e_ref(self):
          """Reference energy.
  
          Defined by `e_ref` column in `FluxPoints.table` or computed as log
          center, if `e_min` and `e_max` columns are present in `FluxPoints.table`.
  
          Returns
          -------
          e_ref : `~astropy.units.Quantity`
              Reference energy.
          """
          try:
              return self.table["e_ref"].quantity
          except KeyError:
              return np.sqrt(self.e_min * self.e_max)
  
      @property
      def e_edges(self):
          """Edges of the energy bin.
  
          Returns
          -------
          e_edges : `~astropy.units.Quantity`
              Energy edges.
          """
          e_edges = list(self.e_min)
          e_edges += [self.e_max[-1]]
          return u.Quantity(e_edges, self.e_min.unit, copy=False)
  
      @property
      def e_min(self):
          """Lower bound of energy bin.
  
          Defined by `e_min` column in `FluxPoints.table`.
  
          Returns
          -------
          e_min : `~astropy.units.Quantity`
              Lower bound of energy bin.
          """
          return self.table["e_min"].quantity
  
      @property
      def e_max(self):
          """Upper bound of energy bin.
  
          Defined by ``e_max`` column in ``table``.
  
          Returns
          -------
          e_max : `~astropy.units.Quantity`
              Upper bound of energy bin.
          """
          return self.table["e_max"].quantity
  
      def plot(
          self, ax=None, energy_unit="TeV", flux_unit=None, energy_power=0, **kwargs
      ):
          """Plot flux points.
  
          Parameters
          ----------
          ax : `~matplotlib.axes.Axes`
              Axis object to plot on.
          energy_unit : str, `~astropy.units.Unit`, optional
              Unit of the energy axis
          flux_unit : str, `~astropy.units.Unit`, optional
              Unit of the flux axis
          energy_power : int
              Power of energy to multiply y axis with
          kwargs : dict
              Keyword arguments passed to :func:`matplotlib.pyplot.errorbar`
  
          Returns
          -------
          ax : `~matplotlib.axes.Axes`
              Axis object
          """
          import matplotlib.pyplot as plt
  
          if ax is None:
              ax = plt.gca()
  
          sed_type = self.sed_type
          y_unit = u.Unit(flux_unit or DEFAULT_UNIT[sed_type])
  
          y = self.table[sed_type].quantity.to(y_unit)
          x = self.e_ref.to(energy_unit)
  
          # get errors and ul
          is_ul = self.is_ul
          x_err_all = self._plot_get_energy_err()
          y_err_all = self._plot_get_flux_err(sed_type)
  
          # handle energy power
          e_unit = self._get_y_energy_unit(y_unit)
          y_unit = y.unit * e_unit ** energy_power
          y = (y * np.power(x, energy_power)).to(y_unit)
  
          y_err, x_err = None, None
  
          if y_err_all:
              y_errn = (y_err_all[0] * np.power(x, energy_power)).to(y_unit)
              y_errp = (y_err_all[1] * np.power(x, energy_power)).to(y_unit)
              y_err = (y_errn[~is_ul].to_value(y_unit), y_errp[~is_ul].to_value(y_unit))
  
          if x_err_all:
              x_errn, x_errp = x_err_all
              x_err = (
                  x_errn[~is_ul].to_value(energy_unit),
                  x_errp[~is_ul].to_value(energy_unit),
              )
  
          # set flux points plotting defaults
          kwargs.setdefault("marker", "+")
          kwargs.setdefault("ls", "None")
  
          ebar = ax.errorbar(
              x[~is_ul].value, y[~is_ul].value, yerr=y_err, xerr=x_err, **kwargs
          )
  
          if is_ul.any():
              if x_err_all:
                  x_errn, x_errp = x_err_all
                  x_err = (
                      x_errn[is_ul].to_value(energy_unit),
                      x_errp[is_ul].to_value(energy_unit),
                  )
  
              y_ul = self.table[sed_type + "_ul"].quantity
              y_ul = (y_ul * np.power(x, energy_power)).to(y_unit)
  
              y_err = (0.5 * y_ul[is_ul].value, np.zeros_like(y_ul[is_ul].value))
  
              kwargs.setdefault("color", ebar[0].get_color())
  
              # pop label keyword to avoid that it appears twice in the legend
              kwargs.pop("label", None)
              ax.errorbar(
                  x[is_ul].value,
                  y_ul[is_ul].value,
                  xerr=x_err,
                  yerr=y_err,
                  uplims=True,
                  **kwargs,
              )
  
          ax.set_xscale("log", nonposx="clip")
          ax.set_yscale("log", nonposy="clip")
          ax.set_xlabel(f"Energy ({energy_unit})")
          ax.set_ylabel(f"{self.sed_type} ({y_unit})")
          return ax
  
      def plot_ts_profiles(
          self,
          ax=None,
          energy_unit="TeV",
          add_cbar=True,
          y_values=None,
          y_unit=None,
          **kwargs,
      ):
          """Plot fit statistic SED profiles as a density plot.
  
          Parameters
          ----------
          ax : `~matplotlib.axes.Axes`
              Axis object to plot on.
          energy_unit : str, `~astropy.units.Unit`, optional
              Unit of the energy axis
          y_values : `astropy.units.Quantity`
              Array of y-values to use for the fit statistic profile evaluation.
          y_unit : str or `astropy.units.Unit`
              Unit to use for the y-axis.
          add_cbar : bool
              Whether to add a colorbar to the plot.
          kwargs : dict
              Keyword arguments passed to :func:`matplotlib.pyplot.pcolormesh`
  
          Returns
          -------
          ax : `~matplotlib.axes.Axes`
              Axis object
          """
          import matplotlib.pyplot as plt
  
          if ax is None:
              ax = plt.gca()
  
          self._validate_table(self.table, "likelihood")
          y_unit = u.Unit(y_unit or DEFAULT_UNIT[self.sed_type])
  
          if y_values is None:
              ref_values = self.table["ref_" + self.sed_type].quantity
              y_values = np.logspace(
                  np.log10(0.2 * ref_values.value.min()),
                  np.log10(5 * ref_values.value.max()),
                  500,
              )
              y_values = u.Quantity(y_values, y_unit, copy=False)
  
          x = self.e_edges.to(energy_unit)
  
          # Compute fit statistic "image" one energy bin at a time
          # by interpolating e2dnde at the log bin centers
          z = np.empty((len(self.table), len(y_values)))
          for idx, row in enumerate(self.table):
              y_ref = self.table["ref_" + self.sed_type].quantity[idx]
              norm = (y_values / y_ref).to_value("")
              norm_scan = row["norm_scan"]
              ts_scan = row["stat_scan"] - row["stat"]
              interp = interpolate_profile(norm_scan, ts_scan)
              z[idx] = interp((norm,))
  
          kwargs.setdefault("vmax", 0)
          kwargs.setdefault("vmin", -4)
          kwargs.setdefault("zorder", 0)
          kwargs.setdefault("cmap", "Blues")
          kwargs.setdefault("linewidths", 0)
  
          # clipped values are set to NaN so that they appear white on the plot
          z[-z < kwargs["vmin"]] = np.nan
          caxes = ax.pcolormesh(x.value, y_values.value, -z.T, **kwargs)
          ax.set_xscale("log", nonposx="clip")
          ax.set_yscale("log", nonposy="clip")
          ax.set_xlabel(f"Energy ({energy_unit})")
          ax.set_ylabel(f"{self.sed_type} ({y_values.unit})")
  
          if add_cbar:
              label = "fit statistic difference"
              ax.figure.colorbar(caxes, ax=ax, label=label)
  
          return ax
  
  
  class FluxPointsEstimator:
      """Flux points estimator.
  
      Estimates flux points for a given list of spectral datasets, energies and
      spectral model.
  
      To estimate the flux point the amplitude of the reference spectral model is
      fitted within the energy range defined by the energy group. This is done for
      each group independently. The amplitude is re-normalized using the "norm" parameter,
      which specifies the deviation of the flux from the reference model in this
      energy group. See https://gamma-astro-data-formats.readthedocs.io/en/latest/spectra/binned_likelihoods/index.html
      for details.
  
      The method is also described in the Fermi-LAT catalog paper
      https://ui.adsabs.harvard.edu/#abs/2015ApJS..218...23A
      or the HESS Galactic Plane Survey paper
      https://ui.adsabs.harvard.edu/#abs/2018A%26A...612A...1H
  
      Parameters
      ----------
      datasets : list of `~gammapy.spectrum.SpectrumDataset`
          Spectrum datasets.
      e_edges : `~astropy.units.Quantity`
          Energy edges of the flux point bins.
      source : str
          For which source in the model to compute the flux points.
      norm_min : float
          Minimum value for the norm used for the fit statistic profile evaluation.
      norm_max : float
          Maximum value for the norm used for the fit statistic profile evaluation.
      norm_n_values : int
          Number of norm values used for the fit statistic profile.
      norm_values : `numpy.ndarray`
          Array of norm values to be used for the fit statistic profile.
      sigma : int
          Sigma to use for asymmetric error computation.
      sigma_ul : int
          Sigma to use for upper limit computation.
      reoptimize : bool
          Re-optimize other free model parameters.
      """
  
      def __init__(
          self,
          datasets,
          e_edges,
          source="",
          norm_min=0.2,
          norm_max=5,
          norm_n_values=11,
          norm_values=None,
          sigma=1,
          sigma_ul=2,
          reoptimize=False,
      ):
          # make a copy to not modify the input datasets
          if not isinstance(datasets, Datasets):
              datasets = Datasets(datasets)
  
          if not datasets.is_all_same_type and datasets.is_all_same_shape:
              raise ValueError(
                  "Flux point estimation requires a list of datasets"
                  " of the same type and data shape."
              )
  
          self.datasets = datasets.copy()
          self.e_edges = e_edges
  
          dataset = self.datasets[0]
  
          # TODO: this is complex and non-obvious behaviour. Simlify!
          if len(dataset.models) > 1:
              model = dataset.models[source].spectral_model
          else:
              model = dataset.models[0].spectral_model
  
          self.model = ScaleSpectralModel(model)
          self.model.norm.min = 0
          self.model.norm.max = 1e3
  
          if norm_values is None:
              norm_values = np.logspace(
                  np.log10(norm_min), np.log10(norm_max), norm_n_values
              )
  
          self.norm_values = norm_values
          self.sigma = sigma
          self.sigma_ul = sigma_ul
          self.reoptimize = reoptimize
          self.source = source
          self.fit = Fit(self.datasets)
  
          self._set_scale_model()
          self._contribute_to_stat = False
  
      def _freeze_parameters(self):
          # freeze other parameters
          for par in self.datasets.parameters:
              if par is not self.model.norm:
                  par.frozen = True
  
      def _freeze_empty_background(self):
          from gammapy.cube import MapDataset
  
          counts_all = self.estimate_counts()["counts"]
  
          for counts, dataset in zip(counts_all, self.datasets):
              if isinstance(dataset, MapDataset) and counts == 0:
                  if dataset.background_model is not None:
                      dataset.background_model.parameters.freeze_all()
  
      def _set_scale_model(self):
          # set the model on all datasets
          for dataset in self.datasets:
              if len(dataset.models) > 1:
                  dataset.models[self.source].spectral_model = self.model
              else:
                  dataset.models[0].spectral_model = self.model
  
      @property
      def ref_model(self):
          return self.model.model
  
      @property
      def e_groups(self):
          """Energy grouping table `~astropy.table.Table`"""
          dataset = self.datasets[0]
          if isinstance(dataset, SpectrumDatasetOnOff):
              energy_axis = dataset.counts.energy
          else:
              energy_axis = dataset.counts.geom.get_axis_by_name("energy")
          return energy_axis.group_table(self.e_edges)
  
      def __str__(self):
          s = f"{self.__class__.__name__}:\n"
          s += str(self.datasets) + "\n"
          s += str(self.e_edges) + "\n"
          s += str(self.model) + "\n"
          return s
  
      def run(self, steps="all"):
          """Run the flux point estimator for all energy groups.
  
          Returns
          -------
          flux_points : `FluxPoints`
              Estimated flux points.
          steps : list of str
              Which steps to execute. See `estimate_flux_point` for details
              and available options.
          """
          rows = []
          for e_group in self.e_groups:
              if e_group["bin_type"].strip() != "normal":
                  log.debug("Skipping under-/ overflow bin in flux point estimation.")
                  continue
  
              row = self.estimate_flux_point(e_group, steps=steps)
              rows.append(row)
  
          table = table_from_row_data(rows=rows, meta={"SED_TYPE": "likelihood"})
          return FluxPoints(table).to_sed_type("dnde")
  
      def _energy_mask(self, e_group, dataset):
          energy_mask = np.zeros(dataset.data_shape)
          energy_mask[e_group["idx_min"] : e_group["idx_max"] + 1] = 1
          return energy_mask.astype(bool)
  
      def estimate_flux_point(self, e_group, steps="all"):
          """Estimate flux point for a single energy group.
  
          Parameters
          ----------
          e_group : `~astropy.table.Row`
              Energy group to compute the flux point for.
          steps : list of str
              Which steps to execute. Available options are:
  
                  * "err": estimate symmetric error.
                  * "errn-errp": estimate asymmetric errors.
                  * "ul": estimate upper limits.
                  * "ts": estimate ts and sqrt(ts) values.
                  * "norm-scan": estimate fit statistic profiles.
  
              By default all steps are executed.
  
          Returns
          -------
          result : dict
              Dict with results for the flux point.
          """
          e_min, e_max = e_group["energy_min"], e_group["energy_max"]
          # Put at log center of the bin
          e_ref = np.sqrt(e_min * e_max)
  
          result = {
              "e_ref": e_ref,
              "e_min": e_min,
              "e_max": e_max,
              "ref_dnde": self.ref_model(e_ref),
              "ref_flux": self.ref_model.integral(e_min, e_max),
              "ref_eflux": self.ref_model.energy_flux(e_min, e_max),
              "ref_e2dnde": self.ref_model(e_ref) * e_ref ** 2,
          }
  
          for dataset in self.datasets:
              dataset.mask_fit = self._energy_mask(e_group=e_group, dataset=dataset)
              mask = dataset.mask_fit
  
              if dataset.mask_safe is not None:
                  mask &= dataset.mask_safe
  
              self._contribute_to_stat |= mask.any()
  
          with self.datasets.parameters.restore_values:
  
              self._freeze_empty_background()
  
              if not self.reoptimize:
                  self._freeze_parameters()
  
              result.update(self.estimate_norm())
  
              if not result.pop("success"):
                  log.warning(
                      "Fit failed for flux point between {e_min:.3f} and {e_max:.3f},"
                      " setting NaN.".format(e_min=e_min, e_max=e_max)
                  )
  
              if steps == "all":
                  steps = ["err", "counts", "errp-errn", "ul", "ts", "norm-scan"]
  
              if "err" in steps:
                  result.update(self.estimate_norm_err())
  
              if "counts" in steps:
                  result.update(self.estimate_counts())
  
              if "errp-errn" in steps:
                  result.update(self.estimate_norm_errn_errp())
  
              if "ul" in steps:
                  result.update(self.estimate_norm_ul())
  
              if "ts" in steps:
                  result.update(self.estimate_norm_ts())
  
              if "norm-scan" in steps:
                  result.update(self.estimate_norm_scan())
  
          return result
  
      def estimate_norm_errn_errp(self):
          """Estimate asymmetric errors for a flux point.
  
          Returns
          -------
          result : dict
              Dict with asymmetric errors for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_errp": np.nan, "norm_errn": np.nan}
  
          result = self.fit.confidence(parameter=self.model.norm, sigma=self.sigma)
          return {"norm_errp": result["errp"], "norm_errn": result["errn"]}
  
      def estimate_norm_err(self):
          """Estimate covariance errors for a flux point.
  
          Returns
          -------
          result : dict
              Dict with symmetric error for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_err": np.nan}
  
          result = self.fit.covariance()
          norm_err = result.parameters.error(self.model.norm)
          return {"norm_err": norm_err}
  
      def estimate_counts(self):
          """Estimate counts for the flux point.
  
          Returns
          -------
          result : dict
              Dict with an array with one entry per dataset with counts for the flux point.
          """
          if not self._contribute_to_stat:
              return {"counts": np.zeros(len(self.datasets))}
  
          counts = []
          for dataset in self.datasets:
              mask = dataset.mask_fit
              if dataset.mask_safe is not None:
                  mask &= dataset.mask_safe
  
              counts.append(dataset.counts.data[mask].sum())
  
          return {"counts": np.array(counts, dtype=int)}
  
      def estimate_norm_ul(self):
          """Estimate upper limit for a flux point.
  
          Returns
          -------
          result : dict
              Dict with upper limit for the flux point norm.
          """
          if not self._contribute_to_stat:
              return {"norm_ul": np.nan}
  
          norm = self.model.norm
  
          # TODO: the minuit backend has convergence problems when the fit statistic is not
          #  of parabolic shape, which is the case, when there are zero counts in the
          #  energy bin. For this case we change to the scipy backend.
          counts = self.estimate_counts()["counts"]
  
          if np.all(counts == 0):
              result = self.fit.confidence(
                  parameter=norm,
                  sigma=self.sigma_ul,
                  backend="scipy",
                  reoptimize=self.reoptimize,
              )
          else:
              result = self.fit.confidence(parameter=norm, sigma=self.sigma_ul)
  
          return {"norm_ul": result["errp"] + norm.value}
  
      def estimate_norm_ts(self):
          """Estimate ts and sqrt(ts) for the flux point.
  
          Returns
          -------
          result : dict
              Dict with ts and sqrt(ts) for the flux point.
          """
          if not self._contribute_to_stat:
              return {"sqrt_ts": np.nan, "ts": np.nan}
  
          stat = self.datasets.stat_sum()
  
          # store best fit amplitude, set amplitude of fit model to zero
          self.model.norm.value = 0
          self.model.norm.frozen = True
  
          if self.reoptimize:
              _ = self.fit.optimize()
  
          stat_null = self.datasets.stat_sum()
  
          # compute sqrt TS
          ts = np.abs(stat_null - stat)
          sqrt_ts = np.sqrt(ts)
          return {"sqrt_ts": sqrt_ts, "ts": ts}
  
      def estimate_norm_scan(self):
          """Estimate fit statistic profile for the norm parameter.
  
          Returns
          -------
          result : dict
              Keys: "norm_scan", "stat_scan"
          """
          if not self._contribute_to_stat:
              nans = np.nan * np.empty_like(self.norm_values)
              return {"norm_scan": nans, "stat_scan": nans}
  
          result = self.fit.stat_profile(
              self.model.norm, values=self.norm_values, reoptimize=self.reoptimize
          )
          return {"norm_scan": result["values"], "stat_scan": result["stat"]}
  
      def estimate_norm(self):
          """Fit norm of the flux point.
  
          Returns
          -------
          result : dict
              Dict with "norm" and "stat" for the flux point.
          """
          if not self._contribute_to_stat:
              return {"norm": np.nan, "stat": np.nan, "success": False}
  
          # start optimization with norm=1
          self.model.norm.value = 1.0
          self.model.norm.frozen = False
  
          result = self.fit.optimize()
  
          if result.success:
              norm = self.model.norm.value
          else:
              norm = np.nan
  
          return {"norm": norm, "stat": result.total_stat, "success": result.success}
  
  
  class FluxPointsDataset(Dataset):
      """
      Fit a set of flux points with a parametric model.
  
      Parameters
      ----------
      models : `~gammapy.modeling.models.SkyModels`
          Models (only spectral part needs to be set)
      data : `~gammapy.spectrum.FluxPoints`
          Flux points.
      mask_fit : `numpy.ndarray`
          Mask to apply for fitting
      mask_safe : `numpy.ndarray`
          Mask defining the safe data range.
  
      Examples
      --------
      Load flux points from file and fit with a power-law model::
  
          from gammapy.modeling import Fit
          from gammapy.modeling.models import PowerLawSpectralModel, SkyModel
          from gammapy.spectrum import FluxPoints, FluxPointsDataset
  
          filename = "$GAMMAPY_DATA/tests/spectrum/flux_points/diff_flux_points.fits"
          flux_points = FluxPoints.read(filename)
  
          model = SkyModel(spectral_model=PowerLawSpectralModel())
  
          dataset = FluxPointsDataset(model, flux_points)
          fit = Fit([dataset])
          result = fit.run()
          print(result)
          print(result.parameters.to_table())
      """
  
      stat_type = "chi2"
      tag = "FluxPointsDataset"
  
      def __init__(self, models, data, mask_fit=None, mask_safe=None, name=""):
          self.data = data
          self.mask_fit = mask_fit
          self.name = name
          self.models = models
          if data.sed_type != "dnde":
              raise ValueError("Currently only flux points of type 'dnde' are supported.")
  
          if mask_safe is None:
              mask_safe = np.isfinite(data.table["dnde"])
  
          self.mask_safe = mask_safe
  
      @property
      def models(self):
          return self._models
  
      @models.setter
      def models(self, value):
          if value is not None:
              self._models = SkyModels(value)
          else:
              self._models = None
  
      @property
      def parameters(self):
          """List of parameters (`~gammapy.modeling.Parameters`)"""
          parameters = []
  
          for component in self.models:
              parameters.append(component.spectral_model.parameters)
  
          return Parameters.from_stack(parameters)
  
      def write(self, filename, overwrite=True, **kwargs):
          """Write flux point dataset to file.
  
          Parameters
          ----------
          filename : str
              Filename to write to.
          overwrite : bool
              Overwrite existing file.
          **kwargs : dict
               Keyword arguments passed to `~astropy.table.Table.write`.
          """
          table = self.data.table.copy()
          if self.mask_fit is None:
              mask_fit = self.mask_safe
          else:
              mask_fit = self.mask_fit
  
          table["mask_fit"] = mask_fit
          table["mask_safe"] = self.mask_safe
          table.write(filename, overwrite=overwrite, **kwargs)
  
      @classmethod
      def from_dict(cls, data, components, models):
          """Create flux point dataset from dict.
  
          Parameters
          ----------
          data : dict
              Dict containing data to create dataset from.
          components : list of dict
              Not used.
          models : list of `SkyModel`
              List of model components.
  
          Returns
          -------
          dataset : `FluxPointsDataset`
              Flux point datasets.
          """
          models = [model for model in models if model.name in data["models"]]
          # TODO: assumes that the model is a skymodel
          # so this will work only when this change will be effective
          table = Table.read(data["filename"])
          mask_fit = table["mask_fit"].data.astype("bool")
          mask_safe = table["mask_safe"].data.astype("bool")
          table.remove_columns(["mask_fit", "mask_safe"])
          return cls(
              models=models,
              name=data["name"],
              data=FluxPoints(table),
              mask_fit=mask_fit,
              mask_safe=mask_safe,
          )
  
      def to_dict(self, filename=""):
          """Convert to dict for YAML serialization."""
          if self.models is not None:
              models = [_.name for _ in self.models]
          else:
              models = []
  
          return {
              "name": self.name,
              "type": self.tag,
              "models": models,
              "filename": str(filename),
          }
  
      def __str__(self):
          str_ = f"{self.__class__.__name__}: \n"
          str_ += "\n"
          if self.models is None:
              str_ += "\t{:32}:   {} \n".format("Model Name", "No Model")
          else:
              str_ += "\t{:32}:   {} \n".format("Total flux points", len(self.data.table))
              str_ += "\t{:32}:   {} \n".format(
                  "Points used for the fit", self.mask.sum()
              )
              str_ += "\t{:32}:   {} \n".format(
                  "Excluded for safe energy range", (~self.mask_safe).sum()
              )
              if self.mask_fit is None:
                  str_ += "\t{:32}:   {} \n".format("Excluded by user", "0")
              else:
                  str_ += "\t{:32}:   {} \n".format(
                      "Excluded by user", (~self.mask_fit).sum()
                  )
              str_ += "\t{:32}:   {}\n".format(
                  "Model Name", self.models.__class__.__name__
              )
              str_ += "\t{:32}:   {}\n".format("N parameters", len(self.parameters))
              str_ += "\t{:32}:   {}\n".format(
                  "N free parameters", len(self.parameters.free_parameters)
              )
              str_ += "\tList of parameters\n"
              for par in self.parameters:
                  if par.frozen:
                      if par.name == "amplitude":
                          str_ += "\t \t {:14} (Frozen):   {:.2e} {} \n".format(
                              par.name, par.value, par.unit
                          )
                      else:
                          str_ += "\t \t {:14} (Frozen):   {:.2f} {} \n".format(
                              par.name, par.value, par.unit
                          )
                  else:
                      if par.name == "amplitude":
                          str_ += "\t \t {:23}:   {:.2e} {} \n".format(
                              par.name, par.value, par.unit
                          )
                      else:
                          str_ += "\t \t {:23}:   {:.2f} {} \n".format(
                              par.name, par.value, par.unit
                          )
              str_ += "\t{:32}:   {:.2f}\n".format("Likelihood value", self.stat_sum())
          return str_
  
      def data_shape(self):
          """Shape of the flux points data (tuple)."""
          return self.data.e_ref.shape
  
      def flux_pred(self):
          """Compute predicted flux."""
          flux = 0.0
          for component in self.models:
              flux += component.spectral_model(self.data.e_ref)
          return flux
  
      def stat_array(self):
          """Fit statistic array."""
          model = self.flux_pred()
          data = self.data.table["dnde"].quantity
          sigma = self.data.table["dnde_err"].quantity
          return ((data - model) / sigma).to_value("") ** 2
  
      def residuals(self, method="diff"):
          """Compute the flux point residuals ().
  
          Parameters
          ----------
          method: {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals. Available options are:
                  - `diff` (default): data - model
                  - `diff/model`: (data - model) / model
                  - `diff/sqrt(model)`: (data - model) / sqrt(model)
                  - `norm='sqrt_model'` for: (flux points - model)/sqrt(model)
  
  
          Returns
          -------
          residuals : `~numpy.ndarray`
              Residuals array.
          """
          fp = self.data
          data = fp.table[fp.sed_type]
  
          model = self.flux_pred()
  
          residuals = self._compute_residuals(data, model, method)
          # Remove residuals for upper_limits
          residuals[fp.is_ul] = np.nan
          return residuals
  
      def peek(self, method="diff/model", **kwargs):
          """Plot flux points, best fit model and residuals.
  
          Parameters
          ----------
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          """
          from matplotlib.gridspec import GridSpec
          import matplotlib.pyplot as plt
  
          gs = GridSpec(7, 1)
  
          ax_spectrum = plt.subplot(gs[:5, :])
          self.plot_spectrum(ax=ax_spectrum, **kwargs)
  
          ax_spectrum.set_xticks([])
  
          ax_residuals = plt.subplot(gs[5:, :])
          self.plot_residuals(ax=ax_residuals, method=method)
          return ax_spectrum, ax_residuals
  
      @property
      def _e_range(self):
          try:
              return u.Quantity([self.data.e_min.min(), self.data.e_max.max()])
          except KeyError:
              return u.Quantity([self.data.e_ref.min(), self.data.e_ref.max()])
  
      @property
      def _e_unit(self):
          return self.data.e_ref.unit
  
      def plot_residuals(self, ax=None, method="diff", **kwargs):
          """Plot flux point residuals.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          method : {"diff", "diff/model", "diff/sqrt(model)"}
              Method used to compute the residuals, see `MapDataset.residuals()`
          **kwargs : dict
              Keyword arguments passed to `~matplotlib.pyplot.errorbar`.
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
  
          residuals = self.residuals(method=method)
  
          fp = self.data
  
          xerr = fp._plot_get_energy_err()
          if xerr is not None:
              xerr = xerr[0].to_value(self._e_unit), xerr[1].to_value(self._e_unit)
  
          model = self.flux_pred()
          yerr = fp._plot_get_flux_err(fp.sed_type)
  
          if method == "diff":
              unit = yerr[0].unit
              yerr = yerr[0].to_value(unit), yerr[1].to_value(unit)
          elif method == "diff/model":
              unit = ""
              yerr = (yerr[0] / model).to_value(""), (yerr[1] / model).to_value(unit)
          else:
              raise ValueError("Invalid method, choose between 'diff' and 'diff/model'")
  
          kwargs.setdefault("marker", "+")
          kwargs.setdefault("ls", "None")
          kwargs.setdefault("color", "black")
  
          ax.errorbar(
              self.data.e_ref.value, residuals.value, xerr=xerr, yerr=yerr, **kwargs
          )
  
          # format axes
          ax.axhline(0, color="black", lw=0.5)
          ax.set_ylabel("Residuals {}".format(unit.__str__()))
          ax.set_xlabel(f"Energy ({self._e_unit})")
          ax.set_xscale("log")
          ax.set_xlim(self._e_range.to_value(self._e_unit))
          y_max = 2 * np.nanmax(residuals).value
          ax.set_ylim(-y_max, y_max)
          return ax
  
      def plot_spectrum(self, ax=None, fp_kwargs=None, model_kwargs=None):
          """
          Plot spectrum including flux points and model.
  
          Parameters
          ----------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          fp_kwargs : dict
              Keyword arguments passed to `FluxPoints.plot`.
          model_kwargs : dict
              Keywords passed to `SpectralModel.plot` and `SpectralModel.plot_error`
  
          Returns
          -------
          ax : `~matplotlib.pyplot.Axes`
              Axes object.
          """
          import matplotlib.pyplot as plt
  
          ax = plt.gca() if ax is None else ax
          fp_kwargs = {} if fp_kwargs is None else fp_kwargs
          model_kwargs = {} if model_kwargs is None else model_kwargs
  
          kwargs = {
              "flux_unit": "erg-1 cm-2 s-1",
              "energy_unit": "TeV",
              "energy_power": 2,
          }
  
          # plot flux points
          plot_kwargs = kwargs.copy()
          plot_kwargs.update(fp_kwargs)
          plot_kwargs.setdefault("label", "Flux points")
          ax = self.data.plot(ax=ax, **plot_kwargs)
  
          plot_kwargs = kwargs.copy()
          plot_kwargs.setdefault("energy_range", self._e_range)
          plot_kwargs.setdefault("zorder", 10)
          plot_kwargs.update(model_kwargs)
          plot_kwargs.setdefault("label", "Best fit model")
          for _ in self.models:
              _.spectral_model.plot(ax=ax, **plot_kwargs)
  
          plot_kwargs.setdefault("color", ax.lines[-1].get_color())
          del plot_kwargs["label"]
  
          if self.models.parameters.covariance is not None:
              try:
                  self.models.plot_error(ax=ax, **plot_kwargs)
              except AttributeError:
                  log.debug("Model does not support evaluation of errors")
  
          # format axes
          ax.set_xlim(self._e_range.to_value(self._e_unit))
          return ax
  
files: gammapy/spectrum/flux_point.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  """Utils to create scripts and command-line tools"""
  import os.path
  from pathlib import Path
  from uuid import uuid4
  import yaml
  
  __all__ = ["read_yaml", "write_yaml", "make_path", "recursive_merge_dicts"]
  
  
  def read_yaml(filename, logger=None):
      """Read YAML file.
  
      Parameters
      ----------
      filename : `~pathlib.Path`
          Filename
      logger : `~logging.Logger`
          Logger
  
      Returns
      -------
      data : dict
          YAML file content as a dict
      """
      path = make_path(filename)
      if logger is not None:
          logger.info(f"Reading {path}")
  
      text = path.read_text()
      return yaml.safe_load(text)
  
  
  def write_yaml(dictionary, filename, logger=None, sort_keys=True):
      """Write YAML file.
  
      Parameters
      ----------
      dictionary : dict
          Python dictionary
      filename : `~pathlib.Path`
          Filename
      logger : `~logging.Logger`
          Logger
      sort_keys : bool
          Whether to sort keys.
      """
      text = yaml.safe_dump(dictionary, default_flow_style=False, sort_keys=sort_keys)
  
      path = make_path(filename)
      path.parent.mkdir(exist_ok=True)
      if logger is not None:
          logger.info(f"Writing {path}")
      path.write_text(text)
  
  
  def make_name():
      return uuid4().hex[:8]
  
  
  def make_path(path):
      """Expand environment variables on `~pathlib.Path` construction.
  
      Parameters
      ----------
      path : str, `pathlib.Path`
          path to expand
      """
      # TODO: raise error or warning if environment variables that don't resolve are used
      # e.g. "spam/$DAMN/ham" where `$DAMN` is not defined
      # Otherwise this can result in cryptic errors later on
      return Path(os.path.expandvars(path))
  
  
  def recursive_merge_dicts(a, b):
      """Recursively merge two dictionaries.
  
      Entries in b override entries in a. The built-in update function cannot be
      used for hierarchical dicts, see:
      http://stackoverflow.com/questions/3232943/update-value-of-a-nested-dictionary-of-varying-depth/3233356#3233356
  
      Parameters
      ----------
      a : dict
          dictionary to be merged
      b : dict
          dictionary to be merged
  
      Returns
      -------
      c : dict
          merged dict
  
      Examples
      --------
      >>> from gammapy.utils.scripts import recursive_merge_dicts
      >>> a = dict(a=42, b=dict(c=43, e=44))
      >>> b = dict(d=99, b=dict(c=50, g=98))
      >>> c = recursive_merge_dicts(a, b)
      >>> print(c)
      {'a': 42, 'b': {'c': 50, 'e': 44, 'g': 98}, 'd': 99}
      """
      c = a.copy()
      for k, v in b.items():
          if k in c and isinstance(c[k], dict):
              c[k] = recursive_merge_dicts(c[k], v)
          else:
              c[k] = v
      return c
  
files: gammapy/utils/scripts.py
files: # Licensed under a 3-clause BSD style license - see LICENSE.rst
  """Utils to create scripts and command-line tools"""
  import os.path
  from pathlib import Path
  import yaml
  
  __all__ = ["read_yaml", "write_yaml", "make_path", "recursive_merge_dicts"]
  
  
  def read_yaml(filename, logger=None):
      """Read YAML file.
  
      Parameters
      ----------
      filename : `~pathlib.Path`
          Filename
      logger : `~logging.Logger`
          Logger
  
      Returns
      -------
      data : dict
          YAML file content as a dict
      """
      path = make_path(filename)
      if logger is not None:
          logger.info(f"Reading {path}")
  
      text = path.read_text()
      return yaml.safe_load(text)
  
  
  def write_yaml(dictionary, filename, logger=None, sort_keys=True):
      """Write YAML file.
  
      Parameters
      ----------
      dictionary : dict
          Python dictionary
      filename : `~pathlib.Path`
          Filename
      logger : `~logging.Logger`
          Logger
      sort_keys : bool
          Whether to sort keys.
      """
      text = yaml.safe_dump(dictionary, default_flow_style=False, sort_keys=sort_keys)
  
      path = make_path(filename)
      path.parent.mkdir(exist_ok=True)
      if logger is not None:
          logger.info(f"Writing {path}")
      path.write_text(text)
  
  
  def make_path(path):
      """Expand environment variables on `~pathlib.Path` construction.
  
      Parameters
      ----------
      path : str, `pathlib.Path`
          path to expand
      """
      # TODO: raise error or warning if environment variables that don't resolve are used
      # e.g. "spam/$DAMN/ham" where `$DAMN` is not defined
      # Otherwise this can result in cryptic errors later on
      return Path(os.path.expandvars(path))
  
  
  def recursive_merge_dicts(a, b):
      """Recursively merge two dictionaries.
  
      Entries in b override entries in a. The built-in update function cannot be
      used for hierarchical dicts, see:
      http://stackoverflow.com/questions/3232943/update-value-of-a-nested-dictionary-of-varying-depth/3233356#3233356
  
      Parameters
      ----------
      a : dict
          dictionary to be merged
      b : dict
          dictionary to be merged
  
      Returns
      -------
      c : dict
          merged dict
  
      Examples
      --------
      >>> from gammapy.utils.scripts import recursive_merge_dicts
      >>> a = dict(a=42, b=dict(c=43, e=44))
      >>> b = dict(d=99, b=dict(c=50, g=98))
      >>> c = recursive_merge_dicts(a, b)
      >>> print(c)
      {'a': 42, 'b': {'c': 50, 'e': 44, 'g': 98}, 'd': 99}
      """
      c = a.copy()
      for k, v in b.items():
          if k in c and isinstance(c[k], dict):
              c[k] = recursive_merge_dicts(c[k], v)
          else:
              c[k] = v
      return c
  
files: gammapy/utils/scripts.py