Added significance function and disclaimers
@@ -7,10 +7,12 @@ Module with S/N calculation functions.
__author__ = 'Carlos Alberto Gomez Gonzalez, O. Absil @ ULg'
__all__ = ['snr',
'snrmap',
+ 'significance',
'frame_report']
import numpy as np
import photutils
+from scipy.stats import norm, t
from hciplot import plot_frames
from skimage import draw
from matplotlib import pyplot as plt
@@ -27,6 +29,14 @@ def snrmap(array, fwhm, approximated=False, plot=False, known_sources=None,
"""Parallel implementation of the S/N map generation function. Applies the
S/N function (small samples penalty) at each pixel.
+ The S/N is computed as in Mawet et al. (2014) for each radial separation.
+
+ *** DISCLAIMER ***
+ Signal-to-noise ratio is not significance! For a conversion from snr to
+ n-sigma (i.e. the equivalent confidence level of a Gaussian n-sigma), use
+ the significance() function.
+
+
Parameters
----------
array : numpy ndarray
@@ -220,6 +230,11 @@ def snr(array, source_xy, fwhm, full_output=False, array2=None, use2alone=False,
* possibility to use only the second array for the noise estimation
(useful for images containing a lot of disk/extended signals).
+ *** DISCLAIMER ***
+ Signal-to-noise ratio is not significance! For a conversion from snr to
+ n-sigma (i.e. the equivalent confidence level of a Gaussian n-sigma), use
+ the significance() function.
+
Parameters
----------
array : numpy ndarray, 2d
@@ -354,6 +369,42 @@ def snr(array, source_xy, fwhm, full_output=False, array2=None, use2alone=False,
return snr_vale
+
+def significance(snr, rad, fwhm, student_to_gauss=True):
+ """ Converts a S/N ratio (measured as in Mawet et al. 2014) into the
+ equivalent gaussian significance, i.e. the n-sigma with the same confidence
+ level as the S/N at the given separation.
+
+
+ Parameters
+ ----------
+ snr : float or numpy array
+ SNR value(s)
+ rad : float or numpy array
+ Radial separation(s) from the star in pixels. If an array, it should be
+ the same shape as snr and provide the radial separation corresponding
+ to each snr measurement.
+ fwhm : float
+ Full Width Half Maximum of the PSF.
+ student_to_gauss : bool, optional
+ Whether the conversion is from Student SNR to Gaussian significance. If
+ False, will assume the opposite: Gaussian significance to Student SNR.
+
+ Returns
+ -------
+ sigma : float
+ Gaussian significance in terms of n-sigma
+
+ """
+
+ if student_to_gauss:
+ sigma = norm.ppf(t.cdf(snr,(rad/fwhm)*2*np.pi-2))
+ else:
+ sigma = t.ppf(norm.cdf(snr), (rad/fwhm)*2*np.pi-2)
+
+ return sigma
+
+
def frame_report(array, fwhm, source_xy=None, verbose=True):
""" Gets information from given frame: Integrated flux in aperture, S/N of
central pixel (either ``source_xy`` or max value), mean S/N in aperture.
