Skip to content

Commit

Permalink
Updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dalmijn
dalmijn committed Oct 3, 2024
1 parent f7701f0 commit 51f2448
Show file tree
Hide file tree
Showing 21 changed files with 328 additions and 182 deletions.
12 changes: 6 additions & 6 deletions docs/PDF_Documentation.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ damages per asset
[**exposure.geom**]
`csv`: This will create an exposure CSV file within the exposure folder ([folder strucute](index.qmd)) that contains the [required information](exposure.qmd) per asset.
`crs`: The projection of the exposure vector file.
`file1`: This will create an exposure vector file within the exposure folder with the assets'geometry and Object ID.
`file1`: This will create an exposure vector file within the exposure folder with the assets'geometry and object_id.

[**vulnerability**]
`file`: This will create an vulnerability curves CSV file within the vulnerability folder ([folder strucute](index.qmd)) that contains the damage curves.
Expand Down Expand Up @@ -254,9 +254,9 @@ If the user prefers to create a more advanced model or to utilize grid data inst
| var_ as_band | True/False Read netCDF subdatasets as raster bands | No | False |
| **[exposure.geom]** | | | |
| csv | File path to exposure.csv file, that contains information about e.g. asset type, max. potential damage, aggregation and so forth) | Yes | 'exposure/exposure.csv' |
| file1 | File path of exposure vector file with Object ID column to enable linking exposure.csv output to vector file. | Yes | 'exposure/buildings.gpkg' |
| file1 | File path of exposure vector file with object_id column to enable linking exposure.csv output to vector file. | Yes | 'exposure/buildings.gpkg' |
| crs | Projection of exposure data | Yes, if crs is unknown in dataset | 'EPSG:32617' |
| index | Define the name of the index column of the data to link the exposure CSV file with the exposure vector file. | No | 'Object ID' |
| index | Define the name of the index column of the data to link the exposure CSV file with the exposure vector file. | No | 'object_id' |
| **[exposure.grid]** | | | |
| file | File path to exposure.nc grid file, that contains the spatial information and information about the maximum potential damage per cell. | Yes, if netCDF is provided as input | 'exposure/raster.nc' |
| crs | Output projection | Yes, if crs is unknown in dataset | 'EPSG:32617' |
Expand Down Expand Up @@ -324,7 +324,7 @@ For users who would want to create their own exposure data, or modify existing e

| Field | Description | Required | Example |
|----------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|----------------------------|
| Object ID | Unique numerical indentifier of the object | Yes | 1 |
| object_id | Unique numerical indentifier of the object | Yes | 1 |
| Object Name | Unique name of the object | No | fp_1 |
| Primary Object Type | Object type | No | RES1_1SNB |
| Secondary Object Type | More specification about object type | No | Res 1,1 Story no basement |
Expand All @@ -342,8 +342,8 @@ For users who would want to create their own exposure data, or modify existing e

A more detailed description of the data fields in the *exposure.csv* can be found below;

**Object ID/Object name**
Object ID and Object name are administrative information, which the user is free to choose. Input must be unique for each object, if they are not unique, FIAT gives a warning and stops the model built-up.
**object_id/Object name**
object_id and Object name are administrative information, which the user is free to choose. Input must be unique for each object, if they are not unique, FIAT gives a warning and stops the model built-up.

