"""
`skystatistics` module provides statistics computation class.
Used by :py:func:`~stcal.skymatch.skymatch.skymatch`
and :py:class:`~stcal.skymatch.skyimage.SkyImage`.
"""
# THIRD PARTY
from copy import deepcopy
from stsci.imagestats import ImageStats
__all__ = ["SkyStats"]
[docs]
class SkyStats:
"""
Class built on top of :py:class:`stsci.imagestats.ImageStats`.
Deligates its functionality to calls to the ``ImageStats`` object. Compared
to :py:class:`stsci.imagestats.ImageStats`, `SkyStats` has "persistent settings"
in the sense that object's parameters need to be set once and these settings
will be applied to all subsequent computations on different data.
"""
def __init__(
self, skystat="mean", lower=None, upper=None, nclip=5, lsig=4.0, usig=4.0, binwidth=0.1, **kwargs
):
"""Initialize the SkyStats object.
Parameters
----------
skystat : optional
possible values are'mode', 'median', 'mode', 'midpt".
Sets the statistics that will be returned by `~stcal.skymatch.skystatistics.SkyStats.calc_sky`.
The following statistics are supported: 'mean', 'mode', 'midpt',
and 'median'. First three statistics have the same meaning as in
`stsdas.toolbox.imgtools.gstatistics <http://stsdas.stsci.edu/\
cgi-bin/gethelp.cgi?gstatistics>`_
while 'median' will compute the median of the distribution.
lower : float, None, optional
Lower limit of usable pixel values for computing the sky.
This value should be specified in the units of the input image(s).
upper : float, None, optional
Upper limit of usable pixel values for computing the sky.
This value should be specified in the units of the input image(s).
nclip : int, optional
A non-negative number of clipping iterations to use when computing
the sky value.
lsig : float, optional
Lower clipping limit, in sigma, used when computing the sky value.
usig : float, optional
Upper clipping limit, in sigma, used when computing the sky value.
binwidth : float, optional
Bin width, in sigma, used to sample the distribution of pixel
brightness values in order to compute the sky background
statistics.
kwargs : dict
A dictionary of optional arguments to be passed to `ImageStats`.
"""
self.npix = None
self.skyval = None
self._fields = f"npix,{skystat}"
self._kwargs = deepcopy(kwargs)
if "fields" in self._kwargs:
del self._kwargs["fields"]
if "image" in self._kwargs:
del self._kwargs["image"]
self._kwargs["lower"] = lower
self._kwargs["upper"] = upper
self._kwargs["nclip"] = nclip
self._kwargs["lsig"] = lsig
self._kwargs["usig"] = usig
self._kwargs["binwidth"] = binwidth
self._skystat = {
"mean": self._extract_mean,
"mode": self._extract_mode,
"median": self._extract_median,
"midpt": self._extract_midpt,
}[skystat]
def _extract_mean(self, imstat):
return imstat.mean
def _extract_median(self, imstat):
return imstat.median
def _extract_mode(self, imstat):
return imstat.mode
def _extract_midpt(self, imstat):
return imstat.midpt
[docs]
def calc_sky(self, data):
"""Compute statistics on data.
Parameters
----------
data : numpy.ndarray
A numpy array of values for which the statistics needs to be
computed.
Returns
-------
statistics : tuple
A tuple of two values: (`skyvalue`, `npix`), where `skyvalue` is
the statistics specified by the `skystat` parameter during the
initialization of the `SkyStats` object and `npix` is the number
of pixels used in computing the statistics reported in `skyvalue`.
"""
imstat = ImageStats(image=data, fields=self._fields, **(self._kwargs))
self.skyval = self._skystat(imstat)
self.npix = imstat.npix
return self.skyval, self.npix
[docs]
def __call__(self, data): # noqa: D102
return self.calc_sky(data)