Guide for clear models

Experienced modelers understand that developing models is about building a clearer shared understanding of the problem among analysts, experts, and clients and other decision makers as much as it is about generating better numbers. The clarity of the model is central to success in improving communication among the decision team.

We designed Analytica to encourage you to create models than are much clearer than typical spreadsheets and programs in conventional procedural languages. Key features include visual influence diagrams, integrated descriptions, and Intelligent Arrays (which vastly simplify many expressions). Nevertheless, just using Analytica doesn't guarantee that a model is entirely lucid. This page (and it's links) is offers tips for creating models that are as clear as possible. Your clients and colleagues will benefit. And you will help yourself out in case you ever have to understand what you did to find a bug or extend the model some time in the future.

Diagram layout

See Creating Lucid Influence Diagrams for tips on how to design your influence diagrams for clarity and elegance.

Descriptions

A clear Description attribute for every Variable, Module, and Function is a great help in understanding a model.

When you move the mouse cursor over a node, normally it shows a Balloon popup with the title, units, and Description of the node.

For models with user interfaces, it is important to include a Description with every user input and output node to guide users in what they mean. When the user moves their mouse, it normally shows a balloon containing the Description (if it has any). If you specify a Help attribute for a node, it shows the Help text instead of the Description. This is useful if you want to provide specific Help text for end users, that is different from the possibly more detailed and technical Description you might include for modelers. (

The Description text appears in Help balloon when the user put their mouse cursor over a node (as with all nodes).

For user inputs:

Checkbox(1): Check this box to do x...

Choice(..): Select an option to .... If the options aren't totally obvious, list the options, each with a phrase or sentence explaining it.

Multichoice(): Select one or more options to ....

Input number: Enter a number to ....

If there are less than say 20 acceptable values for the number, use a Choice(). A choice makes the range of valid values obvious to the user, prevents him or her from putting in an invalid value, and saves you (the modeler) the trouble of having to include a test, error message, and recovery process, in case the user enters an unacceptable value.

• The main purpose of the description of a variable is to say what the variable represents.
• The purpose of the descripion fo
• There's no point in starting the description with "This variable represents.." or "The purpose of this function is".
• Don't just repeat the Title of the object. That wastes everyone's time.
• If the title contains an acronym or technical term, spell it out or explain it in the Description.
• If the variable has specified units, you don't need to repeat them verbatim in the Description. But if the units are not totally obvious, it's a good idea to expand or explain them.

Description of a Function

• The purpose of the description of a function is to say what kind of value it returns and what its parameters are.
• The description

They also know that someone, possibly themselves, may need to refine or extend a model months or years later. While they may feel that descriptions are unnecessary now, they may be absolutely critical later on.

Novice modelers often never fill in Descriptions. Some may add descriptions to a few at the end of the project if they have time. Experienced modelers often add descriptions as they build a model. Some find it helps to add the description before they write the Definition -- because writing the descriptions requires them to think carefully about what the variable represents, a prerequisite for effective writing the expression to calculate the variable.

If your model is.