Add basic documentation

Author: sjpfenninger

docs/index.md

@@ -1,8 +1,72 @@
-# Home
+# Area potentials
 
-Welcome to the documentation of the `module_area_potentials` data module!
-Please consult the [specification guidelines](./specification.md) and the [`clio` documentation](https://clio.readthedocs.io/) for more information.
+This module performs geospatial analyses to determine the available land area for specific technologies, on a by-pixel basis and aggregated to given geographic boundaries (e.g. generated by [module_geo_boundaries](https://github.com/calliope-project/module_geo_boundaries).
 
+## Overview
+
+The analysis in this module is structured as follows:
+
+* Geospatial input data (vector and raster) are acquired. This is automatic for most data, but the following data need to be manually supplied:
+  * Geographic boundaries in the parquet format
+  * WDPA protected areas database from https://www.protectedplanet.net/ in GeoDB format (choose 'File Geodatabase' when downloading).
+* For the extent of the provided boundaries, the input data are reprojected and rasterised to the resolution of the land cover data (GlobCover), and merged into a single dataset for further processing.
+* Based on the supplied configuration, the land-use analysis is done for each defined technology.
+* Results can be reported on a per-geography and per-technology basis, as pixel surface area values (TIFF files), images for reporting purposes (PNG files), and also as a summary report with per-region capacities (CSV and HTML files)
+
+See below for the [data sources](#data-sources).
+
+## Configuration
+
+Configure the analysis in the `config.yaml` file. Examples are visible in `config/config.yaml` and `tests/integration/test_config.yaml`.
+
+In the configuration, you can define any number of `techs`, and for each of them, specify the `initial_area`, `continuous_layers`, and `binary_layers`.
+
+By example, here is a `pv_rooftop` tech. We use the `settlement_area`, which is the settlement area in m² in each pixel, as the initial area from which the further analysis proceeds. In `continuous_layers`, we use the `settlement_share`, which is the share (0-1) of area covered by settlement, and exclude pixels with less than 0.01 settlement share while assuming that of those pixels not excluded by that, 0.8 (80%) of the settled area can be used for rooftop PV. Finally, in the `binary_layers`, we include all land use types except `NOT_SUITABLE` (since the main selection is done via the settlement_share). This means that, for example, `FOREST` pixels with a `settlement_area` > 0 can be included.
+
+```yaml
+pv_rooftop:
+  initial_area: settlement_area
+  continuous_layers:
+    settlement_share:
+      min: 0.01
+      max: 1
+      share: 0.8
+  binary_layers:
+    regions_maritime: 0
+    regions_land: 1
+    protected: 0
+    landcover_FARM: 1
+    landcover_FOREST: 1
+    landcover_URBAN: 1
+    landcover_OTHER: 1
+    landcover_NOT_SUITABLE: 0
+    landcover_WATER: 0
+```
+
+Here is a `wind_offshore` example. We start with the `pixel_area`, the total surface area in m² for each pixel. We include pixels with a slope up to and including 20 degrees, and exclude pixels with a settlement share above 0.01. Furthermore, we include only land areas (`regions_land: 1` and `regions_maritime: 0`) and completely exclude some areas like protected areas or urban areas (`protected: 0`, `landcover_URBAN: 0`), while including only a fraction of other areas (e.g. if a pixel is considered farmland, only 20% of its surface is available: `landcover_FARM: 0.2`).
+
+```yaml
+wind_onshore:
+  initial_area: pixel_area
+  continuous_layers:
+    slope:
+    min: 0
+    max: 20
+    settlement_share:
+    min: 0
+    max: 0.01
+  binary_layers:
+    regions_maritime: 0
+    regions_land: 1
+    protected: 0
+    landcover_FARM: 0.2
+    landcover_FOREST: 0.05
+    landcover_URBAN: 0
+    landcover_OTHER: 0.3
+    landcover_NOT_SUITABLE: 0
+    landcover_WATER: 0
+
+```
 
 ## Data sources