pingmapper 5.4.6__tar.gz → 5.4.9__tar.gz

{pingmapper-5.4.6 → pingmapper-5.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.4.6
+Version: 5.4.9
 Summary: Open-source interface for processing recreation-grade side scan sonar datasets and reproducibly mapping benthic habitat
 Author: Cameron Bodine, Daniel Buscombe, Iury T Simoes-Sousa
 Author-email: bodine.cs@gmail.email
@@ -69,6 +69,15 @@ Dynamic: requires-python
 
 `PINGMapper` is an open-source Python interface for reading and processing side scan sonar datasets and reproducibly mapping benthic habitat features. `PINGMapper` transforms recreation-grade sonar systems (i.e. fishfinders) into scientific data collectors, allowing researchers and citizens alike to reproducibly map their aquatic system with minimal expertise in data processing.
 
+## PING Ecosystem
+
+`PINGMapper` is part of the [**PING Ecosystem**](https://github.com/PINGEcosystem): a coordinated set of tools for installation, conversion, quality checks, and mapping workflows.
+
+- [PINGMapper](https://github.com/CameronBodine/PINGMapper): Core sonar processing and mapping package
+- [PINGInstaller](https://github.com/CameronBodine/PINGInstaller): Recommended installer and environment bootstrap
+- [PINGWizard](https://github.com/CameronBodine/PINGWizard): Point-and-click interface for testing, updates, and routine processing
+- [PINGVerter](https://github.com/CameronBodine/PINGVerter): Sonar data conversion utilities
+
 ## Learn More Now!
 Check out PING-Mapper's [website](https://cameronbodine.github.io/PINGMapper/) for most up to date information:
 
@@ -128,7 +137,7 @@ A manuscript detailing the automated substrate mapping features made availabe in
 
 ### v3.0 - 4.0
 
-Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEcosystem.md) is made possible through mentorship, partnerships, and financial support listed below.
+Continued support for PINGMapper and tools in the [PING Ecosystem](#ping-ecosystem) is made possible through mentorship, partnerships, and financial support listed below.
 
 **Primary Developer:** [Dr. Cameron S. Bodine](https://github.com/CameronBodine)
 
@@ -142,7 +151,24 @@ Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEc
 
 ## Quick Start
 
-### Option A: Conda
+Recommended workflow: install Miniforge, use PINGInstaller to set up the `ping` environment, and launch PINGWizard for testing, updates, and routine processing.
+
+### Recommended: Miniforge + PINGInstaller + PINGWizard
+
+Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions. In short:
+
+```bash
+pip install pinginstaller -U
+python -m pinginstaller
+```
+
+After installation completes, launch PINGWizard using the shortcut created by PINGInstaller, or run:
+
+```bash
+conda run -n ping python -m pingwizard
+```
+
+### Alternative: Direct conda environment
 
 Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions, or simply run:
 
@@ -152,9 +178,9 @@ conda activate ping
 python -m pingmapper gui
 ```
 
-### Option B: Pixi
+### Optional: Pixi
 
-[Pixi](https://pixi.sh) manages all dependencies (including GDAL) automatically from a single `pyproject.toml`.
+[Pixi](https://pixi.sh) is available for users who prefer that workflow, but it is not the recommended installation path.
 
 1. [Install pixi](https://pixi.sh)
 2. Clone and run:
@@ -170,12 +196,18 @@ python -m pingmapper gui
 
 ### Verify Installation
 
-Run a lightweight self-check (same check used in CI):
+Recommended routine verification is to run the included tests from PINGWizard. If you want a prompt-based check, run the lightweight self-check below:
 
 ```bash
 python -m pingmapper check
 ```
 
+Direct unit-test invocation (same lightweight suite run by `check`):
+
+```bash
+python -m unittest pingmapper.test_dq_filter pingmapper.test_cli_self_check -v
+```
+
 Optional longer end-to-end processing validation:
 
 ```bash
@@ -190,9 +222,12 @@ Follow the installation and testing instructions to [Get Started!](https://camer
 
 If you are interested in partnering on future developments, please reach out to [Cameron Bodine](https://cameronbodine.github.io/).
 
-# PING-Mapper is part of the Doodleverse!
-![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
+# PING-Mapper is part of the PING Ecosystem
+
 
-The Doodleverse is an opinionated collection of Python packages designed for geoscientific image segmentation. Find out more on [GitHub](https://github.com/Doodleverse).
+PINGMapper is developed and distributed alongside companion PING tools (PINGInstaller, PINGWizard, and PINGVerter) to provide a complete end-to-end workflow.
 
+PINGMapper also leverages components from the Doodleverse ecosystem for geoscientific image segmentation workflows. Learn more on [GitHub](https://github.com/Doodleverse).
+
+![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
 

{pingmapper-5.4.6 → pingmapper-5.4.9}/README.md

@@ -31,6 +31,15 @@
 
 `PINGMapper` is an open-source Python interface for reading and processing side scan sonar datasets and reproducibly mapping benthic habitat features. `PINGMapper` transforms recreation-grade sonar systems (i.e. fishfinders) into scientific data collectors, allowing researchers and citizens alike to reproducibly map their aquatic system with minimal expertise in data processing.
 
+## PING Ecosystem
+
+`PINGMapper` is part of the [**PING Ecosystem**](https://github.com/PINGEcosystem): a coordinated set of tools for installation, conversion, quality checks, and mapping workflows.
+
+- [PINGMapper](https://github.com/CameronBodine/PINGMapper): Core sonar processing and mapping package
+- [PINGInstaller](https://github.com/CameronBodine/PINGInstaller): Recommended installer and environment bootstrap
+- [PINGWizard](https://github.com/CameronBodine/PINGWizard): Point-and-click interface for testing, updates, and routine processing
+- [PINGVerter](https://github.com/CameronBodine/PINGVerter): Sonar data conversion utilities
+
 ## Learn More Now!
 Check out PING-Mapper's [website](https://cameronbodine.github.io/PINGMapper/) for most up to date information:
 
@@ -90,7 +99,7 @@ A manuscript detailing the automated substrate mapping features made availabe in
 
 ### v3.0 - 4.0
 
-Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEcosystem.md) is made possible through mentorship, partnerships, and financial support listed below.
+Continued support for PINGMapper and tools in the [PING Ecosystem](#ping-ecosystem) is made possible through mentorship, partnerships, and financial support listed below.
 
 **Primary Developer:** [Dr. Cameron S. Bodine](https://github.com/CameronBodine)
 
@@ -104,7 +113,24 @@ Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEc
 
 ## Quick Start
 
-### Option A: Conda
+Recommended workflow: install Miniforge, use PINGInstaller to set up the `ping` environment, and launch PINGWizard for testing, updates, and routine processing.
+
+### Recommended: Miniforge + PINGInstaller + PINGWizard
+
+Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions. In short:
+
+```bash
+pip install pinginstaller -U
+python -m pinginstaller
+```
+
+After installation completes, launch PINGWizard using the shortcut created by PINGInstaller, or run:
+
+```bash
+conda run -n ping python -m pingwizard
+```
+
+### Alternative: Direct conda environment
 
 Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions, or simply run:
 
@@ -114,9 +140,9 @@ conda activate ping
 python -m pingmapper gui
 ```
 
-### Option B: Pixi
+### Optional: Pixi
 
-[Pixi](https://pixi.sh) manages all dependencies (including GDAL) automatically from a single `pyproject.toml`.
+[Pixi](https://pixi.sh) is available for users who prefer that workflow, but it is not the recommended installation path.
 
 1. [Install pixi](https://pixi.sh)
 2. Clone and run:
@@ -132,12 +158,18 @@ python -m pingmapper gui
 
 ### Verify Installation
 
-Run a lightweight self-check (same check used in CI):
+Recommended routine verification is to run the included tests from PINGWizard. If you want a prompt-based check, run the lightweight self-check below:
 
 ```bash
 python -m pingmapper check
 ```
 
+Direct unit-test invocation (same lightweight suite run by `check`):
+
+```bash
+python -m unittest pingmapper.test_dq_filter pingmapper.test_cli_self_check -v
+```
+
 Optional longer end-to-end processing validation:
 
 ```bash
@@ -152,9 +184,12 @@ Follow the installation and testing instructions to [Get Started!](https://camer
 
 If you are interested in partnering on future developments, please reach out to [Cameron Bodine](https://cameronbodine.github.io/).
 
-# PING-Mapper is part of the Doodleverse!
-![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
+# PING-Mapper is part of the PING Ecosystem
+
 
-The Doodleverse is an opinionated collection of Python packages designed for geoscientific image segmentation. Find out more on [GitHub](https://github.com/Doodleverse).
+PINGMapper is developed and distributed alongside companion PING tools (PINGInstaller, PINGWizard, and PINGVerter) to provide a complete end-to-end workflow.
 
+PINGMapper also leverages components from the Doodleverse ecosystem for geoscientific image segmentation workflows. Learn more on [GitHub](https://github.com/Doodleverse).
+
+![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
 

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper/class_mapSubstrateObj.py

@@ -29,7 +29,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-import os, sys
+import os, sys, re
 
 # Add 'pingmapper' to the path, may not need after pypi package...
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -1066,9 +1066,12 @@ class mapSubObj(rectObj):
 
         # Extract chunkID from filename and store in dict
         for n in npzs:
-            c = os.path.basename(n)
-            c = c.split('.')[0]
-            c = int(c.split('_')[-1])
+            c = os.path.splitext(os.path.basename(n))[0]
+            match = re.search(r'_(\d+)$', c)
+            if match is None:
+                continue
+
+            c = int(match.group(1))
             toMap[c] = n
 
         del npzDir, npzs

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper/class_portstarObj.py

@@ -714,8 +714,18 @@ class portstarObj(object):
                 except:
                     pass
 
-            # First built a vrt
-            vrt_options = gdal.BuildVRTOptions(resampleAlg=resampleAlg, bandList = bands_to_use)
+            # For substrate/prediction mosaics, enforce configured map resolution.
+            force_map_res = (not son) and (self.port.pix_res_map != 0)
+            if force_map_res:
+                vrt_options = gdal.BuildVRTOptions(
+                    resampleAlg=resampleAlg,
+                    bandList=bands_to_use,
+                    xRes=self.port.pix_res_map,
+                    yRes=self.port.pix_res_map,
+                    targetAlignedPixels=True,
+                )
+            else:
+                vrt_options = gdal.BuildVRTOptions(resampleAlg=resampleAlg, bandList = bands_to_use)
             gdal.BuildVRT(outVRT, imgs, options=vrt_options)
 
             # Create GeoTiff from vrt
@@ -733,7 +743,10 @@ class portstarObj(object):
             # gdal.Translate(outTIF, ds, xRes=xRes, yRes=yRes, **kwargs)
 
             # Create geotiff
-            gdal.Translate(outTIF, ds, **kwargs)
+            if force_map_res:
+                gdal.Translate(outTIF, ds, xRes=self.port.pix_res_map, yRes=self.port.pix_res_map, **kwargs)
+            else:
+                gdal.Translate(outTIF, ds, **kwargs)
 
             # Generate overviews
             if overview:
@@ -841,7 +854,17 @@ class portstarObj(object):
 
             # Build VRT
             # vrt_options = gdal.BuildVRTOptions(resampleAlg=resampleAlg, bandList = bands, xRes=xRes, yRes=yRes)
-            vrt_options = gdal.BuildVRTOptions(resampleAlg=resampleAlg, bandList = bands_to_use)
+            force_map_res = (not son) and (self.port.pix_res_map != 0)
+            if force_map_res:
+                vrt_options = gdal.BuildVRTOptions(
+                    resampleAlg=resampleAlg,
+                    bandList=bands_to_use,
+                    xRes=self.port.pix_res_map,
+                    yRes=self.port.pix_res_map,
+                    targetAlignedPixels=True,
+                )
+            else:
+                vrt_options = gdal.BuildVRTOptions(resampleAlg=resampleAlg, bandList = bands_to_use)
             gdal.BuildVRT(outVRT, imgs, options=vrt_options)
 
             # Generate overviews
@@ -1981,26 +2004,34 @@ class portstarObj(object):
 
             # 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)
+            # Port and star may have different ping counts; only compare the
+            # overlapping rows.
+            min_len = min(len(portArr), len(starArr))
+            pA = portArr[:min_len]
+            sA = starArr[:min_len]
+            pI = portInst[:min_len]
+            sI = starInst[:min_len]
+
+            pair_valid = np.isfinite(pA) & np.isfinite(sA) & (pA > 0) & (sA > 0)
+            diverge = pair_valid & (np.abs(pA - sA) > 5.0)
             if diverge.any():
-                portErr = np.abs(portArr - portInst)
-                starErr = np.abs(starArr - starInst)
+                portErr = np.abs(pA - pI)
+                starErr = np.abs(sA - sI)
 
-                inst_pair_valid = np.isfinite(portInst) & (portInst > 0) & np.isfinite(starInst) & (starInst > 0)
+                inst_pair_valid = np.isfinite(pI) & (pI > 0) & np.isfinite(sI) & (sI > 0)
                 choose_by_inst = diverge & inst_pair_valid
-                portFlags |= choose_by_inst & (portErr >= starErr)
-                starFlags |= choose_by_inst & (starErr > portErr)
+                portFlags[:min_len] |= choose_by_inst & (portErr >= starErr)
+                starFlags[:min_len] |= 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)
+                    pmed = _rolling_median(pA)
+                    smed = _rolling_median(sA)
+                    presid = np.abs(pA - pmed)
+                    sresid = np.abs(sA - smed)
+                    portFlags[:min_len] |= fallback & (presid >= sresid)
+                    starFlags[:min_len] |= fallback & (sresid > presid)
 
         portArr[portFlags] = np.nan
         starArr[starFlags] = np.nan

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper/class_rectObj.py

@@ -2213,6 +2213,8 @@ class rectObj(sonObj):
                 crs='EPSG:4326',
             ).to_crs(self.humDat['epsg'])
 
+            df[x_col] = df[x_col].astype(float)
+            df[y_col] = df[y_col].astype(float)
             df.loc[need_xy, x_col] = geo.geometry.x.to_numpy()
             df.loc[need_xy, y_col] = geo.geometry.y.to_numpy()
             return df
@@ -2407,7 +2409,7 @@ class rectObj(sonObj):
         NA
         '''
         filterIntensity = False
-        pix_res = self.pix_res_son
+        pix_res = self.pix_res_son if son else self.pix_res_map
         do_resize = True
 
         # # Set pixel resolution
@@ -2784,7 +2786,7 @@ class rectObj(sonObj):
             del out, img
 
             if do_resize:
-                self._pixresResize(gtiff)
+                self._pixresResize(gtiff, son=son)
 
         if self.rect_wcr:
             if son:
@@ -2930,7 +2932,7 @@ class rectObj(sonObj):
             del out
 
             if do_resize:
-                self._pixresResize(gtiff)
+                self._pixresResize(gtiff, son=son)
 
         gc.collect()
 

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper/self_check.py

@@ -20,6 +20,11 @@ REQUIRED_MODULES = [
     "pingverter",
 ]
 
+UNIT_TEST_MODULES = [
+    "pingmapper.test_dq_filter",
+    "pingmapper.test_cli_self_check",
+]
+
 
 def _missing_required_modules() -> list[str]:
     """Return required modules that fail to import."""
@@ -46,7 +51,7 @@ def run_self_check(verbose: bool = True) -> int:
 
     print("Dependency import checks passed.")
 
-    suite = unittest.defaultTestLoader.loadTestsFromName("pingmapper.test_dq_filter")
+    suite = unittest.defaultTestLoader.loadTestsFromNames(UNIT_TEST_MODULES)
     runner = unittest.TextTestRunner(verbosity=2 if verbose else 1)
     result = runner.run(suite)
 

pingmapper-5.4.9/pingmapper/test_cli_self_check.py

@@ -0,0 +1,118 @@
+"""Unit tests for CLI dispatch and self-check behavior."""
+
+import importlib
+import sys
+import types
+import unittest
+from unittest import mock
+
+
+class TestCliDispatch(unittest.TestCase):
+    """Validate command dispatch logic in pingmapper.__main__."""
+
+    def test_main_check_dispatches_to_self_check(self):
+        cli = importlib.import_module('pingmapper.__main__')
+
+        fake_mod = types.ModuleType('pingmapper.self_check')
+        fake_run = mock.Mock(return_value=7)
+        fake_mod.run_self_check = fake_run
+
+        with mock.patch.dict(sys.modules, {'pingmapper.self_check': fake_mod}):
+            result = cli.main('check')
+
+        self.assertEqual(result, 7)
+        fake_run.assert_called_once_with(verbose=True)
+
+    def test_main_test_unit_dispatches_to_self_check(self):
+        cli = importlib.import_module('pingmapper.__main__')
+
+        fake_mod = types.ModuleType('pingmapper.self_check')
+        fake_run = mock.Mock(return_value=3)
+        fake_mod.run_self_check = fake_run
+
+        with mock.patch.dict(sys.modules, {'pingmapper.self_check': fake_mod}):
+            result = cli.main('test_unit')
+
+        self.assertEqual(result, 3)
+        fake_run.assert_called_once_with(verbose=True)
+
+    def test_main_unknown_process_returns_zero(self):
+        cli = importlib.import_module('pingmapper.__main__')
+        self.assertEqual(cli.main('not-a-command'), 0)
+
+    def test_module_sets_default_process_to_gui_when_no_args(self):
+        cli = importlib.import_module('pingmapper.__main__')
+
+        with mock.patch.object(sys, 'argv', ['python']):
+            cli = importlib.reload(cli)
+            self.assertEqual(cli.to_do, 'gui')
+
+    def test_module_uses_first_arg_as_process(self):
+        cli = importlib.import_module('pingmapper.__main__')
+
+        with mock.patch.object(sys, 'argv', ['python', 'check']):
+            cli = importlib.reload(cli)
+            self.assertEqual(cli.to_do, 'check')
+
+
+class TestSelfCheck(unittest.TestCase):
+    """Validate dependency-check and test-run exit code behavior."""
+
+    def test_missing_required_modules_collects_only_failures(self):
+        self_check = importlib.import_module('pingmapper.self_check')
+
+        def _fake_import(name):
+            if name in {'numpy', 'pingwizard'}:
+                raise ImportError('missing')
+            return object()
+
+        with mock.patch.object(self_check.importlib, 'import_module', side_effect=_fake_import):
+            missing = self_check._missing_required_modules()
+
+        self.assertEqual(missing, ['numpy', 'pingwizard'])
+
+    def test_run_self_check_returns_1_when_dependencies_missing(self):
+        self_check = importlib.import_module('pingmapper.self_check')
+
+        with mock.patch.object(self_check, '_missing_required_modules', return_value=['numpy']):
+            code = self_check.run_self_check(verbose=False)
+
+        self.assertEqual(code, 1)
+
+    def test_run_self_check_returns_1_when_tests_fail(self):
+        self_check = importlib.import_module('pingmapper.self_check')
+
+        fake_suite = object()
+        fake_result = types.SimpleNamespace(wasSuccessful=lambda: False)
+        fake_runner = mock.Mock()
+        fake_runner.run.return_value = fake_result
+
+        with mock.patch.object(self_check, '_missing_required_modules', return_value=[]), \
+             mock.patch.object(self_check.unittest.defaultTestLoader, 'loadTestsFromNames', return_value=fake_suite) as load_mock, \
+             mock.patch.object(self_check.unittest, 'TextTestRunner', return_value=fake_runner):
+            code = self_check.run_self_check(verbose=False)
+
+        self.assertEqual(code, 1)
+        load_mock.assert_called_once_with(self_check.UNIT_TEST_MODULES)
+        fake_runner.run.assert_called_once_with(fake_suite)
+
+    def test_run_self_check_returns_0_when_tests_pass(self):
+        self_check = importlib.import_module('pingmapper.self_check')
+
+        fake_suite = object()
+        fake_result = types.SimpleNamespace(wasSuccessful=lambda: True)
+        fake_runner = mock.Mock()
+        fake_runner.run.return_value = fake_result
+
+        with mock.patch.object(self_check, '_missing_required_modules', return_value=[]), \
+             mock.patch.object(self_check.unittest.defaultTestLoader, 'loadTestsFromNames', return_value=fake_suite) as load_mock, \
+             mock.patch.object(self_check.unittest, 'TextTestRunner', return_value=fake_runner):
+            code = self_check.run_self_check(verbose=False)
+
+        self.assertEqual(code, 0)
+        load_mock.assert_called_once_with(self_check.UNIT_TEST_MODULES)
+        fake_runner.run.assert_called_once_with(fake_suite)
+
+
+if __name__ == '__main__':
+    unittest.main()

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper/test_dq_filter.py

@@ -199,5 +199,204 @@ class TestDQFilterEventStateBlocks(unittest.TestCase):
         self.assertEqual(kept, [2, 3, 6])
 
 
+class TestDQFilterValidation(unittest.TestCase):
+    """Input validation and parsing error cases for DQ filtering."""
+
+    def test_missing_dq_time_field_raises(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}])
+        path = _dq_csv([{'ts': 1.0, 'flag': 'Use'}])
+
+        with self.assertRaisesRegex(ValueError, 'dq_time_field is required'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='',
+                dq_flag_field='flag',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+    def test_missing_dq_flag_field_raises(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}])
+        path = _dq_csv([{'ts': 1.0, 'flag': 'Use'}])
+
+        with self.assertRaisesRegex(ValueError, 'dq_flag_field is required'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+    def test_missing_required_csv_column_raises(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}])
+        path = _dq_csv([{'ts': 1.0, 'not_flag': 'Use'}])
+
+        with self.assertRaisesRegex(ValueError, 'dqLog missing required column'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='flag',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+    def test_timestamp_type_mismatch_raises(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}, {'time_s': 3.0}])
+        path = _dq_csv([{'ts': '2024-01-01T00:00:00Z', 'flag': 'Use'}])
+
+        with self.assertRaisesRegex(ValueError, 'timestamp type'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='flag',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+    def test_empty_keep_values_raise(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}])
+        path = _dq_csv([{'ts': 1.0, 'flag': 'Use'}])
+
+        with self.assertRaisesRegex(ValueError, 'dq_keep_values must contain at least one value'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='flag',
+                dq_keep_values=[],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+
+class TestDQKeepValueNormalization(unittest.TestCase):
+    """Normalization of dq_keep_values and DQ flag values."""
+
+    def test_keep_values_normalize_case_and_whitespace(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}, {'time_s': 3.0}])
+        path = _dq_csv([
+            {'ts': 1.5, 'flag': '  usE  '},
+        ])
+
+        result = stub._filterDQ(
+            stub.sonMetaDF,
+            dq_table=path,
+            dq_time_field='ts',
+            dq_flag_field='flag',
+            dq_keep_values='  use  , keep ',
+            dq_src_utc_offset=0.0,
+            dq_target_utc_offset=0.0,
+            dq_time_offset=0.0,
+        )
+
+        kept = list(result[result['filter_dq'] == True].index)
+        self.assertEqual(kept, [1, 2])
+
+
+class TestDQUtcOffsetValidation(unittest.TestCase):
+    """Validation around UTC offset parameters for datetime DQ logs."""
+
+    def test_setting_only_one_utc_offset_raises(self):
+        stub = _make_stub([
+            {'date': '2024-01-01', 'time': '00:00:01', 'time_s': 1.0},
+            {'date': '2024-01-01', 'time': '00:00:02', 'time_s': 2.0},
+        ])
+        path = _dq_csv([
+            {'ts': '2024-01-01 00:00:00', 'flag': 'Use'},
+        ])
+
+        with self.assertRaisesRegex(ValueError, 'must both be provided'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='flag',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset=0.0,
+                dq_target_utc_offset=None,
+                dq_time_offset=0.0,
+            )
+
+    def test_non_numeric_utc_offset_raises(self):
+        stub = _make_stub([
+            {'date': '2024-01-01', 'time': '00:00:01', 'time_s': 1.0},
+            {'date': '2024-01-01', 'time': '00:00:02', 'time_s': 2.0},
+        ])
+        path = _dq_csv([
+            {'ts': '2024-01-01 00:00:00', 'flag': 'Use'},
+        ])
+
+        with self.assertRaisesRegex(ValueError, 'must be a numeric UTC offset'):
+            stub._filterDQ(
+                stub.sonMetaDF,
+                dq_table=path,
+                dq_time_field='ts',
+                dq_flag_field='flag',
+                dq_keep_values=['Use'],
+                dq_src_utc_offset='east',
+                dq_target_utc_offset=0.0,
+                dq_time_offset=0.0,
+            )
+
+
+class TestDQEventBoundaries(unittest.TestCase):
+    """Boundary behavior around event timestamps and duplicate event rows."""
+
+    def test_ping_exactly_at_event_time_kept(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}, {'time_s': 3.0}])
+        path = _dq_csv([
+            {'ts': 2.0, 'flag': 'Use'},
+        ])
+
+        result = stub._filterDQ(
+            stub.sonMetaDF,
+            dq_table=path,
+            dq_time_field='ts',
+            dq_flag_field='flag',
+            dq_keep_values=['Use'],
+            dq_src_utc_offset=0.0,
+            dq_target_utc_offset=0.0,
+            dq_time_offset=0.0,
+        )
+
+        kept = list(result[result['filter_dq'] == True].index)
+        self.assertEqual(kept, [1, 2])
+
+    def test_duplicate_event_timestamp_last_row_wins(self):
+        stub = _make_stub([{'time_s': 1.0}, {'time_s': 2.0}, {'time_s': 3.0}])
+        path = _dq_csv([
+            {'ts': 2.0, 'flag': 'Use'},
+            {'ts': 2.0, 'flag': 'NoUse'},
+        ])
+
+        result = stub._filterDQ(
+            stub.sonMetaDF,
+            dq_table=path,
+            dq_time_field='ts',
+            dq_flag_field='flag',
+            dq_keep_values=['Use'],
+            dq_src_utc_offset=0.0,
+            dq_target_utc_offset=0.0,
+            dq_time_offset=0.0,
+        )
+
+        kept = list(result[result['filter_dq'] == True].index)
+        self.assertEqual(kept, [])
+
+
 if __name__ == '__main__':
     unittest.main()

pingmapper-5.4.9/pingmapper/version.py

@@ -0,0 +1 @@
+__version__ = '5.4.9'

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.4.6
+Version: 5.4.9
 Summary: Open-source interface for processing recreation-grade side scan sonar datasets and reproducibly mapping benthic habitat
 Author: Cameron Bodine, Daniel Buscombe, Iury T Simoes-Sousa
 Author-email: bodine.cs@gmail.email
@@ -69,6 +69,15 @@ Dynamic: requires-python
 
 `PINGMapper` is an open-source Python interface for reading and processing side scan sonar datasets and reproducibly mapping benthic habitat features. `PINGMapper` transforms recreation-grade sonar systems (i.e. fishfinders) into scientific data collectors, allowing researchers and citizens alike to reproducibly map their aquatic system with minimal expertise in data processing.
 
+## PING Ecosystem
+
+`PINGMapper` is part of the [**PING Ecosystem**](https://github.com/PINGEcosystem): a coordinated set of tools for installation, conversion, quality checks, and mapping workflows.
+
+- [PINGMapper](https://github.com/CameronBodine/PINGMapper): Core sonar processing and mapping package
+- [PINGInstaller](https://github.com/CameronBodine/PINGInstaller): Recommended installer and environment bootstrap
+- [PINGWizard](https://github.com/CameronBodine/PINGWizard): Point-and-click interface for testing, updates, and routine processing
+- [PINGVerter](https://github.com/CameronBodine/PINGVerter): Sonar data conversion utilities
+
 ## Learn More Now!
 Check out PING-Mapper's [website](https://cameronbodine.github.io/PINGMapper/) for most up to date information:
 
@@ -128,7 +137,7 @@ A manuscript detailing the automated substrate mapping features made availabe in
 
 ### v3.0 - 4.0
 
-Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEcosystem.md) is made possible through mentorship, partnerships, and financial support listed below.
+Continued support for PINGMapper and tools in the [PING Ecosystem](#ping-ecosystem) is made possible through mentorship, partnerships, and financial support listed below.
 
 **Primary Developer:** [Dr. Cameron S. Bodine](https://github.com/CameronBodine)
 
@@ -142,7 +151,24 @@ Continued support for PINGMapper and tools in the [PING Ecosystem](./docs/PINGEc
 
 ## Quick Start
 
-### Option A: Conda
+Recommended workflow: install Miniforge, use PINGInstaller to set up the `ping` environment, and launch PINGWizard for testing, updates, and routine processing.
+
+### Recommended: Miniforge + PINGInstaller + PINGWizard
+
+Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions. In short:
+
+```bash
+pip install pinginstaller -U
+python -m pinginstaller
+```
+
+After installation completes, launch PINGWizard using the shortcut created by PINGInstaller, or run:
+
+```bash
+conda run -n ping python -m pingwizard
+```
+
+### Alternative: Direct conda environment
 
 Please see [Getting Started](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted) for full instructions, or simply run:
 
@@ -152,9 +178,9 @@ conda activate ping
 python -m pingmapper gui
 ```
 
-### Option B: Pixi
+### Optional: Pixi
 
-[Pixi](https://pixi.sh) manages all dependencies (including GDAL) automatically from a single `pyproject.toml`.
+[Pixi](https://pixi.sh) is available for users who prefer that workflow, but it is not the recommended installation path.
 
 1. [Install pixi](https://pixi.sh)
 2. Clone and run:
@@ -170,12 +196,18 @@ python -m pingmapper gui
 
 ### Verify Installation
 
-Run a lightweight self-check (same check used in CI):
+Recommended routine verification is to run the included tests from PINGWizard. If you want a prompt-based check, run the lightweight self-check below:
 
 ```bash
 python -m pingmapper check
 ```
 
+Direct unit-test invocation (same lightweight suite run by `check`):
+
+```bash
+python -m unittest pingmapper.test_dq_filter pingmapper.test_cli_self_check -v
+```
+
 Optional longer end-to-end processing validation:
 
 ```bash
@@ -190,9 +222,12 @@ Follow the installation and testing instructions to [Get Started!](https://camer
 
 If you are interested in partnering on future developments, please reach out to [Cameron Bodine](https://cameronbodine.github.io/).
 
-# PING-Mapper is part of the Doodleverse!
-![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
+# PING-Mapper is part of the PING Ecosystem
+
 
-The Doodleverse is an opinionated collection of Python packages designed for geoscientific image segmentation. Find out more on [GitHub](https://github.com/Doodleverse).
+PINGMapper is developed and distributed alongside companion PING tools (PINGInstaller, PINGWizard, and PINGVerter) to provide a complete end-to-end workflow.
 
+PINGMapper also leverages components from the Doodleverse ecosystem for geoscientific image segmentation workflows. Learn more on [GitHub](https://github.com/Doodleverse).
+
+![153729377-e16d0679-ca0d-4d0d-a9f9-90306ba2f871](https://github.com/CameronBodine/PINGMapper/assets/54146655/54df6fdd-26a6-4c26-9cab-9fc834e60ed1)
 

{pingmapper-5.4.6 → pingmapper-5.4.9}/pingmapper.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ pingmapper/nonGUI_batch_main.py
 pingmapper/nonGui_main.py
 pingmapper/self_check.py
 pingmapper/test_PINGMapper.py
+pingmapper/test_cli_self_check.py
 pingmapper/test_dq_filter.py
 pingmapper/test_time.py
 pingmapper/version.py

pingmapper-5.4.6/pingmapper/version.py

@@ -1 +0,0 @@
-__version__ = '5.4.6'