Metadata-Version: 2.4
Name: awards
Version: 1.0.2
Summary: Automated Workflow for Analysis Ready Data from Satellite imagery
Author-email: Haijun Li <haijunli@umd.edu>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: coloredlogs
Requires-Dist: lxml
Requires-Dist: matplotlib
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: regex
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: envyaml
Requires-Dist: geographiclib
Requires-Dist: earthaccess
Requires-Dist: requests
Provides-Extra: geo
Requires-Dist: fiona; extra == "geo"
Requires-Dist: rasterio; extra == "geo"
Requires-Dist: geopandas; extra == "geo"
Requires-Dist: shapely; extra == "geo"
Requires-Dist: pyproj; extra == "geo"
Provides-Extra: hpc
Requires-Dist: mpi4py; extra == "hpc"
Provides-Extra: dev
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: awards[dev,geo,hpc]; extra == "all"
Dynamic: license-file

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](./LICENSE)
# AWARDS
## Automated Workflow for Analysis Ready Data from Satellite imagery

<img src="logo.png" alt="Logo" width="750">

Logo created using Google Gemini

## About
Automatic Workflow for Analysis Ready Data from Satellite imagery (AWARDS) to process a large amount of satellite data with high efficiency. It has been developing to support wall-to-wall satellite data processing and analysis ready data (ARD) generation.

## License
This repository is licensed under the GNU General Public License v3.0. This means you are free to use, modify, and distribute the code, provided that:
- You include the original copyright notice and a copy of the license.
- You disclose the source code of your modifications.
- Any derivative works or larger projects incorporating this code are also licensed under GPL-3.0 (the "copyleft" requirement).

See the [LICENSE](./LICENSE) file for full details.

# Supported data resource
- [Sentinel-2 data from Copernicus Data Space Ecosystem (CDSE)](https://dataspace.copernicus.eu/)
- [HLS data from NASA EarthData](https://www.earthdata.nasa.gov/)

# Installation
```bash
# install via pip
# 1. create conda environment
conda create -n my_env -c conda-forge python=3.10 gdal rios rasterio geopandas fiona shapely pyproj mpi4py

# 2. activate
conda activate my_env

# 3. isntall
pip install awards

# 4. verify
python -c "import awards; print(awards.__version__)"

```
  
# Development
## Conda environment setup

```bash
# create the conda environment from yml configuration
# modify the $name in env.yml if needed
conda env create -f env.yml --name awards
```

## Install Fmask modules
- The following modules to generate cloud masks from Fmask algorithms (Zhu et al., 2015) excluded from 'env.yml' file, and should be installed from source
  - [py-fmask-ext](https://github.com/haijunli0629/py-fmask-ext)
  - [py-fmask-l2a](https://github.com/haijunli0629/py-fmask-l2a)

Clone these two repositories then run the following scripts to install the modules.

```bash
# 1. activate the conda environment
conda activate awards

# 1. install py-fmask-ext
# after cloning the repository, enter the directory and run the following installation:
python ./setup.py build && python ./setup.py install 

# 2. install py-fmask-l2a
# after cloning the repository, enter the directory and run the following installation:
python ./setup.py build && python ./setup.py install 
```

## Install AWARDS in editable mode
```bash
pip install -e .
```

## Register the python kernel
```bash
python -m ipykernel install --user --name awards --display-name "awards"

# when run the jupyter notebook tutorials, select the "awards" as the python kernel
```

## Run a test
```bash
# when run the jupyter notebook tutorials, select the "awards" as the python kernel
# if the following works, then the awards module is installed correctly

import logging
from awards.common import yml_logging

yml_logging.setup_logging()
logger = logging.getLogger(__name__)

logger.info("test...")
```

# Tutorials
## Sample data
Sample data can be downloaded fron Zenodo:
- Sentinel-2 ARD and 10-m crop classification: [AWARDS Sentinel-2 Analysis Ready Data (ARD) Sample Dataset V1](https://doi.org/10.5281/zenodo.19430754)
- HLS ARD: [AWARDS Harmonized Landsat Sentinel-2 (HLS) Analysis Ready Data (ARD) Sample Dataset V1](https://doi.org/10.5281/zenodo.19443402)

## Sentinel-2 ARD generation
- Jupyter notebooks: `jupyter/s2`
- Python scripts: `script/s2`
- Bash examples to run the python scripts: `bash/s2`

## HLS ARD generation
- Jupyter notebooks: `jupyter/hls`
- Python scripts: `script/hls`
- Bash examples to run the python scripts: `bash/hls`

## Crop classification using Sentinel-2 ARD and machine learning 
- Jupyter notebooks: `jupyter/crop_classification`
- Python scripts: `script/crop_classification`
- Bash examples to run the python scripts: `bash/crop_classification`


