Extended the documentation

tomorrowcities/content/articles/data.md

@@ -51,18 +51,33 @@ The layers supported by tomorrowcities are listed below.  In this section, we wi
 ### Buildings
 Buildings are the core component of visioning scenarios. The features of the building with some example data are shown below:
 
-|zoneID| bldID | nHouse | residents | specialFac | expStr          | fptarea | geometry     | 
+|zoneid| bldid | nhouse | residents | specialfac | expstr          | fptarea | geometry     | 
 |------|-------|--------|-----------|------------|-----------------|---------|--------------|
 |4     | 17    | 41     | 178       | 0          |RCi+HC+18s+ResCom| 111     | MultiPolygon |
 
 
 where
 
-* **zoneID (integer)** refers to the unique identitifer of the zone that building is located in. The features of the corresponding zone is described in a dedicated zone table.
-* **bldID (integer)** is a unique building identifier.
-* **nHouse (integer)** is the number of household in that building.
+* **zoneid (integer)** refers to the unique identitifer of the zone that building is located in. The features of the corresponding zone is described in a dedicated zone table.
+* **bldid (integer)** is a unique building identifier.
+* **nhouse (integer)** is the number of household in that building.
 * **residents (integer)** stores the number of individual live in the building.
-* **expStr (string)** 
+* **expstr (string)** 
+
+### Households
+Households are defined in a tabular format whose attributes are shown below:
+
+|bldid|hhid|income|nind|commfacid|
+|-----|----|------|----|---------|
+|17   |12  |lowIncomeA|3|3643|
+
+where
+
+* **bldid (integer)** is the building identifier where the household is located in 
+* **hhid (integer)** is the unique identifier for the household
+* **income (string)** is the income level of the household
+* **nind (integer)** is the number of individuals living in the household
+* **commfacid (integer)** is the building identifier of the community facility. In Tomorrow's Cities, it is used to define the hospital associated with the household. 
 
 ### Intensity Measures
 Whether it is flood, debris or earthquake, every hazard map should contain at least two properties: a point geometry and intensity measure denotes by 'im'. The data can be provided via GeoTIFF or GeoJSON format. TIFF files should contain CRS 

tomorrowcities/content/articles/metrics.md

@@ -14,12 +14,12 @@ category:
 [TOC]
 
 ## Metrics
-There are seven fundamental impact metrics displayed in the web application. For each them there is an associcated threhold but for the sake of simplicity, it is not explicitly stated.
+There are seven fundamental impact metrics displayed in the web application. 
+Their calculations heavily depend on the damage state of buildings and/or other
+infrastructural elements such as electrical power generators, roads or bridges. 
 
 ### Metric 1: Number of workers unemployed
-It denotes the number of invidivuals who last their jobs either due to a severe damage at the workplace 
-or lost access to a functional workplace. When the metrics is displayed on a building-level, it is the sum of
-such individuals living in that building.
+It denotes the number of invidivuals who lost their jobs either due to a damage at the workplace or lost access to a workplace. When the metrics is displayed on a building-level, it is the total number of such individuals living in that building.
 
 ### Metric 2: Number of children with no access to education
 Similar to the first metrics but individual here refers to a child who is associated with a school.
@@ -27,8 +27,11 @@ The metric becomes active if the school is damaged or not accessible.
 
 ### Metric 3: Number of households with no access to hospital
 The number of households who lost its access to its associated hospital.
-Either hospital is damaged or the path between the household and the hospital
-is broken.
+Access is lost when any of the following conditions hold:
+
+* the damage state of the associated hospital is beyond a threshold
+* the associated hospital is inaccessible via transportation network
+* the associated hospital has no electricity
 
 ### Metric 4: Number of individuals with no access to hospital
 It is derived from metric 3 by counting the individuals in the corresponding households.

tomorrowcities/content/articles/road.md

@@ -20,28 +20,40 @@ earthquake and flood damage assessment on road networks.
 ## Quick Start
 For the impatient readers, here is a quick road to conduct road network analysis.
 
