core-lens 0.1.dev164__tar.gz → 0.1.dev168__tar.gz

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/CONTRIBUTING.md

@@ -143,7 +143,7 @@ Examples:
 ```text
 feature/stats-similarity
 feature/plugin-validation
-fix/version-clash-fortnightly
+fix/version-clash-sub-annual
 ```
 
 Workflow:
@@ -204,7 +204,7 @@ Examples:
 
 ```text
 feat: add stats.similarity()
-fix: resolve VersionClashError on fortnightly
+fix: resolve VersionClashError on sub-annual
 docs: add plugin guide
 test: add aggregate validation fixtures
 chore: update ruff

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev164
+Version: 0.1.dev168
 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
@@ -10,10 +10,12 @@ License-File: LICENSE
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: GIS
 Classifier: Topic :: Scientific/Engineering :: Hydrology
-Requires-Python: >=3.13
+Requires-Python: >=3.12
 Requires-Dist: core-lens[core]
 Requires-Dist: core-lens[spatial]
 Provides-Extra: core

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/SKILLS.md

@@ -47,7 +47,7 @@ view.between(season="kharif", year=2020)
 # Materialise into a Result object
 static_result = view.static         # has geometry
 annual_result = view.annual         # no geometry
-fortnightly_result = view.fortnightly # no geometry
+sub_annual_result = view.sub_annual # no geometry
 ```
 
 ## 3. Operations on Results (Compute & Aggregation)
