Made set_attenuation_coefficients private (#243)

Co-authored-by: Nabil Freij <[email protected]>

changelog/243.breaking.rst

@@ -0,0 +1,3 @@
+The function ``set_attenuation_coefficients`` has been removed from the public API.
+
+Now you can pass in the inputs used by ``set_attenuation_coefficients`` directly into `sunkit_image.radial.fnrgf`, which now accepts ``mean_attenuation_range`` and ``std_attenuation_range``.

examples/radial_gradient_filters.py

@@ -41,16 +41,19 @@
 base_nrgf = radial.nrgf(aia_map, radial_bin_edges=radial_bin_edges, application_radius=1 * u.R_sun)
 
 ###########################################################################
-# We will need to work out  a few parameters for the FNRGF.
+# We will need to work out a few parameters for the FNRGF.
 #
 # Order is the number of Fourier coefficients to be used in the approximation.
-# The attenuation coefficient are calculated to be linearly decreasing, you should
-# choose them according to your requirements.
+# The attenuation coefficients are calculated to be linearly decreasing, you should
+# choose them according to your requirements. These can be changed by tweaking the following keywords: ``mean_attenuation_range`` and ``std_attenuation_range``.
 
 order = 20
-attenuation_coefficients = radial.set_attenuation_coefficients(order)
-
-base_fnrgf = radial.fnrgf(aia_map, radial_bin_edges=radial_bin_edges, order=order, attenuation_coefficients=attenuation_coefficients, application_radius=1 * u.R_sun)
+base_fnrgf = radial.fnrgf(
+    aia_map,
+    radial_bin_edges=radial_bin_edges,
+    order=order,
+    application_radius=1 * u.R_sun
+)
 
 ###########################################################################
 # Now we will also use the final filter, RHEF.

sunkit_image/radial.py

@@ -19,12 +19,12 @@
     get_radial_intensity_summary,
 )
 
-__all__ = ["fnrgf", "intensity_enhance", "set_attenuation_coefficients", "nrgf", "rhef"]
+__all__ = ["fnrgf", "intensity_enhance", "nrgf", "rhef"]
 
 
 def _fit_polynomial_to_log_radial_intensity(radii, intensity, degree):
     """
-    Fits a polynomial of  a given degree to the log of the radial intensity.
+    Fits a polynomial of a given degree to the log of the radial intensity.
 
     Parameters
     ----------
@@ -130,6 +130,7 @@ def _percentile_ranks_numpy_inplace(arr):
         raise NotImplementedError(msg)
     return ranking_func
 
+
 def intensity_enhance(
     smap,
     *,
@@ -360,15 +361,15 @@ def nrgf(
     return new_map
 
 
-def set_attenuation_coefficients(order, range_mean=None, range_std=None, cutoff=0):
+def _set_attenuation_coefficients(order, mean_attenuation_range=None, std_attenuation_range=None, cutoff=0):
     """
     This is a helper function to Fourier Normalizing Radial Gradient Filter
     (`sunkit_image.radial.fnrgf`).
 
     This function sets the attenuation coefficients in the one of the following two manners:
 
     If ``cutoff`` is ``0``, then it will set the attenuation coefficients as linearly decreasing between
-    the range ``range_mean`` for the attenuation coefficients for mean approximation and ``range_std`` for
+    the range ``mean_attenuation_range`` for the attenuation coefficients for mean approximation and ``std_attenuation_range`` for
     the attenuation coefficients for standard deviation approximation.
 
     If ``cutoff`` is not ``0``, then it will set the last ``cutoff`` number of coefficients equal to zero
