pingmapper 5.4.5__tar.gz → 5.4.8__tar.gz

{pingmapper-5.4.5 → pingmapper-5.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.4.5
+Version: 5.4.8
 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:
@@ -168,6 +194,26 @@ python -m pingmapper gui
    pixi run -e full gui    # GUI with ML support
    ```
 
+### Verify Installation
+
+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
+python -m pingmapper test
+```
+
 ## Ready to get started?
 
 Follow the installation and testing instructions to [Get Started!](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted)
@@ -176,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.5 → pingmapper-5.4.8}/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:
@@ -130,6 +156,26 @@ python -m pingmapper gui
    pixi run -e full gui    # GUI with ML support
    ```
 
+### Verify Installation
+
+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
+python -m pingmapper test
+```
+
 ## Ready to get started?
 
 Follow the installation and testing instructions to [Get Started!](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted)
@@ -138,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.5 → pingmapper-5.4.8}/pingmapper/__main__.py

@@ -49,5 +49,12 @@ def main(process):
         from pingmapper.test_PINGMapper import test
         test(2)
 
+    elif process in ('check', 'test_unit'):
+        print('\n\nRunning PINGMapper self-check...\n\n')
+        from pingmapper.self_check import run_self_check
+        return run_self_check(verbose=True)
+
+    return 0
+
 if __name__ == "__main__":
-    main(to_do)
+    sys.exit(main(to_do))

{pingmapper-5.4.5 → pingmapper-5.4.8}/pingmapper/class_portstarObj.py

@@ -1981,26 +1981,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.5 → pingmapper-5.4.8}/pingmapper/class_rectObj.py

@@ -327,10 +327,7 @@ class rectObj(sonObj):
                     if self.egn_stretch > 0:
                         self._egnDoStretch()
 
-            img = self._reserve_zero_for_nodata(
-                self.sonDat,
-                preserve_zeros=(not bool(getattr(self, 'son8bit', False))),
-            )
+            img = self._reserve_zero_for_nodata(self.sonDat, preserve_zeros=True)
             img = self._prepare_export_uint16(img)
             vals = img[img > 0]
             if vals.size == 0:
@@ -1864,10 +1861,7 @@ class rectObj(sonObj):
             col = df[xPix].to_numpy().astype(int)
             data = df[sonCol].to_numpy()
             if son:
-                data = self._reserve_zero_for_nodata(
-                    data,
-                    preserve_zeros=(not bool(getattr(self, 'son8bit', False))),
-                )
+                data = self._reserve_zero_for_nodata(data, preserve_zeros=True)
             apply_post_rect_colormap = use_16bit and self._rect_colormap_selected(son=son)
             source_scale_bounds = None
             if apply_post_rect_colormap:
@@ -2219,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
@@ -2727,10 +2723,7 @@ class rectObj(sonObj):
 
             img = self.sonDat.copy()
             if son:
-                img = self._reserve_zero_for_nodata(
-                    img,
-                    preserve_zeros=(not bool(getattr(self, 'son8bit', False))),
-                )
+                img = self._reserve_zero_for_nodata(img, preserve_zeros=True)
             apply_post_rect_colormap = use_16bit and self._rect_colormap_selected(son=son)
             source_scale_bounds = None
             if apply_post_rect_colormap:
@@ -2821,10 +2814,7 @@ class rectObj(sonObj):
 
             img = self.sonDat
             if son:
-                img = self._reserve_zero_for_nodata(
-                    img,
-                    preserve_zeros=(not bool(getattr(self, 'son8bit', False))),
-                )
+                img = self._reserve_zero_for_nodata(img, preserve_zeros=True)
             apply_post_rect_colormap = son and use_16bit and self._rect_colormap_selected(son=son)
             source_scale_bounds = None
             if apply_post_rect_colormap:

pingmapper-5.4.8/pingmapper/self_check.py

