Metadata-Version: 2.4
Name: satscout
Version: 0.1.0
Summary: Find, vet, and validate public satellite/climate datasets (STAC discovery + Olofsson et al. 2014 accuracy assessment)
Author-email: Yazen Shunnar <yazen.shunnar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yz-al/satscout
Project-URL: Repository, https://github.com/yz-al/satscout
Project-URL: Issues, https://github.com/yz-al/satscout/issues
Keywords: remote-sensing,satellite,stac,earth-observation,sentinel-2,landsat,accuracy-assessment,area-estimation,olofsson,cloud-cover
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# satscout — find, vet, and validate public satellite/climate datasets

An open-source tool for remote-sensing researchers who need to match public
satellite/climate archives to their own work. Built around two pain points
that came up repeatedly in user interviews:

1. **Finding and vetting data means downloading metadata by hand** — e.g.
   pulling scene metadata just to check cloud cover. satscout searches the
   big public STAC catalogs and surfaces scene metadata (cloud cover,
   revisit gaps, bands, resolution) directly — **nothing is downloaded**.
2. **Validating remote-sensing products to the community standard**
   (Olofsson et al. 2014) is high-value but tedious. satscout ships a
   complete, tested implementation of the good-practice workflow:
   stratified sample design, error-matrix analysis, and unbiased
   (error-adjusted) area estimates with confidence intervals.

## Install

```bash
pip install satscout
```

Or from source:

```bash
git clone https://github.com/yz-al/satscout && cd satscout
pip install .                   # dev: pip install -e '.[dev]'
```

Only dependency: `requests`. Python ≥ 3.10.

## Quick start

### 1. Discover candidate datasets

Which public collections could cover a 2020–2023 study of surface
reflectance over the Central Valley?

```bash
satscout discover \
  --keywords "sentinel-2 surface reflectance" \
  --bbox -121.5,36.5,-120.5,37.5 --start 2020-01-01 --end 2023-12-31
```

Ranks matching collections across **Earth Search (AWS Open Data)**,
**Microsoft Planetary Computer**, and **USGS LandsatLook**. Collections
whose spatial/temporal extent can't cover the request are filtered out;
the rest are ranked by keyword relevance. `satscout catalogs` lists the
endpoints.

### 2. Vet a dataset without downloading anything

```bash
satscout check --catalog earth-search --collection sentinel-2-l2a \
  --bbox -121.5,36.5,-120.5,37.5 --start 2022-06-01 --end 2022-09-30 \
  --max-cloud 20
```

Produces an alignment report: scene count, date coverage, revisit-gap
statistics, the cloud-cover distribution, platforms, resolution, and the
bands/assets present in every scene — plus plain-language warnings (e.g.
"largest temporal gap is 74 days"). `satscout search` lists the individual
scenes; add `--json` to either for machine-readable output.

### 3. Validate a map per Olofsson et al. (2014)

Plan the reference sample (Eq. 13 + allocation with a rare-class floor):

```bash
satscout validate design \
  --map-areas 200000,150000,3200000,6450000 \
  --expected-users 0.70,0.60,0.90,0.95 --target-se 0.01
```

Then, with reference labels collected, feed the error matrix
(CSV, rows = map class, columns = reference class, same order as
`--map-areas`):

```bash
satscout validate assess --matrix matrix.csv \
  --map-areas 200000,150000,3200000,6450000 \
  --classes deforestation,gain,stable-forest,stable-nonforest
```

Output: overall/user's/producer's accuracies with 95% CIs and
**error-adjusted area estimates** with CIs (Eqs. 1–11 of the paper).
The implementation reproduces the paper's worked example — including the
flagship result, deforestation area = 235,086 ± 68,418 ha — in
`tests/test_olofsson.py`.

The same functionality is importable:

```python
from satscout import assess, design_sample
result = assess(matrix, mapped_areas, class_names=names)
print(result.overall_accuracy, result.adjusted_areas)
```

## Tests

```bash
pytest tests -m "not network"   # offline unit tests (fast, no internet)
pytest tests -m network         # real-data tests against the live public APIs
```

The offline suite includes a scripted fake server exercising rate-limit
(HTTP 429) recovery, Retry-After handling, exponential backoff, and both
STAC pagination styles. The network suite hits Earth Search, Planetary
Computer, and USGS live — including a 10-request burst against the
AWS-hosted API to prove throttling is absorbed, not fatal.

## Scope (MVP)

- AOIs are reduced to lon/lat bounding boxes (GeoJSON in, bbox out);
  antimeridian-crossing AOIs must be split.
- Discovery covers the three largest free STAC APIs; adding a catalog is a
  one-line entry in `satscout/catalogs.py`.
- The validation module implements stratified estimators for the standard
  "map classes = strata" design. Reference:
  Olofsson, Foody, Herold, Stehman, Woodcock & Wulder (2014). *Good
  practices for estimating area and assessing accuracy of land change.*
  Remote Sensing of Environment 148:42–57. doi:10.1016/j.rse.2014.02.015
