Merge pull request #44 from plantnet/main

Re-sync

.gitignore

@@ -7,13 +7,18 @@ checkMyCode.sh
 
 !.gitignore
 
+# Build utilities
 docs/_build
+
+# Data
 examples/ecologists/micro_geolifeclef*/dataset/patches
 examples/ecologists/micro_geolifeclef*/dataset/rasters
+examples/ecologists/sentinel-2a/dataset/*.tif
 examples/inference/micro_geolifeclef*/dataset/patches
 examples/inference/micro_geolifeclef*/dataset/rasters
-
-examples/ecologists/sentinel-2a/dataset/*.tif
 examples/inference/sentinel-2a/dataset/*.tif
-
 examples/kaggle/geolifeclef2022/dataset
+
+# Packaging
+dist/
+build/

README.md

@@ -1,10 +1,9 @@
 <p align="center">
+  <a href="https://pypi.org/project/malpolon/"><img src="https://img.shields.io/pypi/v/malpolon" alt="Python version"></a>
+  <a href="https://www.python.org/downloads/release/python-3100/"><img src="https://img.shields.io/pypi/pyversions/malpolon" alt="Python version"></a>
   <a href="https://github.com/plantnet/malpolon/issues"><img src="https://img.shields.io/github/issues/plantnet/malpolon" alt="GitHub issues"></a>
   <a href="https://github.com/plantnet/malpolon/pulls"><img src="https://img.shields.io/github/issues-pr/plantnet/malpolon" alt="GitHub pull requests"></a>
   <a href="https://github.com/plantnet/malpolon/graphs/contributors"><img src="https://img.shields.io/github/contributors/plantnet/malpolon" alt="GitHub contributors"></a>
-  <a href="https://github.com/plantnet/malpolon/network/members"><img src="https://img.shields.io/github/forks/plantnet/malpolon" alt="GitHub forks"></a>
-  <a href="https://github.com/plantnet/malpolon/stargazers"><img src="https://img.shields.io/github/stars/plantnet/malpolon" alt="GitHub stars"></a>
-  <a href="https://github.com/plantnet/malpolon/watchers"><img src="https://img.shields.io/github/watchers/plantnet/malpolon" alt="GitHub watchers"></a>
   <a href="https://github.com/plantnet/malpolon/blob/main/LICENSE"><img src="https://img.shields.io/github/license/plantnet/malpolon" alt="License"></a>
 </p>
 
@@ -39,7 +38,7 @@ Here is a list of the currently available scenarios:
   - <u>Custom dataset</u> : I have my own dataset consisting of pre-extracted image patches and/or rasters and I want to train a model on it.
 - [**Inference**](examples/inference/) : I have an observations file (.csv) and I want to predict the presence of species on a given area using a model I trained previously and a selected dataset or a shapefile I would provide.
 
-## :wrench: Installation
+## 🔧 Installation
 
 To install malpolon, you will first need to install **Python ≥ 3.10**, and several python packages. To do so, it is best practice to create a virtual environment containing all these packages locally.
 
@@ -48,7 +47,7 @@ To install malpolon, you will first need to install **Python ≥ 3.10**, and sev
 <details>
   <summary><i><u>Click here to expand instructions</u></i></summary>
 
-### 0. Requirements
+### Requirements
 
 Before proceeding, please make sure the following packages are installed on your system:
 
@@ -67,7 +66,18 @@ Before proceeding, please make sure the following packages are installed on your
 
 The following instructions show installation commands for Python 3.10, but can be adapted for any of the compatible Python versions metionned above by simply changing the version number.
 
-### 1. Clone the repository
+### Install from `PyPi`
+The backend side of malpolon is distributed as a package on `PyPi`. To install it, simply run the following command:
+
+```script
+pip install malpolon
+```
+
+However, versions available on PyPi are non-experimental and possibly behind the repository's `main` and `dev` branches. To know which version you want download, please refer to the *tags* section of the repository and match it with PyPi.
+Furthermore, the PyPi package does not include the examples and the documentation. If you want to install the full repository, follow the next steps.
+
+### Install from `GitHub`
+#### 1. Clone the repository
 
 Clone the Malpolon repository using `git` in the directory of your choice:
 ```script
@@ -76,7 +86,7 @@ git clone https://github.com/plantnet/malpolon.git
 
 ---
 
-### 2. Create your virtual environment
+#### 2. Create your virtual environment
 
 - **Via `virtualenv`**
 
@@ -106,7 +116,7 @@ conda activate malpolon_3.10
 
 ---
 
-### 3. Install Malpolon as a python package
+#### 3. Install Malpolon as a python package
 
 The malpolon repository can also be installed in your virtual environment as a package. This allows you to import `malpolon` anywhere in your scripts without having to worry about file paths. It can be installed via `pip` using:
 
@@ -140,7 +150,7 @@ git checkout dev
 
 </details>
 
-## :page_facing_up: Documentation
+## 📄 Documentation
 
 An online code documentation is available via GitHub pages at [this link](https://plantnet.github.io/malpolon/). This documentation is updated each time new content is pushed to the `main` branch.
 
@@ -160,7 +170,7 @@ make -C docs html
 
 The result can be found in `docs/_build/html`.
 
-## :train2: Roadmap
+## 🚆 Roadmap
 
 This roadmap outlines the planned features and milestones for the project. Please note that the roadmap is subject to change and may be updated as the project progress.
 

environment_python3.10.yml

@@ -7,5 +7,6 @@ dependencies:
   - cmake==3.26.3
   - pip==23.2.1
   - pip:
+    - --no-deps pipreqs==0.5.0
     - -r requirements_python3.10.txt
 prefix: ~/envs/malpolon

examples/ecologists/micro_geolifeclef2022/cnn_on_rgb_nir_patches.py

@@ -1,3 +1,11 @@
+"""Main script to run training or inference on microlifeclef2022 dataset.
+
+Uses RGB and Near infra-red pre-extracted patches from the dataset.
+
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
 from __future__ import annotations
 
 import os

examples/ecologists/micro_geolifeclef2022/cnn_on_rgb_patches.py

@@ -1,3 +1,11 @@
+"""Main script to run training or inference on microlifeclef2022 dataset.
+
+Uses RGB pre-extracted patches from the dataset.
+
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
 from __future__ import annotations
 
 import os

examples/ecologists/micro_geolifeclef2022/transforms.py

@@ -3,9 +3,10 @@
 These transform classes can be called during training loops to perform
 data augmentation.
 
-Author: Titouan Lorieul <titouan.lorieul@inria.fr>
+Author: Titouan Lorieul <titouan.lorieul@gmail.com>
         Theo Larcher <[email protected]>
 """
+
 import numpy as np
 import torch
 from torchvision import transforms

examples/ecologists/sentinel-2a/cnn_on_rgbnir_torchgeo.py

@@ -3,8 +3,9 @@
 This script runs the RasterSentinel2 dataset class by default.
 
 Author: Theo Larcher <[email protected]>
-        Titouan Lorieul <titouan.lorieul@inria.fr>
+        Titouan Lorieul <titouan.lorieul@gmail.com>
 """
+
 from __future__ import annotations
 
 import os

examples/ecologists/sentinel-2a/transforms.py

@@ -1,5 +1,13 @@
-import numpy as np
+"""Collection of custom PyTorch friendly transform classes.
+
+These transform classes can be called during training loops to perform
+data augmentation.
 
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
+import numpy as np
 import torch
 from torchvision import transforms
 

examples/inference/micro_geolifeclef2022/cnn_on_rgb_nir_patches.py

@@ -1,9 +1,14 @@
-from __future__ import annotations
+"""Main script to run inference on microlifeclef2022 dataset.
+
+Uses RGB and Near infra-red pre-extracted patches from the dataset.
 
-import os
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
+from __future__ import annotations
 
 import hydra
-import numpy as np
 import pytorch_lightning as pl
 import torch
 from omegaconf import DictConfig

examples/inference/micro_geolifeclef2022/cnn_on_rgb_patches.py

@@ -1,6 +1,12 @@
-from __future__ import annotations
+"""Main script to run inference on microlifeclef2022 dataset.
+
+Uses RGB pre-extracted patches from the dataset.
 
-import os
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
+from __future__ import annotations
 
 import hydra
 import pytorch_lightning as pl

examples/inference/micro_geolifeclef2022/transforms.py

@@ -3,9 +3,10 @@
 These transform classes can be called during training loops to perform
 data augmentation.
 
-Author: Titouan Lorieul <titouan.lorieul@inria.fr>
+Author: Titouan Lorieul <titouan.lorieul@gmail.com>
         Theo Larcher <[email protected]>
 """
+
 import numpy as np
 import torch
 from torchvision import transforms

examples/inference/sentinel-2a/cnn_on_rgbnir_torchgeo.py

@@ -3,11 +3,10 @@
 This script runs the RasterSentinel2 dataset class by default.
 
 Author: Theo Larcher <[email protected]>
-        Titouan Lorieul <titouan.lorieul@inria.fr>
+        Titouan Lorieul <titouan.lorieul@gmail.com>
 """
-from __future__ import annotations
 
-import os
+from __future__ import annotations
 
 import hydra
 import pytorch_lightning as pl

examples/inference/sentinel-2a/transforms.py

@@ -1,5 +1,13 @@
-import numpy as np
+"""Collection of custom PyTorch friendly transform classes.
+
+These transform classes can be called during training loops to perform
+data augmentation.
 
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
+import numpy as np
 import torch
 from torchvision import transforms
 

examples/kaggle/geolifeclef2022/cnn_on_rgb_patches.py

@@ -1,8 +1,14 @@
-import os
+"""Main script to run training on microlifeclef2022 dataset.
+
+Uses RGB pre-extracted patches from the dataset.
+This script was created for Kaggle participants of the GeoLifeCLEF 2022
+challenge.
+
+Author: Titouan Lorieul <[email protected]>
+"""
 
 import hydra
-import pytorch_lightning as pl
-import torchmetrics.functional as Fmetrics
+import pytorch_lightning as p
 from omegaconf import DictConfig
 from pytorch_lightning.callbacks import ModelCheckpoint
 from torchvision import transforms

examples/kaggle/geolifeclef2022/cnn_on_rgb_temperature_patches.py

@@ -1,4 +1,12 @@
-import os
+"""Main script to run training on microlifeclef2022 dataset.
+
+Uses RGB pre-extracted patches and temperature rasters from the dataset.
+This script was created for Kaggle participants of the GeoLifeCLEF 2022
+challenge.
+
+Author: Titouan Lorieul <[email protected]>
+"""
+
 from pathlib import Path
 
 import hydra

examples/kaggle/geolifeclef2022/cnn_on_temperature_patches.py

@@ -1,4 +1,12 @@
-import os
+"""Main script to run training on microlifeclef2022 dataset.
+
+Uses temperature rasters from the dataset.
+This script was created for Kaggle participants of the GeoLifeCLEF 2022
+challenge.
+
+Author: Titouan Lorieul <[email protected]>
+"""
+
 from pathlib import Path
 
 import hydra

examples/kaggle/geolifeclef2022/transforms.py

@@ -1,3 +1,12 @@
+"""Collection of custom PyTorch friendly transform classes.
+
+These transform classes can be called during training loops to perform
+data augmentation.
+
+Author: Titouan Lorieul <[email protected]>
+        Theo Larcher <[email protected]>
+"""
+
 import numpy as np
 import torch
 from torchvision import transforms

examples/kaggle/geolifeclef2023/cnn_on_rgbnir_glc23_patches.py

@@ -3,8 +3,8 @@
 This script runs the RasterSentinel2 dataset class by default.
 
 Author: Theo Larcher <[email protected]>
-        Titouan Lorieul <[email protected]>
 """
+
 from __future__ import annotations
 
 import hydra

malpolon/check_install.py

@@ -1,9 +1,15 @@
+"""This module checks the installation of PyTorch and GPU libraries.
+
+Author: Titouan Lorieul <[email protected]>
+"""
+
 import os
 
 import torch
 
 
 def print_cuda_info():
+    """Print information about the CUDA/PyTorch installation."""
     print(f"Using PyTorch version {torch.__version__}")
     print(f"CUDA available: {torch.cuda.is_available()} (version: {torch.version.cuda})")
     print(f"cuDNN available: {torch.backends.cudnn.enabled} (version: {torch.backends.cudnn.version()})")

malpolon/data/data_module.py

@@ -1,8 +1,7 @@
 """This module provides a base class for data modules.
 
 Author: Theo Larcher <[email protected]>
-        Titouan Lorieul <[email protected]>
-
+        Titouan Lorieul <[email protected]>
 """
 
 from __future__ import annotations

malpolon/data/datasets/geolifeclef2022.py

@@ -3,7 +3,7 @@
 This module has since been updated for GeoLifeCLEF2023
 
 Author: Benjamin Deneu <[email protected]>
-        Titouan Lorieul <titouan.lorieul@inria.fr>
+        Titouan Lorieul <titouan.lorieul@gmail.com>
 
 License: GPLv3
 Python version: 3.8
@@ -347,9 +347,9 @@ def download(self):
             return
 
         try:
-            import kaggle
+            import kaggle  # pylint: disable=C0415,W0611 # noqa: F401
         except OSError as error:
-            raise OSError("Have you properly set up your Kaggle API token ? For more information, please refer to section 'Authentication' of the kaggle documentation : https://www.kaggle.com/docs/api"+msg) from error
+            raise OSError("Have you properly set up your Kaggle API token ? For more information, please refer to section 'Authentication' of the kaggle documentation : https://www.kaggle.com/docs/api") from error
 
         answer = input("You are about to download the GeoLifeClef2022 dataset which weighs ~62 GB. Do you want to continue ? [y/n]")
         if answer.lower() in ["y", "yes"]:

malpolon/data/datasets/torchgeo_sentinel2.py

@@ -254,7 +254,7 @@ def plot(
 
 
 class RasterSentinel2GLC23(RasterSentinel2):
-    """Adaptation of RasterSentinel2 for new GLC23 observations"""
+    """Adaptation of RasterSentinel2 for new GLC23 observations."""
     filename_glob = "*.tif"
     filename_regex = r"(?P<band>red|green|blue|nir)_2021"
     all_bands = ["red", "green", "blue", "nir"]