Update docs

Deltares · Sep 29, 2023 · efe3ad0 · efe3ad0
1 parent bf601f7
commit efe3ad0
Show file tree

Hide file tree

Showing 13 changed files with 155 additions and 73 deletions.
diff --git a/docs/_static/deltares-blue.svg b/docs/_static/deltares-blue.svg
diff --git a/docs/_static/format_vulnerability_curves.PNG b/docs/_static/format_vulnerability_curves.PNG
diff --git a/docs/api/api_index.rst b/docs/api/api_index.rst
@@ -20,13 +20,23 @@ Build components
 .. autosummary::
    :toctree: ../_generated/
 
-   fiat.FiatModel.setup_config
    fiat.FiatModel.setup_basemaps
    fiat.FiatModel.setup_vulnerability
+   fiat.FiatModel.setup_vulnerability_from_csv
    fiat.FiatModel.setup_exposure_vector
    fiat.FiatModel.setup_hazard
    fiat.FiatModel.setup_social_vulnerability_index
 
+Delft-FIAT settings
+-------------------
+
+.. autosummary::
+   :toctree: ../_generated/
+
+   fiat.FiatModel.setup_config
+   fiat.FiatModel.setup_global_settings
+   fiat.FiatModel.setup_output
+
 Attributes
 ----------
 

diff --git a/docs/data/data_sources.rst b/docs/data/data_sources.rst
@@ -11,6 +11,7 @@ The following data sources are currently supported:
 * :doc:`national_structure_inventory`
 * :doc:`openstreetmap`
 * :doc:`jrc`
+* :doc:`hazus`
 
 .. toctree::
    :maxdepth: 1
@@ -19,4 +20,5 @@ The following data sources are currently supported:
 
    national_structure_inventory
    openstreetmap
-   jrc
+   jrc
+   hazus
diff --git a/docs/data/hazus.rst b/docs/data/hazus.rst
@@ -0,0 +1,26 @@
+.. _hazus:
+
+===============================================
+HAZUS flood depth-damage functions
+===============================================
+
+Users of **HydroMT-FIAT** can directly and easily make use of the depth-damage 
+functions and repair values from `HAZUS 
+<https://www.fema.gov/flood-maps/products-tools/hazus>`_. Hazus is a US-based 
+program and the depth-damage functions are based on US data. The functions and 
+values can be used only together with the `hydromt_fiat_catalog_USA.yml` and 
+by providing the following values in the configuration file::
+
+    [setup_vulnerability]
+    vulnerability_fn = "default_vulnerability_curves"
+    vulnerability_identifiers_and_linking_fn = "default_hazus_iwr_linking"
+    unit = "ft"
+
+    [setup_exposure_vector]
+    max_potential_damage = "hazus_max_potential_damages"
+    unit = "m"
+
+
+The HAZUS flood depth-damage functions and replacement values are processed into an easy-to-use format 
+for HydroMT-FIAT and stored in the ``hydromt_fiat/data`` folder.
+
diff --git a/docs/data/jrc.rst b/docs/data/jrc.rst
@@ -5,8 +5,9 @@ JRC Global flood depth-damage functions
 ===============================================
 
 Users of **HydroMT-FIAT** can directly and easily make use of the `JRC Global flood depth-damage functions and 
-replacement values <https://publications.jrc.ec.europa.eu/repository/handle/JRC105688>`_ [1]. The user can access 
-the functions and values through providing 'JRC' in the configuration file as such::
+replacement values <https://publications.jrc.ec.europa.eu/repository/handle/JRC105688>`_ [1]. The functions and 
+values can be used only together with the `hydromt_fiat_catalog_global.yml` and 
+by providing the following values in the configuration file::
 
     [setup_vulnerability]
     vulnerability_fn = "jrc_vulnerability_curves"

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,61 +1,41 @@
-======================
-HydroMT plugin: FIAT
-======================
+=====================================================================
+HydroMT-FIAT: Automated and reproducible Delft-FIAT model building
+=====================================================================
 
