teareduce 0.5.8__py3-none-any.whl → 0.6.0__py3-none-any.whl

teareduce/cleanest/definitions.py

@@ -9,26 +9,56 @@
 
 """Definitions for the cleanest module."""
 
+VALID_LACOSMIC_CLEANTYPE_VALUES = ["median", "medmask", "meanmask", "idw"]
+VALID_LACOSMIC_FSMODE_VALUES = ["median", "convolve"]
+VALID_LACOSMIC_PSFMODEL_VALUES = ["gauss", "moffat", "gaussx", "gaussy", "gaussxy"]
+
 # Default parameters for L.A.Cosmic algorithm
 # Note that 'type' is set to the expected data type for each parameter
 # using the intrinsic Python types, so that they can be easily cast
 # when reading user input.
 lacosmic_default_dict = {
     # L.A.Cosmic parameters for run 1
-    "run1_gain": {"value": 1.0, "type": float, "positive": True},
-    "run1_readnoise": {"value": 6.5, "type": float, "positive": True},
     "run1_sigclip": {"value": 5.0, "type": float, "positive": True},
     "run1_sigfrac": {"value": 0.3, "type": float, "positive": True},
     "run1_objlim": {"value": 5.0, "type": float, "positive": True},
-    "run1_niter": {"value": 4, "type": int, "positive": True},
+    "run1_gain": {"value": 1.0, "type": float, "positive": True},
+    "run1_readnoise": {"value": 6.5, "type": float, "positive": True},
+    "run1_satlevel": {"value": 65535, "type": float, "positive": True},
+    "run1_niter": {"value": 4, "type": int, "positive": True, "intmode": "any"},
+    "run1_sepmed": {"value": True, "type": bool},
+    "run1_cleantype": {"value": "meanmask", "type": str, "valid_values": VALID_LACOSMIC_CLEANTYPE_VALUES},
+    "run1_fsmode": {"value": "median", "type": str, "valid_values": VALID_LACOSMIC_FSMODE_VALUES},
+    "run1_psfmodel": {
+        "value": "gaussxy",
+        "type": str,
+        "valid_values": VALID_LACOSMIC_PSFMODEL_VALUES,
+    },
+    "run1_psffwhm_x": {"value": 2.5, "type": float, "positive": True},
+    "run1_psffwhm_y": {"value": 2.5, "type": float, "positive": True},
+    "run1_psfsize": {"value": 7, "type": int, "positive": True, "intmode": "odd"},
+    "run1_psfbeta": {"value": 4.765, "type": float, "positive": True},
     "run1_verbose": {"value": True, "type": bool},
     # L.A.Cosmic parameters for run 2
-    "run2_gain": {"value": 1.0, "type": float, "positive": True},
-    "run2_readnoise": {"value": 6.5, "type": float, "positive": True},
     "run2_sigclip": {"value": 3.0, "type": float, "positive": True},
     "run2_sigfrac": {"value": 0.3, "type": float, "positive": True},
     "run2_objlim": {"value": 5.0, "type": float, "positive": True},
-    "run2_niter": {"value": 4, "type": int, "positive": True},
+    "run2_gain": {"value": 1.0, "type": float, "positive": True},
+    "run2_readnoise": {"value": 6.5, "type": float, "positive": True},
+    "run2_satlevel": {"value": 65535, "type": float, "positive": True},
+    "run2_niter": {"value": 4, "type": int, "positive": True, "intmode": "any"},
+    "run2_sepmed": {"value": True, "type": bool},
+    "run2_cleantype": {"value": "meanmask", "type": str, "valid_values": VALID_LACOSMIC_CLEANTYPE_VALUES},
+    "run2_fsmode": {"value": "median", "type": str, "valid_values": VALID_LACOSMIC_FSMODE_VALUES},
+    "run2_psfmodel": {
+        "value": "gaussxy",
+        "type": str,
+        "valid_values": VALID_LACOSMIC_PSFMODEL_VALUES,
+    },
+    "run2_psffwhm_x": {"value": 2.5, "type": float, "positive": True},
+    "run2_psffwhm_y": {"value": 2.5, "type": float, "positive": True},
+    "run2_psfsize": {"value": 7, "type": int, "positive": True, "intmode": "odd"},
+    "run2_psfbeta": {"value": 4.765, "type": float, "positive": True},
     "run2_verbose": {"value": True, "type": bool},
     # Dilation of the mask
     "dilation": {"value": 0, "type": int, "positive": True},
@@ -39,11 +69,20 @@ lacosmic_default_dict = {
     "ymin": {"value": 1, "type": int, "positive": True},
     "ymax": {"value": None, "type": int, "positive": True},
     # Number of runs to execute L.A.Cosmic
-    "nruns": {"value": 1, "type": int, "positive": True},
+    "nruns": {"value": 1, "type": int, "positive": True, "intmode": "any"},
 }
 
-# Default parameters for cleaning methods
-VALID_CLEANING_METHODS = ["x interp.", "y interp.", "surface interp.", "median", "mean", "lacosmic", "maskfill", "auxdata"]
+# Valid cleaning methods (as shown to the user and their internal codes)
+VALID_CLEANING_METHODS = {
+    "x interp.": "x",
+    "y interp.": "y",
+    "surface interp.": "a-plane",
+    "median": "a-median",
+    "mean": "a-mean",
+    "lacosmic": "lacosmic",
+    "maskfill": "maskfill",
+    "auxdata": "auxdata",
+}
 
 # Maximum pixel distance to consider when finding closest CR pixel
 MAX_PIXEL_DISTANCE_TO_CR = 15
@@ -54,6 +93,13 @@ DEFAULT_NPOINTS_INTERP = 2
 # Default degree for interpolation
 DEFAULT_DEGREE_INTERP = 1
 
+# Default maskfill parameters
+DEFAULT_MASKFILL_SIZE = 3
+DEFAULT_MASKFILL_OPERATOR = "median"
+MASKFILL_OPERATOR_VALUES = ["median", "mean"]
+DEFAULT_MASKFILL_SMOOTH = True
+DEFAULT_MASKFILL_VERBOSE = False
+
 # Default Tk window size
 DEFAULT_TK_WINDOW_SIZE_X = 800
 DEFAULT_TK_WINDOW_SIZE_Y = 700

teareduce/cleanest/gausskernel2d_elliptical.py

@@ -0,0 +1,54 @@
+#
+# Copyright 2025 Universidad Complutense de Madrid
+#
+# This file is part of teareduce
+#
+# SPDX-License-Identifier: GPL-3.0+
+# License-Filename: LICENSE.txt
+#
+
+"""Calculate elliptical 2D Gaussian kernel."""
+
+import math
+import numpy as np
+
+
+def gausskernel2d_elliptical(fwhm_x, fwhm_y, kernsize):
+    """Calculate elliptical 2D Gaussian kernel.
+
+    This kernel can be used as the psfk parameter of
+    ccdproc.cosmicray_lacosmic.
+
+    Parameters
+    ----------
+    fwhm_x : float
+        Full width at half maximum in the x direction.
+    fwhm_y : float
+        Full width at half maximum in the y direction.
+    kernsize : int
+        Size of the kernel (must be odd).
+
+    Returns
+    -------
+    kernel : 2D numpy array
+        The elliptical Gaussian kernel. It is normalized
+        so that the sum of all its elements is 1. It
+        is returned as a float32 array (required by
+        ccdproc.cosmicray_lacosmic).
+    """
+
+    if kernsize % 2 == 0 or kernsize < 3:
+        raise ValueError("kernsize must be an odd integer >= 3.")
+    if fwhm_x <= 0 or fwhm_y <= 0:
+        raise ValueError("fwhm_x and fwhm_y must be positive numbers.")
+
+    sigma_x = fwhm_x / (2 * math.sqrt(2 * math.log(2)))
+    sigma_y = fwhm_y / (2 * math.sqrt(2 * math.log(2)))
+    halfsize = kernsize // 2
+    y, x = np.mgrid[-halfsize : halfsize + 1, -halfsize : halfsize + 1]
+    kernel = np.exp(-0.5 * ((x / sigma_x) ** 2 + (y / sigma_y) ** 2))
+    kernel /= np.sum(kernel)
+
+    # reverse the psf kernel as that is what it is used in the convolution
+    kernel = kernel[::-1, ::-1]
+    return kernel.astype(np.float32)

teareduce/cleanest/interpolate.py

@@ -9,8 +9,16 @@
 
 """Interpolate pixels identified in a mask."""
 
-from scipy import ndimage
+try:
+    from maskfill import maskfill
+except ModuleNotFoundError as e:
+    raise ModuleNotFoundError(
+        "The 'teareduce.cleanest' module requires the 'ccdproc' and 'maskfill' packages. "
+        "Please install teareduce with the 'cleanest' extra dependencies: "
+        "`pip install teareduce[cleanest]`."
+    ) from e
 import numpy as np
+from scipy import ndimage
 from tqdm import tqdm
 
 from .dilatemask import dilatemask
@@ -37,11 +45,12 @@ def interpolate(data, mask_crfound, dilation=0, interp_method=None, npoints=None
         interpolation.
     interp_method : str, optional
         The interpolation method to use. Options are:
-        'x' : Polynomial interpolation in the X direction.
-        'y' : Polynomial interpolation in the Y direction.
-        's' : Surface fit (degree 1) interpolation.
-        'd' : Median of border pixels interpolation.
-        'm' : Mean of border pixels interpolation.
+        'x' : Polynomial interpolation in the X direction using neighbor pixels
+        'y' : Polynomial interpolation in the Y direction using neighbor pixels
+        's' : Surface fit (degree 1) interpolation using neighbor pixels
+        'd' : Median of neighbor pixels interpolation using neighbor pixels
+        'm' : Mean of neighbor pixels interpolation using neighbor pixels
+        'k' : Maskfill method, as described in van Dokkum & Pasha (2024)
     npoints : int, optional
         The number of points to use for interpolation. This
         parameter is relevant for 'x', 'y', 's', 'd', and 'm' methods.
@@ -67,12 +76,14 @@ def interpolate(data, mask_crfound, dilation=0, interp_method=None, npoints=None
     """
     if interp_method is None:
         raise ValueError("interp_method must be specified.")
-    if interp_method not in ["x", "y", "s", "d", "m"]:
+    if interp_method not in ["x", "y", "s", "d", "m", "k"]:
         raise ValueError(f"Unknown interp_method: {interp_method}")
-    if npoints is None:
-        raise ValueError("npoints must be specified.")
-    if degree is None and interp_method in ["x", "y"]:
+    if interp_method in ["x", "y", "s", "d", "m"] and npoints is None:
+        raise ValueError("npoints must be specified for the chosen interp_method.")
+    if interp_method in ["x", "y"] and degree is None:
         raise ValueError("degree must be specified for the chosen interp_method.")
+    if data.shape != mask_crfound.shape:
+        raise ValueError("data and mask_crfound must have the same shape.")
 
     # Apply dilation to the cosmic ray mask if needed
     if dilation > 0:
@@ -93,44 +104,50 @@ def interpolate(data, mask_crfound, dilation=0, interp_method=None, npoints=None
 
     # Fix cosmic rays using the specified interpolation method
     cleaned_data = data.copy()
-    num_cr_cleaned = 0
-    for cr_index in tqdm(range(1, num_features + 1), disable=not debug):
-        if interp_method in ["x", "y"]:
-            if 2 * npoints <= degree:
-                raise ValueError("2*npoints must be greater than degree for polynomial interpolation.")
-            if interp_method == "x":
-                interp_func = interpolation_x
-            else:
-                interp_func = interpolation_y
-            interpolation_performed, _, _ = interp_func(
-                data=cleaned_data,
-                mask_fixed=mask_fixed,
-                cr_labels=cr_labels,
-                cr_index=cr_index,
-                npoints=npoints,
-                degree=degree,
-            )
-            if interpolation_performed:
-                num_cr_cleaned += 1
-        elif interp_method in ["s", "d", "m"]:
-            if interp_method == "s":
-                method = "surface"
-            elif interp_method == "d":
-                method = "median"
-            elif interp_method == "m":
-                method = "mean"
-            interpolation_performed, _, _ = interpolation_a(
-                data=cleaned_data,
-                mask_fixed=mask_fixed,
-                cr_labels=cr_labels,
-                cr_index=cr_index,
-                npoints=npoints,
-                method=method,
-            )
-            if interpolation_performed:
-                num_cr_cleaned += 1
-        else:
-            raise ValueError(f"Unknown interpolation method: {interp_method}")
+    if interp_method == "k":
+        smoothed_output, _ = maskfill(input_image=data, mask=mask_crfound, size=3, operator="median", smooth=True)
+        cleaned_data[mask_crfound] = smoothed_output[mask_crfound]
+        mask_fixed[mask_crfound] = True
+        num_cr_cleaned = num_features
+    elif interp_method in ["x", "y", "s", "d", "m"]:
+        num_cr_cleaned = 0
+        for cr_index in tqdm(range(1, num_features + 1), disable=not debug):
+            if interp_method in ["x", "y"]:
+                if 2 * npoints <= degree:
+                    raise ValueError("2*npoints must be greater than degree for polynomial interpolation.")
+                if interp_method == "x":
+                    interp_func = interpolation_x
+                else:
+                    interp_func = interpolation_y
+                interpolation_performed, _, _ = interp_func(
+                    data=cleaned_data,
+                    mask_fixed=mask_fixed,
+                    cr_labels=cr_labels,
+                    cr_index=cr_index,
+                    npoints=npoints,
+                    degree=degree,
+                )
+                if interpolation_performed:
+                    num_cr_cleaned += 1
+            elif interp_method in ["s", "d", "m"]:
+                if interp_method == "s":
+                    method = "surface"
+                elif interp_method == "d":
+                    method = "median"
+                elif interp_method == "m":
+                    method = "mean"
+                interpolation_performed, _, _ = interpolation_a(
+                    data=cleaned_data,
+                    mask_fixed=mask_fixed,
+                    cr_labels=cr_labels,
+                    cr_index=cr_index,
+                    npoints=npoints,
+                    method=method,
+                )
+                if interpolation_performed:
+                    num_cr_cleaned += 1
+    else:
+        raise ValueError(f"Unknown interpolation method: {interp_method}")
 
     if debug:
         print(f"Number of cosmic rays cleaned............: {num_cr_cleaned:>{len(sdum)}}")