About

GeoCARET is a command line Python tool for delineating and analysing catchments and reservoirs. It relies on Google Earth Engine (GEE) - Google's cloud-based platform developed for planetary-scale environmental analysis. GeoCARET uses Google Earth Engine as a backend for performing geometry operations and data processing and as a database of global spatial data in the form of GIS layers. It additionally relies on several private assets not available in GEE. We have made these assets accessible for analysis by uploading them to a dedicated GEE asset folder.

To request access to those assets please send email to: tomasz.k.janus@gmail.com or tjanus.heet@gmail.com with your email address registered with Google Earth Engine.

Requirements

Our software requires Python 3.8 or 3.9 only.

We are currently experiencing errors when trying to run our software in Python 3.10 caused by frictionless package being limited to version 4.40.8 or lower which does not supporting the new hierarchy of classes in Python's collections module. We are working on resolving this issue.

A number of additional python libraries are required to run the heet tool. These are listed in requirements.txt.

We advise that you create a separate python environment for running GeoCARET (see installation guide for step by step instructions).

Installation

The repository does not require installation but relies on a number of packages. We recommend that you set up a virtual environment dedicated to this repository before attempting to install all the dependencies. There are several packages for creating virtual environments such as venv, virtualenv, pyenv, etc. Please refer to web resources and find out what works best for you, e.g. in https://www.freecodecamp.org/news/how-to-setup-virtual-environments-in-python/.

The dependencies are included in requirements.txt. You can install these dependencies by running: pip install -r requirements.txt

The package can also be installed as a Docker image. For more information, see installation instructions

How to use GeoCARET

Depending on the installation option, either as a Python package or as a Docker image, running GeoCARET requres a slightly different syntax. The details on how to run GeoCARET are provided here.

Demo

We have provided a test data file that can be used to run GeoCARET. The file contains input data for analysis of a single reservoir.

To run the demo using GeoCARET as a Python script, use the following syntax:

```

python heetcli.py tests/data/dams.csv testproject job01 standard ```

To run the demo using GeoCARET Docker container, type the following:

```

docker compose run --rm geocaret python heetcli.py tests/data/dams.csv testproject job01 standard ```

Tests

The repository contains unit tests which test the behaviour of individual components of the software. They can be executed using pytest by typing pytest tests in the root folder where the tests directory is located.

Disclaimer

This software has been written for research purposes and may not be as robust as the software designed to be used by the wider public. We are aware of this and we're trying to make constant improvements, developments and bug fixes. If you run into problems running this software, please submit an issue or contact us directly at tomasz.janus@manchester.ac.uk, tomasz.k.janus@gmail.com or jaise.kuriakose@manchester.ac.uk