Getting Started =============== bca4abm includes activity-based model and four-step trip-based model :ref:`examples` to help get you started. Installation ------------ * Install `Anaconda 64bit Python 3 `__, which includes a number of required Python packages. * Create and activate an Anaconda environment (i.e. a Python install just for this project). :: conda create -n bca4abmtest python=3.7 activate bca4abmtest * Get and install the bca4abm package from `PyPi `_ :: pip install bca4abm .. note:: Support for Python 2 has been discontinued by most major Python packages, including many of bca4abm's dependencies. For the most up-to-date and stable version of bca4abm, using python 3.6+ is recommended, although older versions may still work with some package version fiddling. A stable/tested Python 2.7 version of bca4abm can be installed with the following command, however this branch will not benefit from any bug fixes or improvements moving forward. :: pip install https://github.com/RSGInc/bca4abm/zipball/py2 Running the Model ----------------- * View the list of available examples :: bca4abm create --list * Create a local copy of an example folder :: bca4abm create --example example_4step --destination my_test_example * Run the example :: bca4abm run --working_dir my_test_example or :: bca4abm run -c my_test_example/configs -d my_test_example/data -o my_test_example/output * Check the outputs folder for results, for example the ``final_aggregate_results.csv`` file for the 4step example More usage information can be found via ``bca4abm -h`` and ``bca4abm [command] -h`` .. note:: A customizable run script for power users can be found in the `Github repo `__. This script takes many of the same arguments as the ``bca4abm run`` command, including paths to ``--config``, ``--data``, and ``--output`` directories. It looks for these folders in the current working directory by default. :: python run_bca.py Process Overview ---------------- The basic steps to run the benefits calculator with your travel model are below: * Run procedures to export results from the travel model to produce the base and build scenario inputs required for the calculator * The calculator reads the travel model output files for a base and build scenario * The calculator evaluates user-defined Python expressions (see below) for each data processor to calculate benefits. Expressions are segmented by equity group when applicable, and include subtracting the base from the build quantity, monetization, annualization, etc. * The summation of the calculations by benefit and equity group are written out Expressions ----------- To help illustrate how the benefits calculator works, an example set of expressions for calculating zone benefits is below. Each input is a zone data table with each row a zone and each column a zone attribute. The example processes the base and build home-based-other productions by zone, as well as the base and build mode choice logsum, and calculates an accessibility benefit measure. The idea here is that improvements in multi-modal accessibility (i.e. the logsum) between the based and build scenario results in increased accessibility or additional travel options. The accessibility benefit is calculated using the rule-of-half. As a result, the calculation is half the difference in the productions times the difference in the logsums divided by utilities per minute for home-based-other trips times the value-of-time for home-based-other trips times the annual discount rate times a daily to annual factor. The result is monetized benefits for increases in accessibility by zone. +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | Description | Target | Expression | +===========================================+========================+============================================================================================================================================+ | #zone input data tables | | | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | hbo productions in base scenario | base_prod_hbo | zones.base_hboprl + zones.base_hboprm + zones.base_hboprh | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | hbo productions in build scenario | build_prod_hbo | zones.build_hboprl + zones.build_hboprm + zones.build_hboprh | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | hbo logsum in base scenario | base_ls_hbo | zones.base_hbodcls | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | hbo logsum in build scenario | build_ls_hbo | zones.build_hbodcls | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | #calculate travel options benefit by zone| | | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | access benefit hbo | access_benefit_hbo | (0.5 * (base_prod_hbo + build_prod_hbo) * (build_ls_hbo - base_ls_hbo) / UPM_HBO) * (VOT_HBO / 60) * DISCOUNT_RATE * ANNUALIZATION_FACTOR | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | #add up all travel purposes if calculated| | | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | travel options benefit | travel_options_benefit| access_benefit_hbo + access_benefit_hbr + access_benefit_hbs + access_benefit_hbw + access_benefit_nhbnw + access_benefit_nhbw | +-------------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+