docs: clarify that catalog entries and build paths are not STAC-only

README, dataset-catalog how-to, contributing guides, and interop docs
all implied the catalog and build() are STAC-only. In reality,
DatasetDescriptor supports STAC API, static catalog, or GeoParquet URI
(AEF is a built-in GeoParquet-only entry). Updated framing to present
both source types equally and restructured the dataset contribution
prerequisites to show STAC and GeoParquet verification paths side by
side. Also fixed stale test filename references from the earlier
consolidation.

Author: print-sid8

CONTRIBUTING.md

@@ -32,10 +32,11 @@ uv run pytest -q
 
 ## Adding a dataset to the catalog
 
-Add a `DatasetDescriptor` to `src/rasteret/catalog.py`. Before opening a PR,
-verify the [prerequisites](https://terrafloww.github.io/rasteret/how-to/dataset-catalog/#prerequisites-for-contributing-a-built-in-dataset):
-STAC access works, band map points to parseable COGs, `build()` succeeds
-end-to-end, and license metadata is sourced from the authoritative STAC API.
+Add a `DatasetDescriptor` to `src/rasteret/catalog.py`. Entries can point
+to a STAC API, a static STAC catalog, or a GeoParquet file. Before opening
+a PR, verify the [prerequisites](https://terrafloww.github.io/rasteret/how-to/dataset-catalog/#prerequisites-for-contributing-a-built-in-dataset):
+data source is reachable, band map points to parseable COGs, `build()`
+succeeds end-to-end, and license metadata is verified from the provider.
 
 ## Full contributor guide
 

README.md

@@ -71,7 +71,7 @@ See [Getting Started](https://terrafloww.github.io/rasteret/getting-started/) fo
 
 ## Built-in datasets
 
-Rasteret ships with a growing catalog of datasets, no STAC URLs to memorize:
+Rasteret ships with a growing catalog of datasets. Pick an ID and go:
 
 ```
 $ rasteret datasets list
@@ -90,11 +90,12 @@ pc/usda-cdl                 USDA Cropland Data Layer                   conus
 aef/v1-annual               AlphaEarth Foundation Embeddings (Annual)  global         CC-BY-4.0      none
 ```
 
-Each entry includes license metadata sourced from the authoritative STAC API,
-and a `commercial_use` flag for quick filtering.
+Each entry includes license metadata and a `commercial_use` flag for quick
+filtering.
 
-The catalog is open and community-driven. Each dataset entry is ~20 lines of
-Python: One PR adds a dataset; every user gets access on the next release.
+The catalog is open and community-driven. Each entry is ~20 lines of
+Python pointing to a STAC API or a GeoParquet file. One PR adds a dataset,
+every user gets access on the next release.
 
 Pick any ID and pass it to `build()`. Don't see your dataset? Use
 `build_from_stac()` for any STAC API, `build_from_table()` for existing
@@ -118,9 +119,9 @@ collection = rasteret.build(
 )
 ```
 
-`build()` picks the dataset from the catalog, queries the STAC API, parses
-COG headers, and caches everything as Parquet. The next run loads in
-milliseconds.
+`build()` picks the dataset from the catalog (backed by a STAC API or a
+GeoParquet file, depending on the entry), parses COG headers, and caches
+everything as Parquet. The next run loads in milliseconds.
 
 ### Inspect and filter
 
@@ -130,7 +131,7 @@ collection.bands  # ['B01', 'B02', ..., 'B12', 'SCL']
 len(collection)   # 47
 
 
-# Filter in memory — no network calls
+# Filter in memory, no network calls
 filtered = collection.subset(cloud_cover_lt=15, date_range=("2024-03-01", "2024-06-01"))
 ```
 

docs/contributing.md

@@ -202,27 +202,28 @@ tile reads.
 ## Adding a dataset to the catalog
 
 The built-in catalog lives in `src/rasteret/catalog.py`. Each entry is a
-`DatasetDescriptor`: roughly 20 lines of Python declaring a STAC URL,
-band map, license info, and coverage hints.
+`DatasetDescriptor`: roughly 20 lines of Python declaring a data source
+(STAC API, static STAC catalog, or GeoParquet URI), band map, license
+info, and coverage hints.
 
 Before adding a dataset, work through the
 [prerequisites checklist](how-to/dataset-catalog.md#prerequisites-for-contributing-a-built-in-dataset).
 The short version:
 
-1. **STAC access works**: `pystac_client` for STAC APIs, `pystac` for
-   static catalogs (`catalog.json` on S3).
+1. **Data source is reachable**: STAC API, static catalog, or GeoParquet
+   file. Verify you can query it or read it with PyArrow.
 2. **Band map has at least one working COG**: Rasteret parses COG headers
    during `build()`. If no asset can be parsed, Rasteret can't index or read
    the dataset.
-3. **End-to-end `build()` succeeds**: run `rasteret.build()` with
-   `query={"max_items": 2}` and verify `count_rows() > 0`.
+3. **End-to-end `build()` succeeds**: run `rasteret.build()` with a small
+   scope and verify `len(col) > 0`.
 4. **License is verified from the authoritative source**: pull `license`,
-   `license_url`, and `commercial_use` from the STAC collection metadata.
-   Do not guess.
+   `license_url`, and `commercial_use` from the data provider. Do not guess.
 5. **Descriptor includes required metadata**: include `id`, `name`, `description`,
    `stac_api` (or `geoparquet_uri`), `band_map`, `license`, `license_url`,
    `spatial_coverage`, `temporal_range`. For static catalogs, set
-   `static_catalog=True`.
+   `static_catalog=True`. For GeoParquet sources, include `column_map` if
+   columns need renaming.
 
 For static STAC catalogs (no `/search` endpoint), set `static_catalog=True`
 on the descriptor. Rasteret uses `pystac.Catalog.from_file()` to traverse

docs/explanation/compatibility-matrix.md

@@ -27,7 +27,7 @@ points to the tests that cover them.
 |---|---|---|---|
 | `get_xarray()` | rasterio windowed read | Sentinel-2 uint16, AEF int8 | `test_execution.py` |
 | `get_gdf()` | rasterio windowed read | Sentinel-2 uint16 | `test_execution.py` |
-| `to_torchgeo_dataset()` | Pure TorchGeo GeoDataset | Sentinel-2 uint16 | `test_torchgeo_network_usage.py` |
+| `to_torchgeo_dataset()` | Pure TorchGeo GeoDataset | Sentinel-2 uint16 | `test_torchgeo_network.py` |
 
 ## Running live smoke locally
 

docs/explanation/interop.md

@@ -40,7 +40,7 @@ full contract that samplers and dataset composition rely on:
 | `crs` | Set from the collection's EPSG code via `CRS.from_epsg()` |
 | `res` | Derived from the first record's COG metadata transform |
 | Samplers | Works with `RandomGeoSampler`, `GridGeoSampler`, and any sampler that reads `bounds`, `index`, and `res` |
-| Dataset composition | Works with `IntersectionDataset` and `UnionDataset` — the index is designed so `reset_index()` does not conflict |
+| Dataset composition | Works with `IntersectionDataset` and `UnionDataset`; the index is designed so `reset_index()` does not conflict |
 
 Rasteret replaces the I/O backend (async obstore instead of rasterio/GDAL)
 but speaks the same interface. Nothing downstream of the dataset object
@@ -54,11 +54,11 @@ constructor parameters are Rasteret-specific.
 
 | Feature | What it does | Interop impact |
 |---|---|---|
-| `label_field` | Adds `sample["label"]` from a metadata column | None — extra key, ignored by TorchGeo trainers |
-| `time_series=True` | Stacks all spatially overlapping records into `[T, C, H, W]` | None — standard tensor shape, works with TorchGeo transforms |
-| `target_crs=` | Reprojects scenes from different CRS zones on the fly | None — result has uniform CRS, transparent to samplers |
-| `cloud_config=` | Configures authenticated cloud reads (requester-pays, signed URLs) | None — constructor-level, transparent to samplers |
-| `allow_resample=True` | Resamples bands with different native resolutions onto a common grid | None — output tensor has uniform resolution |
+| `label_field` | Adds `sample["label"]` from a metadata column | None: extra key, ignored by TorchGeo trainers |
+| `time_series=True` | Stacks all spatially overlapping records into `[T, C, H, W]` | None: standard tensor shape, works with TorchGeo transforms |
+| `target_crs=` | Reprojects scenes from different CRS zones on the fly | None: result has uniform CRS, transparent to samplers |
+| `cloud_config=` | Configures authenticated cloud reads (requester-pays, signed URLs) | None: constructor-level, transparent to samplers |
+| `allow_resample=True` | Resamples bands with different native resolutions onto a common grid | None: output tensor has uniform resolution |
 
 #### Behavior details
 
@@ -183,7 +183,7 @@ comparison uses `rasterio.merge.merge` as the oracle, matching what TorchGeo's
 own `_merge_or_stack` calls. Coverage spans 12 datasets including Sentinel-2,
 Landsat, NAIP, Copernicus DEM, ESA WorldCover, and AEF (south-up). See
 `test_dataset_pixel_comparison.py` (requires `--network`), plus
-`test_public_network_smoke.py`, `test_torchgeo_network_usage.py`, and
+`test_public_network_smoke.py`, `test_torchgeo_network.py`, and
 `test_network_smoke.py`.
 
 If you encounter edge cases where output differs from rasterio, please

docs/how-to/dataset-catalog.md

@@ -1,20 +1,19 @@
 # Dataset Catalog
 
 Rasteret ships with a built-in **dataset catalog**: a registry of known
-datasets so you can build a Collection without remembering STAC API URLs or
-endpoint details. Most users only need the `build()` function shown below;
-the later sections cover browsing, local registration, and advanced
-customisation.
+datasets so you can build a Collection by ID without remembering endpoints
+or file paths. Each entry points to a STAC API, a GeoParquet file, or both.
+Most users only need the `build()` function shown below; the later sections
+cover browsing, local registration, and advanced customisation.
 
 The built-in catalog includes 12 datasets: Sentinel-2, Landsat,
 NAIP, Copernicus DEM, ESRI Land Cover, ESA WorldCover, USDA CDL,
 ALOS DEM, NASADEM, and AlphaEarth Foundation embeddings. Run
 `rasteret datasets list` to see them all.
 
-Each catalog entry includes **license metadata** sourced from the
-authoritative STAC API: a license identifier, a URL to the full license
-text, and a `commercial_use` flag so you can quickly tell whether the
-data can be used commercially.
+Each catalog entry includes **license metadata**: a license identifier, a
+URL to the full license text, and a `commercial_use` flag so you can quickly
+tell whether the data can be used commercially.
 
 In short:
 
@@ -55,7 +54,7 @@ Many entries include an **Example bbox** and **Example time**. These are known-g
 ```python
 import rasteret
 
-# Build from a catalog entry (STAC-backed datasets require bbox + date_range)
+# STAC-backed entries need bbox + date_range; GeoParquet entries may not
 collection = rasteret.build(
     "earthsearch/sentinel-2-l2a",
     name="bangalore",
@@ -105,9 +104,9 @@ If you want explicit control over STAC endpoints and collection IDs, use
 
     TorchGeo ships per-dataset Python classes that download data locally
     and read from disk via rasterio/GDAL. Rasteret's catalog points at
-    cloud-hosted data (STAC APIs, GeoParquet): no downloads, no custom
-    code per dataset. You get a standard `Collection` from any catalog
-    entry, then read pixels on demand from the cloud.
+    cloud-hosted data (STAC APIs or GeoParquet files): no downloads, no
+    custom code per dataset. You get a standard `Collection` from any
+    catalog entry, then read pixels on demand from the cloud.
 
 ---
 
@@ -182,7 +181,8 @@ There are two supported patterns:
    )
    ```
 
-   The `band_map` maps user-facing band codes to STAC asset keys.
+   The `band_map` maps user-facing band codes to asset keys (STAC
+   asset keys, or column-derived keys for GeoParquet sources).
    It is auto-registered so downstream code resolves band names
    without users needing to touch `BandRegistry` directly.
 
@@ -202,39 +202,69 @@ requirements. Every built-in entry must actually work with Rasteret's
 pipeline. Listing a dataset that can't be ingested is worse than not
 listing it at all.
 
-### 1. STAC access works
+A catalog entry can point to a **STAC API**, a **static STAC catalog**,
+or a **GeoParquet file** (like the built-in AEF embeddings dataset).
+The verification steps differ slightly depending on the source type.
 
-The dataset must be reachable via either a **STAC API** (with a `/search`
-endpoint) or a **static STAC catalog** (`catalog.json` on S3). Verify
-with:
+### 1. Data source is reachable
 
-```python
-# STAC API
-import pystac_client
-client = pystac_client.Client.open("<stac_api_url>")
-col = client.get_collection("<collection_id>")
+=== "STAC API / static catalog"
 
-# Static catalog
-import pystac
-cat = pystac.Catalog.from_file("<catalog_json_url>")
-items = list(cat.get_all_items())  # should return items
-```
+    The dataset must be reachable via either a **STAC API** (with a `/search`
+    endpoint) or a **static STAC catalog** (`catalog.json` on S3). Verify
+    with:
+
+    ```python
+    # STAC API
+    import pystac_client
+    client = pystac_client.Client.open("<stac_api_url>")
+    col = client.get_collection("<collection_id>")
+
+    # Static catalog
+    import pystac
+    cat = pystac.Catalog.from_file("<catalog_json_url>")
+    items = list(cat.get_all_items())  # should return items
+    ```
+
+=== "GeoParquet"
+
+    The Parquet file must be readable by PyArrow and contain the four
+    required columns (`id`, `datetime`, `geometry`, `assets`), or columns
+    that can be mapped to them via `column_map`. Verify with:
+
+    ```python
+    import pyarrow.parquet as pq
+    table = pq.read_table("<parquet_uri>")
+    print(table.schema)
+    # Confirm id, datetime, geometry, and asset URL columns exist
+    ```
 
-### 2. Band map has at least one working COG asset
+### 2. Assets point to tiled GeoTIFFs (COGs)
 
-The `band_map` must map at least one band code to a STAC asset key that
-points to a Cloud-Optimized GeoTIFF (COG). Rasteret parses COG headers
+The `band_map` must map at least one band code to an asset key that
+points to a Cloud-Optimized GeoTIFF. Rasteret parses COG headers
 during `build()`. If no assets can be parsed, Rasteret can't index or read
 the dataset.
 
-Check a sample item's asset keys:
+=== "STAC"
 
-```python
-item = items[0]
-for key, asset in item.assets.items():
-    print(f"{key}: {asset.media_type}")
-# Look for "image/tiff" or "application=geotiff" entries
-```
+    Check a sample item's asset keys:
+
+    ```python
+    item = items[0]
+    for key, asset in item.assets.items():
+        print(f"{key}: {asset.media_type}")
+    # Look for "image/tiff" or "application=geotiff" entries
+    ```
+
+=== "GeoParquet"
+
+    Check that the `assets` column (or `href_column`) contains URLs
+    pointing to `.tif` / `.tiff` files:
+
+    ```python
+    print(table.column("assets")[0])  # or your href column
+    ```
 
 ### 3. End-to-end `build()` succeeds
 
@@ -245,29 +275,30 @@ import rasteret
 col = rasteret.build(
     "<dataset_id>",
     name="smoke-test",
-    query={"max_items": 2},
+    query={"max_items": 2},  # STAC only; ignored for GeoParquet
     force=True,
 )
-print(col.dataset.count_rows())  # should be > 0
+print(len(col))  # should be > 0
 ```
 
-For STAC API datasets (non-static catalogs), `bbox` and `date_range` are required.
+For STAC API datasets (non-static catalogs), `bbox` and `date_range` are
+required. GeoParquet-backed entries may not need them (the Parquet file
+is the complete record set).
 
 ### 4. License is verified from the authoritative source
 
-Pull the license from the STAC API or catalog metadata. Do not guess:
+Pull the license from the data provider. Do not guess:
 
 ```python
 # STAC API
 col = client.get_collection("<collection_id>")
 print(col.license)  # "CC-BY-4.0", "proprietary", etc.
 license_links = [l.href for l in col.links if l.rel == "license"]
-
-# Static catalog - check item-level properties
-item = items[0]
-print(item.properties.get("license"))
 ```
 
+For GeoParquet-only datasets, check the data provider's website or
+repository for license terms.
+
 Set `commercial_use=False` when the license prohibits it (e.g.
 `CC-BY-NC-4.0`).
 
@@ -276,6 +307,9 @@ Set `commercial_use=False` when the license prohibits it (e.g.
 Include at minimum: `id`, `name`, `description`, `stac_api` (or
 `geoparquet_uri`), `band_map`, `license`, `license_url`, `spatial_coverage`,
 `temporal_range`. For static catalogs, set `static_catalog=True`.
+For GeoParquet sources, include `column_map` if the source uses
+non-standard column names, and `href_column` if asset URLs live in a
+single column rather than a struct.
 
 ---