Skip to content

Commit a0ccd70

Browse files
wesleyboarnbonfantesebabedin
authored
Adding a new use case - v3 merge conflict resolved (#252)
## What Did You Change? _On behalf of @nbonfante:_ > […] adding a New Use Case > — #251 ## Do You Want Support (syntax, design, etc)? - [x] Verify changes matches those of #251. - [x] Create a new PR to fix problems, #255. - [x] Show fixes to @nbonfante so as to teach. ## Any Reference Material Worth Sharing? Fixes merge conflict with #251, whose edits began on v2, but PR was made to v3. --------- Co-authored-by: nbonfante <nbonfante2023@my.fit.edu> Co-authored-by: Seb <sebabedin@gmail.com>
1 parent b13b012 commit a0ccd70

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎user-guide/usecases/pinelli/4usecase.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Empirical Hurricane Vulnerability and Fragility Curves
2+
3+
**Bonfante, N. – Florida Institute of Technology**<br>
4+
**Pinelli, J-P. – Professor - Florida Institute of Technology**<br>
5+
**Bakhshandeh, M. – Florida Institute of Technology**<br>
6+
**Guennec, T. - Florida Institute of Technology**<br>
7+
8+
**Keywords:** Fragility Curves, Vulnerability Matrix, Insurance Claims, Python, Jupyter
9+
10+
## Description
11+
12+
This project develops a reproducible and transparent workflow for analyzing the vulnerability and fragility of buildings subjected to hurricane winds. Using a suite of interconnected Jupyter notebooks, the workflow transforms raw hazard and exposure datasets into processed information, computes building-level or group-level damage ratios, and generates empirical vulnerability matrices. These matrices are then fitted into continuous vulnerability and fragility curves, which quantify how expected damage ratios and probabilities of exceeding damage thresholds evolve with wind speed. The notebooks also provide tools for comparing curves across different building classes, construction types,etc, enabling both validation and deeper insights into resilience.
13+
14+
The data produced in this project can be reused in multiple ways. The outputs (CSV tables and PNG figures) are readily applicable to catastrophe modeling for insurance and reinsurance, where vulnerability and fragility curves form a critical input for risk assessment. They can also support academic research by serving as benchmarks for methodological comparisons, or by being integrated into multi-hazard frameworks. In addition, policy makers and code developers can leverage these datasets to evaluate how construction practices influence structural performance, guiding the design of more resilient standards. Because the entire pipeline is coded in Python and documented step by step, users can easily adapt the notebooks to new datasets, hazard events, or structural inventories, ensuring long-term reusability.
15+
16+
The uniqueness of this project lies in its transparency, flexibility, and modularity. Traditional catastrophe models often operate as black boxes, limiting validation and adaptability. In contrast, this framework provides open-source, step-by-step tools that combine empirical data processing, statistical rigor (outlier detection, logistic regression, performance metrics), and visualization in a single reproducible environment. Users may execute the full sequence of notebooks for a complete study, or selectively run modules to focus on specific tasks such as curve fitting or comparative analysis. This adaptability makes the workflow valuable for both detailed case studies and broad comparative research.
17+
18+
The primary audience for this project includes researchers in wind engineering, structural safety, and risk analysis who require transparent methods for vulnerability modeling. It is also intended for insurance and reinsurance professionals seeking empirically derived curves for underwriting, pricing, and capital allocation. Policy makers and engineers can use the results to support evidence-based decision making and improvements in building codes. Finally, educators and students can adopt the notebooks as teaching material for courses on catastrophe modeling, vulnerability analysis, and disaster risk reduction.
19+
20+
**Key steps:**
21+
22+
- **Data Processing:** Cleaning raw datasets and producing an integrated hazard–damage file.
23+
- **Damage Ratio Calculation:** Computing losses relative to replacement value and assigning wind-speed bins.
24+
- **Vulnerability Matrix Construction:** Aggregating expected damage ratios (EDR) by wind-speed intervals.
25+
- **Curve Fitting:** Generating empirical and logistic-smoothed vulnerability curves.
26+
- **Fragility Development:** Computing exceedance probabilities for defined thresholds.
27+
- **Curve Comparison:** Overlaying curves across structures, construction periods, or datasets.
28+
29+
## Resources
30+
31+
### Jupyter Notebooks
32+
33+
The following Jupyter notebooks are available to facilitate the analysis of each case.
34+
You can access and run them directly on **DesignSafe** by clicking the link below:
35+
36+
| **Scope** | **Notebook** | **Open in DesignSafe** |
37+
|-----------|--------------|-------------------------|
38+
| Generate processed hazard & exposure dataset | `00_generator_of_processed_Info_Natural_Event.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
39+
| Compute damage ratios and define wind ranges | `03_damage_ratios_&_ranges.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
40+
| Build empirical vulnerability matrix | `05_vulnerability_matrix.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
41+
| Fit and visualize vulnerability curves | `08_vulnerability_curve_analysis.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
42+
| Generate fragility curves | `13_Fragility_curve_analysis.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
43+
| Compare curves across structural classes | `18_Comparison_of_curves_analysis.ipynb` | [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2) |
44+
45+
### DesignSafe Resources
46+
47+
The following DesignSafe resources were used in developing this Use Case:
48+
49+
- [Jupyter notebook on DesignSafe JupyterHub](https://www.designsafe-ci.org/rw/workspace/jupyter/)
50+
- [DesignSafe Publication: Empirical Hurricane Vulnerability and Fragility Curves (DOI: 10.17603/ds2-q60v-z247)](https://doi.org/10.17603/ds2-q60v-z247)
51+
52+
## System Requirements
53+
54+
- **Python 3.11+**
55+
- **Jupyter Notebook environment** (DesignSafe JupyterHub or local)
56+
57+
## Required Libraries
58+
59+
Before running the notebook, make sure the following Python libraries are installed:
60+
61+
| **Package** | **Description** |
62+
|-------------|-----------------|
63+
| `numpy` | Numerical operations and array handling |
64+
| `pandas` | Data manipulation and tabular data processing |
65+
| `scipy` | Curve fitting and optimization routines (`curve_fit`) |
66+
| `scikit-learn` | Regression metrics (R², MAE, RMSE) used for evaluating fitted curves |
67+
| `matplotlib` | Plotting vulnerability and fragility curves |
68+
| `seaborn` | Statistical visualization and enhanced plotting (used in damage ratio analysis) |
69+
70+
## Steps to Run
71+
72+
1. **Download or access the repository:** [![Open in DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.published/PRJ-6138?version=2)
73+
74+
2. **Open the Jupyter notebooks** located in the root directory:
75+
- `00_generator_of_processed_Info_Natural_Event.ipynb`
76+
- `03_damage_ratios_&_ranges.ipynb`
77+
- `05_vulnerability_matrix.ipynb`
78+
- `08_vulnerability_curve_analysis.ipynb`
79+
- `13_Fragility_curve_analysis.ipynb`
80+
- `18_Comparison_of_curves_analysis.ipynb`
81+
3. **Use the input CSV files already provided** inside the folder:
82+
```
83+
00_data_cleaned/
84+
```
85+
4. **Execute the notebooks in sequence**, from `00_` to `18_`, ensuring that all cells run successfully.
86+
87+
5. **Processed outputs** will be automatically generated at each stage, including:
88+
- Combined and cleaned datasets
89+
- Damage ratios
90+
- Vulnerability matrices
91+
- Vulnerability curves (empirical and logistic regression)
92+
- Fragility curves
93+
- Comparative vulnerability/fragility plots
94+
95+
6. All output files are saved in the same directory as the notebooks, following the sequential numbering (00–22) generated throughout the workflow.
96+
97+
### Using the Notebooks: A Practical Guide
98+
99+
This workflow provides a structured, step-by-step process for transforming cleaned hazard–damage records into empirical vulnerability and fragility curves. Each notebook performs a specific analytical stage, and running them sequentially ensures a consistent data pipeline from raw inputs to final comparisons.
100+
101+
The following guidance summarizes what each notebook does, what to expect, and how to interpret the outputs.
102+
103+
1. **Generate the processed hazard–exposure dataset**
104+
105+
**Notebook:** `00_generator_of_processed_Info_Natural_Event.ipynb`
106+
This notebook loads the cleaned input files found in `00_data_cleaned/`, verifies their structure, and merges hazard data (wind speeds) with exposure and damage attributes.
107+
It produces the first standardized dataset used by all subsequent steps.
108+
**Outputs:** `01_checking_data.csv`, `02_combined_processed_files.csv`.
109+
110+
111+
2. **Compute damage ratios and define wind-speed ranges**
112+
113+
**Notebook:** `03_damage_ratios_&_ranges.ipynb`
114+
This step calculates the *damage ratio* for each record (loss divided by replacement value) and assigns each row to a wind-speed bin.
115+
The notebook also produces exploratory visualizations to understand early behavior of the data.
116+
**Output:** `04_combined_processed_with_ratios.csv`.
117+
118+
3. **Build the empirical vulnerability matrix**
119+
120+
**Notebook:** `05_vulnerability_matrix.ipynb`
121+
This notebook aggregates thousands of records into an empirical vulnerability matrix, where each wind-speed bin is associated with an Expected Damage Ratio (EDR).
122+
It also generates a graphical summary of empirical EDR values.
123+
**Outputs:** `06_vulnerability_matrix.csv`, `07_vulnerability_matrix.png`.
124+
125+
4. **Fit and visualize vulnerability curves**
126+
127+
**Notebook:** `08_vulnerability_curve_analysis.ipynb`
128+
This step transforms the empirical matrix into a smooth functional curve.
129+
Two representations are produced:
130+
- **Empirical curve** derived directly from observed data.
131+
- **Logistic-regression curve** that provides a smooth vulnerability function across all wind speeds.
132+
133+
Model performance is evaluated using R², RMSE, MAE, and visual comparison.
134+
**Outputs:** `09_vulnerability_data.csv`, `10_vulnerability_data.png`,
135+
`11_vulnerability_curve_with_logistic_regression.csv`,
136+
`12_vulnerability_curve_with_logistic_regression.png`.
137+
138+
139+
140+
5. **Generate fragility curves**
141+
142+
**Notebook:** `13_Fragility_curve_analysis.ipynb`
143+
This notebook converts vulnerability information into *fragility curves*, which express the probability that damage exceeds a specified threshold.
144+
These curves are useful for engineering applications, insurance analysis, and risk modeling.
145+
**Outputs:** `14_fragility_data.csv`, `15_fragility_data.png`,
146+
`16_fragility_curves_with_logistic_regression.csv`,
147+
`17_fragility_curves_with_logistic_regression.png`.
148+
149+
150+
151+
6. **Compare vulnerability and fragility across classes**
152+
153+
**Notebook:** `18_Comparison_of_curves_analysis.ipynb`
154+
The final step allows side-by-side comparisons of vulnerability and fragility curves across construction classes, building types, or datasets.
155+
This notebook highlights differences in performance and produces publication-ready figures.
156+
**Outputs:**
157+
`19_comparison_vulnerability_curves.csv`,
158+
`20_comparison_vulnerability_curves.png`,
159+
`21_fragility_comparison_Fragility_10.csv`,
160+
`22_fragility_comparison_Fragility_10.png`.
161+
162+
163+
164+
### Summary
165+
166+
By following the notebooks in order, the user progresses from clean hazard–damage information to calibrated vulnerability curves, fragility relationships, and cross-class comparisons.
167+
Each stage can be modified or reused independently, allowing researchers, engineers, and practitioners to adapt the workflow to different hazard datasets, damage metrics, or structural classes.
168+
169+
170+
## Inputs and Outputs
171+
172+
| **Notebook** | **Inputs** | **Outputs** |
173+
|--------------|------------|-------------|
174+
| `00_generator_of_processed_Info_Natural_Event.ipynb` | damage CSV files in `00_data_cleaned/` | `01_checking_data.csv`<br>`02_combined_processed_files.csv` |
175+
| `03_damage_ratios_&_ranges.ipynb` | `02_combined_processed_files.csv` | `04_combined_processed_with_ratios.csv` |
176+
| `05_vulnerability_matrix.ipynb` | `04_combined_processed_with_ratios.csv` | `06_vulnerability_matrix.csv`<br>`07_vulnerability_matrix.png` |
177+
| `08_vulnerability_curve_analysis.ipynb` | `06_vulnerability_matrix.csv` | `09_vulnerability_data.csv`<br>`10_vulnerability_data.png`<br>`11_vulnerability_curve_with_logistic_regression.csv`<br>`12_vulnerability_curve_with_logistic_regression.png` |
178+
| `13_Fragility_curve_analysis.ipynb` | `06_vulnerability_matrix.csv` | `14_fragility_data.csv`<br>`15_fragility_data.png`<br>`16_fragility_curves_with_logistic_regression.csv`<br>`17_fragility_curves_with_logistic_regression.png` |
179+
| `18_Comparison_of_curves_analysis.ipynb` | `11_vulnerability_curve_with_logistic_regression.csv`<br>`16_fragility_curves_with_logistic_regression.csv` | `19_comparison_vulnerability_curves.csv`<br>`20_comparison_vulnerability_curves.png`<br>`21_fragility_comparison_Fragility_10.csv`<br>`22_fragility_comparison_Fragility_10.png` |
180+
181+
182+
## Workflow Options
183+
184+
**Case 1 — Single Class Analysis**
185+
Run the full sequence once for one building class:
186+
187+
```
188+
00 → 03 → 05 → 08 → 13
189+
```
190+
191+
Produces vulnerability and fragility curves for a single structural class.
192+
193+
**Case 2 — Comparison of Two Classes**
194+
1. Run the full workflow for **Class A** (with suffix A).
195+
2. Run the workflow again for **Class B** (with suffix B).
196+
3. Compare curves using `18_Comparison_of_curves_analysis.ipynb`.
197+
198+
This enables evaluation across construction periods, structural types, and datasets.
199+
200+
## Citation
201+
> Bonfante, N., Pinelli, J.-P., Bakhshandeh, M., & Guennec, T. (2025). *Empirical Hurricane Vulnerability and Fragility Curves*. DesignSafe-CI. DOI: [10.17603/ds2-q60v-z247](https://doi.org/10.17603/ds2-q60v-z247)
202+
## Licensing
203+
**License:** BSD 3-Clause License
204+
205+
## Acknowledgment:
206+
This research was supported by the **National Science Foundation (NSF)** under **Award No. 1520817**, through the **NHERI DesignSafe Cyberinfrastructure**. The opinions and conclusions expressed are those of the authors and do not necessarily reflect the views of the NSF.

0 commit comments

Comments
 (0)