update docstring for evaluate_equity()

Author: jdlph

README.md

@@ -25,7 +25,7 @@ If you need a specific version of Path4GMNS, say, 0.8.3,
 $ pip install path4gmns==0.8.3
 ```
 
-v0.8.3 comes with accessibility evaluation enhancement and equity evaluation. All previous releases shall be **deprecated**.
+v0.8.3 comes with equity evaluation and enhancement in accessibility evaluation. All previous releases shall be **deprecated**.
 
 ### Dependency
 The Python modules are written in **Python 3.x**, which is the minimum requirement to explore the most of Path4GMNS. Some of its functions require further run-time support, which we will go through along with the corresponding use cases in the following section.
@@ -475,7 +475,7 @@ You are encouraged to join our Slack workspace for more discussions and collabor
 
 ## How to Cite
 
-Li, P. and Zhou, X. (2022, July 11). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
+Li, P. and Zhou, X. (2022, July 12). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
 
 ## References
 Lu, C. C., Mahmassani, H. S., Zhou, X. (2009). Equivalent gap function-based reformulation and solution algorithm for the dynamic user equilibrium problem. Transportation Research Part B: Methodological, 43, 345-364.

path4gmns/accessibility.py

@@ -259,7 +259,69 @@ def evaluate_accessibility(ui,
 
 def evaluate_equity(ui, multimodal=True, mode='p', time_dependent=False,
                     demand_period_id=0, time_budget=60, output_dir='.'):
-    """ evaluate equity for each zone under a time budget """
+    """ evaluate equity for each zone under a time budget
+
+    Parameters
+    ----------
+    ui
+        network object generated by pg.read_network()
+
+    multimodal
+        True or False. Its default value is True. It will only affect the
+        output to accessibility_aggregated.csv.
+
+        If True, the accessibility evaluation will be conducted
+        for all the modes defined in settings.yml. The number of accessible
+        zones from each zone under each defined mode given a budget time (up
+        to 240 minutes) will be outputted to accessibility_aggregated.csv.
+
+        If False, the accessibility evaluation will be only conducted against the
+        target mode. The number of accessible zones from each zone under the
+        target mode given a budget time (up to 240 minutes) will be outputted
+        to accessibility_aggregated.csv.
+
+    mode
+        target mode with its default value as 'p' (i.e., mode auto). It can be
+        either agent type or its name. For example, 'w' and 'walk' are
+        equivalent inputs.
+
+    time_dependent
+        True or False. Its default value is False.
+
+        If True, the accessibility will be evaluated using the period link
+        free-flow travel time (i.e., VDF_fftt). In other words, the
+        accessibility is time-dependent.
+
+        If False, the accessibility will be evaluated using the link length and
+        the free flow travel speed of each mode.
+
+    demand_period_id
+        The sequence number of demand period listed in demand_periods in
+        settings.yml. demand_period_id of the first demand_period is 0.
+
+        Use it with time_dependent when there are multiple demand periods. Its
+        default value is 0.
+
+    time_budget
+        the amount of time to travel in minutes
+
+    output_dir
+        The directory path where accessibility_aggregated.csv and
+        accessibility.csv are output. The default is the current working
+        directory (CDW).
+
+
+    Outputs
+    -------
+    equity_str.csv
+        equity statistics including minimum accessibility (and the corresponding
+        zone), maximum accessibility (and the corresponding zone), and mean
+        accessibility for each bin_index. The accessible zones will be output
+        as well.
+
+        str in the file name refers to the time budget, e.g., it will be
+        equity_60min.csv if the time budget is 60 min.
+    """
     with open(output_dir+'/equity_'+str(time_budget)+'min.csv', 'w',  newline='') as f:
         headers = ['bin_index', 'mode', 'zones',
                    'min_accessibility', 'zone_id',