425 add doc and notebook for equity metric analysis

CHANGELOG.md

@@ -8,6 +8,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)
 
 ### Changed
 - Update docs according to support Interdependent recovery analysis [#417](https://github.com/IN-CORE/incore-docs/issues/417)

manual_jb/content/_toc.yml

@@ -31,6 +31,7 @@ chapters:
       - file: analyses/epf_repair_cost
       - file: analyses/epf_restoration
       - file: analyses/epn_functionality
+      - file: analyses/equity_metric
       - file: analyses/galveston_cge
       - file: analyses/gas_facility_damage
       - file: analyses/housing_household_recovery

manual_jb/content/analyses.md

@@ -17,35 +17,36 @@
 15. [Electric power facility repair cost](analyses/epf_repair_cost)
 16. [Electric power facility restoration](analyses/epf_restoration)
 17. [Electric power network functionality](analyses/epn_functionality)
-18. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
-19. [Gas facility damage](analyses/gas_facility_damage)
-20. [Household-level housing sequential recovery](analyses/housing_household_recovery)
-21. [Housing recovery](analyses/housing_recovery)
-22. [Housing unit allocation](analyses/housingunitallocation)
-23. [Interdependent Network Design Problem](analyses/indp)
-24. [Joplin Computable General Equilibrium (CGE)](analyses/joplin_cge)
-25. [Joplin empirical building restoration](analyses/joplin_empirical_building_restoration)
-26. [Machine Learning Enabled Computable General Equilibrium (CGE) - Salt Lake City](analyses/ml_slc_cge.md)
-27. [Mean damage](analyses/mean_dmg)
-28. [Monte Carlo limit state probability](analyses/mc_limit_state_prob)
-29. [Multi-objective retrofit optimization](analyses/multi_retrofit_optimization)
-30. [Network cascading interdependency functionality](analyses/nci_functionality)
-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)
+18. [Equity Metric](analyses/equity_metric)
+19. [Galveston Computable General Equilibrium (CGE)](analyses/galveston_cge.md)
+20. [Gas facility damage](analyses/gas_facility_damage)
+21. [Household-level housing sequential recovery](analyses/housing_household_recovery)
+22. [Housing recovery](analyses/housing_recovery)
+23. [Housing unit allocation](analyses/housingunitallocation)
+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)

manual_jb/content/analyses/equity_metric.md

@@ -0,0 +1,84 @@
+# Equity Metric
+
+**Description**
+
+The algorithm computes equity metrics to characterize the inequity present in the infrastructure service provision
+between two groups of concerns’ (e.g., low income vs. non-low income, minority vs non-minority, etc.). The metrics are
+built upon Theil’s T, which is a common metric to compute the inequality present in the dispersion of a scarce
+resource (e.g., income). The metrics could also be implemented to assess inequity in different scenarios with other
+scarce resources of concern.
+
+To compute the metrics, a scarce resource should be formulated and calculated for an infrastructure application. The
+scarce resource for infrastructure can be taken as any user defined relevant values, such as a resilience score (i.e.,
+probability of service provision) or recovery time. We've included a companion utility class where we define and
+prepare recovery time as a scarce resource. Other scarce resources can and could be explored if provided by the user.
+
+The equity metric allows for an equity assessment of the current infrastructure service provision. It also enables the
+assessment of equity gains for a given retrofit plan and can be integrated into an overall decision-making process..
+The output metrics tell the following information 1) Theil's T - overall amount of inequality in scarce resource's
+dispersion across a community (distributional inequity)  2) Between Zone Inequality (BZI) - amount of inequality
+attributed to scarce resource differences between groups (restorative inequity), and 3) Within Zone Inequality (WZI) -
+amount of inequality due to resource differences among singular groups.
+
+**Contributors**
+
+- Science: Abigail L. Beck, Ph.D, Eun Jeong Cha, Ph.D, Walter Peacock, Ph.D
+- Implementation: NCSA IN-CORE Dev Team
+
+**Related publications**
+
+- Beck, A.L., Cha, E.J. & Peacock, W.G. "Incorporation of Equity into Infrastructure Decision-Making: Development of an
+  Equity Metric for Infrastructure Retrofitting," The 14th International Conference on Applications of Statistics and
+  Probability in Civil Engineering (ICASP14), Dublin, Ireland, July, 2023. http://hdl.handle.net/2262/103309
+
+**Input parameters**
+
+ key name                                | type  | name                          | description                                                                                                                                                                          
+-----------------------------------------|-------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ `result_name` <sup>*</sup>              | `str` | Result name                   | Name of the result dataset.                                                                                                                                                          
+ `division_decision_column` <sup>*</sup> | `str` | Division decision column name | Column name of a binary variable associated with each household used to group it into two groups (e.g. low income vs non low income, minority vs non-minority, social vulnerability) 
+
+**Input datasets**
+
+ key name                               | type                                                                                                                | name               | description                                                            
+----------------------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------|------------------------------------------------------------------------
+ `housing_unit_allocation` <sup>*</sup> | [`incore:housingUnitAllocation`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:housingUnitAllocation) | Housing allocation | A housing unit allocation dataset.                                     
+ `scarce_resource` <sup>*</sup>         | [`incore:scarceResource`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:scarceResource)               | Scarce resource    | Scarce resource dataset e.g. probability of service, return time, etc. 
+
+**Output datasets**
+
+ key name                     | type                                                                                              | parent key | name          | description                                                                                           
+------------------------------|---------------------------------------------------------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------
+ `equity_metric` <sup>*</sup> | [`incore:equityMetric`](https://incore.ncsa.illinois.edu/semantics/api/types/incore:equityMetric) |            | Equity Metric | CSV file of equity metric, including Theil’s T Value, Between Zone Inequality, Within Zone Inequality 
+
+<small>(* required)</small>
+
+**Execution**
+
+code snippet:
+
+```
+    client = IncoreClient()
+    datasvc = DataService(client)
+
+    # Example of preparing scarce resource
+    repair_time_df = Dataset.from_data_service(housing_recovery_id, datasvc).get_dataframe_from_csv()
+    scarce_resource_df = EquityMetricUtil.prepare_return_time_as_scarce_resource(
+        repair_time_df
+    )
+    scarce_resource = Dataset.from_dataframe(
+        scarce_resource_df, "scarce_resource", data_type="incore:scarceResource"
+    )
+
+    # Example of running equity metric analysis
+    equity_metric = EquityMetric(client)
+    equity_metric.set_parameter("result_name", "Galveston_recovery_time")
+    equity_metric.set_parameter("division_decision_column", "SVI")
+    equity_metric.load_remote_input_dataset(
+        "housing_unit_allocation", housing_unit_allocation_id
+    )
+    equity_metric.set_input_dataset("scarce_resource", scarce_resource)
+    equity_metric.run_analysis()
+```
+
+full analysis: [equity_metric.ipynb](https://github.com/IN-CORE/incore-docs/blob/main/notebooks/equity_metric.ipynb)