PyOPIA 2.16.3__tar.gz → 2.16.4__tar.gz

{pyopia-2.16.3 → pyopia-2.16.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOPIA
-Version: 2.16.3
+Version: 2.16.4
 Summary: A Python Ocean Particle Image Analysis toolbox.
 Project-URL: Repository, https://github.com/sintef/pyopia
 Project-URL: Documentation, https://pyopia.readthedocs.io

pyopia-2.16.4/pyopia/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.16.4"

{pyopia-2.16.3 → pyopia-2.16.4}/pyopia/statistics.py

@@ -1091,6 +1091,125 @@ def vd_to_nd(volume_distribution, dias):
     return number_distribution
 
 
+class PerClassConcentration:
+    """PyOpia pipeline-compatible class for computing per-class number concentrations
+    (in numbers/litre) for each processed image, and appending the result as a
+    timestamp-indexed row to a CSV file.
+
+    Required keys in :class:`pyopia.pipeline.Data`:
+        - :attr:`pyopia.pipeline.Data.stats` (with ``probability_<class>`` columns)
+        - :attr:`pyopia.pipeline.Data.timestamp`
+
+    For every particle in the current image's stats, the most likely class is
+    selected as ``argmax`` over the ``probability_<class>`` columns. Particles
+    whose best-guess probability is below ``probability_threshold`` are counted
+    in an ``unclassified`` column. Counts are divided by the per-image sample
+    volume (computed from pixel size, path length and image dimensions) to give
+    a concentration in numbers/litre.
+
+    A row is appended to ``output_csv`` per image, with the image timestamp as
+    the index. Columns are ``<class_name>`` for each classifier class, plus
+    ``unclassified``, ``total`` and ``sample_volume_L``.
+
+    Both ``pixel_size`` and ``path_length`` are read from the ``general``
+    section of the settings dict (``data['settings']['general']``).
+
+    Parameters
+    ----------
+    output_csv : str
+        Path to the CSV file to write. Parent directory is created if missing.
+    probability_threshold : float, optional
+        Minimum best-guess probability for a particle to count toward its class.
+        Particles below this are counted in the ``unclassified`` column. Default 0.0.
+    overwrite : bool, optional
+        If True, remove any existing ``output_csv`` at construction time so the
+        run starts with a fresh file. Default False (append).
+
+    Returns
+    -------
+    data : :class:`pyopia.pipeline.Data`
+        The pipeline data dict, unchanged.
+
+    Example
+    -------
+    Example config for pipeline usage:
+
+    .. code-block:: toml
+
+        [general]
+        pixel_size = 28
+        path_length = 40
+
+        [steps.classconcentration]
+        pipeline_class = 'pyopia.statistics.PerClassConcentration'
+        output_csv = 'proc/per_class_concentration.csv'
+        probability_threshold = 0.5
+        overwrite = false
+    """
+
+    def __init__(self,
+                 output_csv,
+                 probability_threshold=0.0,
+                 overwrite=False):
+        self.output_csv = output_csv
+        self.probability_threshold = probability_threshold
+
+        outdir = os.path.dirname(self.output_csv)
+        if outdir:
+            os.makedirs(outdir, exist_ok=True)
+
+        if overwrite and os.path.exists(self.output_csv):
+            os.remove(self.output_csv)
+
+    def __call__(self, data):
+        stats = data['stats']
+        timestamp = pd.to_datetime(data['timestamp'])
+        general = data['settings']['general']
+        pixel_size = general['pixel_size']
+        path_length = general['path_length']
+
+        image = data.get('imraw')
+        if image is not None:
+            imy, imx = image.shape[:2]
+        else:
+            imx, imy = 2048, 2448
+
+        sample_volume = get_sample_volume(pixel_size, path_length, imx=imx, imy=imy)
+
+        prob_cols = [c for c in stats.columns if str(c).startswith('probability_')]
+        class_labels = [c[len('probability_'):] for c in prob_cols]
+
+        if len(prob_cols) == 0:
+            logger.warning('PerClassConcentration: no probability_* columns found in stats; '
+                           'writing empty per-class row.')
+
+        counts = {label: 0 for label in class_labels}
+        unclassified = 0
+
+        if not stats.empty and len(prob_cols) > 0:
+            valid = stats.dropna(subset=prob_cols)
+            if len(valid) > 0:
+                probs = valid[prob_cols].to_numpy(dtype=np.float64)
+                best_idx = np.argmax(probs, axis=1)
+                best_value = np.max(probs, axis=1)
+                above = best_value >= self.probability_threshold
+                for i, label in enumerate(class_labels):
+                    counts[label] = int(np.sum((best_idx == i) & above))
+                unclassified = int(np.sum(~above))
+
+        row = {label: counts[label] / sample_volume for label in class_labels}
+        row['unclassified'] = unclassified / sample_volume
+        row['total'] = (sum(counts.values()) + unclassified) / sample_volume
+        row['sample_volume_L'] = sample_volume
+
+        df_row = pd.DataFrame([row], index=pd.DatetimeIndex([timestamp], name='timestamp'))
+
+        write_header = not os.path.exists(self.output_csv)
+        df_row.to_csv(self.output_csv, mode='a', header=write_header)
+
+        return data
+
+
 def vd_to_nc(volume_distribution, dias):
     """calculate number concentration from volume distribution
 

{pyopia-2.16.3 → pyopia-2.16.4}/pyopia/tests/test_pipeline.py

@@ -189,6 +189,77 @@ def test_silcam_pipeline():
                                                      ' Something has altered the number of particles detected')
 
 
+def test_per_class_concentration():
+    '''Verifies PerClassConcentration writes timestamp-indexed per-class
+    number concentrations (numbers/L) to CSV across multiple images.
+    '''
+    import pandas as pd
+    from pyopia.statistics import PerClassConcentration, get_sample_volume
+
+    pixel_size = 28.0
+    path_length = 40.0
+    imy, imx = 2048, 2448
+    sample_volume = get_sample_volume(pixel_size, path_length, imx=imx, imy=imy)
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        output_csv = os.path.join(tempdir, 'sub', 'per_class.csv')
+
+        step = PerClassConcentration(
+            output_csv=output_csv,
+            probability_threshold=0.5,
+            overwrite=True,
+        )
+
+        # Image 1: 2 oil, 1 bubble, 1 below-threshold (unclassified)
+        stats_1 = pd.DataFrame({
+            'equivalent_diameter': [10.0, 12.0, 14.0, 9.0],
+            'probability_oil': [0.9, 0.8, 0.1, 0.4],
+            'probability_bubble': [0.05, 0.15, 0.85, 0.35],
+            'probability_other': [0.05, 0.05, 0.05, 0.25],
+        })
+        ts_1 = pd.Timestamp('2026-05-07T12:00:00')
+
+        # Image 2: empty (placeholder NaN row, like pyopia.process.extract_particles)
+        stats_2 = pd.DataFrame({
+            'equivalent_diameter': [np.nan],
+            'probability_oil': [np.nan],
+            'probability_bubble': [np.nan],
+            'probability_other': [np.nan],
+        })
+        ts_2 = pd.Timestamp('2026-05-07T12:00:01')
+
+        data = {
+            'settings': {'general': {'pixel_size': pixel_size, 'path_length': path_length}},
+            'imraw': np.zeros((imy, imx, 3), dtype=np.uint8),
+        }
+
+        data['stats'] = stats_1
+        data['timestamp'] = ts_1
+        step(data)
+
+        data['stats'] = stats_2
+        data['timestamp'] = ts_2
+        step(data)
+
+        result = pd.read_csv(output_csv, index_col='timestamp', parse_dates=True)
+
+        # Expected concentrations (counts / sample_volume in numbers/L)
+        assert result.shape[0] == 2
+        assert list(result.index) == [ts_1, ts_2]
+        np.testing.assert_allclose(result.loc[ts_1, 'oil'], 2.0 / sample_volume)
+        np.testing.assert_allclose(result.loc[ts_1, 'bubble'], 1.0 / sample_volume)
+        np.testing.assert_allclose(result.loc[ts_1, 'other'], 0.0)
+        np.testing.assert_allclose(result.loc[ts_1, 'unclassified'], 1.0 / sample_volume)
+        np.testing.assert_allclose(result.loc[ts_1, 'total'], 4.0 / sample_volume)
+        np.testing.assert_allclose(result.loc[ts_1, 'sample_volume_L'], sample_volume)
+
+        # Empty image: zero concentrations across the board
+        for col in ['oil', 'bubble', 'other', 'unclassified', 'total']:
+            assert result.loc[ts_2, col] == 0.0
+        np.testing.assert_allclose(result.loc[ts_2, 'sample_volume_L'], sample_volume)
+
+
 if __name__ == "__main__":
     test_holo_pipeline()
     test_silcam_pipeline()
+    test_per_class_concentration()

pyopia-2.16.3/pyopia/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.16.3"