core-lens 0.1.dev83__tar.gz → 0.1.dev88__tar.gz

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev83
+Version: 0.1.dev88
 Summary: Query, analyse, and visualise CoreStack's microwatershed and Earth science data through a clean, composable Python API.
 Project-URL: Homepage, https://github.com/ApoorvaKashyap/core-lens
 Project-URL: Issues, https://github.com/ApoorvaKashyap/core-lens/issues

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/src/core_lens/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.dev83'
-__version_tuple__ = version_tuple = (0, 1, 'dev83')
+__version__ = version = '0.1.dev88'
+__version_tuple__ = version_tuple = (0, 1, 'dev88')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/src/core_lens/base/namespaces/plot.py

@@ -7,6 +7,18 @@ from typing import TYPE_CHECKING, Any
 
 
 class SubplotOn(Enum):
+    """Temporal dimensions to split plot data across.
+
+    Used to specify how data should be partitioned into subplots or map layers
+    based on temporal columns added during materialisation.
+
+    Attributes:
+        YEAR: Split data by year.
+        MONTH: Split data by month.
+        SEASON: Split data by meteorological season.
+        SEASON_YEAR: Split data by season and year.
+    """
+
     YEAR = "year"
     MONTH = "month"
     SEASON = "season"

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/src/core_lens/base/namespaces/stats.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from enum import Enum
 from itertools import combinations
 from typing import TYPE_CHECKING, Any, cast
@@ -14,12 +15,30 @@ if TYPE_CHECKING:
 
 
 class CorrelateMethod(Enum):
+    """Correlation methods.
+
+    Attributes:
+        PEARSON: Pearson correlation coefficient.
+        SPEARMAN: Spearman rank correlation.
+        KENDALL: Kendall Tau correlation.
+    """
+
     PEARSON = "pearson"
     SPEARMAN = "spearman"
     KENDALL = "kendall"
 
 
 class TestMethod(Enum):
+    """Statistical hypothesis testing methods.
+
+    Attributes:
+        T_TEST: Student's t-test.
+        MANN_WHITNEY: Mann-Whitney U test.
+        WILCOXON: Wilcoxon signed-rank test.
+        KS: Kolmogorov-Smirnov test.
+        CHI_SQUARE: Chi-square test.
+    """
+
     __test__ = False
     T_TEST = "t-test"
     MANN_WHITNEY = "mann-whitney"
@@ -29,12 +48,29 @@ class TestMethod(Enum):
 
 
 class ChangeMethod(Enum):
+    """Methods for calculating change over time.
+
+    Attributes:
+        ABSOLUTE: Absolute difference between periods.
+        PERCENTAGE: Percentage change between periods.
+        TREND: Linear trend over time.
+    """
+
     ABSOLUTE = "absolute"
     PERCENTAGE = "percentage"
     TREND = "trend"
 
 
 class AnomalyCrossMethod(Enum):
+    """Methods for detecting cross-sectional anomalies.
+
+    Attributes:
+        ZSCORE: Z-score method.
+        IQR: Interquartile range method.
+        PERCENTILE: Percentile-based method.
+        THRESHOLD: Fixed threshold method.
+    """
+
     ZSCORE = "zscore"
     IQR = "iqr"
     PERCENTILE = "percentile"
@@ -42,12 +78,29 @@ class AnomalyCrossMethod(Enum):
 
 
 class AnomalyTsMethod(Enum):
+    """Methods for detecting time-series anomalies.
+
+    Attributes:
+        STL: Seasonal-Trend decomposition using LOESS.
+        CUSUM: Cumulative sum control chart.
+        MAD: Median Absolute Deviation.
+    """
+
     STL = "stl"
     CUSUM = "cusum"
     MAD = "mad"
 
 
 class SimilarityMethod(Enum):
+    """Methods for calculating similarity or distance.
+
+    Attributes:
+        EUCLIDEAN: Euclidean distance.
+        COSINE: Cosine similarity.
+        MAHALANOBIS: Mahalanobis distance.
+        MANHATTAN: Manhattan distance.
+    """
+
     EUCLIDEAN = "euclidean"
     COSINE = "cosine"
     MAHALANOBIS = "mahalanobis"
