core-lens 0.1.dev183__tar.gz → 0.1.dev186__tar.gz

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: core-lens
-Version: 0.1.dev183
+Version: 0.1.dev186
 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.dev183 → core_lens-0.1.dev186}/SKILLS.md

@@ -57,7 +57,9 @@ aoi = AoI(DATA_ROOT, bbox=(76.0, 31.0, 78.0, 33.0))
 aoi = AoI(DATA_ROOT, mws_id="13_551")
 
 # Optional: Override default seasons (kharif, rabi, zaid)
-custom_seasons = SeasonConfig(kharif=("06-01", "10-15"), rabi=("10-16", "02-28"), zaid=("03-01", "05-31"))
+custom_seasons = SeasonConfig(
+    kharif=("06-01", "10-15"), rabi=("10-16", "02-28"), zaid=("03-01", "05-31")
+)
 aoi_custom = AoI(DATA_ROOT, tehsil="Pangi", seasons=custom_seasons)
 ```
 
@@ -78,6 +80,7 @@ spatial_filtered = mws_view.spatial_filter(bbox=(76.5, 31.5, 77.5, 32.5))
 # Temporal Filtering
 # Note: You can filter by exact years, a range of years, or predefined seasons.
 from core_lens.base.view import Season
+
 temporal_view = mws_view.between(year=(2020, 2022), season=Season.KHARIF)
 current_view = mws_view.between(season=Season.CURRENT)
 ```
@@ -98,9 +101,9 @@ annual_result = temporal_view.annual.materialise()
 
 ```python
 # To access underlying data structures:
-df = static_result.df()        # Polars DataFrame (Zero-copy)
-lazy_df = static_result.lazy() # Polars LazyFrame
-gdf = static_result.gdf()      # GeoPandas GeoDataFrame (Heavy!)
+df = static_result.df()  # Polars DataFrame (Zero-copy)
+lazy_df = static_result.lazy()  # Polars LazyFrame
+gdf = static_result.gdf()  # GeoPandas GeoDataFrame (Heavy!)
 ```
 
 ## 5. Computation and Data Manipulation (Result API)
@@ -145,30 +148,53 @@ result.stats.describe(columns=["ndvi", "rainfall"])
 
 # Correlation (pearson, spearman, kendall)
 from core_lens.base.namespaces.stats import CorrelateMethod
-result.stats.correlate(columns=["ndvi", "rainfall"], method=CorrelateMethod.PEARSON, across="entity")
+
+result.stats.correlate(
+    columns=["ndvi", "rainfall"], method=CorrelateMethod.PEARSON, across="entity"
+)
 
 # Hypothesis Testing (t-test, mann-whitney, wilcoxon, ks, chi-square)
 from core_lens.base.namespaces.stats import TestMethod
-result.stats.test(column="cropping_intensity", groups="temperature_zone", method=TestMethod.MANN_WHITNEY)
+
+result.stats.test(
+    column="cropping_intensity",
+    groups="temperature_zone",
+    method=TestMethod.MANN_WHITNEY,
+)
 
 # Change Detection (absolute, percentage, trend)
 from core_lens.base.namespaces.stats import ChangeMethod
-result.stats.change(column="tree_cover", from_period=2018, to_period=2023, method=ChangeMethod.PERCENTAGE)
+
+result.stats.change(
+    column="tree_cover",
+    from_period=2018,
+    to_period=2023,
+    method=ChangeMethod.PERCENTAGE,
+)
 
 # Anomaly Detection
 from core_lens.base.namespaces.stats import AnomalyTsMethod, AnomalyCrossMethod
+
 # Mode 1: Cross-sectional (zscore, iqr, percentile, threshold)
-result.stats.anomaly(column="ndvi", mode="cross_sectional", method=AnomalyCrossMethod.ZSCORE, baseline=(2010, 2020))
+result.stats.anomaly(
+    column="ndvi",
+    mode="cross_sectional",
+    method=AnomalyCrossMethod.ZSCORE,
+    baseline=(2010, 2020),
+)
 # Mode 2: Time-series (stl, cusum, mad)
-result.stats.anomaly(column="ndvi", mode="timeseries", method=AnomalyTsMethod.STL, baseline=(2010, 2018))
+result.stats.anomaly(
+    column="ndvi", mode="timeseries", method=AnomalyTsMethod.STL, baseline=(2010, 2018)
+)
 
 # Similarity Matching (euclidean, cosine, mahalanobis, manhattan)
 from core_lens.base.namespaces.stats import SimilarityMethod
+
 result.stats.similarity(
     target="13_551",
     columns={"rainfall": ("annual", {"year": 2018})},
     method=SimilarityMethod.EUCLIDEAN,
-    top_n=10
+    top_n=10,
 )
 ```
 
@@ -214,6 +240,7 @@ You can extend core-lens with custom entities by subclassing `BaseEntity`.
 ```python
 from core_lens.base import BaseEntity
 
+
 class CustomEntity(BaseEntity):
     @property
     def key_cols(self) -> list[str]:
@@ -231,6 +258,7 @@ class CustomEntity(BaseEntity):
     def annual_path(self) -> str | None:
         return "custom/annual.parquet"
 