@@ -129,7 +129,7 @@ result.stats.similarity(
     target="13_551",
     columns={
         "rainfall": ("annual", {"year": 2018}),
-        "ndvi": ("fortnightly", {"season": "kharif", "year": 2020})
+        "ndvi": ("sub_annual", {"season": "kharif", "year": 2020})
     },
     method="euclidean",
     top_n=10
@@ -189,8 +189,8 @@ AoI.register(ForestEntity)
 
 ## 9. Execution Environment Context
 
-- **Loading Data**: There is no explicit `AoI.load_data()` method. The `AoI(data_root="...")` constructor acts as the main entry point and defines the directory scope. Data reading happens lazily using Polars `scan_parquet()` when you explicitly call materialization methods like `.static`, `.annual`, or `.fortnightly` on a `View`.
-- **Spatial and Temporal Relationship**: To conserve memory, temporal views (`.annual` and `.fortnightly`) drop geometry columns by default. To establish the spatial relationship between the static boundaries (`mws.parquet`) and the temporal time-series (`annual.parquet`), you use the `Result.with_geometry()` method. This triggers an internal join on the entity's primary key (e.g., `mws_id`) bringing the geometry back into the DataFrame for spatial operations and plotting.
+- **Loading Data**: There is no explicit `AoI.load_data()` method. The `AoI(data_root="...")` constructor acts as the main entry point and defines the directory scope. Data reading happens lazily using Polars `scan_parquet()` when you explicitly call materialization methods like `.static`, `.annual`, or `.sub_annual` on a `View`.
+- **Spatial and Temporal Relationship**: To conserve memory, temporal views (`.annual` and `.sub_annual`) drop geometry columns by default. To establish the spatial relationship between the static boundaries (`mws.parquet`) and the temporal time-series (`annual.parquet`), you use the `Result.with_geometry()` method. This triggers an internal join on the entity's primary key (e.g., `mws_id`) bringing the geometry back into the DataFrame for spatial operations and plotting.
 
 - **Expected Directory Structure**: When initializing `AoI(data_root="data/")`, the library expects a specific folder structure inside the `data_root` for each registered entity. For example, the `MWSEntity` expects:
   ```text
@@ -199,7 +199,7 @@ AoI.register(ForestEntity)
       ├── static/
       │   └── mws.parquet        ← GeoParquet with boundaries
       ├── annual/                ← Directory of Parquets (often partitioned by basin)
-      └── fortnightly/           ← Directory of Parquets (partitioned by year/basin)
+      └── sub-annual/           ← Directory of Parquets (partitioned by year/basin)
   ```
   *(Note: The exact paths for these files/directories are defined within the `BaseEntity` subclasses, e.g., `MWSEntity.static_path`)*
 
@@ -229,9 +229,9 @@ view = aoi.mws.where(ba_name="Barmer")
 temporal_view = view.between(season="kharif", year=2021)
 ```
 
-**5. Materialization:** Trigger the actual Parquet I/O to pull the data into memory by accessing `.static`, `.annual`, or `.fortnightly`.
+**5. Materialization:** Trigger the actual Parquet I/O to pull the data into memory by accessing `.static`, `.annual`, or `.sub_annual`.
 ```python
-result = temporal_view.fortnightly
+result = temporal_view.sub_annual
 ```
 
 **6. Compute & Analysis:** Chain computations, derive metrics, or run statistical tests on the returned `Result`.

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/benchmarks/README.md

@@ -10,7 +10,7 @@ benchmarks/
 ├── run_all.sh                  # Run all benchmarks in sequence
 ├── bench_aoi.py                # AoI init, register, named-boundary resolution
 ├── bench_spatial.py            # build_bbox_index, bbox_intersects_geometry, exact_spatial_filter
-├── bench_view.py               # View.where, spatial_filter, between, materialise (static/annual/fortnightly)
+├── bench_view.py               # View.where, spatial_filter, between, materialise (static/annual/sub-annual)
 ├── bench_result.py             # Result.derive, aggregate, with_geometry, df/gdf
 ├── bench_season.py             # resolve_time_filter, add_temporal_columns, SeasonConfig.season_for
 ├── bench_schema.py             # schema detection (detect, _infer_* helpers)

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/benchmarks/bench_result.py

@@ -7,7 +7,7 @@ Targets:
   - Result.with_geometry()      static-join to attach geometry to non-static result
   - Result.derive()             with_columns expression append
   - Result.aggregate()          group_by + agg (no temporal grouping)
-  - Result.aggregate(by=...)    temporal grouping (annual / fortnightly)
+  - Result.aggregate(by=...)    temporal grouping (annual / sub_annual)
 
 Scalene focuses on:
   - shapely.wkb.loads() in gdf() — Python loop over WKB bytes
@@ -130,7 +130,7 @@ print(
 )
 
 
-# ── Note: meaningful with_geometry() test requires annual/fortnightly result ──
+# ── Note: meaningful with_geometry() test requires annual/sub_annual result ──
 # Uncomment with an MWS entity that has annual_path set:
 
 result_annual = aoi.mws.annual  # no geometry

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/benchmarks/bench_schema.py

@@ -36,7 +36,7 @@ DATA_ROOT = "data/"
 entity = MWSEntity(data_root=DATA_ROOT)
 static_path = entity._resolve(entity.static_path)
 annual_path = entity._resolve(entity.annual_path) if entity.annual_path else None
-fn_path = entity._resolve(entity.fortnightly_path) if entity.fortnightly_path else None
+fn_path = entity._resolve(entity.sub_annual_path) if entity.sub_annual_path else None
 
 
 def _section(title: str) -> None:
@@ -104,7 +104,7 @@ print(
 print(f"Detected time col: {_infer_time_col(schema, static_path)!r}")
 
 
-# ── 5. detect() — cold (no annual/fortnightly) ────────────────────────────────
+# ── 5. detect() — cold (no annual/sub_annual) ────────────────────────────────
 _section("5. detect(static only)  [full detection — cold]")
 REPS = 10
 profile = detect(  # ensure bound before loop
@@ -112,7 +112,7 @@ profile = detect(  # ensure bound before loop
     key_cols=entity.key_cols,
     geometry_col=entity.geometry_col,
     annual_path=None,
-    fortnightly_path=None,
+    sub_annual_path=None,
 )
 t0 = time.perf_counter()
 for _ in range(REPS):
@@ -121,7 +121,7 @@ for _ in range(REPS):
         key_cols=entity.key_cols,
         geometry_col=entity.geometry_col,
         annual_path=None,
-        fortnightly_path=None,
+        sub_annual_path=None,
     )
 t1 = time.perf_counter()
 print(
@@ -133,15 +133,15 @@ print(f"Profile bbox_cols     : {profile.bbox_cols!r}")
 print(f"Profile extra_static  : {profile.extra_static_cols}")
 
 
-# ── 6. detect() — with annual + fortnightly ───────────────────────────────────
+# ── 6. detect() — with annual + sub_annual ───────────────────────────────────
 if annual_path or fn_path:
-    _section("6. detect(static + annual + fortnightly)  [3× schema reads]")
+    _section("6. detect(static + annual + sub_annual)  [3× schema reads]")
     profile_full = detect(  # ensure bound before loop
         static_path=static_path,
         key_cols=entity.key_cols,
         geometry_col=entity.geometry_col,
         annual_path=annual_path,
-        fortnightly_path=fn_path,
+        sub_annual_path=fn_path,
     )
     t0 = time.perf_counter()
     for _ in range(REPS):
@@ -150,7 +150,7 @@ if annual_path or fn_path:
             key_cols=entity.key_cols,
             geometry_col=entity.geometry_col,
             annual_path=annual_path,
-            fortnightly_path=fn_path,
+            sub_annual_path=fn_path,
         )
     t1 = time.perf_counter()
     print(
@@ -158,10 +158,10 @@ if annual_path or fn_path:
         f"({(t1 - t0) / REPS * 1000:.2f} ms/call)"
     )
     print(f"annual_time_col      : {profile_full.annual_time_col!r}")
-    print(f"fortnightly_time_col : {profile_full.fortnightly_time_col!r}")
+    print(f"sub_annual_time_col : {profile_full.sub_annual_time_col!r}")
 else:
     print(
-        "\n[skip] No annual/fortnightly paths on TehsilEntity — add an entity with those paths"
+        "\n[skip] No annual/sub_annual paths on TehsilEntity — add an entity with those paths"
     )
 
 

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/benchmarks/bench_season.py

@@ -6,7 +6,7 @@ Targets:
   - resolve_time_filter()           dict → Polars Expr build (date-range + season modes)
   - _date_range_expr()              expression build for date ranges
   - _season_expr()                  expression build for seasons (year-crossing vs not)
-  - add_temporal_columns()          fortnightly vectorised temporal derivation
+  - add_temporal_columns()          sub_annual vectorised temporal derivation
 
 Scalene focuses on:
   - Python datetime.strptime calls in __post_init__
@@ -35,22 +35,22 @@ from core_lens.utils.season import add_temporal_columns, resolve_time_filter
 START_DATE = date(2010, 1, 1)
 END_DATE = date(2023, 12, 31)
 
-# Number of fortnightly periods between START_DATE and END_DATE (roughly).
-N_FORTNIGHTLY = (END_DATE - START_DATE).days // 14
+# Number of sub_annual periods between START_DATE and END_DATE (roughly).
+N_SUB_ANNUAL = (END_DATE - START_DATE).days // 14
 
-# Representative synthetic fortnightly dataframe for add_temporal_columns.
+# Representative synthetic sub_annual dataframe for add_temporal_columns.
 N_MWS = 500  # number of entity instances (e.g. MWS)
-DATES = [START_DATE + timedelta(days=14 * i) for i in range(N_FORTNIGHTLY)]
-# Long format: N_MWS × N_FORTNIGHTLY rows
+DATES = [START_DATE + timedelta(days=14 * i) for i in range(N_SUB_ANNUAL)]
+# Long format: N_MWS × N_SUB_ANNUAL rows
 _all_dates = DATES * N_MWS
-FORTNIGHTLY_DF = pl.DataFrame(
+SUB_ANNUAL_DF = pl.DataFrame(
     {
         "mws_id": [str(mid) for mid in range(N_MWS) for _ in DATES],
         "date": _all_dates,
-        "ndvi": [0.5] * (N_MWS * N_FORTNIGHTLY),
+        "ndvi": [0.5] * (N_MWS * N_SUB_ANNUAL),
     }
 )
-print(f"Synthetic fortnightly frame: {FORTNIGHTLY_DF.shape}")
+print(f"Synthetic sub_annual frame: {SUB_ANNUAL_DF.shape}")
 
 
 def _section(title: str) -> None:
@@ -162,15 +162,15 @@ print(
 )
 
 
-# ── 8. add_temporal_columns — large fortnightly DataFrame ─────────────────────
-_section(f"8. add_temporal_columns()  [{FORTNIGHTLY_DF.shape[0]:,} rows]")
+# ── 8. add_temporal_columns — large sub_annual DataFrame ─────────────────────
+_section(f"8. add_temporal_columns()  [{SUB_ANNUAL_DF.shape[0]:,} rows]")
 t0 = time.perf_counter()
-result_df = add_temporal_columns(FORTNIGHTLY_DF, "date", cfg)
+result_df = add_temporal_columns(SUB_ANNUAL_DF, "date", cfg)
 t1 = time.perf_counter()
 print(f"add_temporal_columns: {(t1 - t0) * 1000:.2f} ms")
 print(f"Output shape        : {cast(pl.DataFrame, result_df).shape}")
 print(
-    f"New columns added   : {[c for c in cast(pl.DataFrame, result_df).columns if c not in FORTNIGHTLY_DF.columns]}"
+    f"New columns added   : {[c for c in cast(pl.DataFrame, result_df).columns if c not in SUB_ANNUAL_DF.columns]}"
 )
 
 # Second call — all columns already present, should be near-zero.

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/benchmarks/bench_view.py

@@ -4,14 +4,14 @@ Targets:
   - View.where()                attribute filter (Polars semi-join on static file)
   - View.spatial_filter()       STRtree filter narrowing existing keys
   - View.between()              time-filter dict construction (no I/O)
-  - View._materialise()         static / annual / fortnightly Parquet reads
+  - View._materialise()         static / annual / sub_annual Parquet reads
   - View chaining               where → spatial_filter → between → static
 
 Scalene focuses on:
   - scan_with_key_filter()      predicate-pushdown LazyFrame
   - collect_lf()                streaming collect (CPU or GPU)
   - resolve_time_filter()       expression build for time predicates
-  - add_temporal_columns()      fortnightly temporal column derivation
+  - add_temporal_columns()      sub_annual temporal column derivation
 
 Usage:
     uv run scalene run --html --outfile benchmarks/profiles/bench_view.html benchmarks/bench_view.py
@@ -140,12 +140,12 @@ print(f"annual           : {(t1 - t0) * 1000:.2f} ms")
 print(f"Shape            : {result_annual.df().shape}")
 
 
-# ── 11. fortnightly materialisation ───────────────────────────────────────────
-_section("11. aoi_small.mws.fortnightly  [fortnightly materialisation]")
+# ── 11. sub_annual materialisation ───────────────────────────────────────────
+_section("11. aoi_small.mws.sub_annual  [sub_annual materialisation]")
 t0 = time.perf_counter()
-result_fn = aoi_small.mws.between(season=Season.KHARIF, year=2022).fortnightly
+result_fn = aoi_small.mws.between(season=Season.KHARIF, year=2022).sub_annual
 t1 = time.perf_counter()
-print(f"fortnightly      : {(t1 - t0) * 1000:.2f} ms")
+print(f"sub_annual      : {(t1 - t0) * 1000:.2f} ms")
 print(f"Shape            : {result_fn.df().shape}")
 
 

core_lens-0.1.dev168/docs/source/concepts.md

@@ -0,0 +1,7 @@
+# Core Concepts
+
+CoreLens is built on three main layers:
+
+1. **AoI (Area of Interest)**: The primary entry point. It represents a spatial boundary and acts as a gateway to all registered entities that intersect that boundary.
+2. **View**: A lazy, immutable query definition. Filtering by attributes (`where`), space (`spatial_filter`), or time (`between`) returns a new `View` without reading any Parquet data.
+3. **Result**: The lazy computation graph. Accessing `.static`, `.annual`, or `.sub_annual` on a `View` resolves the query plan and returns a `Result` object wrapping a Polars `LazyFrame`. Data is not actually read until you materialise it by calling `.df()` or `.gdf()`. This delays execution and reduces memory footprint, allowing the Polars streaming engine (automatically routed to the GPU if RAPIDS `cudf-polars` is installed) to optimize the query globally. All statistical operations, aggregations, and plotting are done on `Result` objects.

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/docs/source/logging.md

@@ -27,6 +27,6 @@ aoi = AoI("data/", tehsil="Pangi", district="Chamba")
 
 `core_lens` emits logs at different levels depending on the operational context:
 
-- **INFO**: Materialisation events (reading static, annual, or fortnightly Parquet files), entity registrations, AoI initialisation, and cross-entity spatial joins.
+- **INFO**: Materialisation events (reading static, annual, or sub-annual Parquet files), entity registrations, AoI initialisation, and cross-entity spatial joins.
 - **DEBUG**: Sub-operations such as spatial bounding box index generation, exact geometry relationships, lazy attribute filters, and query generation.
 - **ERROR**: Incorrect initialisation arguments, failed path validations, missing geometries, unknown schema structures, or conflicting date configurations.

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/docs/source/queries.md

@@ -11,10 +11,10 @@ annual_data = aoi.mws.between("2010-01-01", "2023-12-31").annual
 # Season-based filtering (defaults to Kharif, Rabi, Zaid)
 from core_lens.base.view import Season
 
-kharif_2020 = aoi.mws.between(season=Season.KHARIF, year=2020).fortnightly
+kharif_2020 = aoi.mws.between(season=Season.KHARIF, year=2020).sub_annual
 
 # Current season based on today's date
-current = aoi.mws.between(season=Season.CURRENT).fortnightly
+current = aoi.mws.between(season=Season.CURRENT).sub_annual
 ```
 
 ## Aggregations & Derived Columns
@@ -31,10 +31,10 @@ derived_res = res_annual.derive(
     pl.when(pl.col("rainfall") < 500).then(1).otherwise(0)
 )
 
-# 2. Aggregate (temporal grouping like "month" requires fortnightly, but "year" works on annual too)
-res_fortnightly = aoi.mws.fortnightly
-monthly_avg = res_fortnightly.aggregate(pl.mean("ndvi"), by="month")
-seasonal_avg = res_fortnightly.aggregate(pl.mean("ndvi"), by="season_year")
+# 2. Aggregate (temporal grouping like "month" requires sub-annual, but "year" works on annual too)
+res_sub_annual = aoi.mws.sub_annual
+monthly_avg = res_sub_annual.aggregate(pl.mean("ndvi"), by="month")
+seasonal_avg = res_sub_annual.aggregate(pl.mean("ndvi"), by="season_year")
 ```
 
 ## Cross-Entity Spatial Joins
@@ -59,5 +59,5 @@ joined_view = aoi.mws.spatial_join(
 ```
 
 ```{note}
-Cross-entity spatial join execution (materialisation) is currently under development and will be added in a subsequent release. Calling materialisation methods (like `.annual`, `.static`, or `.fortnightly`) on a joined view will raise a `NotImplementedError` in the current version.
+Cross-entity spatial join execution (materialisation) is currently under development and will be added in a subsequent release. Calling materialisation methods (like `.annual`, `.static`, or `.sub_annual`) on a joined view will raise a `NotImplementedError` in the current version.
 ```

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/docs/source/stats.md

@@ -107,7 +107,7 @@ similar = res.stats.similarity(
     target="13_551",
     columns={
         "rainfall": ("annual", {"year": 2018}),
-        "ndvi": ("fortnightly", {"season": "kharif", "year": 2020})
+        "ndvi": ("sub_annual", {"season": "kharif", "year": 2020})
     },
     method=SimilarityMethod.EUCLIDEAN,
     top_n=10

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/examples/demo_mws.py

@@ -16,13 +16,13 @@ Data layout expected
         │   └── mws.parquet   ← GeoParquet with WKB geometry in "geom"
         ├── annual/
         │   └── ...           ← Parquet partitioned by year
-        └── fortnightly/
+        └── sub_annual/
             └── ...           ← Parquet partitioned by basin and year
 
 Columns available:
 - Static: mws_id, tehsil, district, state, area_in_ha, ba_name, geometry, etc.
 - Annual: mws_id, year, dw_precipitation, dw_et, ci_cropping_intensity, etc.
-- Fortnightly: mws_id, date, df_precipitation, df_et, season, etc.
+- SubAnnual: mws_id, date, df_precipitation, df_et, season, etc.
 """
 
 from __future__ import annotations
@@ -122,9 +122,9 @@ print("\nDataFrame head (static):")
 print(df_static.select(["mws_id", "tehsil", "district", "state", "area_in_ha"]).head(3))
 
 
-# ── 9. Temporal querying & Materialisation — .annual & .fortnightly ──────────
+# ── 9. Temporal querying & Materialisation — .annual & .sub_annual ──────────
 # Use .between() to specify a time filter (year range, or season)
-# Then use .annual or .fortnightly to materialise
+# Then use .annual or .sub_annual to materialise
 
 # Annual data for a range of years
 view_annual = view_barmer.between("2018-01-01", "2023-12-31")
@@ -133,13 +133,13 @@ print("\nAnnual result columns (first 10):", result_annual.columns[:10])
 print("Resolution            :", result_annual.resolution)
 print("Has geometry          :", result_annual.has_geometry)  # False by default
 
-# Fortnightly data for a specific season and year
-result_fn = view_barmer.between(season=Season.KHARIF, year=2021).fortnightly
-print("\nFortnightly columns (first 10):", result_fn.columns[:10])
+# SubAnnual data for a specific season and year
+result_fn = view_barmer.between(season=Season.KHARIF, year=2021).sub_annual
+print("\nSubAnnual columns (first 10):", result_fn.columns[:10])
 
 
 # ── 10. with_geometry() ──────────────────────────────────────────────────────
-# .annual and .fortnightly lack geometry to save memory. Use with_geometry()
+# .annual and .sub_annual lack geometry to save memory. Use with_geometry()
 # to join geometry from the static table.
 
 result_annual_geo = result_annual.with_geometry()
@@ -174,7 +174,7 @@ print(desc_annual_by_entity.df().head(5))
 
 
 # ── 13. Stats — correlate ────────────────────────────────────────────────────
-# Pairwise correlations on fortnightly data
+# Pairwise correlations on sub_annual data
 corr = result_fn.stats.correlate(
     columns=["df_precipitation", "df_et"],
     method=CorrelateMethod.PEARSON,
@@ -197,7 +197,7 @@ print(test_result.df())
 
 
 # ── 15. Stats — change ───────────────────────────────────────────────────────
-# Computes change over time. Perfect for annual/fortnightly results!
+# Computes change over time. Perfect for annual/sub_annual results!
 
 change_result = result_annual.stats.change(
     column="dw_et",
@@ -302,12 +302,12 @@ print("GeoParquet written: output_mws.geoparquet")
 final = (
     aoi.mws.where(ba_name="Barmer")
     .between(season=Season.KHARIF, year=2021)
-    .fortnightly.derive(
+    .sub_annual.derive(
         "et_ratio", (pl.col("df_et") / pl.col("df_precipitation")).round(3)
     )
 )
 
-print("\nFull pipeline (fortnightly) result shape:", final.data.shape)
+print("\nFull pipeline (sub_annual) result shape:", final.data.shape)
 print("Columns:", final.columns[:10])
 
 top_et = final.df().sort("et_ratio", descending=True).head(5)

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/examples/demo_tehsil.py

@@ -208,7 +208,7 @@ print(test_vs_ref.metadata)
 
 
 # ── 14. Stats — change ────────────────────────────────────────────────────────
-# Note: change() is most meaningful on annual/fortnightly data.
+# Note: change() is most meaningful on annual/sub_annual data.
 # For static entities it still works if the data carries a numeric column
 # that can be compared between two named groups or derived states.
 # Here we illustrate absolute change between two derived values stored
@@ -254,7 +254,7 @@ print("Polygon-filtered count  :", len(result_poly.df()))
 
 
 # ── 17. with_geometry() ───────────────────────────────────────────────────────
-# .static already has geometry.  On annual/fortnightly results (other entities)
+# .static already has geometry.  On annual/sub_annual results (other entities)
 # you'd call this to join geometry back in.  Demonstrated here for completeness.
 
 result_geo = result.with_geometry()  # no-op since already has_geometry=True

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/pyproject.toml

@@ -4,11 +4,13 @@ dynamic = ["version"]
 description = "Query, analyse, and visualise CoreStack's microwatershed and Earth science data through a clean, composable Python API."
 readme = "README.md"
 authors = [{ name = "Apoorva Kashyap" }]
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 license = "GPL-3.0-or-later"
 license-files = ["LICEN[CS]E*"]
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Operating System :: POSIX :: Linux",
     "Development Status :: 2 - Pre-Alpha",
     "Topic :: Scientific/Engineering",

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

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/src/core_lens/aoi.py

@@ -272,7 +272,7 @@ class AoI:
 
     ``AoI`` holds no data itself.  Entity attributes are lazy
     :class:`~core_lens.base.view.View` objects; no Parquet I/O occurs until a
-    materialisation property (``.static``, ``.annual``, ``.fortnightly``) is
+    materialisation property (``.static``, ``.annual``, ``.sub_annual``) is
     accessed on a View.
 
     **Registration** must happen before any ``AoI`` is constructed::
@@ -685,7 +685,7 @@ def _bbox_to_polygon(
 def _validate_entity_paths(entity: BaseEntity, name: str) -> None:
     """Validate an entity's path existence only — no Parquet I/O.
 
-    Checks that ``static_path``, ``annual_path``, and ``fortnightly_path``
+    Checks that ``static_path``, ``annual_path``, and ``sub_annual_path``
     resolve to existing local files.  Schema validation (key columns,
     geometry column, geometry type) is intentionally deferred to first data
     access via :attr:`BaseEntity.schema_profile`, which routes through the
@@ -727,7 +727,7 @@ def _validate_entity_paths(entity: BaseEntity, name: str) -> None:
         )
 
     # --- Temporal path existence checks (no schema read) --------------------
-    for attr, label in [("annual_path", "annual"), ("fortnightly_path", "fortnightly")]:
+    for attr, label in [("annual_path", "annual"), ("sub_annual_path", "sub_annual")]:
         path = getattr(entity, attr)
         if path is not None:
             try:

{core_lens-0.1.dev164 → core_lens-0.1.dev168}/src/core_lens/base/entity.py

@@ -77,7 +77,7 @@ def _cached_detect(
     key_cols: tuple[str, ...],
     geometry_col: str,
     annual_path: str | None,
-    fortnightly_path: str | None,
+    sub_annual_path: str | None,
     storage_options_key: tuple[tuple[str, Any], ...],
 ) -> "SchemaProfile":
     """Cached wrapper around :func:`~core_lens.schema.detection.detect`.
@@ -96,7 +96,7 @@ def _cached_detect(
         key_cols=list(key_cols),
         geometry_col=geometry_col,
         annual_path=annual_path,
-        fortnightly_path=fortnightly_path,
+        sub_annual_path=sub_annual_path,
         storage_options=dict(storage_options_key) or None,
     )
 
@@ -150,7 +150,7 @@ class BaseEntity(ABC):
     Subclasses **may** override:
 
     * :attr:`annual_path`       — path to the annual time-series Parquet file
-    * :attr:`fortnightly_path`  — path to the fortnightly time-series Parquet file
+    * :attr:`sub_annual_path`  — path to the sub_annual time-series Parquet file
     * :attr:`schema_profile`    — override auto-detection by returning an
                                   explicit :class:`~core_lens.schema.profile.SchemaProfile`
 
@@ -176,7 +176,7 @@ class BaseEntity(ABC):
     1. ``static_path`` exists and is readable.
     2. ``key_cols`` are present and unique in the static file.
     3. ``geometry_col`` is present and contains valid geometries.
-    4. ``annual_path`` and ``fortnightly_path`` exist if declared.
+    4. ``annual_path`` and ``sub_annual_path`` exist if declared.
 
     Any failure raises :class:`~core_lens.base.entity.EntityValidationError`.
     """
@@ -192,7 +192,7 @@ class BaseEntity(ABC):
             data_root (str | pathlib.Path | None, optional): Root data directory or cloud
                 URI prefix (e.g. ``"s3://bucket/data"``).  Relative
                 :attr:`static_path`, :attr:`annual_path`, and
-                :attr:`fortnightly_path` values are resolved against this
+                :attr:`sub_annual_path` values are resolved against this
                 root.  Defaults to ``None`` (resolved against cwd).
             storage_options (dict[str, Any] | None, optional): Cloud credential /
                 configuration options forwarded to ``pyarrow.fs`` and
@@ -322,15 +322,15 @@ class BaseEntity(ABC):
         return None
 
     @property
-    def fortnightly_path(self) -> str | None:
-        """Path to the fortnightly time-series Parquet file, or ``None``.
+    def sub_annual_path(self) -> str | None:
+        """Path to the sub_annual time-series Parquet file, or ``None``.
 
-        Override in subclasses that carry fortnightly temporal data.  If
+        Override in subclasses that carry sub_annual temporal data.  If
         declared, the file must exist at :meth:`AoI.register` time or
         :class:`EntityValidationError` is raised.
 
         Returns:
-            str | None: A path string, or ``None`` if the entity has no fortnightly data.
+            str | None: A path string, or ``None`` if the entity has no sub_annual data.
 
         """
         return None
@@ -369,9 +369,9 @@ class BaseEntity(ABC):
                     if self.annual_path is not None
                     else None
                 ),
-                fortnightly_path=(
-                    self._resolve(self.fortnightly_path)
-                    if self.fortnightly_path is not None
+                sub_annual_path=(
+                    self._resolve(self.sub_annual_path)
+                    if self.sub_annual_path is not None
                     else None
                 ),
                 storage_options_key=_so_key(_so),
@@ -659,7 +659,7 @@ class BaseEntity(ABC):
         r"""Return a lazy :class:`~core_lens.base.view.View` with a cross-entity join pending.
 
         The join is recorded in the View's ``join_spec`` and computed only at
-        materialisation time (``.static``, ``.annual``, or ``.fortnightly``).
+        materialisation time (``.static``, ``.annual``, or ``.sub_annual``).
         Joined columns are namespaced as ``{entity_name}_{column_name}``.
 
         Args: