The Graph tool has a three-level hierarchy: graph labeling and control, scale grouping, and descriptors for the individual variables to be included in the graph. For each hierarchical level the order, after the keyword beginning the hierarchy (:GRAPH, :SCALE and :VAR respectively), is unimportant and keywords are shown alphabetically below.
Scales can be specified with the :SCALE keyword or by separating the names of variables with commas , using the :VAR keyword. Both of these work the same way. The :SCALE keyword is more flexible but also more cumbersome. Use the one most convenient for you.
NOTE A complete Custom Graph definition requires one :GRAPH and one :VAR line.
Graph Labeling and Control
:GRAPH name begins the description of a graph. The name appears in the Custom Output Selection dialog as an identifier for the graph.
:CUMULATIVE plots the cumulative (integrated) value of the graph variable.
:DOTS does not interpolate between points when drawing the graph lines. This option is handy for creating scatter plot of noisy data where connecting the dots would make the graph hard to read. It is also useful for looking at Data variable to see exactly where they fall.
:HEIGHT value specifies the height of the graph (including all labels). The value for height is in inches or centimeters depending on what you have set in the Global Options dialog.
:LABEL-LINES specifies x-axis labels centered on vertical grid lines. This is the default.
:LABEL-INTERVALS specifies x-axis labels centered between the vertical grid lines. A plot on a scale presented in calendar years usually looks best if it is graphed with the labels placed between vertical lines; other plots make sense only if the grid lines are marked.
:LANDSCAPE specifies horizontal printed orientation. This does not affect the appearance of the graph on the screen. This option will only take effect if orientation is set to Best Choice in the Print Options dialog.
:MAX-POINTS n specifies the maximum number of points to be used in a work in progress graph. This value default to 100 and should be set larger if you are making simulations in which (FINAL TIME-INITIAL TIME)/SAVEPER is bigger than 100.
:NO-LEGEND n suppresses the legend at the bottom of the graph, the title of the graph and labels. Use 1 to suppress the legend, 2 to suppress the title and 4 to suppress the x-axis labels. Adding these up will suppress more than one thing (for example 3 suppressed the legend and title). This is useful if it is obvious from the graph lines what they are, or if you want to add a legend in a different format after exporting the graph.
:PORTRAIT specifies vertical printed orientation. This does not affect the appearance of the graph on the screen. This option will only take effect if orientation is set to Best Choice in the Print Options dialog.
:STACK N plots the graph variables as a stackup, that is, VAR_1, VAR_1 + VAR_2, VAR_1 + VAR_2 + VAR_3, and so on. Only variables grouped under a single :SCALE will be stacked. If N is specified and nonzero only the first N variables will be stacked – additional variables will be graphed normally.
:STACK-FILL like stack except that the area between the graph lines is filled with the graph line color. Generally useful with only a single :SCALE.
:STAMP text|ident defines a stamp that appears on a printed version of the graph such as CONFIDENTIAL. text appears in a large font that overwrites the lower right part of the graph. A vertical bar | separates the text from identifier. identifier appears in the lower left-hand corner of the printed graph. Neither the stamp nor the identifier appear on the screen.
:TITLE text gives the title of the graph. This appears centered over the top of the graph. If no title is specified, the graph name is used.
:WIDTH value specifies the width of the graph (including labels). The value for width is in inches or centimeters depending on what you have set in the Global Options dialog.
:WIP marks the graph as a work in progress graphs. Work in progress graphs are displayed automatically during a simulation. Work in progress graphs are not scaled automatically so it is usually necessary to specify the minimum and maximum values for all the axis. You can have up to 10 work in progress graphs defined.
:X-AXIS name gives the name of the graph's independent variable. If :X-AXIS is not specified, the Time Base currently selected in the Time Axis Control dialog is used. The y-axis names depend on which variables are selected for graphing.
:X-DIV value or :XDIV ?value=label?value=label... specifies the number of horizontal graph divisions. If :X-DIV is left set to 0 or not included, the number of divisions will be determined based on the x-axis values in the graph. If you want the number of divisions as set in the Time Axis Control dialog use :X-DIV -1. You can also use the :XDIV keyword to break up the x axis with qualitative labels. Just follow :X-DIV with a series of values and labels and the x-axis will be broken up according to the values and given to corresponding labels.
:X-LABEL text defines the label to be displayed on the x-axis. By default this is the name of the graph's independent variable. The labeling on the y-axis is modified variable by variable using the :VAR keyword.
:X-MAX value specifies the maximum value on the x-axis.
:X-MIN value specifies the minimum value on the x-axis.
:Y-DIV value specifies the number of vertical graph divisions. If you do not specify a value the number set in the Scale Control dialog will be used.
:Y-LABEL ?value=label?value=label... specifies that the Y axis should be given special labels according the values specified. The values should be increasing but need not be equally spaced. This allows explicit entry of important value break points. All variables must share the same scale when :Y-LABEL is used.
:Y-MAX value specifies the maximum value on the y-axis. This value is overridden whenever a specific variable is given a value for :Y-MAX.
:Y-MIN value specifies the minimum value on the y-axis. This value is overridden whenever a specific variable is given a value for :Y-MIN.
Scale Grouping
:SCALE groups variables to appear on a single vertical scale. If :SCALE is not specified, variables appearing on separate lines will appear on separate scales. If conflicting :UNITS, :Y-MIN or :Y-MAX values are specified for variables in a single scale, those from the last variable will be used.
Variables on the Graph
:VAR name1|label1,name2|label2, ... specifies one or more variables that will appear on the graph, on the same scale. The labels are optional. If not specified, the variable's name will be combined with the name or a dataset.
:CONFIDENCE %=color, %=color, ... specifies that the variable will be displayed as a percentile graph if it is a saved variable from a sensitivity simulation. % is a number between 1 and 100 that describes the percentile range. Color is a RGB color specification with the values separated by vertical bars | as in 255|0|0 for pure red. You can specify as many ranges as you want or leave them blank to get defaults. You can also include more than one confidence plot on a graph, though the results might be confusing. If the dataset is not a sensitivity simulation or the variable was not saved nothing will be displayed. This cannot be used with :SENS-LINES
:DATASET filename|label specifies the name of the dataset in which values for the variable will be found. The label is optional and will be used only if there is no label for the variable. If no dataset is named, the first loaded dataset will be used.
| - Wildcard datasets (such as "*1") can be used to refer to one of the currently loaded datasets. Instead of explicitly naming a dataset, you may use an asterisk * and a number from 1 to 9 to denote the corresponding dataset in the Dataset Control dialog. For example, "baserun" would use values from the file baserun.vdf, whereas *2 would use the second loaded dataset. If you omit references to a dataset, Vensim uses the first or last loaded dataset (depending on whether Vensim is configured to load datasets in first or last position - see Dataset Control Panel). Use *B to refer to the last loaded dataset. Use * to refer to all loaded datasets. Use # followed by a number (such as "#3") to refer to all loaded datasets up to and including that one. For example #3 will use the first, second, and third loaded datasets. |
:LINE-COLOR r-g-b specifies the color for the graph line (or shapes). The color is specified as a combination or red, green and blue components each of which must be between 0 and 255. If this is blank the standard graph line colors (as set in the global options for Vensim) are used.
:LINE-STYLE style specifies the style for a line. The choices are DOT, DASH, DASHDOT and DASHDOTDOT. Note that this can’t be mixed with a line width (styled lines must have width 1).
:LINE-WIDTH width specifies the width that the graph line will have. Normally graph lines have the same width, but different colors. Can’t be mixed with line style.
:MEAN color specifies that the mean of the sensitivity simulation should be displayed as a line of the specified color. This option will only have an effect if one of :SENS-LINES or :CONFIDENCE is specified.
:SENS-LINES color specifies that the results from a sensitivity simulation should be displayed as line traces. You can specify the color to show the traces with or leave it blank for black. This cannot be used with :CONFIDENCE.
:SHAPE shape,size(for use with :DOTS only) lets you specify the shape that the dots will take on. Acceptable shapes are SQUARE, SOLID-SQUARE, CIRCLE, SOLID-CIRCLE, CROSS, X, DIAMOND, TRIANGLE, and UPTRIANGLE (upside down triangle). The size is in pixels and gets properly translated on printing.
:RUN filename|label is a synonym for :DATASET.
:UNITS units defines the units label for the variable(s). If no units label is given, the Workbench model will be searched to see if it can determine a units label. If not, nothing will be shown.
:Y-MIN value specifies the local minimum value for the y-axis.
:Y-MAX value specifies the local maximum value for the y-axis.
Example 1 - Multiple Variable Graph
| :graph world base (#3) |
| :title Base run from the WORLD model. |
| :var Capital |
| :var Natural_Resources |
| :var quality_of_life |
| :var Population |
| :var Pollution |
Results in the output:
Example 2 - Dataset Control
| :GRAPH SPEED |
| :TITLE Work Speed |
| :X-AXIS time |
| :X-LABEL Month |
| :X-MIN 0 |
| :X-MAX 100 |
| :Y-MIN 0 |
| :Y-MAX 1.0 |
| :VAR wrk_speed[ASSY] |
| :DATASET simulation.vdf |
| :UNITS dimensionless |
| :VAR experience_effect[ASSY],fatigue_eff[ASSY] |
| :DATASET simulation.vdf |
| :UNITS dimensionless |
Example 3 Scaling Control
| :GRAPH LABOR |
| :TITLE Assembly Headcount |
| :X-MIN 1980 |
| :X-MAX 1990 |
| :Y-MIN 0 |
| :Y-MAX 1000 |
| :SCALE |
| :VAR direct_labor[ASSY]|Direct Labor |
| :RUN simulation.vdf |
| :VAR direct_labor[ASSY]|. . . . . . . . .actual |
| :DATASET actual.vdf |
| :UNITS people |
| :Y-MAX 10000 |
| :SCALE |
| :VAR indirect_labor[ASSY] |
| :RUN simulation.vdf |
| :UNITS people |
| :Y-MAX 500 |
Note that variable-specific limits override the global :Y-MAX values on this graph.
Example 4 - Sensitivity Graphs
:GRAPH Sens1
| :var net cash flow |
| :confidence 50=255|244|128,75=0|255|0,95=0|0|255,100=128|128|128 |
Example 5 - Qualitative Display
:GRAPH Qualitative
:TITLE Natural Resources over Time
:X-DIV ?1900=Early?1997=Now?2100=A century later
:X-LABEL During the Industrial Age
:Y-LABEL ?0=None?4E11=Not Much?1E12=Lots
:VAR Natural Resources
:NO-LEGEND
