fix default depth key

Author: mloubout

docs/scan.qmd

@@ -21,3 +21,12 @@ summarises multiple files and returns a
 [pysegy.SegyScan](reference/SegyScan.html#pysegy.SegyScan) that can lazily read data
 for each shot. Use ``by_receiver=True`` to group traces by receiver coordinates
 instead of source coordinates.
+
+Depth field detection
+- The source and receiver depth fields are auto-detected using a fixed
+  priority, not by picking headers with the largest value spread. This reduces
+  surprises with unlikely headers.
+- Source priority: ``SourceDepth`` > ``SourceDatumElevation`` >
+  ``SourceSurfaceElevation`` > ``SourceWaterDepth``.
+- Receiver priority: ``RecGroupElevation`` > ``RecDatumElevation`` >
+  ``GroupWaterDepth``.

pysegy/plotting.py

@@ -276,6 +276,7 @@ def compare_shots(
     cmap: Sequence[str] | str = "gray",
     side_by_side: bool = False,
     chunksize: int = 20,
+    new_fig: bool = False,
     **kw,
 ):
     """
@@ -305,7 +306,7 @@ def compare_shots(
         out1[:, start:start + chunksize] = arr1[:, start:start + chunksize]
     for start in range(chunksize, nrec, 2 * chunksize):
         out2[:, start:start + chunksize] = arr2[:, start:start + chunksize]
-    plot_sdata(out1, spacing, cmap=cmap[0], **kw)
+    plot_sdata(out1, spacing, cmap=cmap[0], new_fig=new_fig, **kw)
     _plot_with_units(
         out2,
         spacing,

pysegy/scan.py

@@ -33,7 +33,7 @@ class ShotRecord:
     path: str
     coordinates: Tuple[float, float, float]
     fileheader: FileHeader
-    rec_depth_key: str = "GroupWaterDepth"
+    rec_depth_key: str = "RecGroupElevation"
     depth_key: str = "SourceDepth"
     by_receiver: bool = False
     segments: List[Tuple[int, int]] = field(default_factory=list)

pysegy/tests/test_extra.py

@@ -173,7 +173,7 @@ def test_source_candidates(self, source_key):
         dest = self._write_block(f"depth_source_{source_key}.segy", headers)
         detected_source, detected_receiver = seg.detect_depth_keys(str(dest))
         assert detected_source == source_key
-        assert detected_receiver == "GroupWaterDepth"
+        assert detected_receiver == "RecGroupElevation"
 
     @pytest.mark.parametrize("receiver_key", _RECEIVER_DEPTH_FIELDS)
     def test_receiver_candidates(self, receiver_key):
@@ -204,7 +204,7 @@ def test_defaults_when_empty(self):
         dest = self._write_block("depth_default.segy", [th])
         source_key, receiver_key = seg.detect_depth_keys(str(dest))
         assert source_key == "SourceDepth"
-        assert receiver_key == "GroupWaterDepth"
+        assert receiver_key == "RecGroupElevation"
 
     def test_detect_depth_keys_with_no_traces(self):
         fh = FileHeader()
@@ -213,7 +213,7 @@ def test_detect_depth_keys_with_no_traces(self):
             seg.write.write_fileheader(f, fh)
         source_key, receiver_key = seg.detect_depth_keys(str(dest))
         assert source_key == "SourceDepth"
-        assert receiver_key == "GroupWaterDepth"
+        assert receiver_key == "RecGroupElevation"
 
     def test_segy_scan_uses_detected_keys(self):
         headers = []

pysegy/utils.py

@@ -33,16 +33,21 @@
 }
 
 _SOURCE_DEPTH_FIELDS: Tuple[str, ...] = (
+    # Likely-first: true source depth when present
     "SourceDepth",
-    "SourceWaterDepth",
+    # Next prefer datum elevation over water depth; surface elevation after
     "SourceDatumElevation",
     "SourceSurfaceElevation",
+    # Least likely candidate
+    "SourceWaterDepth",
 )
 
 _RECEIVER_DEPTH_FIELDS: Tuple[str, ...] = (
-    "GroupWaterDepth",
+    # Prefer receiver group elevation first
     "RecGroupElevation",
     "RecDatumElevation",
+    # Least likely candidate
+    "GroupWaterDepth",
 )
 
 _DEPTH_SENTINELS = {0, 2147483647, -2147483648, 32767, -32768}
@@ -151,6 +156,15 @@ def get_header(
 
 
 def _depth_score(values: Iterable[float]) -> Tuple[int, float]:
+    """
+    Compute a simple quality score for a sequence of depth-like values.
+
+    The score returns a tuple of ``(count, span)`` where ``count`` is the
+    number of non-sentinel entries and ``span`` is the range of the data. This
+    is retained for backwards compatibility but is no longer used to choose the
+    preferred header field. Header selection now follows a fixed priority order
+    and simply checks for the presence of valid (non-zero, non-sentinel) data.
+    """
     cleaned: List[float] = []
     for val in values:
         fval = float(val)
@@ -227,21 +241,27 @@ def detect_depth_keys(
         if not headers:
             return source_key, receiver_key
 
-    best_source_score = (0, 0.0)
+    def _has_valid(values: Iterable[float]) -> bool:
+        """Return True when any non-sentinel, non-zero value is present."""
+        for v in values:
+            fval = float(v)
+            if fval in _DEPTH_SENTINELS:
+                continue
+            if fval != 0.0:
+                return True
+        return False
+
     for candidate in _SOURCE_DEPTH_FIELDS:
         vals = get_header(headers, candidate)
-        score = _depth_score(vals)
-        if score > best_source_score:
-            best_source_score = score
+        if _has_valid(vals):
             source_key = candidate
+            break
 
-    best_receiver_score = (0, 0.0)
     for candidate in _RECEIVER_DEPTH_FIELDS:
         vals = get_header(headers, candidate)
-        score = _depth_score(vals)
-        if score > best_receiver_score:
-            best_receiver_score = score
+        if _has_valid(vals):
             receiver_key = candidate
+            break
 
     return source_key, receiver_key