Customizing Data Variables 

User-Defined Variables

You can create user-defined variables under the sections for Demand Sites, Supply and Resources, and Water Quality, which you can reference in expressions elsewhere in WEAP. This is a very powerful feature, as it allows you to easily create your own models within WEAP.  For example, SEI researchers created an experimental glacier module in WEAP, tracking accretion, depletions and runoff from glaciers, using user-defined variables for WEAP's catchment objects.  

As opposed to Key Assumptions, which are added as new branches to the tree, User-Defined Variables are added as new variable tabs to existing branches.  Key Assumptions are best if you are using the same expression in multiple places in your model, or to highlight a major modeling assumption.  User-defined variables are better if you want to create a variable whose values will vary by demand site (or groundwater node, or reservoir, etc.).  See the Key Assumptions section for more information about them.

To create a user-defined variable, go to the Data View, right click on any of the existing variable tabs, and choose Create.  (Alternatively, for Create and all other user-defined variable actions, you can use the main menu: Edit, Data Variable.)  To edit an existing variable, make sure it is the active variable, then right click on the variable tab and choose Edit.  When you create a variable, it will initially take on the properties (described below) of the highlighted variable.


Each variable needs a Name and Category.  Unit and Comment are optional.  

Result Variable

Some data variables may actually represent calculated results, especially if you provide a default expression (below).  In this case, you might want to highlight the result by having it appear in the Results View among the built-in result variables, instead of with all the other data variables under the results category "Input Data."  To do this, check Result Variable and choose the results category under which it should appear (e.g., Demand, Reservoir, Groundwater).  You may create your own result variable categories -- in the category dropdown box, choose < Edit Categories > to go to the "Manage Result Categories" screen, where you can create new categories and choose where in the results hierarchy to place them.


The Scope section determines where and how the variable will appear.  Choose between Monthly or Annual.  Select whether the variable will appear in both Current Accounts and Scenarios, Current Accounts Only, or Scenarios Only.  Finally, for variables under Demand Sites and Catchments, whether the variable appears at the Top Level Only (the Demand Site or Catchment level), the Lowest Level Only, All Levels, One Level Below Top Level (branches just beneath a demand site or catchment), or Two Levels Below Top Level.  (Note: if you choose one or two levels below top level, and a demand site does not have one or two levels below it, that variable will not exist for that demand site.)  For comparison, Annual Activity Level appears at All Levels, Annual Water Use Rate appears at the Lowest Level Only, and Monthly Variation appears at the Top Level Only.


The Values section determines how to constrain the values of the variable.  You can specify Minimum or Maximum limits for values of the variable, or leave them blank if there are no limits.  If it makes sense to sum the values across the branches (e.g., Land Area can be summed, but not Consumption), check Sum Across Branches.  

Most variables do not allow gaps in the data, where some timesteps have values but others are missing.  For example, air temperature data for the soil moisture catchment method must exist for every timestep.  (Tip: when reading data from a CSV file with ReadFromFile, you can have it fill in missing values for you.)  Missing values are denoted by a special value (-9999), which is known as the MissingValue.  The Allow MissingValue checkbox will determine whether or not this user-defined variable is allowed to have gaps.

Default Value or Expression

Data variables will typically default to 0, but in some cases to another value (e.g., Consumption defaults to 100%, Demand Priority defaults to 1).  You can also create variables that are calculated, which will have a default expression that is not a constant.  For example, to model population you might create two new variables: Population Growth Rate, and Population.  Population Growth Rate is data, and will contain the annual growth rate, whereas Population is calculated (in the Scenario).  In this case, the scope of Population Growth Rate is Scenarios Only, with a default of 0.  Population will appear in both Current Accounts and Scenarios, but the default expressions will be different--the default for the Current Accounts is 0 (entered as data), and for the Scenarios the default will be Growth(Population Growth Rate).  In the case of a calculated variable, it is a good idea to mark it as Read Only.  This will prevent anyone from overriding the calculation (in the default expression).

Built-In Data Variables

You may customize WEAP's built-in variables (such as Demand Site Annual Activity Level or Consumption) to some extent.  You are allowed to edit (right click on the variable and choose Edit) a variable's Unit, Category, Minimum and Maximum Values and Default Value or Expression.  (Changing the default expression can be especially useful if you have created your own model using user-defined variables and you want to link a built-in WEAP variable to the result from a user-defined variable.)  You may not change the name, comment or scope.  You are not allowed to change the unit here if the unit is chosen on the main menu General Units screen (e.g., Reservoir storage volume) or independently for each branch (e.g., Demand Site Annual Activity Level).

Although you are not allowed to delete a built-in variable, you may hide it.  Right click on the variable and choose Hide.  To unhide previously hidden variables, right click and choose Unhide, and then choose the variable to show, or All Variables to unhide all previously hidden variables.  Hiding unused variables can be a useful way to simplify a model's appearance, perhaps for display to stakeholders.  Note: variables can still be used in calculations even when hidden (e.g., if you enter 50% for a demand site's consumption and then hide the Consumption variable, WEAP will still use the hidden value of 50% in determining how much water is consumed by the demand site).  Therefore, to prevent confusion, it is best not to hide variables which currently hold data.

Data Variables Report

To see a list of all (unhidden) data variables along with their definitions (the information listed above), from the main menu choose Edit, Data Variable, Report.  Variables for non-existent objects (e.g., reservoir variables if the area has no reservoirs) are not shown.  The report can be exported to a CSV, ASCII, Excel, Word, HTML or XML file, or to the Windows clipboard.  This report will not include any data expressions -- for those, you will need to see the Data Expressions Report or Export Expressions to Excel.

To delete a user-defined variable, right click on its tab and choose Delete.

You can reorder the variables tabs -- right click on a tab and choose Move Left or Move Right.

Note: If you want to perform an action on a variable (Edit, Delete, Move Left, Move Right, or Hide), you must first make sure that the variable is the current, highlighted variable.  If it is not, left click on the variable tab to select it, then right click on it and choose the desired action.

Note: Customizing data variables only applies to the current WEAP dataset.  If you want to add or customize variables in other datasets, you will need to do it separately for each one.  If you have added many user-defined variables to an area and you want to have the same variables in a new area, create the new area as a copy of the existing area with the user-defined variables.  If you want to add the user-defined variables from one area to another existing WEAP area, create a Plugin containing the user-defined variables from the first area, and Import it into the second area.

See also: Customizing Result Variables

Menu Option: Edit: Data Variable