@@ -871,9 +924,11 @@ class StatsNamespace:
         tidx = ids.index(target)
 
         # z-score normalise before computing distances.
-        means = np.nanmean(mat, axis=0)
-        stds = np.nanstd(mat, axis=0, ddof=1)
-        stds[stds == 0] = 1.0
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            means = np.nanmean(mat, axis=0)
+            stds = np.nanstd(mat, axis=0, ddof=1)
+        stds[np.isnan(stds) | (stds == 0)] = 1.0
         norm = (mat - means) / stds
         tvec = norm[tidx]
 

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/src/core_lens/base/result.py

@@ -235,12 +235,12 @@ class Result:
             )
 
         if by is None:
-            new_data = self.data.group_by(self.key_cols).agg(exprs)
+            new_data = self.data.group_by(self.key_cols).agg(*exprs)
         else:
             # Temporal grouping columns are expected to already exist on the
             # frame (added by the materialisation layer from the time column).
             group_cols = self.key_cols + [by]
-            new_data = self.data.group_by(group_cols).agg(exprs)
+            new_data = self.data.group_by(group_cols).agg(*exprs)
 
         return self._replace(data=new_data)
 

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/src/core_lens/utils/season.py

@@ -81,7 +81,26 @@ def _date_range_expr(time_col: str, start: str, end: str) -> pl.Expr:
     start_date = datetime.date.fromisoformat(start)
     end_date = datetime.date.fromisoformat(end)
     col = pl.col(time_col)
-    return col.is_between(pl.lit(start_date), pl.lit(end_date))
+
+    # We use cast to string to avoid ComputeError when the column is an integer,
+    # but still allow exact date comparison.
+    # For integer year columns (e.g., 2020), cast to string yields "2020".
+    # For date columns, cast to string yields "2020-01-01".
+    # So we compare strings directly! Lexicographical string comparison works perfectly for ISO-8601 dates and 4-digit years.
+    # For year integers, "2020" >= "2020-01-01" is False.
+    # Wait, "2020" < "2020-01-01". So if it's an integer, "2020" will not be between "2020-01-01" and "2023-12-31" because "2020" is less than "2020-01-01".
+    # To fix this, we can extract the year for the integer comparison using a regex or length check.
+    # Better: check the length of the casted string. If 4, it's a year.
+    s_col = col.cast(pl.String)
+    is_year_int = s_col.str.len_bytes() == 4
+
+    # Use strict=False so "2020-01-01" casts to null instead of raising ComputeError
+    year_expr = s_col.cast(pl.Int32, strict=False).is_between(
+        start_date.year, end_date.year
+    )
+    date_expr = s_col.is_between(pl.lit(start), pl.lit(end))
+
+    return pl.when(is_year_int).then(year_expr).otherwise(date_expr)
 
 
 def _season_expr(

{core_lens-0.1.dev83 → core_lens-0.1.dev88}/tests/unit/test_season.py

@@ -31,6 +31,36 @@ class TestResolveTimeFilter:
         assert "date" in str(expr)
         # We can't strictly assert string contents, but we know it's built successfully
 
+    def test_date_range_evaluation_on_types(self, season_config: SeasonConfig) -> None:
+        df = pl.DataFrame(
+            {
+                "year_int": [2019, 2020, 2021],
+                "date_col": [
+                    datetime.date(2019, 6, 1),
+                    datetime.date(2020, 1, 15),
+                    datetime.date(2021, 1, 1),
+                ],
+            }
+        )
+
+        # Test integer year column
+        expr_int = resolve_time_filter(
+            {"start": "2020-01-01", "end": "2020-12-31"},
+            time_col="year_int",
+            season_config=season_config,
+        )
+        res_int = df.filter(expr_int)
+        assert res_int["year_int"].to_list() == [2020]
+
+        # Test Date column
+        expr_date = resolve_time_filter(
+            {"start": "2020-01-01", "end": "2020-12-31"},
+            time_col="date_col",
+            season_config=season_config,
+        )
+        res_date = df.filter(expr_date)
+        assert res_date["year_int"].to_list() == [2020]
+
     def test_season_no_year(self, season_config: SeasonConfig) -> None:
         expr = resolve_time_filter(
             {"season": "kharif"},