add documentation pages

added: * introduction * model structure * data sources * interim presentations
Red-Sigma · Jan 28, 2024 · e9671cd · e9671cd
1 parent 610cdb8
commit e9671cd
Show file tree

Hide file tree

Showing 8 changed files with 173 additions and 3 deletions.
diff --git a/docs/book.toml b/docs/book.toml
@@ -4,3 +4,7 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Elk Island National Park Simmulation"
+
+[output.html]
+no-section-label = true # no numbers in front of sections
+default-theme = "light"
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -1,12 +1,11 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Installation](./installation.md)
-- [Configuration](./configuration.md)
 - [Running & Output](./running.md)
+- [Model Structure and Resources](./model_structure.md)
 - [Data sources](./data_sources.md)
 - [Analysis](./analysis.md)
 - [Visualization]()
 
 ---
-[Interimpresentations]()
+[Interim presentations](./presentations.md)
diff --git a/docs/src/assets/01_Presentation_06_Nov_23.pdf b/docs/src/assets/01_Presentation_06_Nov_23.pdf
diff --git a/docs/src/assets/02_Presentation_18_Dez_23.pdf b/docs/src/assets/02_Presentation_18_Dez_23.pdf
diff --git a/docs/src/data_sources.md b/docs/src/data_sources.md
@@ -0,0 +1,89 @@
+# Data sources
+
+## Park
+General Infos and official data [(click)](https://open.canada.ca/en)
+
+## Animals
+### Bison
+
+- Number of Bison in the park
+    - Sources:
+        - [EINP Canada](https://parks.canada.ca/pn-np/ab/elkisland/nature/eep-sar/faq_bison)
+        - [Parks Canada](https://open.canada.ca/data/en/organization/pc?q=Elk+Island+National+Park&keywords=Alberta&portal_type=dataset&collection=primary&sort=)
+- Bison Behaviour
+    - Sources: 
+        - [EINP Canada](https://parks.canada.ca/pn-np/ab/elkisland/securite-safety/bison)
+        - [National Geographic](https://kids.nationalgeographic.com/animals/mammals/facts/american-bison)
+        - [US doi](https://www.doi.gov/blog/15-facts-about-our-national-mammal-american-bison)
+        - [WorldWildLife](https://www.worldwildlife.org/stories/meet-the-bison-facts-about-america-s-iconic-species)
+        - [National park trust](https://parktrust.org/blog/10-facts-about-bison/)
+
+### Moose
+- Number of Moose in the Park
+    - Sources: 
+        - [National Park](https://national-parks.org/canada/elk-island#:~:text=The%20estimates%20for%20these%20include,Exceeding%20over%20500%20deer)
+        - [Parks Canada](https://open.canada.ca/data/en/organization/pc?q=Elk+Island+National+Park&keywords=Alberta&portal_type=dataset&collection=primary&sort=)
+- Moose Behaviour
+    - Sources: 
+        - [National Geographic](https://www.nationalgeographic.com/animals/mammals/facts/moose)
+        - [OneKindPlanet](https://www.onekindplanet.org/animal/moose/)
+        - [NWF org](https://www.nwf.org/Educational-Resources/Wildlife-Guide/Mammals/Moose)
+        - [Northern Ontario](https://northernontario.travel/sunset-country/interesting-facts-about-moose)
+        - [a-z-Animals](https://a-z-animals.com/blog/incredible-moose-facts/)
+
+### Elk
+- Number of Elk in the Park
+    - Sources: 
+        - [National Park](https://national-parks.org/canada/elk-island#:~:text=The%20estimates%20for%20these%20include,Exceeding%20over%20500%20deer)
+        - [Parks Canada](https://open.canada.ca/data/en/organization/pc?q=Elk+Island+National+Park&keywords=Alberta&portal_type=dataset&collection=primary&sort=)
+- Elk Behaviour
+    - Sources: 
+        - [National Geographic](https://www.nationalgeographic.com/animals/mammals/facts/elk-1)
+        - [Altina Wildlife](https://www.altinawildlife.com/wapiti/)
+        - [Nature Canada](https://naturecanada.ca/news/blog/north-american-elk-wapiti/)
+        - [BioKids](http://www.biokids.umich.edu/critters/Cervus_elaphus/)
+        - [a-z-Animals](https://a-z-animals.com/animals/elk/)
+
+
+### Vegetation layer
+
+- NDVI
+    - Satellite pictures: [LANDSAT 8](https://landsat.gsfc.nasa.gov/satellites/landsat-8/ )
+
+
+We have used Normalized Difference Vegetation Index (NDVI) for Vegetation layer, since it is a simple indicator that can be used to analyse remote sensing measurements and assess whether the target area contains live green vegetation or not. It is calculated from the visible and near-infrared light reflected by vegetation. NDVI values range from -1 to 1, with higher values indicating healthier, more dense vegetation.
+
+![Image](https://eos.com/wp-content/uploads/2020/07/plants.jpg.webp)
+
+The formula for NDVI is:
+
+    NDVI = (NIR - RED) \ (NIR + RED)
+
+Where:
+
+NIR represents the amount of near-infrared light reflected.
+RED represents the amount of red light reflected.
+
+All calculations and file format conversions are made in QGIS.
+
+## Map/Geo features
+Layers for our model (water layer, wood, roads etc.) were extracted from OpenStreetMap and converted in format supported by MARS. More info on feature extraction and how to query them on [OpenStreet Map Wiki](https://wiki.openstreetmap.org/wiki/Map_features#Street_parking_tagged_on_the_main_roadway_(see_Street_parking)).
+
+## How to get additional raster data
+To create a georeferenced raster layer of your simulation area, please see the [MARS](https://www.mars-group.org/docs/tutorial/intro#what-is-mars) documentation.
+
+Raster layers can be queried, extracted and converted with [QGIS](https://qgis.org/en/site/) or at [Geojson](https://geojson.io/) website.
+
+## Reference projects and papers
+
+[MARS-Group-HAW/blueprint-georaster](https://github.com/MARS-Group-HAW/blueprint-georaster)
+[MARS-Group-HAW/model-knp-elephant](https://github.com/MARS-Group-HAW/model-knp-elephant)
+
+Jennifer M., Boyce Mark S. (2022). Bison and elk spatiotemporal interactions in Elk Island National Park. [(link)](https://www.frontiersin.org/articles/10.3389/fcosc.2022.937203/full)
+
+Thomas Clemen, Ulfia A. Lenfers, Janus Dybulla, Sam M. Ferreira, Greg A. Kiker, Carola Martens, Simon Scheiter. (2021).
+A cross-scale modeling framework for decision support on elephant management in Kruger National Park, South Africa.
+Ecological Informatics. [(link)](https://www.sciencedirect.com/science/article/pii/S1574954121000571)
+
+Bunting, Erin & Fullman, Timothy & Kiker, G. & Southworth, Jane. (2016). Utilization of the SAVANNA model to analyze future patterns of vegetation cover in Kruger National Park under changing climate. [(link)](https://geog.ufl.edu/2016/10/17/utilization-of-the-savanna-model-to-analyze-future-patterns-of-vegetation-cover-in-kruger-national-park-under-changing-climate/)
+
diff --git a/docs/src/introduction.md b/docs/src/introduction.md
@@ -0,0 +1,54 @@
+# Introduction
+The EINP Model is a simple MARS model that incorporates georeferenced raster and vector data. The model's environment represents the Elk Island National Park in Alberta, Canada. This area is modelled as a grid layer with georeferenced cells.
+
+We simulate the behaviour of Bison, Moose and Elk inside the park, using agents.
+
+Our goal is to provide an initial impression of how the animal populations evolves over time to make an estimate of to total carrying capacity of Elk Island National Park.
+
+> Note: In its current state the model does not represent real animal behaviour accurately, and we hope that more features can be added in the future.
+
+## Quickstart
+To use the model clone the repository by running:
+```bash
+git clone https://github.com/Red-Sigma/einp-model.git
+```
+
+Then go into the newly downloaded project and run the simulation:
+```bash
+cd einp-model/GeoRasterBlueprint/
+dotnet run -sm config.json
+```
+
+If you want more details and options on how to run the simulation please have a look at [Running & Output](./running.md)
+
+## Project Structure
+
+After running `git clone` you should have a folder that looks similar to the one below.
+
+```bash
+einp-model/
+├── docs/
+├── GeoRasterBlueprint/
+│   ├── Model/
+│   ├── Resources/
+│   ├── config.json
+│   ├── GeoRasterBlueprint.csproj
+│   ├── Program.cs
+│   └── run.sh
+├── GeoRasterBlueprint.sln
+├── LICENSE
+└── README.md
+```
+
+- `docs/`: the source of [red-sigma.github.io/einp-model](https://red-sigma.github.io/einp-model/)
+- `GeoRasterBlueprint/`: contains most of the model source
+    - `Model/`: source code for layers and agents
+    - `Resources/`: assets like the spawn locations of the animals
+    - `config.json`: the main configuration file that parametrizes the model
+    - `GeoRasterBlueprint.csproj`: a configuration file of the .NET framework
+    - `Program.cs`: the main entry point where the simulation starts
+    - `run.sh`: a convenience [bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) script to run the model from a terminal
+- `GeoRasterBlueprint.sln`: a .NET solution file for use with Visual Studio
+- `LICENSE`: a copy of the MIT-license under which this project is licensed
+- `README.md`: a file describing the project
+
diff --git a/docs/src/model_structure.md b/docs/src/model_structure.md
@@ -0,0 +1,16 @@
+# Model Structure and Resources
+
+The following components and resources make up the model:
+
+- `Bison`: This agent type models a bison that moves around randomly in the Elk Island National Park. When its Energy is below a certain threshold, it queries the WaterLayer (see below) for a water source to navigate to. Bison agents are parameterized with the **bisons.csv** file in the `Resources` folder.
+
+- `Moose`: This agent type models a moose that moves around randomly in the Elk Island National Park. When its Energy is below a certain threshold, it queries the WaterLayer (see below) for a water source to navigate to. Moose agents are parameterized with the **moose.csv** file in the `Resources` folder.
+
+- `Elk`: This agent type models an elk that moves around randomly in the Elk Island National Park. When its Energy is below a certain threshold, it queries the WaterLayer (see below) for a water source to navigate to. Bison agents are parameterized with the **elks.csv** file in the `Resources` folder.
+
+- `Perimeter`: This vector layer holds the perimeter of the Elk Island National Park. The georeferenced data are provided by the `einp_perimeter.geojson` file in the `Resources/` folder.
+
+- `WaterLayer`: The raster layer holds a set of pixels that represent water sources in the Elk Island National Park. The georeferenced data of the water sources are provided by the `einp_water_spots.geojson` file in the `Resources/` folder.
+
+- `LandscapeLayer`: This layer holds a grid of cells. Each cell is referenced by geo-coordinates. The georeferenced data contained in the `Model` folder are used to determine which cell is accessible (i.e., within the perimeter) and inaccessible (i.e., outside the perimeter).
+
diff --git a/docs/src/presentations.md b/docs/src/presentations.md
@@ -0,0 +1,8 @@
+# Interim presentations
+
+Presentations that were used to show our progress to the other people in the course.
+
+- [Presentation 1 on 11th November 2023](./assets/01_Presentation_06_Nov_23.pdf)
+- [Presentation 2 on 18th December 2023](./assets/02_Presentation_18_Dez_23.pdf)
+- [Presentation 3 on 29th January 2024]()
+  - TODO: add presentation