-`HydroMT <https://github.com/Deltares/hydromt>`_ is a python package, developed by Deltares, to build 
-and analyse hydro models. It provides a generic model api with attributes to access the model schematization, 
-(dynamic) forcing data, results and states. 
+With the `HydroMT-FIAT plugin <https://github.com/Deltares/hydromt_fiat>`_, users can easily benefit 
+from the rich set of tools of the `HydroMT package <https://github.com/Deltares/hydromt>`_ to build and update 
+`Delft-FIAT <https://github.com/Deltares/Delft-FIAT>`_ models from available global and local data.
 
-This plugin provides an implementation for the 
-`Delft-FIAT <https://github.com/Deltares/Delft-FIAT>`_ flood impact assessment tool. 
-It details the different steps and explains how to use HydroMT to easily get started and work on your own FIAT model.
+This plugin assists the FIAT modeller in:
+
+- Quickly setting up a Delft-FIAT model based on existing hazard maps, global and user-input exposure layers, and global, US national, or user-input vulnerability curves.
+- Creating a Social Vulnerability Index (SVI) based on US Census or user-input data.
+- Adjusting and updating components of a Delft-FIAT model and their associated parameters in a consistent way.
+
+The HydroMT-FIAT plugin aims to make the FIAT model building process **fast**, **modular**, and **reproducible** 
+by configuring the model building process from single *yml* file.
 
 For detailed information on HydroMT itself, you can visit the `core documentation <https://deltares.github.io/hydromt/>`_.
 
+
 Overview
 =============
 
 **Getting Started**
 
-* :doc:`intro`
 * :doc:`installation`
 * :doc:`examples/index`
 
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-   :caption: Getting Started
-
-   intro
-   installation
-   examples/index
-
 **User Guide**
 
 * :doc:`user_guide/user_guide_overview`
 * :doc:`data/data_sources`
 
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-   :caption: User Guide
-
-   user_guide/user_guide_overview
-   data/data_sources
-
-**References & Help**
+**Technical documentation**
 
 * :doc:`api/api_index`
 * :doc:`changelog`
 
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-   :caption: References & Help
-
-   api/api_index
-   changelog
-
 
 Contributing
 ------------
@@ -74,4 +54,16 @@ License as published by the Free Software Foundation, either version 3 of the Li
 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 
-You can find the full terms of the GNU General Public License at <https://www.gnu.org/licenses/>.
+You can find the full terms of the GNU General Public License at <https://www.gnu.org/licenses/>.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+   :hidden:
+
+   installation
+   examples/index
+   user_guide/user_guide_overview
+   data/data_sources
+   api/api_index
+   changelog
diff --git a/docs/intro.rst b/docs/intro.rst
diff --git a/docs/user_guide/exposure_vector.rst b/docs/user_guide/exposure_vector.rst
@@ -0,0 +1,8 @@
+.. _exposure_vector:
+.. currentmodule:: hydromt_fiat.workflows.exposure_vector
+
+===============================
+Exposure Module for Vector data
+===============================
+
+Coming soon..
diff --git a/docs/user_guide/hazard.rst b/docs/user_guide/hazard.rst
@@ -0,0 +1,9 @@
+.. _hazard:
+.. currentmodule:: hydromt_fiat.workflows.hazard
+
+=======================
+Hazard Module
+=======================
+
+Coming soon..
+
diff --git a/docs/user_guide/social_vulnerability_index.rst b/docs/user_guide/social_vulnerability_index.rst
@@ -0,0 +1,9 @@
+.. _svi:
+.. currentmodule:: hydromt_fiat.workflows.social_vulnerability_index
+
+=================================
+Social Vulnerability Index Module
+=================================
+
+Coming soon..
+
diff --git a/docs/user_guide/user_guide_overview.rst b/docs/user_guide/user_guide_overview.rst
@@ -17,12 +17,16 @@ The Delft-FIAT model methods are available from the HydroMT Command Line and Pyt
 allow you to build or update Delft-FIAT model schematizations.
 
 Built-in data sources are available for the exposure and vulnerability components, see the available 