**Primary/Secondary object type**
The primary object type describes the category of the asset (e.g. residential or commercial). The secondary object type allows for a more detailed profile of the object (e.g. single-story home, or grocery store). The developer of the exposure dataset is free to set their own categories of object types. (*Exception: FIAT requires **roads** to be assigned as **primary object type = ‘road**’, to summarize road damages separately from buildings and utilities*.)
Expand Down
17 changes: 13 additions & 4 deletions docs/_quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,9 @@ website:
- "setup_guide/general/docker.qmd"
- section: "FIAT package"
contents:
- setup_guide/kernel/installation.qmd
- setup_guide/kernel/application.qmd
- setup_guide/kernel/linux.qmd
- setup_guide/kernel/install.qmd
- setup_guide/kernel/dev.qmd
- setup_guide/kernel/build.qmd
- title: "User guide"
collapse-level: 1
contents:
Expand All @@ -115,8 +115,9 @@ website:
- text: Exposure data
file: user_guide/data/exposure.qmd
contents:
- user_guide/data/exposure/csv.qmd
- user_guide/data/exposure/data.qmd
- user_guide/data/exposure/geometries.qmd
- user_guide/data/exposure/csv.qmd
- user_guide/data/vulnerability.qmd
- user_guide/data/supported.qmd
- title: Examples
Expand Down Expand Up @@ -183,6 +184,14 @@ quartodoc:
children: separate
- name: GridModel
children: separate
- subtitle: Methods
desc: The hazard functions
package: fiat.methods
contents:
- ead.risk_density
- ead.calc_ead
- flood.calculate_hazard
- flood.calculate_damage

# Logging
- title: Logging
Expand Down
24 changes: 21 additions & 3 deletions docs/changelog.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,56 @@ title: "What's new?"
This contains the unreleased changes to Delft-FIAT.

### Added
- Attribute `size` of `GeomSource` object for in situ size return; `count` becomes private
- Attribute `size` of `GridSource` object for in situ size return; `count` becomes private
- Attributes `dtypes` and `geom_type` of `GeomModel`
- Build time to FIAT cli (when build with pyinstaller), viewed with `fiat --version`
- Different types of exposure (e.g. 'damage', 'affected', 'outage' etc.)
- Docker file for docker image creation
- Function (`generate_jobs`) to generate jobs for parallelization
- Function (`execute_pool`) to execute code in parallel using `multiprocessing`
- Flood hazard/ damage functions (`methods` submodule)
- General method of creating output files in `GeomModel` (`_setup_output_files`)
- Method `_create_model_dirs` of `ConfigReader` object for creating result directories in one go
- Method `add_handler` of the `Log` object; user setting of custom stream
- Method `add_feature_with_map` of `GeomModel` to set features with extra info
- Method `create` of `GeomModel` to create an ogr.DataSource (new dataset)
- Method `set` of `ConfigReader` object
- Method `size` of `GeomSource` object for in situ size return; `count` becomes private
- Method `size` of `GridSource` object for in situ size return; `count` becomes private
- Numpy >= 2.0.0 support
- Python 3.12 support
- Settings toml file: global setting 'loglevel'
- Settings toml file: global setting 'global.loglevel'; default 'INFO'
- Settings toml file: exposure setting 'exposure.types'; default 'flood'
- Setting return period as a variable in hazard map bands (risk)
- Support for using pixi for binary creation (properly)

### Changed
- Better version of `BufferHandler`
- Exposure data headers are now lower-/ snakecase ('object_id' -> 'objectId'), see [docs](./user_guide/data/exposure/data.qmd)
- Fixed binary creation in general, but also specifically for `GDAL >= v3.9.1`
- Made read methods of `BaseModel`, `GeomModel` and `GridModel` public (removed underscore)
- Made csv files (exposure data) optional
- Moved hazard/ damage calculation function to `methods` submodule
- Proper checking for duplicate columns in csv files
- Settings toml file: exposure setting 'exposure.csv.file' (becomes optional)
- Testing of workers (not properly caught due to using `multiprocessing`)
- Testing only based on integers

