Help:Analytica conventions in open assessment

Analytica conventions in open assessment describe practices that have been found useful when using Analytica, or extended causal diagrams produced with other software.

Conventions for diagrams

Follow the node types and colours described in Help for enhanced causal diagrams.ANA

Conventions for coding

If you must choose between several intermediate nodes with no clear interpretation, or one node with a lengthy code, go for one node.
Try to separate input parameters and the actual code into different nodes. Usually input parameters can be pink data-driven nodes.
Locate the nodes so that all arrows are shown. An exception to this rule is a situation where one node uses a large number of similar nodes as input; then the input nodes are located in row so that only one arrow is visible.
Avoid descriptions {inside brackets} in the code, because it makes it difficult to temporarily move parts of the code out by using { }.
Instead, divide the code into sections using empty lines between the sections. Then number and describe each section in the Description field.
Do not add user-defined attributes to the model.
If the node is an open assessment variable (i.e., it has a wiki page), do the following:
- bevel the node
- make a link to the wiki page by using: <a href="URL_of_the_page">Variable description in wiki</a>
- change the name of the variable into the var_name of the variable, e.g. H1998.
Index names should be in singular (e.g. Emission, which is a list of different kinds of emissions), while variables are often intuitive being plural (e.g. Emissions, which is the amount of emissions, indexed by Emission).
If your local variable can have a clear and short descriptive name, use it. However, often the variables are complex objects that do not have obvious names; then it is better to use just letters.
- If a local index shows in the final output, it should have a clear descriptive name.
- Local variables are named starting with a, b, c, and so on. Usually local variable a is something that transforms in the code to become the final result.
- If you don't need a new local variable, use the existing one.
- Local indices use i, j, k, and so on.
- While-do loops use x, y, z as local loop variables.

Layout guidance (useful tips rather than rules):

If possible, the arrows should flow mostly from top to bottom and either from sides to the centre or from left to right.
Nodes should be located in such a way that all arrows are visible.
Extra empty space between nodes should be avoided.
The whole module should be visible in its window.
The window size for modules should be as small as possible. Users may want to keep several windows open.

Indices

The following rules apply only to indices for variables. Analytica nodes that are not variables in Opasnet are not considered.
Each index should belong to at least one dimension. (Indices such as age may belong to both Time and Person or group dimensions.)
Each index must have a page in Opasnet. The page may be shared by several indices, such as Year, which contains indices Year1 [2000], Year2 [1997,2000] TARKISTA!.
The identifier of the page is the Ident attribute of the index.
When the model is uploaded to the Opasnet base, the indices used must be added to the module Opasnet base conncetion.ANA.
Changeing indices should NOT be used in data tables. If there is a need to use case-specific indices (e.g. sexes separated/combined), then this should be done after the data table.
Indices should NOT contain units. Avoid situations where the units of different rows would be different. If you'd like to e.g. show some rows in mg/l and others in ng/l, then use g/l for all rows instead. The prefix m or n will show up in the result.

Easier coding

Consider the code <anacode> var a:=Lognormal_raw_water3[Database_water_qual1='TOC (mgC/l) - Raw']; var b:=Lognormal_raw_water3[Database_water_qual1='Chlorine dose (mg/l) - Postchlorination']; var c:=Lognormal_raw_water3[Database_water_qual1='Bromides (?g/l) Raw']; var d:=Lognormal_raw_water3[Database_water_qual1='pH - Raw']; var e:=Lognormal_raw_water3[Database_water_qual1='Temperature (oC) - Raw']; var f:=Lognormal_raw_water3[Database_water_qual1='Residence time (h) average estimated by company'];

(0.0412*a)*(b^0.152)*(c^0.068)*(d^0.609)*(e^1.601)*(f^0.263) </anacode>

This is problematic, because a) it refers to texts in an index, and they are likely to change, and b) the code is long. This is my suggested correction. The problems with this is that it is disrupted if the row ordering of Database_water_qual1 change, and that the numbers are not descriptive. Therefore, the descriptions of index rows used should be placed in the Description.

<anacode> var g:=Lognormal_raw_water3; var a:= g[@Database_water_qual1=22]; var b:= g[@Database_water_qual1=15]; var c:= g[@Database_water_qual1=20]; var d:= g[@Database_water_qual1=12]; var e:= g[@Database_water_qual1=10]; var f:= g[@Database_water_qual1=9]; (0.0412*a)*(b^0.152)*(c^0.068)*(d^0.609)*(e^1.601)*(f^0.263) </anacode>

Use of Description attribute

The basic principle is that the model contents are described in the Opasnet wiki, at the relevant variable pages. The description attribute in the model should contain a link to the wiki page. In addition, the description may contain technical information and explanations about the code. The code should NOT be commented within the Definition attribute, although it is possible by using {comment} or /*comment*/. This is because comments distort the functionality of temporarily blocking parts of the code out using { and }. (Analytica does not understand double brackets {{ }}.)

If the code is lengthy, it should be divided into reasonably small parts by empty lines. These parts are then numbered in the Description and the details are described. In this way, the code itself does not contain comments, but it is easy to follow the explanations about the code.

Attributes

Previously, we have used user-defined attributes such as Log, References, Moderator, and Focus+scope. These should NOT be used any more. The first priority is to document these information on the Opasnet wiki page instead of in the model. If node-specific log info is needed, then it can be written to the description of the node or to a separate Log node.

A new attribute has been created: Ident. This is the Opasnet wiki page identifier (e.g. Op_en1912), and it is used to connect a node in an Analytica model to variable results in Opasnet base, and also to the variable page in Opasnet wiki. It is especially important when uploading results from a model to the Base, because the Ident attribute is used to identify the correct variables in the Base.