-data_sources_.
+:ref:`data_sources`.
 
 For python users, all FIAT attributes and methods are available, see the :ref:`api_model`.
 
 Exposure
 =======================
+
+Vector data
+-----------------------
+
 Exposure data can be build from a data_catalog_, a data API key, or by supplying an absolute path 
 to local data on the user's machine. The `asset_locations`, `occupancy_type`, and `max_potential_damage` 
 data should be provided as a vector file (e.g. *.shp* or *.gpkg*). The `ground_floor_height` can currently 
@@ -41,11 +45,15 @@ See below how the `setup_exposure_vector` method can be used to build or update
 The following method is used to build or update the **exposure** data:
 
 .. autosummary::
-   :toctree: ../_generated/
-   :nosignatures:
-
    FiatModel.setup_exposure_vector
 
+For more information, see the :ref:`exposure_vector`.
+
+Raster data
+-----------------------
+This option will be implemented at a later stage.
+
+
 Vulnerability
 =======================
 Vulnerability data can be build from a data_catalog_ or by supplying an absolute path 
@@ -71,46 +79,47 @@ See below how the `setup_vulnerability` method can be used to build or update th
 The following methods can be used to build or update the **vulnerability** data:
 
 .. autosummary::
-   :toctree: ../_generated/
-   :nosignatures:
-
    FiatModel.setup_vulnerability
    FiatModel.setup_vulnerability_from_csv
 
+For more information, see the :ref:`vulnerability`.
 
 Hazard
 =======================
 The following methods can be used to build or update the **hazard** data:
 
 .. autosummary::
-   :toctree: ../_generated/
-   :nosignatures:
-
    FiatModel.setup_hazard
 
+For more information, see the :ref:`hazard`.
 
 Social Vulnerability Index
 ===========================
 The following methods can be used to build or update the **Social Vulnerability Index** data:
 
 .. autosummary::
-   :toctree: ../_generated/
-   :nosignatures:
-
    FiatModel.setup_social_vulnerability_index
 
+For more information, see the :ref:`svi`.
 
 Output and run settings
 ========================
 The following methods are available to set up the **output and run settings** for Delft-FIAT:
 
 .. autosummary::
-   :toctree: ../_generated/
-   :nosignatures:
-
    FiatModel.setup_global_settings
    FiatModel.setup_output
 
 
 .. _data_catalog: https://deltares.github.io/hydromt/latest/user_guide/data_prepare_cat.html
 .. _region: https://deltares.github.io/hydromt/latest/user_guide/cli.html#region-options
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Modules
+
+   exposure_vector
+   vulnerability
+   hazard
+   social_vulnerability_index
diff --git a/docs/user_guide/vulnerability.rst b/docs/user_guide/vulnerability.rst
@@ -5,3 +5,34 @@
 Vulnerability Module
 =======================
 
+The vulnerability module contains functions to select vulnerability curves from 
+existing (pre-defined) sources and transform them to a common 
+`Delft-FIAT <https://github.com/Deltares/Delft-FIAT>`_ format, see vulnerability_format_. 
+The currently available sources are :ref:`jrc` and :ref:`hazus`.
+
+Note that the terms vulnerability curves and damage functions are used interchangeably 
+in this module and documentation.
+
+.. _vulnerability_format:
+
+Vulnerability CSV format
+------------------------
+
+The format of a `Delft-FIAT <https://github.com/Deltares/Delft-FIAT>`_ vulnerability 
+curve database is a csv file structured as follows:
+
+.. image:: /_static/format_vulnerability_curves.PNG
+    :width: 300px
+    :align: center
+    :alt: Format vulnerability curves
+
+
+The first row contains the **unit** of the hazard values that are specified in the 
+first column. The second row contains the **method** (mean or max) that should be 
+used by FIAT to compute the hazard value for each asset when an aereal extraction 
+method is used. This method links to the vulnerability curve specified in the same 
+column below. For example, if the method of a certain vulnerability curves is set 
+to `max`, the maximum value of the hazard values under the assets using that curve 
+will be used to compute the damage. The third row contains the **name of the hazard 
+and names of the damage functions**.
+