-* Download [Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing)
-* Go to https://huggingface.co/spaces/hkayabilisim/app-engine/engine
-* Go the [Engine](/engine)
-* Drag and drop the following files inside sample dataset to the engine:
-* rapti_road_edges.geojson
-* rapti_road_nodes.geojson
-* rapti_road_fragility.xlsx
-* rapti_flood_max_depth_70yr_future_212mm_05.tif
-* rapti_dummy_individual.json
-* rapti_dummy_household.json
-* rapti_dummy_buildings.geojson
-* Unselect *Building*
-* Select Road and Earthquake for infrastructure and hazard type, respectively.
-* Click Calculate to run the engine.
+* Go to engine
+* Download [Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing) to your local environment and unzip the archive file.
+* Drag/drop following files in the sample dataset to the drop zone of the engine.
+   rapti_dummy_buildings.geojson
+   rapti_dummy_earthquake_fragility.xlsx
+   rapti_dummy_household.json
+   rapti_dummy_individual.json
+   rapti_dummy_landuse.geojson
+   rapti_flood_max_depth_20yr_future_173mm_05.tif
+   rapti_road_edges.geojson
+   rapti_road_fragility.xlsx
+   rapti_road_nodes.geojson
+* Select **building** from the infrastructure, **earthquake** from hazard and click **calculate**
+* Observe the metrics populating. Please note that metric3 (number of households with no access to hospitals) is zero because the only hospital in the exposure is not affected.
+* Now also select **road** from the infrastructure and click **calculate**
+* Observe that the metric3 will be non-zero because there will be many buildings which lost access to the hospital due to the damaged bridges in the transportation network.
+
+<video width="853" controls>
+  <source src="https://github.com/TomorrowsCities/tomorrowcities/assets/2515171/ec2dc36d-fe76-42fb-b9be-47a1690374de" type="video/mp4">
+</video>
 
 When completed successfully:
 
 * The damage state of the bridges will be shown in the *ds* attribute of the *road edges* layer.
 * In the same layer, you will see the boolean *is_damaged* attribute.
 * The roads in the *road edge* layer will also be colored red if *is_damaged* attribute is true.
-* Every building will have a new attribute called *nearest_road_node* which determines the nearest junction point
+* Every building will have a new attribute called *node_id* which determines the nearest junction point
 of the transportation network. When you click the buildings, this information will be shown in details view.
+* In **building** and **household** layers, a new attribute (**hospital_acccess**) will be shown to indicate 
+the accessibility of hospital. For a household, it implies the accessibility of associated hospital whereas, 
+for a building it means that the building can access to at least one *hospital node* which is simple a node in the 
+transportation network for which a hospital is assigned to. 
+* The third metric, which is the number of households with no access to hospitals, will be non-zero when **road**
+infrastructure is selected for analysis.
 
 ## Data
 From a computational point of perspective, a road transportation network is a bi-directional graph
@@ -104,9 +116,8 @@ Whereas a sink is a node where hospitals are associated.
 
 ### Earthquake
 * Unlike flood, in earthquake we don't need to create a buffer around roads. Instead,
-we simply find the nearest intensity measure to the road.
+we simply find centroid of the bridge and find closest intensity measure to the centroid.
 
-After 
 
 ### Parameters
 As you may notice, there are several parameters used in the calculations. Let's summarize them here:

tomorrowcities/content/articles/welcome.md

@@ -17,6 +17,16 @@ category:
 TCDSE is a web application designed to conduct computational tasks to generate information needed for decision mechanisms in designing future cities. The web application, which will be referred as TCDSE for short, contains a computational engine capable of executing several hazard scenarios on different exposure datasets and infrastructures. 
 
 ## What is New?
