README.md

# Modspa Pixel

A more detailed documentation can be found in the ``index.html`` file located [here](./docs/build/html/index.html) (it should be opened with a web browser).

## Description

ModSpa pixel is an adaptation of the existing [modspa](https://gitlab.cesbio.omp.eu/modelisation/modspa) processing chain. It uses a mix of satellite data (optical and weather data) to run models like [SAMIR or SAFY](https://www.cesbio.cnrs.fr/la-recherche/activites/modeliser-codes-et-modelisation/liste-et-descriptif-des-modeles/modspa/) (*only SAMIR is currently supported*) on spatialized data. The previous modspa version used ``pandas dataframes`` to run the SAMIR model on the **parcel scale** (inputs are satellite data aggregated to the parcel scale). ModSpa pixel uses ``numpy`` to run the SAMIR model at the **pixel scale**. This allows for higher resolution modelisation at the cost of an increase in storage and calculation requirements. However, this ModSpa version can still run at the parcel scale, the user can **choose between parcel and pixel mode**


## Installation

To begin, clone the project from the [github](https://forge.ird.fr/cesbio/modelisation/modspa_pixel) page with the following command:

```bash
$ git clone https://forge.ird.fr/cesbio/modelisation/modspa_pixel.git
```

This should create a modspa_pixel directory in your current directory.

If you have not yet installed **conda** on your machine, you should start with this step : [conda installation](https://conda.io/projects/conda/en/latest/user-guide/install/index.html).

A ``yml`` file is included to automatically create a conda virtual environnment with the correct libraries and dependencies installed. To install it run this command in the root directory of the modspa_pixel project:

```bash
(base) /modspa_pixel$ conda env create -f modspa_pixel_env.yml
```

To activate the environment:

```bash
(base) /modspa_pixel$ conda activate modspa_pixel

(modspa_pixel) /modspa_pixel$
```

That's all for this step!

_Warning_: The OTB package might not be properly installed with conda, check out [this](https://www.orfeo-toolbox.org/CookBook/Installation.html) page for more information.


## Usage

The first step if to correctly fill the [``json configuration file``](./config/config_modspa.example.json) (an example is provided). 

Once this is done, you can download and prepare the optical and weather data automatically with this script :

```bash
$ python main_prepare_inputs.py
```

This will create the NDVI and WEATHER datacubes. The soil data and land cover data has to be manually downloaded and prepare based on the region of study. Jupyter [notebooks](./preprocessing/) are included in the preprocessing scripts to help you format this data.

You should also fill the [input parameter files](./parameters/csv_files/) for the *SAMIR* model.

When all the input data is prepared, you can run the *SAMIR* model with this script :

```bash
$ python main_run_samir.py
```

Various scripts exist in the [postprocessing](./postprocessing/) directory to visualize the output data. There are notebooks to plot spatial or temporal statistics and scripts to generate output GIFs.

More details on how to run the ModSpa tool can be found on the complete [documentation](./docs/build/html/index.html).

## Roadmap

Graphical interface for configuration file should come in the following versions.

## Authors and acknowledgment

AUCLAIR Jérémy -- IRD Research Engineer at CESBIO

RIVALLAND Vincent -- CNRS Research Engineer at CESBIO

## License

_**TEST**_

This is free software under the GNU Affero General Public License v3.0. See
http://www.gnu.org/licenses/agpl.html for details.


## Project status

In development.