From 3ac29275522616dc74e45b1668561e57188af629 Mon Sep 17 00:00:00 2001 From: Jeremy Raw Date: Mon, 25 Mar 2024 14:45:48 -0400 Subject: [PATCH] Rendered updates to input files --- docs/03-tutorial.md | 4 +- docs/04-inputs.md | 160 ++- docs/api-documentation.html | 2 +- docs/common-use-cases.html | 2 +- docs/conceptprimer.html | 2 +- docs/detailed-installation.html | 2 +- docs/developing-scenarios.html | 2 +- docs/getting-started.html | 2 +- docs/index.html | 2 +- docs/index.md | 2 +- docs/model-geography-and-years.html | 6 +- docs/model-inputs.html | 1368 ++++++++++++---------- docs/picking-a-model.html | 2 +- docs/reference-keys.txt | 10 +- docs/search.json | 2 +- docs/software-framework.html | 164 +-- docs/topic-index.html | 2 +- docs/tutorial.html | 2 +- docs/validation-and-troubleshooting.html | 2 +- docs/ve-buildprocess.html | 2 +- docs/ve-estimation.html | 2 +- docs/verpat.html | 958 +++++++-------- docs/verspm.html | 22 +- docs/vestate.html | 22 +- 24 files changed, 1458 insertions(+), 1286 deletions(-) diff --git a/docs/03-tutorial.md b/docs/03-tutorial.md index c40eecc..f2d8c48 100644 --- a/docs/03-tutorial.md +++ b/docs/03-tutorial.md @@ -89,11 +89,11 @@ individual zones. The user is free to choose what conventions they will use. **Example of a geo.csv file that only specifies Azones** -![](images/Azone_geo_file.png) +![](images/azone_geo_file.png) **Example of geo.csv file that specifies Azones and Bzones** -![](images/Azone_Bzone_geo_file.png) +![](images/azone_bzone_geo_file.png) #### Model Geography Example This section details the model geography for ODOT's VE-State model as an example. The geography levels are defined as follows: diff --git a/docs/04-inputs.md b/docs/04-inputs.md index 85f13a2..edba66d 100644 --- a/docs/04-inputs.md +++ b/docs/04-inputs.md @@ -2,13 +2,19 @@ -Once VisionEval model has been installed, a directory with sample data will be available within the model directory (e.g., `../models/VERSPM/` where `..` refers to the parent directory of the unzipped installer file). +Once a VisionEval model has been installed, a directory with sample data will be available within the model directory (e.g., `../models/VERSPM/` where `..` refers to the parent directory of the unzipped installer file). See VisionEval walkthrough files for instructions on installng sample models. The model directory serves the dual purposes of providing sample data and a template for local modification to other locations. -The default VERSPM and VERPAT directories contains sample input files for the Rogue Valley region in Oregon, while the default VE-State directory contains sample input files for the State of Oregon. These inputs can be modified or replaced to investigate the impacts of policy changes or to model a different region. +The default VERSPM and VERPAT directories contain sample input files for the Rogue Valley region in Oregon, while the default VE-State directory contains sample input files for the State of Oregon. These inputs will be modified or replaced to investigate the impacts of policy changes or to model a different region. -The `defs` directory contains five model definition files which are introduced in [Set-Up Inputs](#defs) section. +## Standard Model Structure {#model-structure} + +VisionEval models all have a standard structure, which can be customized. The typical structure is described here. + +The `visioneval.cnf` in the model directory defines the model's structure. It is introducted in [Model Configuration](#visioneval-cnf). + +The `defs` directory contains three model definition files which are introduced in [Set-Up Inputs](#defs) section. The `inputs` directory contains a number of `CSV` and `JSON` files that provide inputs for the modules. Each module specifies what input files it needs. The majority of input files are `CSV` formatted text files. The names of the file identify the geography level for the input data. For example, `azone_hh_pop_by_age.csv` is the input for household population by age, and should have data at the Azone level. Each input file has: @@ -26,47 +32,114 @@ Field names can also have modifiers, such as the year that money values are deno The rest of this section will contain generalized best practices for input development applicable to all VisionEval models and go into the details of inputs for each model. -## Set-up Inputs {#defs} -The set-up inputs are those in the `defs` directory. Most of these files shouldn’t change much from the download, unless users want their own deflators, etc. The exception is the geo.csv file which will need to be developed to inform the model geography. +## Model Configuration (`visioneval.cnf`) {#visioneval-cnf} + +This file contains parameters that define key attributes of the model and its computational stages and scenarios. This file can be in YAML format (typical) or JSON (for backward compatibility - it replaces `run_parameters.json` in older versions of VisionEval). Certain elements of `visioneval.cnf` need to be modified by the user to specify the model base year and run years. A more detailed description of the file is not currently available (but will appear soon). The typical contents of `visioneval.cnf` are as follows: + +```yaml +# Model-wide description +Model : VE-State 3.0 +Region : Oregon # Change to your local area +State : OR # Change to your local area +BaseYear : 2010 # Change to your model's base year +Script : run_model.R + +# Model Stages and Scenarios +ModelStages: + base-year-2010: # Change base year stage name + Years : [2010] # Change 2010 to your model's base year + Description : Oregon Base Year 2010 # Change to correct description + future-year-2040: + StartFrom : base-year-2010 # Change to be consistent with base year stage name + Years : [2040] # Change 2040 to your model's future year + Description : Oregon Future Year 2040 # Change to correct description +``` -- [run_parameters.json](#run_parameters.json) -- [model_parameters.json](#model_parameters.json) -- [deflators.csv](#deflators.csv) -- [geo.csv](#geo.csv) -- [units.csv](#units.csv) +See the separate scenarios section (under construction) to learn how to set scenarios up efficiently within models. -### run_parameters.json -This file contains parameters that define key attributes of the model run and relationships to other model runs. This file is a needs to be modified by the user to specify the model base year and run years. A more detailed description of the file can be found [here](https://github.com/visioneval/VisionEval/blob/master/api/model_system_design.md#61-model-directory-structure). The results of model run are stored in a directory with the name specified by ```"DatastoreName"```. This name should be changed when running different scenarios. For e.g. when running base scenario the output directory name can be set to *BaseScenario* by using ```"DatastoreName": "BaseScenario"``` in the file. The format of this file is as follows: +With this standard setup, model results will be generated in folder called `results`, and the model stages will each generate their outputs into a sub-folder of `results` named after the stage. + +The model directory structure will look like the following, though the `results` directory won't exist until you run the model: -```json -{ - "Model": "VERSPM", - "Scenario": "Test", - "Description": "Test of VERSPM", - "Region": "RVMPO", - "BaseYear": "2010", - "Years": ["2010", "2038"], - "DatastoreName": "Datastore", - "DatastoreType": "RD", - "Seed": 1 -} +``` +VE-State-years # or whatever your model is called in the `models` folder +-- defs + -- deflators.csv + -- geo.csv + -- units.csv +-- inputs + ... all the `.csv` files plus `model_parameters.json` used in the model +-- results + -- base-year-2010 + -- Datastore + -- ... (Subfolders and files with the model outputs) + -- Log_....txt (model run notices, including warnings and errors) + -- ModelState.Rda + -- future-year-2040 + -- Datastore (folder) + -- Log_....txt + -- ModelState.Rda +-- scripts + -- run_model.R +-- visioneval.cnf ``` -### model_parameters.json -This file contains global parameters for a particular model configuration that may be used by multiple modules. A more detailed description of the file and its structure can be found [here](https://github.com/visioneval/VisionEval/blob/master/api/model_system_design.md#61-model-directory-structure). The source of the default $16/hr in 2010$ was derived from a Nov 2014 Oregon DOT Report: ["The Value of Travel-Time: Estimates of the Hourly Value of Time for Vehicles in Oregon"](https://www.oregon.gov/ODOT/Data/Documents/Value-of-Travel-Time-for-Vehicles.pdf). Note the input looks for the dollars in the year of the base model. +## Model Script {#run_model_script} -The format of this file is as follows: +The `scripts` folder contains one or more model scripts describing the sequence of VisionEval modules that the model will run to genereate its outputs. Typically, there will be one script called `run_model.R` but the name can be changed in `visioneval.cnf`. -```json -[ - {"NAME": "ValueOfTime", - "VALUE": "16", - "TYPE": "double", - "UNITS": "base cost year dollars per hour" +Here is the standard `run_model.R` script for the VERSPM model. Generally, the script won't be changed except for debugging purposes. One reason to change the script might be to use a locally customized package with a different name (e.g. `VEMyPowertrainsAndFuels` versus `VEPowertrainsAndFuels`). + +``` +for(Year in getYears()) { + runModule("CreateHouseholds", "VESimHouseholds", RunFor = "AllYears", RunYear = Year) + runModule("PredictWorkers", "VESimHouseholds", RunFor = "AllYears", RunYear = Year) + runModule("AssignLifeCycle", "VESimHouseholds", RunFor = "AllYears", RunYear = Year) + runModule("PredictIncome", "VESimHouseholds", RunFor = "AllYears", RunYear = Year) + runModule("PredictHousing", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("LocateEmployment", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("AssignLocTypes", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("Calculate4DMeasures", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("CalculateUrbanMixMeasure", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("AssignParkingRestrictions", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("AssignDemandManagement", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("AssignCarSvcAvailability", "VELandUse", RunFor = "AllYears", RunYear = Year) + runModule("AssignTransitService", "VETransportSupply", RunFor = "AllYears", RunYear = Year) + runModule("AssignRoadMiles", "VETransportSupply", RunFor = "AllYears", RunYear = Year) + runModule("AssignDrivers", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("AssignVehicleOwnership", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("AssignVehicleType", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("CreateVehicleTable", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("AssignVehicleAge", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("CalculateVehicleOwnCost", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("AdjustVehicleOwnership", "VEHouseholdVehicles", RunFor = "AllYears", RunYear = Year) + runModule("CalculateHouseholdDvmt", "VEHouseholdTravel", RunFor = "AllYears", RunYear = Year) + runModule("CalculateAltModeTrips", "VEHouseholdTravel", RunFor = "AllYears", RunYear = Year) + runModule("CalculateVehicleTrips", "VEHouseholdTravel", RunFor = "AllYears", RunYear = Year) + runModule("DivertSovTravel", "VEHouseholdTravel", RunFor = "AllYears", RunYear = Year) + runModule("CalculateCarbonIntensity", "VEPowertrainsAndFuels", RunFor = "AllYears", RunYear = Year) + runModule("AssignHhVehiclePowertrain", "VEPowertrainsAndFuels", RunFor = "AllYears", RunYear = Year) + for (i in 1:2) { + runModule("CalculateRoadDvmt", "VETravelPerformance", RunFor = "AllYear", RunYear = Year) + runModule("CalculateRoadPerformance", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("CalculateMpgMpkwhAdjustments", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("AdjustHhVehicleMpgMpkwh", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("CalculateVehicleOperatingCost", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("BudgetHouseholdDvmt", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("BalanceRoadCostsAndRevenues", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) } -] + runModule("CalculateComEnergyAndEmissions", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) + runModule("CalculatePtranEnergyAndEmissions", "VETravelPerformance", RunFor = "AllYears", RunYear = Year) +} ``` +## Set-up Inputs {#defs} +The set-up inputs are those in the `defs` directory. The `geo.csv` file will need to set up to represent the model geography. `deflators.csv` may need to be adjusted to ensure that all years prior to the model base year are present. `units.csv` typically will not need to be adjusted. + +- [deflators.csv](#deflators.csv) +- [geo.csv](#geo.csv) +- [units.csv](#units.csv) + ### deflators.csv This file defines the annual deflator values, such as the consumer price index, that are used to convert currency values between different years for currency denomination. This file does not need to be modified unless the years for which the dollar values used in the input dataset is not contained in this file. The format of the file is as follows: @@ -122,7 +195,7 @@ This file describes the default units to be used for storing complex data types ## Inputs by Concept -This section covers over generalized inputs by concepts shared by all VisionEval models. Best practices for inputs by concepts are also discussed. To learn about the specific inputs used by each model skip ahead to the following sections: +This section covers generalized inputs by concepts shared by all VisionEval models. Best practices for inputs by concepts are also discussed. To learn about the specific inputs used by each model skip ahead to the following sections: * [VERSPM inputs](#verspm-inputs) * [VE-State inputs](#vestate-inputs) @@ -192,6 +265,21 @@ Many of the inputs relating to household multi-modal travel are those that also * **Parking.** Parking in VisionEval is defined by parking supply and [parking restrictions](#parking-restrictions), including [parking costs](#parking-costs). +### model_parameters.json +This input file contains global parameters for a particular model configuration that may be used by multiple modules. A more detailed description of the file and its structure can be found [here](https://github.com/visioneval/VisionEval/blob/master/api/model_system_design.md#61-model-directory-structure). The source of the default $16/hr in 2010$ was derived from a Nov 2014 Oregon DOT Report: ["The Value of Travel-Time: Estimates of the Hourly Value of Time for Vehicles in Oregon"](https://www.oregon.gov/ODOT/Data/Documents/Value-of-Travel-Time-for-Vehicles.pdf). Note the input looks for the dollars in the year of the base model. + +The format of this file is as follows: + +```json +[ + {"NAME": "ValueOfTime", + "VALUE": "16", + "TYPE": "double", + "UNITS": "base cost year dollars per hour" + } +] +``` + ### Vehicle, Fuels and Emissions Inputs {#vehicle-inputs} Vehicle and fuel technology are expected to change significantly during the next several decades as vehicles turn-over and the newer fleets are purchased. The characteristics of the fleet of new cars and trucks are influenced by federal CAFÉ standards as well as state energy policies and promotions. Local areas can contribute through decisions about the light-duty fleet used by local transit agencies and by assisting in deployment of electric vehicle charging stations and their costs in work and home locations, but otherwise have less influence on the characteristics of the future vehicle fleet, including auto, light truck, and heavy truck vehicles. As a consequence, the VisionEval inputs on vehicle and fuel technology are largely specified modelwide at the [region](#region) level. These inputs can be used to assess the impacts of changing vehicle [powertrains](#powertrain) and fuels on energy use and GHG emissions in the model area. The key local contribution to these inputs is the bus powertrain and fuels inputs, which are defined by [metropolitan area (Marea)](#metropolitan-area) although defaults can be used if no additional local data is available. These variables are briefly summarized below. @@ -364,7 +452,7 @@ This section details the specific VERSPM input files. * [**region_prop_externalities_paid.csv**](#verspm-region_prop_externalities_paid.csv) This file supplies data for climate change and other social costs and is used in the [CalculateVehicleOperatingCost](#verspm-calculatevehicleoperatingcost) module. -### azone_carsvc_characteristics.csv +### azone_carsvc_characteristics.csv {#verspm-azone_carsvc_characteristics.csv} This file specifies the different characteristics for high and low car service levels by `Azone`. More information on car service can be found here(placeholder). Changing this input is *optional* and using the default input values is standard practice. - **HighCarSvcCost**: Average cost in dollars per mile for travel by high service level car service exclusive of the cost of fuel, road use taxes, and carbon taxes (and any other social costs charged to vehicle use) diff --git a/docs/api-documentation.html b/docs/api-documentation.html index b2c5d70..16dbe3d 100644 --- a/docs/api-documentation.html +++ b/docs/api-documentation.html @@ -104,7 +104,7 @@