### Deprecated
- Base object `_BaseHandler`; incompatible with Python 3.12
- Function `open_exp` from `fiat.io`, superseded by general use of `open_csv`
- Method `add_c_handler` in favour of the more generalized `add_handler`
- Methods `_create_output_dir`, `_create_tmp_dir` and `_create_risk_dir` of the `ConfigReader` object
- Object `ExposureTable`, now done via `TableLazy`
- Resolve stage of `GeomModel`; now properly handled in `GeomModel.run`
- Setting return period via the name of the hazard band (risk)
- Settings toml file: global setting 'global.keep_temp_files'
- Settings toml file: output setting 'output.geom.chunk'; superseded by 'global.geom.chunk'
- Support of `Python` versions under `3.9.0`
- Temporary files (`GeomModel`)
- `TextHandler` object; unused

### Documentation
- Added methods to the api
- Cleaner home page
- Getting started remade into `Information`

Expand Down
2 changes: 1 addition & 1 deletion docs/examples/single_event.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@
"from pathlib import Path\n",
"\n",
"# check the output\n",
"out = open_csv(Path(\"../../.testdata/output/geom_event\", \"output.csv\"), index=\"Object ID\")\n",
"out = open_csv(Path(\"../../.testdata/output/geom_event\", \"output.csv\"), index=\"object_id\")\n",
"print(out.columns)"
]
},
Expand Down
3 changes: 2 additions & 1 deletion docs/setup_guide/general/conda.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ In order to develop on **FIAT** locally, the Python package manager **Miniforge3

