How abdelghanibelgaid/agrs works
Project Type and Purpose
• This is an open-source, domain-specific Python library (AGRS) for agricultural remote sensing.
• It provides opinionated pipelines to search Sentinel-2 imagery, compute agronomic indices, select snapshots, aggregate to field-level features, and return a tidy DataFrame.
• There is no separate “frontend” or “backend” service; rather, it’s a modular library that orchestrates data retrieval and processing via the Microsoft Planetary Computer STAC API.
High-Level Components
a. Entry Point
• agrs/client.py
• Factory function s2agc() returns a client instance.
• Public API method: client.get_features(...).
b. Configuration
• agrs/config.py
• Holds default parameters (e.g., indices list, snapshot strategies).
c. Data Source Integration
• agrs/sources/planetary_computer_source.py
• STAC queries, scene retrieval, cloud masks.
• Wraps HTTP calls to Planetary Computer STAC API.
d. Index Computation
• agrs/indices.py
• Implements band-math formulas for NDVI, EVI, SAVI, etc.
e. Snapshot Selection
• agrs/selection.py
• Implements strategies: fractional, fixed_date, top_n_cloudfree.
f. Aggregation
• agrs/aggregation.py
• Aggregates pixel-level indices to field-level statistics (mean, median, etc.) per growth stage.
g. Utilities
• agrs/utils.py
• GeoDataFrame clipping, date utilities, error handling, logging.
h. Packaging & Metadata
• setup.py, pyproject.toml, requirements.txt
External Dependencies and Services
• Planetary Computer STAC API (external service).
• GeoPandas & Shapely (field geometry).
• Pandas (DataFrame).
• HTTP client library (requests or similar, abstracted by source module).
Relationships and Data Flow
1. User code calls s2agc().get_features(fields, ...).
2. Client reads config and passes parameters to the Source module.
3. Source module queries STAC API → downloads imagery assets.
4. Retrieved imagery → passed to Index module → computes spectral indices per scene.
5. Computed indices → passed to Selection module → selects snapshots per strategy.
6. Selected snapshots → passed to Aggregation module → computes field-level statistics by growth stage.
7. Final tidy DataFrame returned to user.
Architectural Patterns & Design Principles
• Modular layering: each concern (I/O, computation, selection, aggregation) in its own module.
• Chain of responsibility / pipeline pattern: data flows through sequential processing stages.
• Factory pattern in client creation for pluggable sources or future strategies.
• Opinionated defaults in config for reproducibility.