Fixes #401 - added buyout decision analysis documentation

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Social vulnerability score analysis documentation and example notebook [#392](https://github.com/IN-CORE/incore-docs/issues/392)
 - Google Analytics to the main documentation [#399](https://github.com/IN-CORE/incore-docs/issues/399)
 - Google Analytics to the api sphinx documentation [#396](https://github.com/IN-CORE/incore-docs/issues/396)
+- Buyout decision analysis documentation and example notebook [#401](https://github.com/IN-CORE/incore-docs/issues/401)
 
 ## [4.11.0] - 2024-04-30
 

manual_jb/content/_toc.yml

@@ -20,6 +20,7 @@ chapters:
       - file: analyses/building_func
       - file: analyses/building_loss
       - file: analyses/building_nonstructural_dmg
+      - file: analyses/buyout_decision
       - file: analyses/capital_shocks
       - file: analyses/combined_wind_wave_surge_building_dmg
       - file: analyses/combined_wind_wave_surge_building_loss

manual_jb/content/analyses.md

@@ -6,45 +6,46 @@
 4. [Building functionality](analyses/building_func)
 5. [Building economic loss](analyses/building_loss)
 6. [Building nonstructural damage](analyses/building_nonstructural_dmg)
-7. [Capital shocks](analyses/capital_shocks)
-8. [Combined wind wave surge building damage](analyses/combined_wind_wave_surge_building_dmg)
-9. [Combined wind wave surge building loss](analyses/combined_wind_wave_surge_building_loss)
-10. [Commercial building recovery](analyses/commercial_building_recovery)
-11. [Cumulative building damage](analyses/cumulative_building_dmg)
-12. [Electric power facility damage](analyses/epf_dmg)
-13. [Electric power facility repair cost](analyses/epf_repair_cost)
-14. [Electric power facility restoration](analyses/epf_restoration)
-15. [Electric power network functionality](analyses/epn_functionality)
-16. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
-16. [Gas facility damage](analyses/gas_facility_damage)
-17. [Household-level housing sequential recovery](analyses/housing_household_recovery)
-18. [Housing recovery](analyses/housing_recovery)
-19. [Housing unit allocation](analyses/housingunitallocation)
-20. [Interdependent Network Design Problem](analyses/indp)
-21. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
-22. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
-23. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
-24. [Mean damage](analyses/mean_dmg)
-25. [Monte Carlo failure probability](analyses/mc_failure_prob)
-26. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
-27. [Network cascading interdependency functionality](analyses/nci_functionality)
-28. [Nonstructural building damage](analyses/non_structural_building_dmg)
-29. [Pipeline damage](analyses/pipeline_dmg)
-30. [Pipeline damage with repair rate](analyses/pipeline_dmg_w_repair_rate)
-31. [Pipeline functionality](analyses/pipeline_functionality)
-32. [Pipeline repair cost](analyses/pipeline_repair_cost)
-33. [Pipeline restoration](analyses/pipeline_restoration)
-34. [Population dislocation](analyses/populationdislocation)
-35. [Residential building recovery](analyses/residential_building_recovery)
-36. [Road damage](analyses/road_dmg)
-37. [Salt Lake City Computable General Equilibrium (CGE)](analyses/slc_cge.md)
-38. [Seaside Computable General Equilibrium (CGE)](analyses/seaside_cge)
-39. [Social Vulnerability](analyses/social_vulnerability)
-40. [Social Vulnerability Score](analyses/social_vulnerability_score)
-41. [Tornado electric power network (EPN) damage](analyses/tornadoepn_dmg)
-42. [Traffic flow recovery](analyses/traffic_flow_recovery)
-43. [Transportation recovery](analyses/transportation_recovery)
-44. [Water facility damage](analyses/waterfacility_dmg)
-45. [Water network functionality](analyses/wfn_functionality)
-46. [Water facility repair cost](analyses/water_facility_repair_cost)
-47. [Water facility restoration](analyses/water_facility_restoration)
+7. [Buyout decision](analyses/buyout_decision)
+8. [Capital shocks](analyses/capital_shocks)
+9. [Combined wind wave surge building damage](analyses/combined_wind_wave_surge_building_dmg)
+10. [Combined wind wave surge building loss](analyses/combined_wind_wave_surge_building_loss)
+11. [Commercial building recovery](analyses/commercial_building_recovery)
+12. [Cumulative building damage](analyses/cumulative_building_dmg)
+13. [Electric power facility damage](analyses/epf_dmg)
+14. [Electric power facility repair cost](analyses/epf_repair_cost)
+15. [Electric power facility restoration](analyses/epf_restoration)
+16. [Electric power network functionality](analyses/epn_functionality)
+17. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
+18. [Gas facility damage](analyses/gas_facility_damage)
+19. [Household-level housing sequential recovery](analyses/housing_household_recovery)
+20. [Housing recovery](analyses/housing_recovery)
+21. [Housing unit allocation](analyses/housingunitallocation)
+22. [Interdependent Network Design Problem](analyses/indp)
+23. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
+24. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
+25. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
+26. [Mean damage](analyses/mean_dmg)
+27. [Monte Carlo failure probability](analyses/mc_failure_prob)
+28. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
+29. [Network cascading interdependency functionality](analyses/nci_functionality)
+30. [Nonstructural building damage](analyses/non_structural_building_dmg)
+31. [Pipeline damage](analyses/pipeline_dmg)
+32. [Pipeline damage with repair rate](analyses/pipeline_dmg_w_repair_rate)
+33. [Pipeline functionality](analyses/pipeline_functionality)
+34. [Pipeline repair cost](analyses/pipeline_repair_cost)
+35. [Pipeline restoration](analyses/pipeline_restoration)
+36. [Population dislocation](analyses/populationdislocation)
+37. [Residential building recovery](analyses/residential_building_recovery)
+38. [Road damage](analyses/road_dmg)
+39. [Salt Lake City Computable General Equilibrium (CGE)](analyses/slc_cge.md)
+40. [Seaside Computable General Equilibrium (CGE)](analyses/seaside_cge)
+41. [Social Vulnerability](analyses/social_vulnerability)
+42. [Social Vulnerability Score](analyses/social_vulnerability_score)
+43. [Tornado electric power network (EPN) damage](analyses/tornadoepn_dmg)
+44. [Traffic flow recovery](analyses/traffic_flow_recovery)
+45. [Transportation recovery](analyses/transportation_recovery)
+46. [Water facility damage](analyses/waterfacility_dmg)
+47. [Water network functionality](analyses/wfn_functionality)
+48. [Water facility repair cost](analyses/water_facility_repair_cost)
+49. [Water facility restoration](analyses/water_facility_restoration)

manual_jb/content/analyses/buyout_decision.md

@@ -0,0 +1,67 @@
+# Buyout Decision
+
+**Description**
+
+This analysis helps identify candidate properties for buyout and allows practitioners and researchers to evaluate 
+the potential equity outcomes of their selection under different scenario events.
+
+The outputs of this analysis is a CSV file with buildings to consider for buyout based on the set criteria. This can assist local 
+practitioners to identify candidate properties for buyout selection and allows practitioners and researchers to evaluate the potential equity 
+outcomes of their selection 
+
+**Input parameters**
+
+key name | type | name | description
+--- |-------------------------|-------------------------| ---
+`result_name` <sup>*</sup> | `str`                   | Result name             | Name of the result dataset.
+`residential_archetypes` <sup>*</sup> | `list`                  | Residential archtetypes | Residential archetypes to consider for buyout.
+`fema_buyout_cap` <sup>*</sup> | `float`                 | FEMA buyout cap | FEMA buyout cap is the maximum appraised value considered for buyout. 
+
+**Input datasets**
+
+key name | type | name | description
+--- |-------------------------|-------------------------| ---
+`buildings` <sup>*</sup> | [`ergo:buildingInventoryVer4`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer4)<br>[`ergo:buildingInventoryVer5`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer5)<br>[`ergo:buildingInventoryVer6`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer6)<br>[`ergo:buildingInventoryVer7`](https://incore.ncsa.illinois.edu/semantics/api/types/ergo:buildingInventoryVer7) | Building dataset         |  A building dataset.
+`past_building_damage` <sup>*</sup> | [`ergo:buildingDamageVer6`](https://incore.ncsa.illinois.<br/>edu/semantics/api/types/ergo:buildingDamageVer6) | Previous Building damage |  Building damage from a previous event.
+`future_building_damage` <sup>*</sup> | [`ergo:buildingDamageVer6`](https://incore.ncsa.illinois.<br/>edu/semantics/api/types/ergo:buildingDamageVer6) | Future/predicted Building damage |  Building damage from a future/predicted event.
+`housing_unit_allocation` <sup>*</sup> | [`incore:housingUnitAllocation`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:housingUnitAllocation) | Housing unit allocation | Housing unit allocation.
+`population_dislocation` <sup>*</sup> | [`incore:popDislocation`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:popDislocation) | Population dislocation   | Population dislocation results.
+
+
+**Output datasets**
+
+key name | type | parent key | name | description
+--- |-------------------------------------------------------------------------------------------------------| --- | --- | ---
+`result` <sup>*</sup> | [`incore:buyoutDecision`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:buyoutDecision) | `buildings` | Results | A dataset containing buyout decision results <br>(format: CSV).
+
+<small>(* required)</small>
+
+**Execution**
+
+code snippet:
+
+```
+    # Create buyout analysis
+    buyout_decision = BuyoutDecision(client)
+
+    # Load input datasets
+    buyout_decision.load_remote_input_dataset("buildings", buildings_id)
+    buyout_decision.load_remote_input_dataset("housing_unit_allocation", hua_id)
+    buyout_decision.load_remote_input_dataset("past_building_damage", past_building_damage_id)
+    buyout_decision.load_remote_input_dataset("future_building_damage", future_building_damage_id)
+    buyout_decision.load_remote_input_dataset("population_dislocation", past_pop_dislocation_id)
+
+
+    # Specify the result name
+    result_name = "galveston_buyout_result"
+    
+    # Set analysis parameters
+    buyout_decision.set_parameter("fema_buyout_cap", fema_buyout_cap)
+    buyout_decision.set_parameter("residential_archetypes", residential_archetypes)
+    buyout_decision.set_parameter("result_name", result_name)
+
+    # Run buyout analysis
+    buyout_decision.run_analysis()
+```
+
+full analysis: [buyout_decision.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/buyout_decision.ipynb)