Add clip_coh_below phase linking parameter to zero out low correlat…

…ion values

src/dolphin/phase_link/_core.py

@@ -65,6 +65,7 @@ def run_phase_linking(
     strides: Strides = DEFAULT_STRIDES,
     use_evd: bool = False,
     beta: float = 0.0,
+    clip_coh_below: float = 0.0,
     reference_idx: int = 0,
     nodata_mask: ArrayLike | None = None,
     mask_input_ps: bool = False,
@@ -96,6 +97,9 @@ def run_phase_linking(
         the EMI algorithm.
     beta : float, optional
         The regularization parameter, by default 0 (no regularization).
+    clip_coh_below : float, optional
+        Snap correlation values in the coherence matrix below this value to 0.
+        Default is 0 (no clipping).
     reference_idx : int, optional
         The index of the (non compressed) reference SLC, by default 0
     nodata_mask : ArrayLike, optional
@@ -191,6 +195,7 @@ def run_phase_linking(
         strides=strides,
         use_evd=use_evd,
         beta=beta,
+        clip_coh_below=clip_coh_below,
         reference_idx=reference_idx,
         neighbor_arrays=neighbor_arrays,
         calc_average_coh=calc_average_coh,
@@ -247,6 +252,7 @@ def run_cpl(
     strides: Strides,
     use_evd: bool = False,
     beta: float = 0,
+    clip_coh_below: float = 0.0,
     reference_idx: int = 0,
     neighbor_arrays: Optional[np.ndarray] = None,
     calc_average_coh: bool = False,
@@ -272,6 +278,9 @@ def run_cpl(
         the EMI algorithm.
     beta : float, optional
         The regularization parameter, by default 0 (no regularization).
+    clip_coh_below : float, optional
+        Snap correlation values in the coherence matrix below this value to 0.
+        Default is 0 (no clipping).
     reference_idx : int, optional
         The index of the (non compressed) reference SLC, by default 0
     use_slc_amp : bool, optional
@@ -328,6 +337,7 @@ def run_cpl(
         C_arrays,
         use_evd=use_evd,
         beta=beta,
+        clip_coh_below=clip_coh_below,
         reference_idx=reference_idx,
     )
     # Get the temporal coherence
@@ -364,6 +374,7 @@ def process_coherence_matrices(
     C_arrays,
     use_evd: bool = False,
     beta: float = 0.0,
+    clip_coh_below: float = 0.0,
     reference_idx: int = 0,
 ) -> tuple[Array, Array, Array]:
     """Estimate the linked phase for a stack of coherence matrices.
@@ -383,6 +394,9 @@ def process_coherence_matrices(
         The regularization parameter for inverting Gamma = |C|
         The regularization is applied as (1 - beta) * Gamma + beta * I
         Default is 0 (no regularization).
+    clip_coh_below : float, optional
+        Snap correlation values in the coherence matrix below this value to 0.
+        Default is 0 (no clipping).
     reference_idx : int, optional
         The index of the reference acquisition, by default 0
         All outputs are multiplied by the conjugate of the data at this index.
@@ -420,6 +434,8 @@ def process_coherence_matrices(
         if beta > 0:
             # Perform regularization
             Gamma = (1 - beta) * Gamma + beta * Id
+        # if clip_coh_below > 0.0:
+        Gamma = jnp.where(Gamma < clip_coh_below, 0, Gamma)
 
         # Attempt to invert Gamma
         cho, is_lower = cho_factor(Gamma)

src/dolphin/workflows/config/_common.py

@@ -106,6 +106,14 @@ class PhaseLinkingOptions(BaseModel, extra="forbid"):
         ge=0.0,
         le=1.0,
     )
+    clip_coh_below: float = Field(
+        0.00,
+        description=(
+            "Snap correlation values in the coherence matrix below this value to 0."
+        ),
+        ge=0.0,
+        le=1.0,
+    )
     shp_method: ShpMethod = ShpMethod.GLRT
     shp_alpha: float = Field(
         0.001,

src/dolphin/workflows/sequential.py

@@ -45,6 +45,7 @@ def run_wrapped_phase_sequential(
     shp_nslc: Optional[int] = None,
     use_evd: bool = False,
     beta: float = 0.00,
+    clip_coh_below: float = 0.0,
     similarity_nearest_n: int | None = None,
     compressed_slc_plan: CompressedSlcPlan = CompressedSlcPlan.ALWAYS_FIRST,
     max_num_compressed: int = 100,
@@ -123,6 +124,7 @@ def already_processed(d: Path, search_ext: str = ".tif") -> bool:
                 strides=strides,
                 use_evd=use_evd,
                 beta=beta,
+                clip_coh_below=clip_coh_below,
                 mask_file=mask_file,
                 ps_mask_file=ps_mask_file,
                 amp_mean_file=amp_mean_file,

src/dolphin/workflows/single.py

@@ -44,6 +44,7 @@ def run_wrapped_phase_single(
     half_window: dict,
     strides: Optional[dict] = None,
     beta: float = 0.00,
+    clip_coh_below: float = 0.0,
     use_evd: bool = False,
     mask_file: Optional[Filename] = None,
     ps_mask_file: Optional[Filename] = None,
@@ -198,6 +199,7 @@ def run_wrapped_phase_single(
                 strides=strides_tup,
                 use_evd=use_evd,
                 beta=beta,
+                clip_coh_below=clip_coh_below,
                 reference_idx=ministack.output_reference_idx,
                 nodata_mask=nodata_mask[in_rows, in_cols],
                 ps_mask=ps_mask[in_rows, in_cols],

src/dolphin/workflows/wrapped_phase.py

@@ -189,18 +189,19 @@ def run(
             strides=strides,
             use_evd=cfg.phase_linking.use_evd,
             beta=cfg.phase_linking.beta,
+            clip_coh_below=cfg.phase_linking.clip_coh_below,
             mask_file=mask_filename,
             ps_mask_file=ps_output,
             amp_mean_file=cfg.ps_options._amp_mean_file,
             amp_dispersion_file=cfg.ps_options._amp_dispersion_file,
             shp_method=cfg.phase_linking.shp_method,
             shp_alpha=cfg.phase_linking.shp_alpha,
             shp_nslc=shp_nslc,
+            baseline_lag=cfg.phase_linking.baseline_lag,
+            compressed_slc_plan=cfg.phase_linking.compressed_slc_plan,
             similarity_nearest_n=similarity_nearest_n,
             cslc_date_fmt=cfg.input_options.cslc_date_fmt,
             block_shape=cfg.worker_settings.block_shape,
-            baseline_lag=cfg.phase_linking.baseline_lag,
-            compressed_slc_plan=cfg.phase_linking.compressed_slc_plan,
             **kwargs,
         )
     # Dump the used options for JSON parsing