Installation

Clone the git folder

At first you will need to clone the GEOP4TH Git repository.

with a Git application

If you are new to Git, we recommend the use of a Git app such as SourceTree or Github Desktop.

For example with Github Desktop, you can download it here (no need to create an account) and install it. Once in GitHub Desktop you can:

1. Go to File > Clone repository...

2. Got to URL tab and enter https://gitlab.com/AlexandreCoche/geop4th.git

Tip

The local path should end with geop4th (it should be automatically the case)

with Anaconda Prompt

If you use Anaconda Prompt, just enter:

conda install git # if needed
git clone https://gitlab.com/AlexandreCoche/geop4th.git "<your/local/path/ending/with/a/folder/named/geop4th>"

Cloning the online GEOP4TH repository creates a copy of the repository on your computer and establishes a connection that enables synchronization.

Install the Python virtual environment

After cloning the Git repository, we still need to install the required Python environment containing all external librairies and modules used in GEOP4TH.

with conda

Conda is a package and environment manager. To use it, you first need to install a conda distributions such as Anaconda or Miniconda.

After installing one of those, you should be able to open an 📟 Anaconda Prompt (conda console). Let’s open this Anaconda Prompt (in Admin mode) and install the virtual environment needed for GEOP4TH by using the 📄 environment.yml file that contains the installation procedure.

You can find this file in the 📁 install folder located in your local 📁 geopath folder you just cloned.

Note

This folder contains several .yaml files but we will only use the environment.yml one so far.

You can create the environment and give it a name (here geoenv):

conda env create -f "your/path/to/geop4th/install/environment.yml" -n geoenv

(this step can take quite a long time: have a look at mamba for a faster way)

Tip

Please mind the quote signs " if your path contains some white spaces

Use an existing environment

Alternatively, if you want to use an existing environment, the required packages can be installed as follow:

conda install -c conda-forge numpy>1.0.0 setuptools>=67 pandas>1.0.0 geopandas>0.10 xarray rioxarray>=0.10.0 rasterio~=1.0 shapely>=1.8 affine~=2.3 fiona~=1.8 matplotlib plotly Pillow~=11.0 git
pip install pysheds>=0.3 kaleido

with mamba

Mamba is a fast package manager, containing especially libmamba and mamba (which allows to run conda commands by replacing conda with mamba). To use it, you first need to install a mamba distribution such as Miniforge (fresh install).

Once mamba has been installed, you can proceed as follow in the 📟 Miniforge Prompt (or in the Anaconda Prompt):

mamba env create -f "your/path/to/geop4th/install/environment.yml" -n geoenv

Install mamba on top of conda

You can install mamba in your base environment in your Anaconda Prompt, following the steps described by merv on this issue

## prioritize 'conda-forge' channel
conda config --add channels conda-forge

## update existing packages to use 'conda-forge' channel
conda update -n base --all

## install 'mamba'
conda install -n base mamba

Nevertheless, this kind of installation can raise some issues later, especially between libmamba and spyder. When using mamba, it is recommended to do a fresh install instead.

Use mamba without installing it, for conda > 23.10

Since conda 23.10.0, the libmamba solver is installed by default. You can directly use (without installing mamba):

conda env create -f environment_mamba.yml -n geoenv --solver=libmamba
# and
conda install spyder --solver=libmamba

with pip

Pip is a Python package manager. Please note that before create a virtual environment with pip, you need to have installed python==3.11 beforehand.

First you need to create a virtual environment by entering in the command prompt:

Unix/macOS

python3 -m venv "your/path/to/geoenv"

Windows

py -m venv "your/path/to/geoenv"

(if py is not recognized, try python.exe instead)

"your/path/to/geoenv" is the location of your choice where you want to install the virtual environment.

Tip

Please mind the quote signs " if your path contains some white spaces

…and activate it:

"your\path\to\geoenv\Scripts\activate"

Tip

If you enter this command in Anaconda Prompt, we advise to first escape the base environment with:

deactivate

You can then update pip:

Unix/macOS

python3 -m pip install --upgrade pip

Windows

py -m pip install --upgrade pip

(if py is not recognized, try python.exe instead)

…and install geop4th as a local package and its dependencies:

pip install -e "path/to/geop4th/folder"

"path/to/geop4th/folder" is the path to your local 📁 geop4th folder you just cloned, in which is located the 📄 pyproject.toml file that will be used for installation.

Note

We mean your root 📁 geop4th folder, not the 📁 geop4th/geop4th folder inside.

Attention

No IDE (Spyder, Jupyter Notebook, PyDev, PyCharm, IDLE, VS Code… ) is included in this initial environment. You will need to manually install one of your choice (see Install and open an IDE)

Activate the environment

Let’s now activate your brand new environment:

with conda

In Anaconda Prompt:

conda activate geoenv

with mamba

In Anaconda Prompt:

mamba activate geoenv # (or) conda activate geoenv

with pip

In the command prompt:

"your\path\to\geoenv\Scripts\activate"

Tip

If you enter this command in Anaconda Prompt, we advise to first escape the base environment with:

deactivate

Install and open an IDE

(for example Spyder)

with conda

conda install -c conda-forge spyder

spyder

with mamba

mamba install spyder

spyder

with pip

pip install spyder

spyder

Troubleshooting of Spyder

If you use Spyder, you might encounter some kernel issue when launching it, making you unable to use the IPython Console in Spyder. Here are some frequent causes:

• it can be due to the presence of another Spyder installed on your computer. To solve it, go to Tools > Preferences > Python Interpreter and check the checkbox Internal. This option enables Spyder to automatically select the kernel corresponding to the Python virtual environment from which it has been launched.

• if you are using mamba, it may be an issue between mamba and Spyder. Instead of launching mamba activate geoenv, try to use conda activate geoenv instead, before entering spyder to run Spyder (the (geoenv) prefix may not be shown when activating your virutal environment with conda, but you can check that your geoenv environment has well been activated with the command conda info)

• if the previous workarounds do not work, you can also try to uninstall and reinstall spyder-kernels and spyder in your environment

• if it still does not work, you can try to gain more insight about the bug by lauching the IPython Console in different environments (in Spyder, you can do a righ click on Console 1/A and open New console in environment

You might also encounter issues with Qt (used for the graphical user interface):

• if you encounter an error with loading Qt platform plugin, you can enter the command:

  QT_QPA_PLATFORM=wayland
  

If you have troubles for installing Spyder, you may want to try another GEOP4TH installation procedure (with pip or mamba instead of conda, see above)

Additionaly, you may want to check that the python version you use is well supported by Spyder.

Import modules

Finally, you can import the main modules as follow:

from geop4th import (
    geobricks as geo,
    download_fr as dl,
    trajplot as tjp,
)

And workflows can be imported similarly:

from geop4th import (
    standardize_fr as stz,
    cwatm,
)

Module not found

No module named 'geop4th'

This error should not happen. However, if it does, you may try to amend the PYTHONPATH.

You can amend the PYTHONPATH in your IDE, by adding your local 📁 geop4th folder.

Note

We mean your root 📁 geop4th folder, not the 📁 geop4th/geop4th folder inside.

Alternatively you can also add your 📁 geop4th folder to sys.path by entering in your IDE:

import sys
sys.path.append(r"your/path/to/geop4th")