+
 AoI.register(CustomEntity)
 ```
 

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/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.dev183'
-__version_tuple__ = version_tuple = (0, 1, 'dev183')
+__version__ = version = '0.1.dev186'
+__version_tuple__ = version_tuple = (0, 1, 'dev186')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/src/core_lens/aoi.py

@@ -20,7 +20,7 @@ from loguru import logger
 
 from core_lens.base.entity import BaseEntity, EntityValidationError
 from core_lens.utils.paths import is_cloud_uri
-from core_lens.utils.polars_utils import cached_read_schema
+from core_lens.utils.polars_utils import cached_read_schema, parquet_scan_path
 
 if TYPE_CHECKING:
     from core_lens.base.view import View
@@ -225,7 +225,9 @@ def _cached_resolve_boundary(
     geom_col = schema.geometry_col
     static_path = candidate._resolve(candidate.static_path)
 
-    lf = pl.scan_parquet(static_path, storage_options=storage_options or None)
+    lf = pl.scan_parquet(
+        parquet_scan_path(static_path), storage_options=storage_options or None
+    )
     filter_expr = pl.lit(True)
     schema_types = cached_read_schema(static_path, storage_options)
     for col, val in entity_kwargs.items():

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/src/core_lens/base/entity.py

@@ -29,7 +29,7 @@ from core_lens.utils.spatial import (
     build_bbox_index,
     exact_spatial_filter,
 )
-from core_lens.utils.polars_utils import cached_read_schema
+from core_lens.utils.polars_utils import cached_read_schema, parquet_scan_path
 
 if TYPE_CHECKING:
     import shapely
@@ -475,7 +475,7 @@ class BaseEntity(ABC):
                 )
 
         # --- Combine attribute and spatial filters into a single lazy pipeline ---
-        lf = pl.scan_parquet(static)
+        lf = pl.scan_parquet(parquet_scan_path(static))
 
         if attr_kwargs:
             filter_expr = pl.lit(True)

core_lens-0.1.dev186/src/core_lens/entities/farms.py

@@ -0,0 +1,63 @@
+from core_lens.base import BaseEntity
+
+
+class FarmEntity(BaseEntity):
+    """Farms entity.
+
+    Backed by:
+    - Static: farms/static
+    - Annual: farms/annual
+    - SubAnnual: farms/sub_annual
+
+    All paths are relative to the AoI ``data_root``.
+    """
+
+    @property
+    def key_cols(self) -> list[str]:
+        """Get the property value.
+
+        Returns:
+            list[str]: The key columns for the entity.
+
+        """
+        return ["farm_id"]
+
+    @property
+    def geometry_col(self) -> str:
+        """Get the property value.
+
+        Returns:
+            str: The geometry column name.
+
+        """
+        return "geometry"
+
+    @property
+    def static_path(self) -> str:
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the static data.
+
+        """
+        return "farms/static.parquet"
+
+    @property
+    def annual_path(self) -> str:
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the annual data.
+
+        """
+        return "farms/annual.parquet"
+
+    @property
+    def sub_annual_path(self) -> str:
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the monthly data.
+
+        """
+        return "farms/sub_annual.parquet"

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/src/core_lens/utils/polars_utils.py

@@ -7,6 +7,8 @@ import functools
 
 import polars as pl
 
+import os
+
 _GPU_AVAILABLE: bool | None = None  # None = not yet probed
 
 
@@ -16,9 +18,34 @@ def _so_key(storage_options: dict[str, Any] | None) -> tuple[tuple[str, Any], ..
     return tuple(sorted(storage_options.items()))
 
 
+def parquet_scan_path(path: str) -> str:
+    """Return a glob-safe path for ``pl.scan_parquet``.
+
+    When *path* is a directory polars will reject it if the directory contains
+    files with mixed extensions (e.g. a ``data_dictionary.csv`` sitting
+    alongside Hive-partitioned ``.parquet`` files).  This helper coerces a bare
+    directory to ``<path>/**/*.parquet`` so only Parquet files are matched.
+
+    Args:
+        path (str): Filesystem path or cloud URI to a Parquet file or directory.
+
+    Returns:
+        str: The original path if it already points to a file, otherwise
+        ``<path>/**/*.parquet``.
+    """
+    if os.path.isdir(path):
+        return os.path.join(path, "**", "*.parquet")
+    return path
+
+
 @functools.cache
 def _cached_schema_internal(path: str, so_key: tuple[tuple[str, Any], ...]) -> Any:
-    return pl.scan_parquet(path, storage_options=dict(so_key) or None).collect_schema()
+    # Coerce bare directory paths to a *.parquet glob so polars doesn't raise
+    # InvalidOperationError when the directory contains mixed-extension files
+    # (e.g. data_dictionary.csv alongside Hive-partitioned .parquet files).
+    return pl.scan_parquet(
+        parquet_scan_path(path), storage_options=dict(so_key) or None
+    ).collect_schema()
 
 
 def cached_read_schema(path: str, storage_options: dict[str, Any] | None = None) -> Any:

{core_lens-0.1.dev183 → core_lens-0.1.dev186}/src/core_lens/utils/spatial.py

@@ -12,6 +12,7 @@ import shapely
 from loguru import logger
 
 from core_lens.utils.paths import is_cloud_uri, path_exists, resolve_fs_and_path
+from core_lens.utils.polars_utils import parquet_scan_path
 
 if TYPE_CHECKING:
     pass
@@ -361,7 +362,7 @@ def exact_spatial_filter(
 
     # Build a lazy scan and push down an inner join to load only required geometries.
     full_df = (
-        pl.scan_parquet(static_path)
+        pl.scan_parquet(parquet_scan_path(static_path))
         .select(key_cols + [geometry_col])
         .join(candidates.select(key_cols).lazy(), on=key_cols, how="semi")
         .collect()
@@ -684,7 +685,7 @@ def point_in_entities(
         static_path: str = entity._resolve(entity.static_path)
 
         geom_df = (
-            pl.scan_parquet(static_path)
+            pl.scan_parquet(parquet_scan_path(static_path))
             .select(key_cols + [geom_col])
             .join(candidates.select(key_cols).lazy(), on=key_cols, how="semi")
             .collect()