evi_runner

The evi_runner Python package automates the analysis of Enhanced Vegetation Index (EVI) trends for agricultural monitoring using remote sensing data. It provides a programmatic interface for executing a parameterized Jupyter notebook that extracts EVI time series for a specified African country and time window.

This package is particularly useful for research and operational monitoring of crop health, drought conditions, and phenological baselines using NASA Earth Engine data.

---

📊 Purpose

The main goal is to extract, baseline, and assess deviations in EVI signals within known agricultural zones. The analysis focuses on:

• Extracting EVI time series from satellite data (e.g., MODIS or Sentinel-2).
• Computing a reference/baseline EVI from historical years.
• Identifying anomalous vegetation performance (e.g., potential drought or planting failure).
• Saving both the executed notebook and textual results to disk.

---

🔧 Installation

First, create a clean conda environment and install the required libraries:

conda create -n niger python=3.10
conda activate niger
pip install ipykernel
python -m ipykernel install --user --name niger

# Clone supporting repository
cd Repos  # or any directory to save repositories
git clone https://github.com/andresfchamorro/phenolopy.git
cd phenolopy
git checkout -b dev
git pull origin dev
cd ..

# Install required libraries
pip install earthengine-api
python -m pip install git+https://github.com/worldbank/GEE_Zonal.git
pip install geemap
pip install xarray
pip install geojson
pip install tqdm
pip install dask[distributed]
pip install plotnine
pip install rasterstats
pip install xee
pip install netCDF4
pip install h5netcdf
pip install rioxarray

Then clone this repository and install the evi_runner package:

git clone https://github.com/your-org/evi_runner.git
cd evi_runner
pip install -e .

🚀 Quick Start

You can run the analysis from a script or terminal using:

python -m evi_runner.evi_automation "Nigeria" "NGA" "2023-01-01" "2023-12-31"

Or directly from the function in a Python script:

from evi_runner import run_evi_analysis

run_evi_analysis(
    country="Nigeria",
    iso3="NGA",
    start_date="2023-01-01",
    end_date="2023-12-31",
    output_dir="outputs"
)

This will:

• Execute the evi-reference.ipynb notebook.
• Inject the provided parameters (country, iso3, start_date, end_date).
• Save the executed notebook and a text summary in the outputs/ directory.

---

🧪 Example Output

• outputs/evi_NGA_20230501-142310.ipynb: Executed notebook with plots and analysis.
• outputs/evi_NGA_20230501-142310.txt: Plain text summary of key findings, suitable for logging or reporting.

---

📂 Project Structure

evi_runner/
├── evi_runner/
│   ├── __init__.py
│   └── evi_automation.py         # Core logic to run the parameterized notebook
├── notebooks/
│   └── evi-reference.ipynb       # Notebook for EVI reference analysis
├── outputs/                      # Destination for generated reports
├── tests/
│   └── test_evi_automation.py    # Basic test for automation function
├── README.md
├── setup.py
└── MANIFEST.in

---

🧠 Scientific Context

This package builds on methodologies outlined in projects like the Niger Economic Monitoring and NASA crop monitoring initiatives. It leverages Google Earth Engine (via geemap and earthengine-api) and geospatial analysis libraries like rasterstats, xarray, and plotnine.

The notebook can be adapted to:

• Overlay conflict data to study the intersection of crop stress and insecurity.
• Extend analysis to drought statistics and interannual trends.

---

🧪 Testing

To run the test suite:

pytest tests/

---

📬 Contributions & Issues

Feel free to fork, file issues, or open PRs to expand functionality — such as:

• Additional analysis notebooks (drought, classification, etc.)
• Support for batch processing across multiple countries
• Integration with dashboards or APIs

---

📜 License

This projects is licensed under the Mozilla Public License - see the LICENSE file for details.

Code of Conduct

The template used to create this project maintains a Code of Conduct to ensure an inclusive and respectful environment for everyone. Please adhere to it in all interactions within our community.