+
+**v0.2.1**
+
+* [27dd195](https://github.com/TomorrowsCities/tomorrowcities/commit/27dd195a240cbb97a97d124fc9b132ee2ea1f5e9) Integrated road network analysis into metric3
+* [de6fbca](https://github.com/TomorrowsCities/tomorrowcities/commit/de6fbca8d8b03d350096190ae35646f47a9a0414) Changed engine layout to be more compact 
+* [bc436b6](https://github.com/TomorrowsCities/tomorrowcities/commit/bc436b62c35f66b7432e40ca5e6c47364690c8f3) Bugfix a layout problem in engine page 
+* [0b1cd96](https://github.com/TomorrowsCities/tomorrowcities/commit/0b1cd96149e129de30e5524f8956db1569202450) Bugfix in metric calculation: a typo in code_level 
+* Extended documentation in welcome, data, metrics, and road pages.
+* Added [a demonstration video](https://github.com/TomorrowsCities/tomorrowcities/assets/2515171/ec2dc36d-fe76-42fb-b9be-47a1690374de) to GitHub discussion page[discussion](https://github.com/TomorrowsCities/tomorrowcities/discussions/6).
+
 **v0.2**
 
 * Transportation network analysis for flood and earthquake damage assessment
@@ -47,41 +57,55 @@ TCDSE is a web application designed to conduct computational tasks to generate i
 when clicked.
 * Implementation Capacity Score is added. If medium or low is selected, then building-level metrics is increased by 25% and 50%, respectively. If high is selected, there is no change in the metrics.
 
-### New policies
-* Eight new policies are added. See their definitions [here](/docs/policies)
-* New info related to flood damage assessment is added [here](/docs/flood)
+## Quickstart
+* Download [Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing) to your local environment and unzip the archieve file.
+* Go to [engine](/engine)
+* Drag/drop necessary files to the drop zone of the engine and execute the engine. A sample session is displayed below. 
+* The impact metrics will be immediately seen on the page.
+
+<video width="853" controls>
+  <source src="https://github-production-user-asset-6210df.s3.amazonaws.com/2515171/270064030-0733ad34-0a7f-445e-86fb-9a61df4e2969.mp4" type="video/mp4">
+</video>
 
-### Policy Support
-Two new policies are added to the computing engine. More info is [here](/docs/policies)
+In case the file names in the video are not clearly seen, they are: 
 
-### Excel support:
-You can  upload Excel files containing your tabular data such as individual, household, fragility or vulnerability data. However, processing excel files is very slower than processing JSON files so I definitely suggest working with JSON files. You can convert your Excel files via panda framework. The platform also does not try to convert the coordinates even if there is any in the Excel file because there is no way to know which columns represent the coordinates or coordinate reference systems without metadata. So Excel spreadsheets should be used to provide non-geo related tabular data.  So please use them only for data not containing any geo-specific information. 
+* nairobi_business_buildings.geojson
+* nairobi_business_household.json
+* nairobi_business_individual.json
+* nairobi_earthquake_fragility.json
+* nairobi_earthquake_intensity.geojson
 
-### Dar Es Salaam Study
-[Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing) now contains some visioning scenario for Dar Es Salaam case.
+The used files above satisfy minimum requirements to run Earthquake analysis on buildings. 
 
 ## Features
 General capabilities/features of the web application can be summarized as follows:
 
-
 *Hazard Scenarios*
 
 * Earthquake
 * Flood
-* Debris
 
 *Exposure Scenarios*
 
 * Buildings
 * Power networks
 * Transportation
-* Water networks
 
 *Impact Metrics*
 
 * Building and infrastructure-level damage states
 * Household and individual-level derived metrics
 
+*Policies*
+
+* 20 [policies](/docs/policies) related to damage mitigation
+
+*[Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing)*
+
+* Dar Es Salaam
+* Rapti
+* Nairobi
+
 *Visualization*
 
 * GIS Maps
@@ -92,7 +116,8 @@ General capabilities/features of the web application can be summarized as follow
 *Data structure*
 
 * GeoJSON format for geospatial data
-* Vanilla JSON for non-geospatioal tabular data
+* Vanilla JSON and Excel for non-geospatioal tabular data
+* XML support for [Global Vulnerability Model](https://github.com/gem/global_vulnerability_model) 
 
 *Software*
 
@@ -100,25 +125,4 @@ General capabilities/features of the web application can be summarized as follow
 * Reactive user interface via Solara
 * geospatial database via postgis
 * Leaflet backend for maps
-* Easy deployment to cloud
-
-
-## Quickstart
-* Download [Sample Dataset](https://drive.google.com/file/d/1BGPZQ2IKJHY9ExOCCHcNNrCTioYZ8D1y/view?usp=sharing) to your local environment and unzip the archieve file.
-* Go to [engine](/engine)
-* Drag/drop necessary files to the drop zone of the engine and execute the engine. A sample session is displayed below. 
-* The impact metrics will be immediately seen on the page.
-
-<video width="853" controls>
-  <source src="https://github-production-user-asset-6210df.s3.amazonaws.com/2515171/270064030-0733ad34-0a7f-445e-86fb-9a61df4e2969.mp4" type="video/mp4">
-</video>
-
-In case the file names in the video are not clearly seen, they are: 
-
-* nairobi_business_buildings.geojson
-* nairobi_business_household.json
-* nairobi_business_individual.json
-* nairobi_earthquake_fragility.json
-* nairobi_earthquake_intensity.geojson
-
-The used files above satisfy minimum requirements to run Earthquake analysis on buildings. 
+* Easy deployment to cloud