Guide for clear models

Experienced modelers understand that developing models is as much about building a clearer shared understanding of the problem among analysts, experts, and clients and other decision makers as it is about generating numbers. So the clarity of the model is central to success. 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 your models are 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 the section on Creating Lucid Diagrams

Descriptions

Adding a clear description for each Variable, Module, and Function is a great help in understanding a model. For a model

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.