add ml enabled joplin cge notebook (#430)

* add ml enabled joplin cge notebook

* add entried in mardown files

* add entry in toc file

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - API documentation for project service [#423](https://github.com/IN-CORE/incore-docs/issues/423)
 - Documentation for Equity Metric Analysis [#425](https://github.com/IN-CORE/incore-docs/issues/425)
+- ML Enabled Joplin CGE notebook [#429](https://github.com/IN-CORE/incore-docs/issues/429)
 
 ### Changed
 - Update docs according to support Interdependent recovery analysis [#417](https://github.com/IN-CORE/incore-docs/issues/417)

manual_jb/content/_toc.yml

@@ -42,6 +42,8 @@ chapters:
       - file: analyses/joplin_empirical_restoration
       - file: analyses/mean_dmg
       - file: analyses/mc_limit_state_prob
+      - file: analyses/ml_joplin_cge
+      - file: analyses/ml_slc_cge
       - file: analyses/multi_retrofit_optimization
       - file: analyses/nci_functionality
       - file: analyses/pipeline_dmg

manual_jb/content/analyses.md

@@ -26,27 +26,28 @@
 24. [Interdependent Network Design Problem](analyses/indp)
 25. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
 26. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
-27. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
-28. [Mean damage](analyses/mean_dmg)
-29. [Monte Carlo limit state probability](analyses/mc_limit_state_prob)
-30. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
-31. [Network cascading interdependency functionality](analyses/nci_functionality)
-32. [Pipeline damage](analyses/pipeline_dmg)
-33. [Pipeline damage with repair rate](analyses/pipeline_dmg_w_repair_rate)
-34. [Pipeline functionality](analyses/pipeline_functionality)
-35. [Pipeline repair cost](analyses/pipeline_repair_cost)
-36. [Pipeline restoration](analyses/pipeline_restoration)
-37. [Population dislocation](analyses/populationdislocation)
-38. [Residential building recovery](analyses/residential_building_recovery)
-39. [Road damage](analyses/road_dmg)
-40. [Salt Lake City Computable General Equilibrium (CGE)](analyses/slc_cge.md)
-41. [Seaside Computable General Equilibrium (CGE)](analyses/seaside_cge)
-42. [Social Vulnerability](analyses/social_vulnerability)
-43. [Social Vulnerability Score](analyses/social_vulnerability_score)
-44. [Tornado electric power network (EPN) damage](analyses/tornadoepn_dmg)
-45. [Traffic flow recovery](analyses/traffic_flow_recovery)
-46. [Transportation recovery](analyses/transportation_recovery)
-47. [Water facility damage](analyses/waterfacility_dmg)
-48. [Water network functionality](analyses/wfn_functionality)
-49. [Water facility repair cost](analyses/water_facility_repair_cost)
-50. [Water facility restoration](analyses/water_facility_restoration)
+27. [Machine Learning Enabled Computable General Equilibrium (CGE) - Joplin](analyses/ml_joplin_cge.md)
+28. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
+29. [Mean damage](analyses/mean_dmg)
+30. [Monte Carlo limit state probability](analyses/mc_limit_state_prob)
+31. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
+32. [Network cascading interdependency functionality](analyses/nci_functionality)
+33. [Pipeline damage](analyses/pipeline_dmg)
+34. [Pipeline damage with repair rate](analyses/pipeline_dmg_w_repair_rate)
+35. [Pipeline functionality](analyses/pipeline_functionality)
+36. [Pipeline repair cost](analyses/pipeline_repair_cost)
+37. [Pipeline restoration](analyses/pipeline_restoration)
+38. [Population dislocation](analyses/populationdislocation)
+39. [Residential building recovery](analyses/residential_building_recovery)
+40. [Road damage](analyses/road_dmg)
+41. [Salt Lake City Computable General Equilibrium (CGE)](analyses/slc_cge.md)
+42. [Seaside Computable General Equilibrium (CGE)](analyses/seaside_cge)
+43. [Social Vulnerability](analyses/social_vulnerability)
+44. [Social Vulnerability Score](analyses/social_vulnerability_score)
+45. [Tornado electric power network (EPN) damage](analyses/tornadoepn_dmg)
+46. [Traffic flow recovery](analyses/traffic_flow_recovery)
+47. [Transportation recovery](analyses/transportation_recovery)
+48. [Water facility damage](analyses/waterfacility_dmg)
+49. [Water network functionality](analyses/wfn_functionality)
+50. [Water facility repair cost](analyses/water_facility_repair_cost)
+51. [Water facility restoration](analyses/water_facility_restoration)

manual_jb/content/analyses/ml_joplin_cge.md

@@ -0,0 +1,61 @@
+# Machine Learning Enabled Computable General Equilibrium (CGE) - Joplin
+
+**Description**
+
+The "Machine Learning Enabled Computable General Equilibrium (CGE) - Joplin" analysis merges advanced machine learning with traditional CGE models to offer unprecedented insights into the economic impacts of disaster scenarios on Joplin. Trained on a comprehensive dataset of numerous simulated disasters and their economic effects, this hybrid approach excels in predicting the intricate dynamics of the city's economy under various crises.
+
+A computable general equilibrium (CGE) model is based on fundamental economic principles. A CGE model uses multiple data sources to reflect the interactions of households, firms, and relevant government entities as they contribute to economic activity. The model is based on (1) utility-maximizing households that supply labor and capital, using the proceeds to pay for goods and services (both locally produced and imported) and taxes; (2) the production sector, with perfectly competitive, profit-maximizing firms using intermediate inputs, capital, land, and labor 
+to produce goods and services for both domestic consumption and export; (3) the government sector that collects taxes and uses tax revenues in order to finance the provision of public services; and (4) the rest of the world.
+
+
+The output of this analysis are CSV files with domestic supply, gross income, before- and post-disaster factor demand and household count.
+
+**Contributors**
+
+- Science: Charles Nicholson, Nushra Zannat, Hwayoung Jeon, Tao Lu, Harvey Cutler, Anita Pena
+- Implementation: NCSA IN-CORE Dev Team
+
+
+**Input parameters**
+
+key name | type | name | description
+--- | --- | --- | ---
+`result_name` | `str` | Output File Name prefix | Sets the file name prefix for output files.
+
+**Input datasets**
+
+key name | type | name | description
+--- | --- | --- | ---
+`sector_shocks` <sup>*</sup> | [`incore:capitalShocks`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:capitalShocks) | Capital shocks | Building states to capital <br>shocks per sector.
+
+**Output datasets**
+
+key name | type | name | description
+--- | --- | --- | ---
+`domestic-supply` <sup>*</sup> | [`incore:Employment`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:Employment) | Supply results | A dataset containing domestic supply results (format: CSV).
+`gross-income` <sup>*</sup> | [`incore:Employment`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:Employment) | Gross income | A dataset of resulting gross income (format: CSV).
+`pre-disaster-factor-demand` <sup>*</sup> | [`incore:FactorDemand`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:FactorDemand) | Factor demand | A dataset of factor demand before disaster (format: CSV).
+`post-disaster-factor-demand` <sup>*</sup> | [`incore:FactorDemand`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:FactorDemand) | Factor demand | A dataset of factor demand after disaster (format: CSV).
+`household-count` <sup>*</sup> | [`incore:HouseholdCount`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:HouseholdCount) | Household count | A dataset of household count (format: CSV).
+
+<small>(* required)</small>
+
+**Execution**
+
+code snippet:
+
+```
+    # Create Machine Learning Enabled CGE Joplin Model
+    mlcgejoplin = MlEnabledCgeJoplin(client)
+    
+    # Set analysis input datasets
+    mlcgejoplin.load_remote_input_dataset("sector_shocks", sector_shocks)
+
+    # Optional parameters for file naming
+    mlcgejoplin.set_parameter("result_name", "test_joplin_mlcge_result")
+
+    # Run Joplin CGE model analysis
+    mlcgejoplin.run_analysis()
+```
+
+full analysis: [ml_enabled_joplin_cge.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/ml_enabled_joplin_cge.ipynb)