Metadata-Version: 2.4
Name: olmoearth-inferencex
Version: 1.1.2
Summary: Label-free audit of Earth-observation prediction maps: which windows to review first, why, and how two inferences differ
Author: Ziming Qi
License-Expression: Apache-2.0
Project-URL: Documentation, https://olmoearth-inferencex.readthedocs.io
Project-URL: Repository, https://github.com/2imi9/olmoearth_inferenceX
Project-URL: Changelog, https://github.com/2imi9/olmoearth_inferenceX/blob/main/CHANGELOG.md
Keywords: earth-observation,remote-sensing,selective-classification,error-ranking,OlmoEarth,audit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Operating System :: OS Independent
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: encoder
Requires-Dist: olmoearth-pretrain<0.2,>=0.1; extra == "encoder"
Requires-Dist: torch<2.8,>=2.7; extra == "encoder"
Provides-Extra: geo
Requires-Dist: rasterio>=1.4; extra == "geo"
Requires-Dist: geopandas>=1.0; extra == "geo"
Requires-Dist: shapely>=2.0; extra == "geo"
Requires-Dist: pystac-client>=0.8; extra == "geo"
Requires-Dist: planetary-computer>=1.0; extra == "geo"
Requires-Dist: matplotlib>=3.8; extra == "geo"
Requires-Dist: scipy>=1.11; extra == "geo"
Dynamic: license-file

olmoearth_inferenceX is a tool for auditing Earth-observation prediction maps without
labels. It ranks the windows of a map by the model's own confidence, so a reviewer knows
where to look first, says why each window is flagged, and measures how two inferences of
the same scene differ.

<img src="https://raw.githubusercontent.com/2imi9/olmoearth_inferenceX/main/docs/figures/pipeline.png" alt="One scene through the audit: Sentinel-2 bands, the frozen OlmoEarth encoder and the task head, the prediction, confidence and boundary layers, the review set at a 5% budget drawn on the scene, and the reasons per flagged window" width="760">

On the 24 tasks of Ai2's published embedding suite where a confidence margin is defined,
the model's own confidence ranks its errors better than any control that sees no model,
on every one. <!-- claim:suite-margin-wins-every-task -->

Full documentation is available at **https://olmoearth-inferencex.readthedocs.io/**:
the [findings](https://olmoearth-inferencex.readthedocs.io/en/latest/Findings/#in-short), the [usage](https://olmoearth-inferencex.readthedocs.io/en/latest/Usage/), the
[recipe](https://olmoearth-inferencex.readthedocs.io/en/latest/method/recipe/) and the evidence experiment by experiment.


Demo
----

```bash
pip install olmoearth-inferencex
oe-inferencex demo
```

It audits a real map, one tile of Dynamic World land cover, chosen by a rule fixed in advance (the median tile of 18, not the best one), and draws this: <!-- claim:demo-sample-is-the-median-tile -->

<img src="https://raw.githubusercontent.com/2imi9/olmoearth_inferenceX/main/docs/figures/demo_real_map.png" alt="Three panels of a real land-cover map in southern Peru. Left: the 5% of windows to check first, outlined in black along the class boundaries. Middle: the same windows over the map's real errors in red. Right: a random 5% of windows over the same errors" width="760">

*Left: the 5% of windows to check first, found without labels. Middle: the same windows over the real errors, in red: 67% of them are wrong, against 19% of windows picked at random. Right: a random 5%. Most of the red lies outside the flagged windows because the map is 19% wrong and the review is 5%: no 5% could hold more than 26% of the errors, and these hold 17%; a 20% review finds 55%.* <!-- claim:demo-sample-hit-rate -->

Your own map: `oe-inferencex assess your_map.tif --out audit`.


Setup
-----

```bash
pip install olmoearth-inferencex        # add [geo] to read and write GeoTIFFs
```

To work on the repository, clone it, then `uv sync` and `uv run pytest`; the experiments
also need `uv sync --extra encoder --extra geo`.

Apache License 2.0, see [LICENSE](https://github.com/2imi9/olmoearth_inferenceX/blob/main/LICENSE); to cite, see [CITATION.cff](https://github.com/2imi9/olmoearth_inferenceX/blob/main/CITATION.cff).
For questions and suggestions, please
[open an issue on GitHub](https://github.com/2imi9/olmoearth_inferenceX/issues).