Download and install [Miniforge3](https://github.com/conda-forge/miniforge#mambaforge)

Initialize conda by running the following in the Miniforge prompt:
Make sure the conda binary (and mamba) is added to PATH. In windows this is simply done via the 'set environment variables' screen, on linux one can append the 'PATH' variable via the `.bashrc` configurations file (or another rc file corresponding with the shell in use).
Initialize conda by running the following command in your shell.

```bash
conda init
Expand Down
14 changes: 6 additions & 8 deletions docs/setup_guide/index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,18 @@ title: "Setup guide"
<ul id="index-chooser" class="nav nav-tabs" role="tablist">
<li class="nav-item" role="presentation">
<a class="nav-link" href="kernel/installation.html">
<a class="nav-link" href="kernel/install.html">
<i class="bi bi-download"></i>Installing FIAT
</a>
</li>
<li class="nav-item" role="presentation">
<a class="nav-link" href="kernel/application.html">
<i class="bi bi-gear"></i>Freeze FIAT as an application
<a class="nav-link" href="kernel/dev.html">
<i class="bi bi-file-earmark-code"></i>Development install
</a>
</li>
<li class="nav-item" role="presentation">
<a class="nav-link" href="kernel/linux.html">
<i class="bi bi-ubuntu"></i>Linux
<a class="nav-link" href="kernel/build.html">
<i class="bi bi-gear"></i>Building FIAT
</a>
</li>
</ul>
Expand All @@ -28,6 +28,4 @@ title: "Setup guide"
:::

## Overview
FIAT requires Python 3.9 or greater, a [package manager](general/conda.qmd), and Git to be installed. After that, FIAT can be [installed](kernel/installation.qmd) for use or for development, or it can be [freezed](kernel/application.qmd) as an application/executable.

It's possible to [run FIAT on Linux](kernel/linux.qmd) but this is currently in the bèta phase.
FIAT requires Python 3.10 or greater, a [package manager](general/conda.qmd), and Git to be installed. After that, FIAT can be [installed](kernel/install.qmd) for use or for [development](kernel/dev.qmd), or it can be [built](kernel/build.qmd) as an application/executable.
28 changes: 0 additions & 28 deletions docs/setup_guide/kernel/application.qmd
View file

This file was deleted.

67 changes: 67 additions & 0 deletions docs/setup_guide/kernel/build.qmd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: "Building FIAT"
---

To build FIAT as an executable/ binary, it is required to clone the FIAT repository to your local drive.
This required [git](https://git-scm.com/) to be installed on your local machine.

```bash
git clone [email protected]:Deltares/Delft-FIAT.git
```

Besides git, a python installation/ environment with the necessary packages is needed.
It is recommended to use [miniforge3](../general/conda.qmd) for this purpose.

::: {.panel-tabset}

## Windows

- Create a yml for a seperate **build** environment:

```bash
python make_env.py build
```

- Create the environment with mamba. This time, FIAT will be automatically installed with the environment:

```bash
mamba env create -f environment.yml
```

- Go to the .build/ directory and execute the win64.bat script:

```bash
cd ./.build

win64.bat
```

That's it.
A FIAT application will be located in the `{root}/bin/Release` folder.

## Linux

- Create a yml for a seperate **build** environment:

```bash
python make_env.py build
```

- Create the environment with mamba. This time, FIAT will be automatically installed with the environment:

```bash
mamba env create -f environment.yml
```

- Set the rights of the shell script and exexute it:

```bash
chmod u+x .build/linux64.sh

.build/linux64.sh
```

That's it.
A FIAT application will be located in the `{root}/bin/Release` folder

:::
37 changes: 37 additions & 0 deletions docs/setup_guide/kernel/dev.qmd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
title: "Development install"
---

This is for those who wish to contribute to the development of FIAT.

- First, clone the FIAT repository on Github into a local directory of choice:

```bash
cd ~/{your path}

git clone https://github.com/Deltares/Delft-FIAT.git fiat
```

- Create a new development environment. Make sure you either have tomli or tomllib (build-in with Python 3.11) in your base enviroment. Go into your cloned FIAT repository folder and create the environment file by running the *make_env.py* script:

```bash
cd ~/{your path}/fiat

python make_env.py dev
```

- Then, create and activate the new environment in conda:

```bash
conda env create -f environment.yml

conda activate fiat_dev
```

- To install all the required dependencies, run:

```bash
pip install -e .
```

There you go. FIAT is now installed on your local machine for development purposes.
45 changes: 13 additions & 32 deletions docs/setup_guide/kernel/installation.qmd → docs/setup_guide/kernel/install.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,58 +11,39 @@ To create a new environment follow the steps below.
- Create a new environment:

```bash
conda create -n fiat python=3.11.*
conda create -n fiat python=3.12.*
```
- Activate the environment:

```bash
conda activate fiat`
```

- Install FIAT from Github. After creating the new environment, you need to install all dependencies from the Deltares Github repository. You can use **pip install** to do so:

```bash
pip install git+https://github.com/Deltares/Delft-FIAT.git
```

### Existing environment
If you want to install FIAT into an existing environment, simply activate the desired environment and run:

```bash
pip install git+https://github.com/Deltares/Delft-FIAT.git
```

## For Development
This is for those who wish to contribute to the development of FIAT.

- First, clone the FIAT repository on Github into a local directory of choice:
- Install FIAT from [pypi]():

```bash
cd ~/{your path}
git clone https://github.com/Deltares/Delft-FIAT.git fiat
pip install delft_fiat
```

- Create a new development environment. Make sure you either have tomli or tomllib (build-in with Python 3.11) in your base enviroment. Go into your cloned FIAT repository folder and create the environment file by running the *make_env.py* script:
- Install FIAT from [conda-forge]()

```bash
cd ~/{your path}/fiat
# When conda-forge is added as a channel
conda install delft_fiat
python make_env.py dev
# When not
conda install delft_fiat -c conda-forge
```

- Then, create and activate the new environment in conda:
- Install FIAT from Github. After creating the new environment, you need to install all dependencies from the Deltares Github repository. You can use **pip install** to do so:

```bash
conda env create -f environment.yml
conda activate fiat_dev
pip install git+https://github.com/Deltares/Delft-FIAT.git
```

- To install all the required dependencies, run:
### Existing environment
If you want to install FIAT into an existing environment, simply activate the desired environment and run:

```bash
pip install -e .
pip install git+https://github.com/Deltares/Delft-FIAT.git
```

There you go. FIAT is now installed on your local machine for development purposes.
Loading

0 comments on commit 51f2448

Please sign in to comment.