Installation =============== Clone the git folder ---------------------------- At first you will need to clone the GEOP4TH **Git repository**. .. tab-set:: .. tab-item:: 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) .. tab-item:: with Anaconda Prompt If you use *Anaconda Prompt*, just enter:: conda install git # if needed git clone https://gitlab.com/AlexandreCoche/geop4th.git "" Cloning the online GEOP4TH repository creates a copy of the repository on your computer and establishes a connection that enables synchronization. .. _install-venv: 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. .. tab-set:: :sync-group: package_manager .. tab-item:: with conda :sync: 1 **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 .. dropdown:: Use an existing environment :color: primary :icon: file-diff **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 .. tab-item:: with mamba :sync: 2 **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 .. dropdown:: Install mamba on top of conda :color: info :icon: light-bulb 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. .. dropdown:: Use mamba without installing it, for conda > 23.10 :color: success :icon: light-bulb 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 .. tab-item:: with pip :sync: 3 **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: .. tab-set:: :sync-group: OS .. tab-item:: Unix/macOS :sync: 1 :: python3 -m venv "your/path/to/geoenv" .. tab-item:: Windows :sync: 2 :: 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: .. tab-set:: :sync-group: OS .. tab-item:: Unix/macOS :sync: 1 :: python3 -m pip install --upgrade pip .. tab-item:: Windows :sync: 2 :: py -m pip install --upgrade pip (if ``py`` is not recognized, try ``python.exe`` instead) |br| ...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: .. tab-set:: :sync-group: package_manager .. tab-item:: with conda :sync: 1 In Anaconda Prompt:: conda activate geoenv .. tab-item:: with mamba :sync: 2 In Anaconda Prompt:: mamba activate geoenv # (or) conda activate geoenv .. tab-item:: with pip :sync: 3 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 .. _4: Install and open an |IDE| ------------------------------------------------ *(for example Spyder)* .. tab-set:: :sync-group: package_manager .. tab-item:: with conda :sync: 1 :: conda install -c conda-forge spyder spyder .. tab-item:: with mamba :sync: 2 :: mamba install spyder spyder .. tab-item:: with pip :sync: 3 :: pip install spyder spyder .. dropdown:: Troubleshooting of Spyder :color: warning :icon: bug 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: .. code-block:: python3 from geop4th import ( geobricks as geo, download_fr as dl, trajplot as tjp, ) And workflows can be imported similarly: .. code-block:: python3 from geop4th import ( standardize_fr as stz, cwatm, ) .. dropdown:: Module not found :color: warning :icon: bug :: 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") .. |IDE| raw:: html IDE .. # define a hard line break for HTML .. |br| raw:: html
.. |nbsp| unicode:: 0xA0 :trim: