Python for Earth Observation (PyEO)

PyEO is designed to provide a set of portable, extensible and modular Python scripts for machine learning in earth observation and GIS, including downloading, preprocessing, creation of baseline composites, classification and validation.

Full documentation of the functions provided are available at https://clcr.github.io/pyeo/build/html/index.html

Additionally, users on the cloud-processing platform, SEPAL, can follow the PyEO sepal user guide:

Example notebooks are available at:

• SEPAL specific notebooks
  • SEPAL Orientation
  • Training a PyEO ML Model on SEPAL
  • Running PyEO deforestation monitoring on SEPAL

Requirements

Python library requirements are categorised by Platform (Operating System - OS). For use in the Cloud Processing platform SEPAL - pyeo is already installed in a virtual environment. SEPAL is a cloud computing platform for geospatial data which offers remote Linux Instances that are customised for performing geospatial analysis in R or Python. More information can be found here: https://github.com/openforis/sepal

Package management is performed by Conda, for instructions on how to install Conda, please refer to: https://docs.conda.io/en/latest/.
Note: Conda can be installed as part of Anaconda https://www.anaconda.com/

For installation locally on an OS of your choice, see the sections below.

To install pyeo, put the following commands into Bash (Linux), Terminal (Mac) or the Anaconda Prompt (Windows)

Ubuntu or MacOS

conda install -c conda-forge git
git clone https://github.com/clcr/pyeo.git
cd pyeo
conda env create --file environment.yml --name pyeo_env
conda activate pyeo_env
python -m pip install -e .

If you do not want to edit pyeo, replace python -m pip install -e . line with

python -m pip install -vv .

Google Colab (Linux)

# from a Jupyter Notebook in Colab, do this:
# clone and install a github repo on Colab: https://github.com/clcr/pyeo
!pwd
!git clone https://github.com/clcr/pyeo.git
!pip install git+https://github.com/clcr/pyeo

Windows

conda install -c conda-forge git
git clone https://github.com/clcr/pyeo.git
cd pyeo
conda env create --file environment_windows_w1.yml --name pyeo_env
conda activate pyeo_env
python -m pip install -e .

If you do not want to edit pyeo, replace python -m pip install -e . line with

python -m pip install -vv .

A Note on .ini file encoding on Windows

If the OS that pyeo is running on is Windows, we have noticed that pyeo_windows.ini may need to be saved with ANSI encoding instead of the usual UTF-8. See this webpage for more details.

Satellite Imagery Providers

From July 2023, Scihub will be deprecated in favour of the Copernicus Data Space Ecosystem (CDSE). In the meantime, if you wish to download from Scihub, you will need a Scihub account: https://scihub.copernicus.eu/

To use the CDSE, you will need a separate account: https://dataspace.copernicus.eu

Once you have created your account, you will need to enter your email address and password into the credentials_dummy.ini file in the folder credentials, like this:

[sent_2]
user=replace_this_with_your_email_address
pass=replace_this_with_your_password

[dataspace]
user=replace_this_with_your_email_address
pass=replace_this_with_your_password

Where user and pass under [sent_2] correspond to your scihub account details, and user and pass under [dataspace] correspond to your dataspace account details.

To process Sentinel-2 L1Cs, you will also need Sen2Cor installed: http://step.esa.int/main/third-party-plugins-2/sen2cor/.

Installation Test Steps

To learn about how to install PyEO, the easiest way is to apply for a free account on SEPAL, and to follow the SEPAL tutorial notebooks indicated at the top of this file.

You can test your installation by typing the following in Bash/Terminal/Anaconda Prompt:

python

import pyeo.classification

or, by running the same import command above, after having started a jupyter notebook via:

jupyter notebook

Please note, if you are using SEPAL, jupyter notebooks have to be started via a GUI method instead of from Bash, see: https://user-images.githubusercontent.com/149204/132491851-5ac0303f-1064-4e12-9627-f34e3f78d880.png

How PyEO works

As a broad overview, PyEO implements the following steps:

1. Takes a Region of Interest (ROI) and calculates which Sentinel-2 (S2) tiles overlap with the ROI.
2. Builds a Baseline Composite to compare land cover changes against, by downloading S2 images and calculating the median of these images.
3. Downloads Change Images over the Change Period to be monitored.
4. Classifies the Composite and the Change Images using a Random Forest Classifier.
5. Calculates the Class Changes between sets of from classes and to classes, for each classified image. For example, this could be changes from forest to bare soil.
6. Creates a Change Report describing the consistency of the Class Changes.
7. Vectorises the Change Report and filters out any Class Changes outside of the ROI.

How to Run PyEO as an Automated Pipeline

More information on how to run PyEO as a pipeline from the command line can be found in the SEPAL User Guide.

How to cite this software

Please use the following references when using pyeo:

Roberts, J.F., Mwangi, R., Mukabi, F., Njui, J., Nzioka, K., Ndambiri, J.K., Bispo, P.C., Espirito-Santo, F.D.B., Gou, Y., Johnson, S.C.M. and Louis, V., 2022. Pyeo: A Python package for near-real-time forest cover change detection from Earth observation using machine learning. Computers & Geosciences, 167, p.105192.

Roberts, J., Balzter, H., Gou, Y., Louis, V., Robb, C., 2020. Pyeo: Automated satellite imagery processing. https://doi.org/10.5281/zenodo.3689674

Pacheco-Pascagaza, A.M., Gou, Y., Louis, V., Roberts, J.F., Rodríguez-Veiga, P., da Conceição Bispo, P., Espírito-Santo, F.D., Robb, C., Upton, C., Galindo, G. and Cabrera, E., 2022. Near real-time change detection system using Sentinel-2 and machine learning: A test for Mexican and Colombian forests. Remote Sensing, 14(3), p.707.