rename alpha with more meaningful name

Author: nvaytet

docs/utilities/utilities.rst

@@ -10,3 +10,4 @@ Modules
 
    logging
    nexus
+   uncertainty

src/ess/sans/i_of_q.py

@@ -225,7 +225,7 @@ def to_I_of_Q(data: sc.DataArray,
               gravity: bool = False,
               wavelength_mask: Optional[sc.DataArray] = None,
               wavelength_bands: Optional[sc.Variable] = None,
-              alpha_threshold: float = 0.1) -> sc.DataArray:
+              signal_over_monitor_threshold: float = 0.1) -> sc.DataArray:
     """
     Compute the scattering cross-section I(Q) for a SANS experimental run, performing
     binning in Q and a normalization based on monitor data and a direct beam function.
@@ -271,7 +271,7 @@ def to_I_of_Q(data: sc.DataArray,
         If defined, return the data as a set of bands in the wavelength dimension. This
         is useful for separating different wavelength ranges that contribute to
         different regions in Q space.
-    alpha_threshold:
+    signal_over_monitor_threshold:
         The threshold for the ratio of detector counts to monitor counts above which
         an error is raised because it is not safe to drop the variances of the monitor.
 
@@ -311,7 +311,7 @@ def to_I_of_Q(data: sc.DataArray,
         direct_incident_monitor=direct_monitors['incident'],
         direct_transmission_monitor=direct_monitors['transmission'],
         direct_beam=direct_beam,
-        alpha_threshold=alpha_threshold)
+        signal_over_monitor_threshold=signal_over_monitor_threshold)
 
     # Insert a copy of coords needed for conversion to Q.
     # TODO: can this be avoided by copying the Q coords from the converted numerator?

src/ess/sans/normalization.py

@@ -7,7 +7,7 @@
 import scippneutron as scn
 
 from ..logging import get_logger
-from ..uncertainty import alpha_ratio
+from ..uncertainty import variance_normalized_signal_over_monitor
 
 
 def solid_angle_of_rectangular_pixels(data: sc.DataArray, pixel_width: sc.Variable,
@@ -80,32 +80,33 @@ def transmission_fraction(data_monitors: Dict[str, sc.DataArray],
 
 def _verify_normalization_alpha(numerator: sc.DataArray,
                                 denominator: sc.DataArray,
-                                alpha_threshold: float = 0.1):
+                                signal_over_monitor_threshold: float = 0.1):
     """
     Verify that the ratio of sample detector counts to monitor counts is small, so
     we can safely drop the variances of the monitor to avoid broadcasting issues.
     See Heybrock et al. (2023).
     """
-    alpha = alpha_ratio(numerator, denominator)
-    if alpha > 0.25 * alpha_threshold:
+    alpha = variance_normalized_signal_over_monitor(numerator, denominator)
+    if alpha > 0.25 * signal_over_monitor_threshold:
         logger = get_logger('sans')
         logger.warning(
-            f'alpha = {alpha} is close to the specified threshold of '
-            f'{alpha_threshold}. This means we are close to the regime where it is no '
-            'longer safe to drop the variances of the normalization term.')
-    if alpha > alpha_threshold:
+            f'signal_over_monitor = {alpha} is close to the specified threshold of '
+            f'{signal_over_monitor_threshold}. This means we are close to the regime '
+            'where it is no longer safe to drop the variances of the normalization '
+            'term.')
+    if alpha > signal_over_monitor_threshold:
         raise ValueError(
-            f'alpha = {alpha} > {alpha_threshold}! This means that the ratio of '
-            'detector counts to monitor counts is too high, and the variances of the '
-            'monitor data cannot be safely dropped.')
+            f'signal_over_monitor = {alpha} > {signal_over_monitor_threshold}! '
+            'This means that the ratio of detector counts to monitor counts is too '
+            'high, and the variances of the monitor data cannot be safely dropped.')
 
 
 def iofq_denominator(data: sc.DataArray,
                      data_transmission_monitor: sc.DataArray,
                      direct_incident_monitor: sc.DataArray,
                      direct_transmission_monitor: sc.DataArray,
                      direct_beam: Optional[sc.DataArray] = None,
-                     alpha_threshold: float = 0.1) -> sc.DataArray:
+                     signal_over_monitor_threshold: float = 0.1) -> sc.DataArray:
     """
     Compute the denominator term for the I(Q) normalization. This is basically:
     ``solid_angle * direct_beam * data_transmission_monitor * direct_incident_monitor / direct_transmission_monitor``
@@ -131,7 +132,7 @@ def iofq_denominator(data: sc.DataArray,
         The transmission monitor counts from the direct run (depends on wavelength).
     direct_beam:
         The DataArray containing the direct beam function (depends on wavelength).
-    alpha_threshold:
+    signal_over_monitor_threshold:
         The threshold for the ratio of detector counts to monitor counts above which
         an error is raised because it is not safe to drop the variances of the monitor.
 
@@ -153,7 +154,7 @@ def iofq_denominator(data: sc.DataArray,
         _verify_normalization_alpha(
             numerator=data.hist(wavelength=denominator.coords['wavelength']),
             denominator=denominator,
-            alpha_threshold=alpha_threshold)
+            signal_over_monitor_threshold=signal_over_monitor_threshold)
 
     solid_angle = solid_angle_of_rectangular_pixels(
         data,

src/ess/uncertainty.py

@@ -9,12 +9,16 @@
 T = TypeVar("T", bound=Union[sc.Variable, sc.DataArray])
 
 
-def alpha_ratio(numerator: T, denominator: T) -> float:
+def variance_normalized_signal_over_monitor(numerator: T, denominator: T) -> float:
     """
+    Calculates the ratio of detector variance-normalized counts over monitor
+    variance-normalized counts:
+
     .. math::
        \\alpha = \\frac{\\sum_{i} \\text{var}_{i}(b) a_{i}^{2}}{\\text{var}_{i}(a) b_{i}^{2}}
 
     where :math:`a` is the numerator and :math:`b` the denominator.
+    See Heybrock et al. (2023) for more details.
 
     Parameters
     ----------