@@ -0,0 +1,67 @@
+"""Lightweight install/runtime checks for CI and end-user validation."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import unittest
+
+
+REQUIRED_MODULES = [
+    "osgeo",
+    "numpy",
+    "pandas",
+    "geopandas",
+    "rasterio",
+    "pyproj",
+    "cv2",
+    "pinginstaller",
+    "pingwizard",
+    "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."""
+    missing = []
+    for mod_name in REQUIRED_MODULES:
+        try:
+            importlib.import_module(mod_name)
+        except Exception:
+            missing.append(mod_name)
+    return missing
+
+
+def run_self_check(verbose: bool = True) -> int:
+    """Run dependency checks and unit tests. Returns process exit code."""
+    print("\nPINGMapper self-check\n")
+
+    missing = _missing_required_modules()
+    if missing:
+        print("Missing required modules:")
+        for name in missing:
+            print(f" - {name}")
+        print("\nSelf-check failed: install appears incomplete.")
+        return 1
+
+    print("Dependency import checks passed.")
+
+    suite = unittest.defaultTestLoader.loadTestsFromNames(UNIT_TEST_MODULES)
+    runner = unittest.TextTestRunner(verbosity=2 if verbose else 1)
+    result = runner.run(suite)
+
+    if not result.wasSuccessful():
+        print("\nSelf-check failed: unit tests did not pass.")
+        return 1
+
+    print("\nSelf-check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_self_check())

{pingmapper-5.4.5 → pingmapper-5.4.8}/pingmapper/test_PINGMapper.py

@@ -72,7 +72,7 @@ def test(ds):
     #     ds = int(sys.argv[1])
     # else:
     #     print("\n\nERROR: \nPlease enter argument to choose which test file to process:")
-    #     print("1 = Short recording \n2 = Long recording \n\nSYNTAX: python test_PINGMapper.py <1 or 2>\n\n")
+    #     print("1 = Short recording \n2 = Long recording \n\nSYNTAX: python -m pingmapper test <1 or 2>\n\n")
     #     sys.exit()
 
     #################
@@ -87,15 +87,15 @@ def test(ds):
         download_name = 'sample_recording'
     else:
         print("\n\nERROR: \nPlease enter argument to choose which test file to process:")
-        print("1 = Short recording \n2 = Long recording \n\nSYNTAX: python test_PINGMapper.py <1 or 2>\n\n")
+        print("1 = Short recording \n2 = Long recording \n\nSYNTAX: python -m pingmapper test <1 or 2>\n\n")
         sys.exit()
 
-    repo_root = PACKAGE_DIR
-    d = os.environ.get(
-        'PINGMAPPER_DATA_DIR',
-        os.path.join(repo_root, '.data'),
-    )
-    exampleDir = os.path.join(d, 'example_data')
+    repo_root = PACKAGE_DIR
+    d = os.environ.get(
+        'PINGMAPPER_DATA_DIR',
+        os.path.join(repo_root, '.data'),
+    )
+    exampleDir = os.path.join(d, 'example_data')
     ds_path = os.path.join(exampleDir, ds_name)
     ds_path = os.path.normpath(ds_path)
 
@@ -122,12 +122,12 @@ def test(ds):
     # Path to data/output
     inFile = ds_path+'.DAT'
     sonPath = ds_path
-    proj_base_dir = os.environ.get(
-        'PINGMAPPER_TEST_OUTPUT_DIR',
-        os.path.join(d, 'test_runs'),
-    )
-
-    projDir = os.path.join(proj_base_dir, 'PINGMapper-'+ds_name)
+    proj_base_dir = os.environ.get(
+        'PINGMAPPER_TEST_OUTPUT_DIR',
+        os.path.join(d, 'test_runs'),
+    )
+
+    projDir = os.path.join(proj_base_dir, 'PINGMapper-'+ds_name)
 
     inFile = os.path.abspath(inFile)
     sonPath = os.path.abspath(sonPath)
@@ -246,7 +246,7 @@ def test(ds):
     if project_mode == 0:
         # Create new project
         if not os.path.exists(projDir):
-            os.makedirs(projDir, exist_ok=False)
+            os.makedirs(projDir, exist_ok=False)
         else:
             projectMode_1_inval()
 
@@ -255,7 +255,7 @@ def test(ds):
         if os.path.exists(projDir):
             shutil.rmtree(projDir)
 
-        os.makedirs(projDir, exist_ok=False)
+        os.makedirs(projDir, exist_ok=False)
 
     elif project_mode == 2:
         # Update project

pingmapper-5.4.8/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.5 → pingmapper-5.4.8}/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.8/pingmapper/version.py

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

{pingmapper-5.4.5 → pingmapper-5.4.8}/pingmapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.4.5
+Version: 5.4.8
 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:
@@ -168,6 +194,26 @@ python -m pingmapper gui
    pixi run -e full gui    # GUI with ML support
    ```
 
+### Verify Installation
+
+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
+python -m pingmapper test
+```
+
 ## Ready to get started?
 
 Follow the installation and testing instructions to [Get Started!](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted)
@@ -176,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.5 → pingmapper-5.4.8}/pingmapper.egg-info/SOURCES.txt

@@ -20,7 +20,9 @@ pingmapper/main_readFiles.py
 pingmapper/main_rectify.py
 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.5 → pingmapper-5.4.8}/pyproject.toml

@@ -105,5 +105,7 @@ full = { features = ["ml"], solve-group = "default" }
 pingmapper = "python -m pingwizard"
 gui = "python -m pingmapper gui"
 gui-batch = "python -m pingmapper gui_batch"
+check = "python -m pingmapper check"
+test-unit = "python -m pingmapper test_unit"
 test = "python -m pingmapper test"
 test-large = "python -m pingmapper test_large"

pingmapper-5.4.5/pingmapper/version.py

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