Change Log:
2022/6/15: enable command-line parser, so that users can customize input/output file names, PM2.5 factor, etc. by changing parameters in settings.yaml file. 
2022/9/5: PM2.5 factor changed from 0 to 0.15; emission input changed from "nei_isrm_summary_onroad.csv" to "nei_isrm_summary_onroad_LDV.csv" (i.e., removed light commercial truck categories, now only 7, instead of 10, SCCs are considered of interest). 

_______________________________________________________________

The LDVEMIS model in BILD-AQ project is designed to translate VMT changes in different scenarios to emission changes of air pollutants such as NOx, VOC, NH3, SOx and PM2.5. 

Input (in "input" folder) includes a tract-level VMT data file (E.g., "Sample_Input_CA.csv") that should be provided either by the user directly or by upstream models, and two other data files that have already been pre-generated by LDVEMIS team. Output of the LDVEMIS model is a csv file that estimates changes of NOx, VOC, NH3, SOx and PM2.5 emissions at each ISRM grid (unit = short ton/year). 

_______________________________________________________________
Description of files in the LDVEMIS library:

1. run.py - an executable python script that reads settings from settings.yaml and calls LDVEMIS docker to execute the whole simulation.

2. settings.yaml - a user-friendly configuration file for setting high-level parameters, such as input/output file name, emission category, etc. 

3. environment.txt - a list of python packages needed for running run.py. Please make sure to install them before starting. 

4. input/HPMS/network_isrm_*.RData - pre-processed data for simulations inside each of the CONUS states. Each row in this RData is a HPMS road segment by census tract and ISRM grid. Data for four states are still misssing now and will be added later: Idoha, Missouri, Montana, Texas.

5. input/nei_isrm_summary_onroad_LDV.csv - a pre-processed data that allocates 2014 National Emission Inventory (NEI) to each ISRM grids. 7 emission categories (SCCs) are considered of interest, and their description can be found in the documentation folder.

6. input/Sample_Input_CA.csv - a FAKE example of user- or upstream-provided VMT data. In general, this input should provides tract-level VMT data under the baseline ("VMT_base" column) versus in a specific scenario ("VMT_scenarios" column). You can provide VMT data for any number of census tracts, and can also name it whatever you like (but make sure to change "input_fname" accordingly in settings.yaml). 

7. output/Sample_Output_ISRM_CA_Gas_LD_Veh..csv - a FAKE example output that LDVEMIS generates using the FAKE "Sample_Input_CA.csv". Its "VOC/NOx/NH3/SOx/PM25" columns indicate emission changes of those air pollutants at each ISRM grid (unit = short ton/year). 

_______________________________________________________________
To run the LDVEMIS module:

1) Check environment.txt and make sure you have installed the packages listed. 

2) Make sure your docker engine is running properly by entering "sudo service docker status". If not running,  start it by "sudo service docker start". 

3) Under a directory that you like, ${LDVEMIS_HOME}, put "settings.yaml" and "run.py"

4) Create two folders named "input" and "output"

5) Put nei_isrm_summary_onroad_LDV.csv and HPMS/network_isrm_*.RData in input folder

6) Provide the VMT change data anyname_input.csv (its data should follow the "Sample_Input_CA.csv" format) in input folder
*** this is the only input required from user/upstream model

7) In settings.yaml, set input_fname to be the input name you used (e.g., "input_fname: anyname_input.csv"). 

8) Update setting in settings.yaml if needed. For example, you can change PM2.5 factor to any value reasonable (default = 0.15). 

9) Under ${LDVEMIS_HOME} directory, enter "python run run.py" to run the main python script

10) When the run is done, check the output (its name can be customized in settings.yaml before the run) in output folder