@@ -388,10 +389,10 @@ def set_attenuation_coefficients(order, range_mean=None, range_std=None, cutoff=
     ----------
     order : `int`
         The order of the Fourier approximation.
-    range_mean : `list`, optional
+    mean_attenuation_range : `list`, optional
         A list of length of ``2`` which contains the highest and lowest values between which the coefficients for
         mean approximation be calculated in a linearly decreasing manner.
-    range_std : `list`, optional
+    std_attenuation_range : `list`, optional
         A list of length of ``2`` which contains the highest and lowest values between which the coefficients for
         standard deviation approximation be calculated in a linearly decreasing manner.
     cutoff : `int`, optional
@@ -402,16 +403,16 @@ def set_attenuation_coefficients(order, range_mean=None, range_std=None, cutoff=
     `numpy.ndarray`
         A numpy array of shape ``[2, order + 1]`` containing the attenuation coefficients for the Fourier
         coffiecients. The first row describes the attenustion coefficients for the Fourier coefficients of
-        the mean approximation. The second row contains the attenuation coefficients for the Fourier coefficients
+        mean approximation. The second row contains the attenuation coefficients for the Fourier coefficients
         of the standard deviation approximation.
     """
-    if range_std is None:
-        range_std = [1.0, 0.0]
-    if range_mean is None:
-        range_mean = [1.0, 0.0]
+    if std_attenuation_range is None:
+        std_attenuation_range = [1.0, 0.0]
+    if mean_attenuation_range is None:
+        mean_attenuation_range = [1.0, 0.0]
     attenuation_coefficients = np.zeros((2, order + 1))
-    attenuation_coefficients[0, :] = np.linspace(range_mean[0], range_mean[1], order + 1)
-    attenuation_coefficients[1, :] = np.linspace(range_std[0], range_std[1], order + 1)
+    attenuation_coefficients[0, :] = np.linspace(mean_attenuation_range[0], mean_attenuation_range[1], order + 1)
+    attenuation_coefficients[1, :] = np.linspace(std_attenuation_range[0], std_attenuation_range[1], order + 1)
 
     if cutoff > (order + 1):
         msg = "Cutoff cannot be greater than order + 1."
@@ -426,9 +427,11 @@ def set_attenuation_coefficients(order, range_mean=None, range_std=None, cutoff=
 def fnrgf(
     smap,
     *,
-    attenuation_coefficients,
     radial_bin_edges=None,
     order=3,
+    mean_attenuation_range=None,
+    std_attenuation_range=None,
+    cutoff=0,
     ratio_mix=None,
     intensity_summary=np.nanmean,
     width_function=np.std,
@@ -466,10 +469,17 @@ def fnrgf(
     order : `int`, optional
         Order (number) of fourier coefficients and it can not be lower than 1.
         Defaults to 3.
-    attenuation_coefficients : `float`
-        A two dimensional array of shape ``[2, order + 1]``. The first row contain attenuation
-        coefficients for mean calculations. The second row contains attenuation coefficients
-        for standard deviation calculation.
+    mean_attenuation_range : `list`, optional
+        A list of length of ``2`` which contains the highest and lowest values between which the coefficients for
+        mean approximation be calculated in a linearly decreasing manner.
+        Defaults to `None`.
+    std_attenuation_range : `list`, optional
+        A list of length of ``2`` which contains the highest and lowest values between which the coefficients for
+        standard deviation approximation be calculated in a linearly decreasing manner.
+        Defaults to `None`.
+    cutoff : `int`, optional
+        The numbers of coefficients from the last that should be set to ``zero``.
+        Defaults to 0.
     ratio_mix : `float`, optional
         A one dimensional array of shape ``[2, 1]`` with values equal to ``[K1, K2]``.
         The ratio in which the original image and filtered image are mixed.
@@ -532,6 +542,9 @@ def fnrgf(
     # Storage for the filtered data
     data = np.ones_like(smap.data) * fill
 
+    # Set attenuation coefficients
+    attenuation_coefficients = _set_attenuation_coefficients(order, mean_attenuation_range, std_attenuation_range, cutoff)
+
     # Iterate over each circular ring
     for i in tqdm(range(nbins), desc="FNRGF: ", disable=not progress):
         # Finding the pixels which belong to a certain circular ring

sunkit_image/tests/test_radial.py

@@ -78,12 +78,13 @@ def test_fnrgf(map_test1, map_test2, radial_bin_edges):
         [96.0, 224.0, 288.0, 224.0, 96.0],
         [-0.0, 96.0, 128.0, 96.0, -0.0],
     ]
-    attenuation_coefficients = rad.set_attenuation_coefficients(order)
     expect = rad.fnrgf(
         map_test1,
-        attenuation_coefficients=attenuation_coefficients,
         radial_bin_edges=radial_bin_edges,
         order=order,
+        mean_attenuation_range=[1.0, 0.0],
+        std_attenuation_range=[1.0, 0.0],
+        cutoff=0,
         application_radius=0.001 * u.R_sun,
         number_angular_segments=4,
         fill=0,
@@ -102,7 +103,9 @@ def test_fnrgf(map_test1, map_test2, radial_bin_edges):
         map_test2,
         radial_bin_edges=radial_bin_edges,
         order=order,
-        attenuation_coefficients=attenuation_coefficients,
+        mean_attenuation_range=[1.0, 0.0],
+        std_attenuation_range=[1.0, 0.0],
+        cutoff=0,
         application_radius=0.001 * u.R_sun,
         number_angular_segments=4,
         fill=0,
@@ -120,12 +123,13 @@ def test_fnrgf(map_test1, map_test2, radial_bin_edges):
         [0.0, 90.52799999986772, 124.46862915010152, 90.52799999989331, -0.0],
     ]
 
-    attenuation_coefficients = rad.set_attenuation_coefficients(order)
     expect2 = rad.fnrgf(
         map_test1,
         radial_bin_edges=radial_bin_edges,
         order=order,
-        attenuation_coefficients=attenuation_coefficients,
+        mean_attenuation_range=[1.0, 0.0],
+        std_attenuation_range=[1.0, 0.0],
+        cutoff=0,
         application_radius=0.001 * u.R_sun,
         number_angular_segments=4,
         fill=0,
@@ -142,12 +146,13 @@ def test_fnrgf(map_test1, map_test2, radial_bin_edges):
         [0.0, 120.55347470601022, 124.46862915010152, 90.67852529370734, -0.0],
     ]
 
-    attenuation_coefficients = rad.set_attenuation_coefficients(order)
     expect3 = rad.fnrgf(
         map_test2,
         radial_bin_edges=radial_bin_edges,
         order=order,
-        attenuation_coefficients=attenuation_coefficients,
+        mean_attenuation_range=[1.0, 0.0],
+        std_attenuation_range=[1.0, 0.0],
+        cutoff=0,
         application_radius=0.001 * u.R_sun,
         number_angular_segments=4,
         fill=0,
@@ -162,7 +167,9 @@ def test_fnrgf_errors(map_test1):
         rad.fnrgf(
             map_test1,
             order=0,
-            attenuation_coefficients=rad.set_attenuation_coefficients(0),
+            mean_attenuation_range=[1.0, 0.0],
+            std_attenuation_range=[1.0, 0.0],
+            cutoff=0,
         )
 
 @figure_test
@@ -180,8 +187,7 @@ def test_fig_fnrgf(aia_171_map):
     radial_bin_edges = utils.equally_spaced_bins()
     radial_bin_edges *= u.R_sun
     order = 20
-    attenuation_coefficients = rad.set_attenuation_coefficients(order)
-    out = rad.fnrgf(aia_171_map, radial_bin_edges=radial_bin_edges, order=order, attenuation_coefficients=attenuation_coefficients)
+    out = rad.fnrgf(aia_171_map, radial_bin_edges=radial_bin_edges, order=order, mean_attenuation_range=[1.0, 0.0], std_attenuation_range=[1.0, 0.0], cutoff=0)
     out.plot()
 
 
@@ -232,29 +238,28 @@ def test_multifig_rhef(aia_171_map):
 
     return fig
 
-
 def test_set_attenuation_coefficients():
     order = 1
     # Hand calculated
     expect1 = [[1, 0.0], [1, 0.0]]
 
-    result1 = rad.set_attenuation_coefficients(order)
+    result1 = rad._set_attenuation_coefficients(order)
     assert np.allclose(expect1, result1)
 
     order = 3
     # Hand calculated
     expect2 = [[1.0, 0.66666667, 0.33333333, 0.0], [1.0, 0.66666667, 0.33333333, 0.0]]
 
-    result2 = rad.set_attenuation_coefficients(order)
+    result2 = rad._set_attenuation_coefficients(order)
     assert np.allclose(expect2, result2)
 
     expect3 = [[1.0, 0.66666667, 0.0, 0.0], [1.0, 0.66666667, 0.0, 0.0]]
 
-    result3 = rad.set_attenuation_coefficients(order, cutoff=2)
+    result3 = rad._set_attenuation_coefficients(order, cutoff=2)
     assert np.allclose(expect3, result3)
 
     with pytest.raises(ValueError, match="Cutoff cannot be greater than order \\+ 1"):
-        rad.set_attenuation_coefficients(order, cutoff=5)
+        rad._set_attenuation_coefficients(order, cutoff=5)
 
 
 def test_fit_polynomial_to_log_radial_intensity():