pingmapper 5.3.7__tar.gz → 5.4.1__tar.gz

{pingmapper-5.3.7 → pingmapper-5.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.3.7
+Version: 5.4.1
 Summary: Open-source interface for processing recreation-grade side scan sonar datasets and reproducibly mapping benthic habitat
 Author: Daniel Buscombe
 Author-email: Cameron Bodine <bodine.cs@gmail.email>

{pingmapper-5.3.7 → pingmapper-5.4.1}/pingmapper/class_portstarObj.py

@@ -1199,13 +1199,45 @@ class portstarObj(object):
         # Find ping-wise water column width from min and max depth prediction
         Wp = maxDepths+minDepths
 
-        # Try cropping so water column ~1/3 of target size area
-        WCProp = 1/3
+        # Try cropping so water column ~1/4 of target size area.
+        # Keeping less water column generally improves bed segmentation stability.
+        WCProp = 1/4
 
         # Buffers so we don't crop too much
         WwcBuf = 150
         WsBuf = 150
 
+        # Use instrument depth to constrain max bed search depth when available.
+        # This helps avoid far-range false positives when returns are only valid
+        # near the center (e.g., shallow channels with large configured range).
+        # inst_depth_mult=3.0 means max search depth = 3x instrument depth, which
+        # keeps the water column at roughly 25% of each side's range.
+        inst_depth_mult = 3.0
+
+        if not hasattr(self.port, 'sonMetaDF'):
+            self.port._loadSonMeta()
+        if not hasattr(self.star, 'sonMetaDF'):
+            self.star._loadSonMeta()
+
+        portChunk = self.port.sonMetaDF[self.port.sonMetaDF['chunk_id'] == i]
+        starChunk = self.star.sonMetaDF[self.star.sonMetaDF['chunk_id'] == i]
+
+        portInstM = pd.to_numeric(portChunk['inst_dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+        starInstM = pd.to_numeric(starChunk['inst_dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+        portPixM = pd.to_numeric(portChunk['pixM'], errors='coerce').to_numpy(dtype=float, copy=True)
+        starPixM = pd.to_numeric(starChunk['pixM'], errors='coerce').to_numpy(dtype=float, copy=True)
+
+        portInstPix = np.where((portInstM > 0) & (portPixM > 0), portInstM / portPixM, np.nan)
+        starInstPix = np.where((starInstM > 0) & (starPixM > 0), starInstM / starPixM, np.nan)
+
+        instPix = np.concatenate((portInstPix, starInstPix))
+        validInstPix = instPix[np.isfinite(instPix) & (instPix > 0)]
+        if validInstPix.size > 0:
+            instMedPix = np.nanmedian(validInstPix)
+            maxDepByInst = instMedPix * inst_depth_mult
+            if np.isfinite(maxDepByInst) and maxDepByInst > 0:
+                maxDep = min(maxDep, maxDepByInst)
+
         # Sum Wp to determine area of water column
         WpArea = np.nansum(Wp)
 
@@ -1235,16 +1267,31 @@ class portstarObj(object):
         if Ws > (C-(Wwc/2)):
             Ws = int( C - (Wwc/2) - (W/2) - WsBuf)
 
+        # If Ws is negative, inst_depth * mult exceeds the recorded range.
+        # Pad the far-range side with zeros so the crop proportions are correct.
+        # Zero columns = no acoustic return, which the model interprets as bed,
+        # anchoring the pick at the data boundary when depth approaches range.
+        pad_far = 0
+        if Ws < 0:
+            pad_far = int(-Ws)
+            Ws = 0
+
         # Crop the original sonogram
         ## Port Crop
         lC = Ws # left side crop
         rC = int(C - (Wwc/2)) # right side crop
         portCrop = son3bnd[:, lC:rC,:]
+        if pad_far > 0:
+            _pad = np.zeros((portCrop.shape[0], pad_far, portCrop.shape[2]), dtype=np.uint8)
+            portCrop = np.concatenate((_pad, portCrop), axis=1)  # extend far range (left)
 
         ## Star Crop
         lC = int(C + (Wwc/2)) # left side crop
         rC = int(N - Ws) # right side crop
         starCrop = son3bnd[:, lC:rC, :]
+        if pad_far > 0:
+            _pad = np.zeros((starCrop.shape[0], pad_far, starCrop.shape[2]), dtype=np.uint8)
+            starCrop = np.concatenate((starCrop, _pad), axis=1)  # extend far range (right)
 
 
         ## Concatenate port & star crop
@@ -1277,8 +1324,9 @@ class portstarObj(object):
         # Calculate depth from prediction
         portDepPixCrop, starDepPixCrop = self._findBed(crop_label) # get pixel location of bed
 
-        # add Wwc/2 to get final estimate at original sonogram dimensions
-        portDepPixFinal = np.flip( np.asarray(portDepPixCrop) + int(Wwc/2) )
+        # add Wwc/2 to get final estimate at original sonogram dimensions.
+        # Subtract pad_far from port since padding shifted its columns left.
+        portDepPixFinal = np.flip( np.asarray(portDepPixCrop) + int(Wwc/2) - pad_far )
         starDepPixFinal = np.flip( np.asarray(starDepPixCrop) + int(Wwc/2) )
 
         #############
@@ -1400,6 +1448,34 @@ class portstarObj(object):
             isChunk = son.sonMetaDF['chunk_id'] == chunk
             sonMeta = son.sonMetaDF[isChunk].reset_index()
             acoustic_depth = pd.to_numeric(sonMeta['inst_dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+            acoustic_med = pd.Series(acoustic_depth).rolling(window=31, center=True, min_periods=1).median().to_numpy()
+            acoustic_resid = np.abs(acoustic_depth - acoustic_med)
+            acoustic_valid = np.isfinite(acoustic_depth) & (acoustic_depth > 0)
+            acoustic_bad = np.zeros(acoustic_depth.shape, dtype=bool)
+            if acoustic_valid.any():
+                resid_valid = acoustic_resid[acoustic_valid]
+                resid_center = np.nanmedian(resid_valid)
+                resid_mad = np.nanmedian(np.abs(resid_valid - resid_center))
+                resid_thr = max(0.5, 6.0 * resid_mad if np.isfinite(resid_mad) else 0.5)
+                acoustic_bad |= acoustic_valid & (acoustic_resid > resid_thr)
+
+            if acoustic_depth.size >= 3:
+                prev_step = acoustic_depth[1:-1] - acoustic_depth[:-2]
+                next_step = acoustic_depth[2:] - acoustic_depth[1:-1]
+                step_mag = np.abs(np.concatenate((prev_step, next_step)))
+                step_mag = step_mag[np.isfinite(step_mag)]
+                if step_mag.size > 0:
+                    step_center = np.nanmedian(step_mag)
+                    step_mad = np.nanmedian(np.abs(step_mag - step_center))
+                    jump_thr = max(0.5, 6.0 * step_mad if np.isfinite(step_mad) else 0.5)
+                    acoustic_bad[1:-1] |= (
+                        acoustic_valid[1:-1] & acoustic_valid[:-2] & acoustic_valid[2:] &
+                        (np.abs(prev_step) > jump_thr) &
+                        (np.abs(next_step) > jump_thr) &
+                        ((prev_step * next_step) < 0)
+                    )
+
+            acoustic_depth = np.where(acoustic_bad, np.nan, acoustic_depth)
             acousticBed = np.round(acoustic_depth / sonMeta['pixM'].to_numpy(dtype=float, copy=True), 0)
             acousticBed = acousticBed[np.isfinite(acousticBed) & (acousticBed > 0)]
 
@@ -1407,8 +1483,8 @@ class portstarObj(object):
             # Step 1 : Acoustic Bedpick Filter
             # Use acoustic bed pick to crop image
             if acousticBed.size > 0:
-                bedMin = max(int(np.nanmin(acousticBed)) - 50, 0)
-                bedMax = int(np.nanmax(acousticBed)) + pix_buf
+                bedMin = max(int(np.nanpercentile(acousticBed, 5)) - 50, 0)
+                bedMax = int(np.nanpercentile(acousticBed, 95)) + pix_buf
             else:
                 bedMin = 0
                 bedMax = H
@@ -1570,6 +1646,82 @@ class portstarObj(object):
                 return '0 pixels'
             return str(float(adjDep) / float(valid_pix.iloc[0])) + ' pixels'
 
+        def _rolling_median(vals, window=31):
+            return pd.Series(vals).rolling(window=window, center=True, min_periods=1).median().to_numpy()
+
+        def _flag_depth_outliers(depth, inst_depth=None, inst_depth_mult=None,
+                     resid_floor_m=0.5, jump_floor_m=0.5,
+                     iterative_jump=False):
+            depth = np.asarray(depth, dtype=float)
+            flags = np.zeros(depth.shape, dtype=bool)
+
+            valid = np.isfinite(depth) & (depth > 0)
+            if not valid.any():
+                return flags
+
+            med = _rolling_median(depth)
+            resid = np.abs(depth - med)
+            resid_valid = resid[valid]
+            resid_center = np.nanmedian(resid_valid)
+            resid_mad = np.nanmedian(np.abs(resid_valid - resid_center))
+            resid_thr = max(resid_floor_m, 6.0 * resid_mad if np.isfinite(resid_mad) else resid_floor_m)
+            flags |= valid & (resid > resid_thr)
+
+            if depth.size >= 3:
+                prev_step = depth[1:-1] - depth[:-2]
+                next_step = depth[2:] - depth[1:-1]
+                step_mag = np.abs(np.concatenate((prev_step, next_step)))
+                step_mag = step_mag[np.isfinite(step_mag)]
+                if step_mag.size > 0:
+                    step_center = np.nanmedian(step_mag)
+                    step_mad = np.nanmedian(np.abs(step_mag - step_center))
+                    jump_thr = max(jump_floor_m, 6.0 * step_mad if np.isfinite(step_mad) else jump_floor_m)
+                    spike_mid = (
+                        valid[1:-1] & valid[:-2] & valid[2:] &
+                        (np.abs(prev_step) > jump_thr) &
+                        (np.abs(next_step) > jump_thr) &
+                        ((prev_step * next_step) < 0)
+                    )
+                    flags[1:-1] |= spike_mid
+
+            # Acoustic depth failures often persist as a step change rather than
+            # a single-ping spike (e.g., 2.4 m -> 6.3 m for many consecutive
+            # records). Iteratively flagging the later side of large jumps peels
+            # back those runs until continuity is restored.
+            if iterative_jump:
+                work = depth.copy()
+                max_iter = max(1, depth.size)
+                for _ in range(max_iter):
+                    valid_work = np.isfinite(work) & (work > 0)
+                    valid_idx = np.flatnonzero(valid_work)
+                    if valid_idx.size < 2:
+                        break
+
+                    step_vals = np.abs(np.diff(work[valid_idx]))
+                    step_vals = step_vals[np.isfinite(step_vals)]
+                    if step_vals.size == 0:
+                        break
+
+                    step_center = np.nanmedian(step_vals)
+                    step_mad = np.nanmedian(np.abs(step_vals - step_center))
+                    jump_thr = max(jump_floor_m, 6.0 * step_mad if np.isfinite(step_mad) else jump_floor_m)
+
+                    diffs = np.abs(np.diff(work[valid_idx]))
+                    bad_step_pos = np.flatnonzero(np.isfinite(diffs) & (diffs > jump_thr))
+                    if bad_step_pos.size == 0:
+                        break
+
+                    new_bad_idx = valid_idx[bad_step_pos + 1]
+                    flags[new_bad_idx] = True
+                    work[new_bad_idx] = np.nan
+
+            if inst_depth is not None and inst_depth_mult is not None:
+                inst_depth = np.asarray(inst_depth, dtype=float)
+                inst_valid = np.isfinite(inst_depth) & (inst_depth > 0)
+                flags |= valid & inst_valid & (depth > (inst_depth * inst_depth_mult))
+
+            return flags
+
         def _sync_trackline_depth(beam_obj, beam_df):
             trk_file = os.path.join(beam_obj.metaDir, 'Trackline_Smth_' + beam_obj.beamName + '.csv')
             if not os.path.exists(trk_file):
@@ -1586,6 +1738,8 @@ class portstarObj(object):
                 depth_cols.append('dep_m_smth')
             if 'dep_m_adjBy' in beam_df.columns:
                 depth_cols.append('dep_m_adjBy')
+            if 'dep_m_interp' in beam_df.columns:
+                depth_cols.append('dep_m_interp')
 
             depth_df = beam_df[depth_cols].drop_duplicates(subset=['record_num'], keep='last').set_index('record_num')
             trk_df = trk_df.set_index('record_num')
@@ -1597,6 +1751,8 @@ class portstarObj(object):
                 trk_df['dep_m_smth'] = depth_df['dep_m_smth']
             if 'dep_m_adjBy' in depth_df.columns:
                 trk_df['dep_m_adjBy'] = depth_df['dep_m_adjBy']
+            if 'dep_m_interp' in depth_df.columns:
+                trk_df['dep_m_interp'] = depth_df['dep_m_interp']
 
             trk_df.reset_index().to_csv(trk_file, index=False, float_format='%.14f')
 
@@ -1749,10 +1905,59 @@ class portstarObj(object):
             portDF['dep_m_adjBy'] = _format_depth_adjustment(portDF['pixM'])
             starDF['dep_m_adjBy'] = _format_depth_adjustment(starDF['pixM'])
 
+        # Outlier and jump filtering before interpolation.
+        # detectDep=0: continuity-only acoustic QC.
+        # detectDep=1/2: continuity QC plus instrument-depth proportional cap.
+        portArr = pd.to_numeric(portDF['dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+        starArr = pd.to_numeric(starDF['dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+        portInst = pd.to_numeric(portDF['inst_dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+        starInst = pd.to_numeric(starDF['inst_dep_m'], errors='coerce').to_numpy(dtype=float, copy=True)
+
+        portFlags = np.zeros(portArr.shape, dtype=bool)
+        starFlags = np.zeros(starArr.shape, dtype=bool)
+
+        if detectDep == 0:
+            portFlags |= _flag_depth_outliers(portArr, iterative_jump=True)
+            starFlags |= _flag_depth_outliers(starArr, iterative_jump=True)
+        elif detectDep in (1, 2):
+            portFlags |= _flag_depth_outliers(portArr, portInst, inst_depth_mult=3.0)
+            starFlags |= _flag_depth_outliers(starArr, starInst, inst_depth_mult=3.0)
+
+            # If sides diverge strongly, invalidate the side farther from
+            # instrument depth so interpolation can recover continuity.
+            pair_valid = np.isfinite(portArr) & np.isfinite(starArr) & (portArr > 0) & (starArr > 0)
+            diverge = pair_valid & (np.abs(portArr - starArr) > 5.0)
+            if diverge.any():
+                portErr = np.abs(portArr - portInst)
+                starErr = np.abs(starArr - starInst)
+
+                inst_pair_valid = np.isfinite(portInst) & (portInst > 0) & np.isfinite(starInst) & (starInst > 0)
+                choose_by_inst = diverge & inst_pair_valid
+                portFlags |= choose_by_inst & (portErr >= starErr)
+                starFlags |= choose_by_inst & (starErr > portErr)
+
+                # Fallback for rows without valid instrument depth on one/both sides.
+                fallback = diverge & (~inst_pair_valid)
+                if fallback.any():
+                    pmed = _rolling_median(portArr)
+                    smed = _rolling_median(starArr)
+                    presid = np.abs(portArr - pmed)
+                    sresid = np.abs(starArr - smed)
+                    portFlags |= fallback & (presid >= sresid)
+                    starFlags |= fallback & (sresid > presid)
+
+        portArr[portFlags] = np.nan
+        starArr[starFlags] = np.nan
+        portDF['dep_m'] = portArr
+        starDF['dep_m'] = starArr
+
         # Interpolate over nan's (and set zeros to nan)
         portDep = portDF['dep_m'].to_numpy(copy=True)
         starDep = starDF['dep_m'].to_numpy(copy=True)
 
+        portInterp = np.isnan(portDep) | (portDep == 0)
+        starInterp = np.isnan(starDep) | (starDep == 0)
+
         portDep[portDep == 0] = np.nan
         starDep[starDep == 0] = np.nan
 
@@ -1762,6 +1967,7 @@ class portstarObj(object):
         else:
             portDep[nans] = 0
         portDF['dep_m'] = portDep
+        portDF['dep_m_interp'] = portInterp.astype(np.uint8)
 
         nans, x = np.isnan(starDep), lambda z: z.nonzero()[0]
         if (~nans).any():
@@ -1769,6 +1975,7 @@ class portstarObj(object):
         else:
             starDep[nans] = 0
         starDF['dep_m'] = starDep
+        starDF['dep_m_interp'] = starInterp.astype(np.uint8)
 
         # Export to csv
         portDF.to_csv(self.port.sonMetaFile, index=False, float_format='%.14f')
@@ -1778,18 +1985,23 @@ class portstarObj(object):
 
         try:
             # Take average of both estimates to store with downlooking sonar csv
-            depDF = pd.DataFrame(columns=['dep_m', 'dep_m_Method', 'dep_m_smth', 'dep_m_adjBy'])
+            depDF = pd.DataFrame(columns=['dep_m', 'dep_m_Method', 'dep_m_smth', 'dep_m_adjBy', 'dep_m_interp'])
             depDF['dep_m'] = np.nanmean([portDF['dep_m'].to_numpy(), starDF['dep_m'].to_numpy()], axis=0)
             depDF['dep_m_Method'] = portDF['dep_m_Method']
             depDF['dep_m_smth'] = portDF['dep_m_smth']
             depDF['dep_m_adjBy'] = portDF['dep_m_adjBy']
+            depDF['dep_m_interp'] = np.maximum(
+                pd.to_numeric(portDF['dep_m_interp'], errors='coerce').fillna(0).to_numpy(dtype=np.uint8, copy=True),
+                pd.to_numeric(starDF['dep_m_interp'], errors='coerce').fillna(0).to_numpy(dtype=np.uint8, copy=True)
+            )
         except:
             # In case port and star are not same length
-            depDF = pd.DataFrame(columns=['dep_m', 'dep_m_Method', 'dep_m_smth', 'dep_m_adjBy'])
+            depDF = pd.DataFrame(columns=['dep_m', 'dep_m_Method', 'dep_m_smth', 'dep_m_adjBy', 'dep_m_interp'])
             depDF['dep_m'] = portDF['dep_m']
             depDF['dep_m_Method'] = portDF['dep_m_Method']
             depDF['dep_m_smth'] = portDF['dep_m_smth']
             depDF['dep_m_adjBy'] = portDF['dep_m_adjBy']
+            depDF['dep_m_interp'] = portDF['dep_m_interp']
 
         del portDF, starDF
         gc.collect()

{pingmapper-5.3.7 → pingmapper-5.4.1}/pingmapper/class_sonObj.py

@@ -253,6 +253,13 @@ class sonObj(object):
                           max_speed,
                           aoi,
                           time_table,
+                          dq_table=False,
+                          dq_time_field=False,
+                          dq_flag_field=False,
+                          dq_keep_values=False,
+                          dq_src_utc_offset=0.0,
+                          dq_target_utc_offset=0.0,
+                          dq_time_offset=0.0,
                           ):
         '''
         '''
@@ -284,6 +291,20 @@ class sonObj(object):
         if time_table:
             sonDF = self._filterTime(sonDF, time_table)
 
+        ####################
+        # Data Quality Filter
+        if dq_table:
+            sonDF = self._filterDQ(
+                sonDF,
+                dq_table,
+                dq_time_field,
+                dq_flag_field,
+                dq_keep_values,
+                dq_src_utc_offset,
+                dq_target_utc_offset,
+                dq_time_offset,
+            )
+
         return sonDF
     
     # ======================================================================
@@ -304,6 +325,232 @@ class sonObj(object):
         return df
 
 
+    # ======================================================================
+    def _filterDQ(self,
+                  sonDF,
+                  dq_table,
+                  dq_time_field,
+                  dq_flag_field,
+                  dq_keep_values,
+                  dq_src_utc_offset,
+                  dq_target_utc_offset,
+                  dq_time_offset,
+                  ):
+        '''
+        Filter sonar pings using a data-quality (DQ) log CSV.
+
+        Each row in the DQ log is treated as a state-change event: the flag
+        recorded at time T applies to every sonar ping from T until the next
+        event row. Pings that occur before the first DQ event are removed.
+        '''
+
+        filtDQCol = 'filter_dq'
+        filtCol = 'filter'
+        dqTimeCol = '_dq_ts'
+
+        if not dq_time_field:
+            raise ValueError('dq_time_field is required when dq_table is provided.')
+        if not dq_flag_field:
+            raise ValueError('dq_flag_field is required when dq_table is provided.')
+
+        keep_vals = self._normalizeDQKeepValues(dq_keep_values)
+        if len(keep_vals) == 0:
+            raise ValueError('dq_keep_values must contain at least one value to keep.')
+
+        sonDF = sonDF.copy()
+        sonDF[filtDQCol] = False
+
+        if filtCol not in sonDF.columns:
+            sonDF[filtCol] = True
+
+        dqDF = pd.read_csv(dq_table)
+        missing_cols = [c for c in [dq_time_field, dq_flag_field] if c not in dqDF.columns]
+        if missing_cols:
+            raise ValueError('dqLog missing required column(s): {}'.format(', '.join(missing_cols)))
+
+        dqTimes, dqKind = self._coerceDQTimestampSeries(dqDF[dq_time_field], dq_time_field)
+        sonTimes, sonKind = self._getSonarFilterTimestamp(sonDF)
+
+        if dqKind != sonKind:
+            raise ValueError(
+                'dqLog timestamp type ({}) does not match sonar timestamp type ({}).'.format(dqKind, sonKind)
+            )
+
+        if dqKind == 'datetime':
+            dqTimes = self._shiftDQDatetimeToTargetOffset(
+                dqTimes,
+                dq_src_utc_offset,
+                dq_target_utc_offset,
+            )
+
+        dqDF = dqDF.copy()
+        dqDF[dqTimeCol] = dqTimes
+        dqDF = dqDF[dqDF[dqTimeCol].notna()].copy()
+        if dqDF.empty:
+            raise ValueError('dqLog contained no valid timestamps after parsing {}.'.format(dq_time_field))
+
+        offset = float(dq_time_offset)
+        if sonKind == 'datetime':
+            sonTimes = sonTimes + pd.to_timedelta(offset, unit='s')
+        else:
+            sonTimes = sonTimes + offset
+
+        sonMerge = pd.DataFrame({
+            '_son_idx': sonDF.index,
+            '_son_ts': sonTimes,
+        })
+        sonMerge = sonMerge[sonMerge['_son_ts'].notna()].copy()
+
+        dqDF['_dq_keep'] = dqDF[dq_flag_field].map(self._normalizeDQValue).isin(keep_vals)
+
+        event_state = dqDF[[dqTimeCol, '_dq_keep']].copy()
+        event_state.sort_values(dqTimeCol, inplace=True)
+        event_state = event_state.groupby(dqTimeCol, as_index=False)['_dq_keep'].last()
+
+        keep_idx = self._applyDQEventState(sonMerge, event_state, dqTimeCol)
+
+        sonDF.loc[keep_idx, filtDQCol] = True
+        sonDF[filtCol] = sonDF[filtCol] & sonDF[filtDQCol]
+
+        return sonDF
+
+    # ======================================================================
+    def _normalizeDQKeepValues(self, dq_keep_values):
+
+        if dq_keep_values is False or dq_keep_values is None:
+            return set()
+
+        if isinstance(dq_keep_values, str):
+            dq_keep_values = dq_keep_values.split(',')
+
+        keep_vals = set()
+        for value in dq_keep_values:
+            norm = self._normalizeDQValue(value)
+            if norm:
+                keep_vals.add(norm)
+
+        return keep_vals
+
+    # ======================================================================
+    def _normalizeDQValue(self, value):
+
+        if pd.isna(value):
+            return ''
+        return str(value).strip().lower()
+
+    # ======================================================================
+    def _coerceDQTimestampSeries(self, series, field_name):
+
+        non_na = series.dropna()
+        numeric = pd.to_numeric(series, errors='coerce')
+        if len(non_na) > 0 and numeric.notna().sum() == len(non_na):
+            return numeric, 'numeric'
+
+        dt = pd.to_datetime(series, errors='coerce')
+        if dt.notna().any():
+            try:
+                if dt.dt.tz is not None:
+                    dt = dt.dt.tz_localize(None)
+            except AttributeError:
+                pass
+            return dt, 'datetime'
+
+        if numeric.notna().any():
+            return numeric, 'numeric'
+
+        raise ValueError('Unable to parse dqLog timestamps from column: {}'.format(field_name))
+
+    # ======================================================================
+    def _shiftDQDatetimeToTargetOffset(self,
+                                       dq_times,
+                                       dq_src_utc_offset=False,
+                                       dq_target_utc_offset=False):
+
+        src_offset = self._coerceDQUtcOffset(dq_src_utc_offset, 'dq_src_utc_offset')
+        target_offset = self._coerceDQUtcOffset(dq_target_utc_offset, 'dq_target_utc_offset')
+
+        if src_offset is None and target_offset is None:
+            return dq_times
+
+        if src_offset is None or target_offset is None:
+            raise ValueError(
+                'dq_src_utc_offset and dq_target_utc_offset must both be provided when either is set.'
+            )
+
+        return dq_times + pd.to_timedelta(target_offset - src_offset, unit='h')
+
+    # ======================================================================
+    def _coerceDQUtcOffset(self, value, field_name):
+
+        if value is False or value is None or value == '':
+            return None
+
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            raise ValueError('{} must be a numeric UTC offset in hours.'.format(field_name))
+
+    # ======================================================================
+    def _getSonarFilterTimestamp(self, sonDF):
+
+        if 'date' in sonDF.columns and 'time' in sonDF.columns:
+            dt = pd.to_datetime(
+                sonDF['date'].astype(str).str.strip() + ' ' + sonDF['time'].astype(str).str.strip(),
+                errors='coerce',
+                format='mixed',
+            )
+            if dt.notna().any():
+                try:
+                    if dt.dt.tz is not None:
+                        dt = dt.dt.tz_localize(None)
+                except AttributeError:
+                    pass
+                return dt, 'datetime'
+
+        if 'time' in sonDF.columns:
+            dt = pd.to_datetime(sonDF['time'], errors='coerce', format='mixed')
+            if dt.notna().any():
+                try:
+                    if dt.dt.tz is not None:
+                        dt = dt.dt.tz_localize(None)
+                except AttributeError:
+                    pass
+                return dt, 'datetime'
+
+        if 'time_s' in sonDF.columns:
+            numeric = pd.to_numeric(sonDF['time_s'], errors='coerce')
+            if numeric.notna().any():
+                return numeric, 'numeric'
+
+        raise ValueError('Unable to determine sonar timestamps for dqLog filtering.')
+
+
+    # ======================================================================
+    def _applyDQEventState(self, son, event_state, dqTimeCol):
+        '''
+        Return the subset of sonar indices whose ping timestamp falls within a
+        "keep" state block as defined by the DQ event log.
+
+        Uses np.searchsorted so each ping inherits the state of the most-recent
+        event that preceded it.  Pings before the first event are excluded.
+        '''
+
+        event_times = event_state[dqTimeCol].to_numpy()
+        event_keep  = event_state['_dq_keep'].to_numpy(dtype=bool)
+        son_times   = son['_son_ts'].to_numpy()
+
+        # searchsorted(side='right') - 1 gives index of last event <= ping time
+        event_idx = np.searchsorted(event_times, son_times, side='right') - 1
+
+        # Pings before the first event get event_idx == -1 → exclude
+        valid_idx = event_idx >= 0
+
+        keep_mask = np.zeros(len(son), dtype=bool)
+        keep_mask[valid_idx] = event_keep[event_idx[valid_idx]]
+
+        return son.loc[keep_mask, '_son_idx']
+
+
     # ======================================================================
     def _filterHeading(self,
                        df,