tobac 1.6.2__py3-none-any.whl → 1.6.3__py3-none-any.whl

tobac/__init__.py

@@ -6,9 +6,7 @@ if sys.version_info < (3, 7):
     Support for Python versions less than 3.7 is deprecated. 
     Version 1.5 of tobac will require Python 3.7 or later.
    Python {py} detected. \n\n
-    """.format(
-        py=".".join(str(v) for v in sys.version_info[:3])
-    )
+    """.format(py=".".join(str(v) for v in sys.version_info[:3]))
 
     print(warning)
 

tobac/feature_detection.py

@@ -1555,9 +1555,8 @@ def feature_detection_multithreshold(
                 label_fields[i].data[~wh_all_labels] = 0
 
     else:
-        features = None
-        label_fields = None
-        logging.debug("No features detected")
+        features = internal_utils.coordinates.make_empty_features_dataframe(is_3D=is_3D)
+        logging.debug("No features detected; returning empty features DataFrame")
 
     logging.debug("feature detection completed")
 

tobac/segmentation/watershed_segmentation.py

@@ -1258,6 +1258,12 @@ def segmentation(
         name="segmentation_mask",
     ).assign_attrs(threshold=threshold)
 
+    if features is None or features.empty:
+        logging.debug(
+            "No features provided; returning empty segmentation mask and empty features DataFrame"
+        )
+        return segmentation_out_data, features
+
     features_out_list = []
 
     if len(field.coords[time_var_name]) == 1:

tobac/tests/segmentation_tests/test_segmentation.py

@@ -1,6 +1,8 @@
 import pytest
 import tobac.segmentation as seg
 import numpy as np
+import xarray as xr
+import pandas as pd
 from tobac import segmentation, feature_detection, testing
 from tobac.utils import periodic_boundaries as pbc_utils
 
@@ -1181,3 +1183,43 @@ def test_seg_alt_unseed_num(below_thresh, above_thresh, error):
 
         seg_out_arr = seg_output.core_data()
         assert np.all(correct_seg_arr == seg_out_arr)
+
+
+def test_segmentation_returns_early_for_empty_features():
+    """
+    Tests that segmentation exits early and returns an empty segmentation mask and the empty features input when no features are provided.
+    """
+    from tobac.utils.internal import make_empty_features_dataframe
+
+    field = xr.DataArray(
+        np.zeros((2, 10, 12), dtype=float),
+        dims=("time", "y", "x"),
+        coords={"time": pd.date_range("2000-01-01", periods=2, freq="2min")},
+        name="test_field",
+    )
+
+    df = make_empty_features_dataframe(is_3D=False)
+    seg_mask, features_out = seg.segmentation(
+        features=df,
+        field=field,
+        dxy=1000.0,
+        threshold=1.0,
+    )
+
+    # mask exists and is all zeros
+    assert seg_mask.shape == field.shape
+    assert np.all(seg_mask.data == 0)
+
+    # features returned unchanged and still empty
+    assert features_out is df
+    assert features_out.empty
+
+    sef_mask_none, features_out_none = seg.segmentation(
+        features=None,
+        field=field,
+        dxy=1000.0,
+        threshold=1.0,
+    )
+
+    assert np.all(sef_mask_none.data == 0)
+    assert features_out_none is None

tobac/tests/test_feature_detection.py

@@ -5,6 +5,7 @@ import tobac.feature_detection as feat_detect
 import pytest
 import numpy as np
 import xarray as xr
+import pandas as pd
 from pandas.testing import assert_frame_equal
 
 
@@ -1319,3 +1320,92 @@ def test_banded_feature():
     assert len(fd_output) == 1
     assert fd_output.iloc[0]["hdim_1"] == pytest.approx(24.5)
     assert fd_output.iloc[0]["hdim_2"] == pytest.approx(24.5)
+
+
+def test_feature_detection_2d_no_features_returns_empty_df():
+    """
+    Test that 2D feature detection returns an empty, properly formatted DataFrame when no features are detected.
+    """
+    # 2D + time => (time, y, x)
+    data = np.zeros((2, 10, 12), dtype=float)
+    da = xr.DataArray(
+        data,
+        dims=("time", "y", "x"),
+        coords={"time": pd.date_range("2000-01-01", periods=2, freq="2min")},
+        name="field",
+    )
+
+    features = feat_detect.feature_detection_multithreshold(
+        da,
+        dxy=1000.0,
+        threshold=[1e9],
+        return_labels=False,
+    )
+
+    assert isinstance(features, pd.DataFrame)
+    assert features.empty
+
+    expected_cols = [
+        "frame",
+        "idx",
+        "hdim_1",
+        "hdim_2",
+        "num",
+        "threshold_value",
+        "feature",
+        "time",
+        "timestr",
+        "y",
+        "x",
+        "latitude",
+        "longitude",
+    ]
+    assert list(features.columns) == expected_cols
+
+
+def test_feature_detection_3d_no_features_returns_empty_df():
+    """
+    Test that 3D feature detection returns an empty, properly formatted DataFrame when no features are detected.
+    """
+    # 3D + time => (time, z, y, x)
+    data = np.zeros((2, 3, 10, 12), dtype=float)
+    da = xr.DataArray(
+        data,
+        dims=("time", "z", "y", "x"),
+        coords={
+            "time": pd.date_range("2000-01-01", periods=2, freq="2min"),
+            "z": np.arange(3),
+            "y": np.arange(10),
+            "x": np.arange(12),
+        },
+        name="field",
+    )
+
+    features = feat_detect.feature_detection_multithreshold(
+        da,
+        dxy=1000.0,
+        threshold=[1e9],
+        return_labels=False,
+    )
+
+    assert isinstance(features, pd.DataFrame)
+    assert features.empty
+
+    expected_cols = [
+        "frame",
+        "idx",
+        "vdim",
+        "hdim_1",
+        "hdim_2",
+        "num",
+        "threshold_value",
+        "feature",
+        "time",
+        "timestr",
+        "z",
+        "y",
+        "x",
+        "latitude",
+        "longitude",
+    ]
+    assert list(features.columns) == expected_cols

tobac/tests/test_utils_internal.py

@@ -4,6 +4,7 @@ import tobac.testing as tbtest
 import pytest
 import numpy as np
 import xarray as xr
+import pandas.api.types as ptypes
 
 
 @pytest.mark.parametrize(
@@ -95,3 +96,90 @@ def test_detect_latlon_coord_name(
     )
     assert out_lat_name == expected_result[0]
     assert out_lon_name == expected_result[1]
+
+
+def test_make_empty_features_dataframe_2d():
+    """
+    Test that the empty 2D feature DataFrame has the correct columns and dtypes.
+    """
+    df = internal_utils.make_empty_features_dataframe(is_3D=False)
+
+    expected_cols = [
+        "frame",
+        "idx",
+        "hdim_1",
+        "hdim_2",
+        "num",
+        "threshold_value",
+        "feature",
+        "time",
+        "timestr",
+        "y",
+        "x",
+        "latitude",
+        "longitude",
+    ]
+
+    assert list(df.columns) == expected_cols
+    assert df.empty
+
+    assert ptypes.is_integer_dtype(df["frame"].dtype)
+    assert ptypes.is_integer_dtype(df["idx"].dtype)
+    assert ptypes.is_float_dtype(df["hdim_1"].dtype)
+    assert ptypes.is_float_dtype(df["hdim_2"].dtype)
+    assert ptypes.is_integer_dtype(df["num"].dtype)
+    assert ptypes.is_integer_dtype(df["threshold_value"].dtype)
+    assert ptypes.is_integer_dtype(df["feature"].dtype)
+
+    assert ptypes.is_datetime64_ns_dtype(df["time"].dtype)
+    assert df["timestr"].dtype == object
+
+    assert ptypes.is_float_dtype(df["y"].dtype)
+    assert ptypes.is_float_dtype(df["x"].dtype)
+    assert ptypes.is_float_dtype(df["latitude"].dtype)
+    assert ptypes.is_float_dtype(df["longitude"].dtype)
+
+
+def test_make_empty_features_dataframe_3d_schema_and_dtypes():
+    """
+    Test that the empty 3D feature DataFrame has the correct columns and dtypes.
+    """
+    df = internal_utils.make_empty_features_dataframe(is_3D=True)
+
+    expected_cols = [
+        "frame",
+        "idx",
+        "vdim",
+        "hdim_1",
+        "hdim_2",
+        "num",
+        "threshold_value",
+        "feature",
+        "time",
+        "timestr",
+        "z",
+        "y",
+        "x",
+        "latitude",
+        "longitude",
+    ]
+    assert list(df.columns) == expected_cols
+    assert df.empty
+
+    assert ptypes.is_integer_dtype(df["frame"].dtype)
+    assert ptypes.is_integer_dtype(df["idx"].dtype)
+    assert ptypes.is_float_dtype(df["vdim"].dtype)
+    assert ptypes.is_float_dtype(df["hdim_1"].dtype)
+    assert ptypes.is_float_dtype(df["hdim_2"].dtype)
+    assert ptypes.is_integer_dtype(df["num"].dtype)
+    assert ptypes.is_integer_dtype(df["threshold_value"].dtype)
+    assert ptypes.is_integer_dtype(df["feature"].dtype)
+
+    assert ptypes.is_datetime64_ns_dtype(df["time"].dtype)
+    assert df["timestr"].dtype == object
+
+    assert ptypes.is_float_dtype(df["z"].dtype)
+    assert ptypes.is_float_dtype(df["y"].dtype)
+    assert ptypes.is_float_dtype(df["x"].dtype)
+    assert ptypes.is_float_dtype(df["latitude"].dtype)
+    assert ptypes.is_float_dtype(df["longitude"].dtype)

tobac/utils/internal/coordinates.py

@@ -428,3 +428,59 @@ def detect_latlon_coord_name(
                 out_lon = test_lon_name
                 break
     return out_lat, out_lon
+
+
+def make_empty_features_dataframe(is_3D: bool) -> pd.DataFrame:
+    """
+    Create an empty but properly formatted feature DataFrame.
+
+    Returns an empty pandas DataFrame with the same columns and dtypes as the feature detection output.
+    This is used when no features are detected, to ensure a consistent return type and avoid returning ``None``.
+
+    Parameters
+    ----------
+    is_3d : bool
+        Whether the feature detection is 3D. If True, include vertical coordinate columns.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Empty DataFrame with the correct columns and dtypes for feature output.
+    """
+
+    if is_3D:
+        schema = {
+            "frame": "int64",
+            "idx": "int64",
+            "vdim": "float64",
+            "hdim_1": "float64",
+            "hdim_2": "float64",
+            "num": "int64",
+            "threshold_value": "int64",
+            "feature": "int64",
+            "time": "datetime64[ns]",
+            "timestr": "object",
+            "z": "float64",
+            "y": "float64",
+            "x": "float64",
+            "latitude": "float64",
+            "longitude": "float64",
+        }
+    else:
+        schema = {
+            "frame": "int64",
+            "idx": "int64",
+            "hdim_1": "float64",
+            "hdim_2": "float64",
+            "num": "int64",
+            "threshold_value": "int64",
+            "feature": "int64",
+            "time": "datetime64[ns]",
+            "timestr": "object",
+            "y": "float64",
+            "x": "float64",
+            "latitude": "float64",
+            "longitude": "float64",
+        }
+
+    return pd.DataFrame({c: pd.Series(dtype=t) for c, t in schema.items()})

{tobac-1.6.2.dist-info → tobac-1.6.3.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: tobac
-Version: 1.6.2
+Version: 1.6.3
 Summary: A package for identifying and tracking atmospheric phenomena
 Author-email: Max Heikenfeld <max.heikenfeld@physics.ox.ac.uk>, William Jones <william.jones@physics.ox.ac.uk>, Fabian Senf <senf@tropos.de>, Sean Freeman <sean.freeman@uah.edu>, Julia Kukulies <kukulies@ucar.edu>, Kelcy Brunner <Kelcy.Brunner@ttu.edu>, Sven Starzer <sven.starzer@proton.me>
-License-Expression: BSD-3-Clause
+License: BSD-3-Clause
 Project-URL: Homepage, http://github.com/tobac-project/tobac
 Project-URL: Documentation, http://tobac.io
 Project-URL: Issues, http://github.com/tobac-project/tobac/issues
@@ -32,7 +32,7 @@ Requires-Dist: numpy
 Requires-Dist: scipy
 Requires-Dist: scikit-image
 Requires-Dist: scikit-learn
-Requires-Dist: pandas
+Requires-Dist: pandas<3
 Requires-Dist: matplotlib
 Requires-Dist: scitools-iris
 Requires-Dist: xarray
@@ -77,7 +77,7 @@ Requires-Dist: dask; extra == "all"
 Requires-Dist: intake==0.7.0; extra == "all"
 Requires-Dist: intake-xarray==0.7.0; extra == "all"
 Requires-Dist: healpix; extra == "all"
-Requires-Dist: easygems; extra == "all"
+Requires-Dist: easygems==0.1.2; extra == "all"
 Dynamic: license-file
 
 # tobac - Tracking and Object-based Analysis of Clouds

{tobac-1.6.2.dist-info → tobac-1.6.3.dist-info}/RECORD

@@ -1,6 +1,6 @@
-tobac/__init__.py,sha256=Au5BW9GLvQ6zR8GFQWf84MhPNIVPw0PtXC4asKwhHSk,3124
+tobac/__init__.py,sha256=ATNzG0Kt3Nag2yfCR2dWq5GIjR5kpr8kQMcOlJ6I0LI,3110
 tobac/centerofgravity.py,sha256=4aEqK-T3w1zQ1CwqSSyD7AKQpnu3tmGqG8Rsp4ieAcM,7312
-tobac/feature_detection.py,sha256=DVgngbmCYeOFKt9dCrMZ-d7jEtdo44TDi-kmoAETbjw,71504
+tobac/feature_detection.py,sha256=AomXobZ6zU-vs92P4ZTiKmbudvmbUymm9FxbVDglaxg,71577
 tobac/merge_split.py,sha256=Y3jMCkb3IbWztZ9261JDvJMCRdDPT1AO-snDAWe2cjc,12291
 tobac/plotting.py,sha256=PBlISvYu9dWNCdHBNNvkWjC32sPQ04nAFncBIyH4u6Q,78926
 tobac/testing.py,sha256=zj6k0Oag8jEzbcZctQ46fpmLMZolIhshX1DIZ7EoLzg,38842
@@ -11,12 +11,12 @@ tobac/analysis/cell_analysis.py,sha256=0lt-u1qSQylVE_Sy4xYksWPnA83DUoGTzVyPExqsd
 tobac/analysis/feature_analysis.py,sha256=Z23yLxkMR3L7GvPraZ4LNEjHVIo1LcFEHGFWdDc-3hs,6726
 tobac/analysis/spatial.py,sha256=Gryz3N3HYTDkKM3qQBeyJeZac9vuXgrHg1vvJcfcJD4,22774
 tobac/segmentation/__init__.py,sha256=jal-uj581IXyJRJNoor7ktxH_EqDAmnvs5mJDhPSPKQ,225
-tobac/segmentation/watershed_segmentation.py,sha256=J6Yo14HuqjVsunzoORLLw8WVefqn-GpLiIh6mWlDO0o,54848
+tobac/segmentation/watershed_segmentation.py,sha256=JMi70cIFetnNiL5QYOhJq0yJs71lbFuwlam96eNd6Kc,55071
 tobac/tests/test_analysis_spatial.py,sha256=FLl7CJ2N9x7OR1ipON-OhdyMOMiR1egAEShEQoxN7wI,31997
 tobac/tests/test_convert.py,sha256=xOrUPfUCtUlHLAN1HpEp72g5XiOii6bB7U4COQRHSTQ,8821
 tobac/tests/test_datetime.py,sha256=UKQqdA5yHWHYBrqp8ebn82kQZt07Mwh1r0BGNHQ3PZ4,7120
 tobac/tests/test_decorators.py,sha256=Hbus1UPA1uKoAXiDsjITBzZFPwMRb15ete9XawY8ylg,4903
-tobac/tests/test_feature_detection.py,sha256=6BoOf2nTn8cCtyEP-0zNKe5VQjSXrLKLOVem8EI3B0E,38910
+tobac/tests/test_feature_detection.py,sha256=78_PWq-KGktFdjJqiqK8E62G8L0XjEAoJIGsCUOMbK4,41058
 tobac/tests/test_generators.py,sha256=zvbv0DRw9EYFEggjBgNtYvxtOTZUlJBbl_lyO20rl5k,7829
 tobac/tests/test_import.py,sha256=NtyS_dUKIm9eBERHx3H_0x0WUQPB1A5MfnyiJVP1gWc,663
 tobac/tests/test_iris_xarray_match_utils.py,sha256=4ku2ALQxT-2fUQQauNgwlkzYG7-K4ZAafaYt-cW-ljk,7996
@@ -28,10 +28,10 @@ tobac/tests/test_tracking.py,sha256=AIvPuNfrv4mfeq7ZMSPhODbgbZfmIT7SEPPrjkXX0Mo,
 tobac/tests/test_utils.py,sha256=Ep0i-A7n1akEz-XaI6uctBNYYvE6GRuwBRgR8z27asg,22145
 tobac/tests/test_utils_bulk_statistics.py,sha256=w3CtQ3sKSGFD2B-R6Sg50zAerVAUNIIyNmJrYA-_vNs,21398
 tobac/tests/test_utils_coordinates.py,sha256=dDyhrrYDHgjlzOt80QDvsVUARy4719dnbj-qDXPtMJw,11022
-tobac/tests/test_utils_internal.py,sha256=GF6DaEb4C0zCWOTLvB0e-PVhNl0mX_73HXE2BxxI_jc,2985
+tobac/tests/test_utils_internal.py,sha256=ByaSZeuvySw1mPu0jBfwZ4Au6_4Y9HP1_FHm4E_q_x8,5625
 tobac/tests/test_xarray_utils.py,sha256=pAFQ73gN--ph1WTqjgfCTj-u8lw_7448PL-m7Ikex0A,6852
 tobac/tests/segmentation_tests/test_iris_xarray_segmentation.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tobac/tests/segmentation_tests/test_segmentation.py,sha256=qow8b54Rsz4_Gqvu0GIxwdr-AuVxIxsPtckOK-xWFqI,39257
+tobac/tests/segmentation_tests/test_segmentation.py,sha256=jKIR58qEPTMjxCvmkMCG-CvOMf4OYrIwotHubRA6UZg,40443
 tobac/tests/segmentation_tests/test_segmentation_time_pad.py,sha256=HF2VHf0qihisaIK65Zgx1NazCIYqRWqsgQEkk1oEhLs,3432
 tobac/utils/__init__.py,sha256=_Oo5j2RSJimy_MehrN0f4uedvq57chGgbtOcp17Hrwo,627
 tobac/utils/bulk_statistics.py,sha256=1JpL4wUB8kTb0JE3BnnD0GPxfbN_NzeWBymsZULn2NA,15382
@@ -42,12 +42,12 @@ tobac/utils/generators.py,sha256=cqhh9PevrqOWFxZKxLsPOywanuoxULoxDrVOb7QWcD0,323
 tobac/utils/mask.py,sha256=hcqgLs-Bw5WOl6zjDW0q2qNW8z8UfSGM1fb_8L9ysVc,9696
 tobac/utils/periodic_boundaries.py,sha256=pVgXHiRzLX7-8mniOLayh9FTsWVue3QWgW8kpizYay4,14948
 tobac/utils/internal/__init__.py,sha256=R7RSo6H59_VWM5YiwluwwVyhb3hO0xhhr212x8MMC5w,54
-tobac/utils/internal/coordinates.py,sha256=11CQpFakt0R2DtCJZxF68e2zuFGAJUhx7UXd2NBJ-JU,13799
+tobac/utils/internal/coordinates.py,sha256=71WsuGtai3rVp3uSzQgnLqSvSCiOU9v84uUTz78Thiw,15489
 tobac/utils/internal/iris_utils.py,sha256=kvIQmSEnC3e0oZSeOgOZJ9GdGbmSb-jaXtaUUE1AZ8o,17333
 tobac/utils/internal/label_props.py,sha256=3xfnHrjZH_OZ3BAewVvRf3xIzNS5ubPFbsuIg8I8QIQ,2654
 tobac/utils/internal/xarray_utils.py,sha256=8EeG5gDQ8kTyOPSLR3AZTxUeQlgjVUrU9F_RGj9qBBM,14708
-tobac-1.6.2.dist-info/licenses/LICENSE,sha256=K4976MT1KjThzaCHoyvqiMt8QQCS-ldJ5jJXGzUTpHk,1517
-tobac-1.6.2.dist-info/METADATA,sha256=fCoMZqJ3JzIQYnBetaoQa98ZBhuBFTkrMqjVI20A3so,7769
-tobac-1.6.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-tobac-1.6.2.dist-info/top_level.txt,sha256=9D2iec8rq7k-nI49UeTTBQYgBYULzK9HzTf06r-5SEI,6
-tobac-1.6.2.dist-info/RECORD,,
+tobac-1.6.3.dist-info/licenses/LICENSE,sha256=K4976MT1KjThzaCHoyvqiMt8QQCS-ldJ5jJXGzUTpHk,1517
+tobac-1.6.3.dist-info/METADATA,sha256=rOe3pbqJaajIScCfFIjF9_iJ_CKMAtTSa38KknCH-jw,7767
+tobac-1.6.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tobac-1.6.3.dist-info/top_level.txt,sha256=9D2iec8rq7k-nI49UeTTBQYgBYULzK9HzTf06r-5SEI,6
+tobac-1.6.3.dist-info/RECORD,,

{tobac-1.6.2.dist-info → tobac-1.6.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any