# whatIf? Wiki

### Site Tools

tutorials:tool_quick_reference_card

This is an old revision of the document!

# TOOL Quick Reference Card

A “cheat sheet” of commonly used tools, control structures and their syntax.

TOOL lines beginning with the '!' character are considered comments and will be ignored by the interpreter.

## Tools and examples

### E

extend() syntax and example:

```A[..,Y,..] = extend (B[..,X,..]; dim=name, {start=s} {,end=e})
A[s,t] = extend (B[s,t]; dim=time, end=1998)```

### L

linint() syntax:

`A[..S] = linint(B[..S];{start={on,off}}, {end={on,off}}, {fixedStart={on,off}}, {fixedEnd={on,off}})`

### M

map() example:

`A[x] = map (B[y], yTox[x,y])`

where map can be created:

```map1[x,y] = create (; dim=x, dim=y, format=mapping, y1->x1,..,yi->xi,...)
map2[x,y] = import (; dataFormat=mapping, y1->x1,..,yi->xi,...)```

### N

norm() examples:

```a[x,y,t] = norm (b[x,y,t]; dim=x)
a[x,y,t] = norm (b[x,y,t]; dim1=x,dim2=y)
a[x,y,t] = norm (b[x,y,t]; dim=all)
a[k->j,t] = norm (b[k->j,t]; dim=Name(k->j)@Name(k))
```

### S

sum() examples:

```a[t] = sum (b[t,a]; dim=age)
a[t] = sum (b[s,t,a]; dim1=sex, dim2=age)
a[s,t] = sum (b[s->c,t]; dim=stateCOcounty@state)
a[] = sum (b[s,a]; dim=all)```

glue() syntax and example:

## TOOL commands

TOOL comments are lines beginning with the '!' character and will be ignored.

Navigation and display: `where(), moveto(“pathName”), up(), look(), showenv()`

buildstring() syntax:

`buildstring (\$var, string1, string2, ...)`

listen() example:

```string \$target
say ("")
listen ("What do you want for the 2031 total dwelling unit target? {0..}[340500] ",\$target)
if \$target == ""
\$target = "340500"
target[] = create (; entity=dwellUnit, data=\$target)
else
target[] = create (; entity=dwellUnit, data=\$target)
endif```

```menu (prompt, numItems, {item1, ..., itemN},{\$items[]}, \$choices[]
{defaultChoice=itemNumber}, {oneChoice={on,off}})```

Example1: using variable strings, defaults and one choice only paramters

```	integer \$numChoices = 3
boolean \$choices[\$numChoices]
string \$choiceStrs[\$numChoices]

\$choiceStrs[1] = "ON Ministry of Finance - low scenario"
\$choiceStrs[2] = "ON Ministry of Finance - reference scenario"
\$choiceStrs[3] = "ON Ministry of Finance - high scenario"

menu ("Which result do you you want to see?  ", \$numChoices, \
\$choiceStrs[], \$choices[]; defaultChoice=1, oneChoice=true)

if (\$choices[1] == true)
say (\$choiceStrs[1])
...
endif
if (\$choices[2] == true)
say (\$choiceStrs[2])
...
endif
if (\$choices[3] == true)
say (\$choiceStrs[3])
...
endif

etc.```

If-Else syntax:

```if arithmeticExpression

{else}

endif```

For loop syntax:

```for \$controlVar from start {upto, downto} end {by step}
...
endfor```

## Object Creation and Shaping

create() syntax:

```A[X1,..,Xn] = create (; {object=array},
dim=dimString(X1), ...,dimString=Name(Xn),
{dimFromi=D[..]},{SIuom=uomStr,{metre=ni, m=ni},
{kilogram=ni, kg=ni},{second=ni, sec=ni, s=ni},{degreeC=ni, degC=ni},
{altUom=altUomStr}, {entity=entStr},
{SIuomFrom=S[..]}, {altUomFrom=T[..]}, {entityFrom=E[..]},
{dataType={real, integer}},{desc=descrStr},
{format={agg,coord,record,mdi}, useIndex={on,off},
{translate1=string1, .., translaten=stringn,..,value1=number1,..,valuen=numbern,
...,format dependent parameters...)```

Examples:

```labourRate[s,t] = create (; dim=sex, dim=SEQ;time:1992:1994:1;year, \
entity="(person*year)/auto", rowTitles=on, dataFile=labour.txt)```

changeshape() syntax:

```A[..,Y,..] = changeshape (B[..,X,..]; {Name (X)->newDim, DimNum (X)->newDim}, {reduceEnt}, {entity=ent}, \
{altUom=auom}, {entityFrom=C[..]}, {SIuomFrom=D[..]}, {altUomFrom=E[..]}, {desc=str},{addDimn=dimName}, \

Examples:

`A[s,thwb] = changeshape (B[a,s,th]; time->SEQ;time:1991:2006:1;year, deleteDims:age)`

copyshape() syntax:

`A[..] = copyshape (B[..])`

changeseq() syntax:

`A[..,Y,..] = changeseq (B[..,X,..]; dim=X, {name=c}, {interval=i},{start=b}, {end=e}, {step=s},{shift=n})`

reorder() example:

`popx[s,a,t] = reorder (pop[s,t,a]; sex, age, time)`

seeshape() syntax:

`seeshape (A1[],..,An[])`

## Defining Sequences; Extracting and Inserting

A sequence is defined by the string: `SEQ;name:start:end:step;stepInterval`
For example:

`x[t] = create (; dim=SEQ;time:1986:2006:1;year)`

Examples of extract(), selection ranges from sequences.

```A[s,t] = extract (B[s,t]; time:1993..1994)
A[s,t] = extract (B[s,t]; time:+1..+2)
A[s,t] = extract (B[s,t]; 2:1993..1994)
A[s,t] = extract (B[s,t]; 2:+1..+2)
A[s,t] = extract (B[s,t]; 2:+1..-2)
A[s,t] = extract (B[s,t]; time:1991..2006@5)```

Non-sequence extraction:

```A[s,tmp] = extract (B[s,t]; time:"1993,1995")
A[s,t] = extract (B[s,t]; time:+1,+3)
A[s,t] = extract (B[s,t]; time:"1987,1991..1998,2003")```

Set from a set:

```A[cp,t] = extract (B[c,t]; cities:"NY,Toronto")
A[cp,t] = extract (B[c,t]; time:+1,+2)```

Multi-dimensional extraction with shrink:

`A[t] = extract (B[s,t]; sex:male, time:1993..1994, shrink=on)`

insert() examples

```popx[t] = insert (popy[tc]; time->time:+0@5)
A[s,t] = insert (B[t]; sex:male)```

## Sets

`crop[] = create (; object=set, data="wheat corn barley")`

Or using a file

`crop[] = create (; object=set, dataFile=crop.txt)`

where 'crop.txt' is a file containing:

```! the set 'crop'
wheat "wheat seed crop"
corn "corn seed crop"
barley "barley seed crop"```

## Categories

Syntax of category creation:

`A[] = create (;object=category, groups=X, members=Y, dataFile=fileName,{desc=descrStr})`

where the category definition file syntax is `groupElemString : memberElemString` or `memberElemString`. For example:

```! munWard category elements
downtown : hamlet
othello
east : romeo
west : juliet
west : falstaff
kingLear```

mapcat() syntax:

```A[..,cs,es,..] = mapcat (B[..,cs->es,..]; dim=csCOes)
A[..,cs->es] = mapcat (B[..,cs,es,..]; category=csCOes)
A[..,cs->es] = mapcat (B[..,cs,..]; category=csCOes)
A[..,cs->es] = mapcat (B[..,es,..]; category=csCOes)```

Category sum() syntax:

`A[s1,..,sn,k,t1,..,tm] = sum (B[s1,..,sn,k->j,t1,..,tm]; dim=Name(k->j)@Name(k), {ensureShare=(on,off)})`

## TOOL Object Info

getobjinfo syntax:

`getobjinfo (A[r,s,t], \$infoVar; info=sequenceStart, dim=time)`

where common info parameter values are: `sequenceName, sequenceStart, sequenceEnd, sequenceStep, rank`

Example:

```integer \$timeStart, \$timeEnd, \$targetYear
getobjinfo (population[uss,ts], \$timeStart; dim=time, info=sequenceStart)
getobjinfo (population[uss,ts], \$timeEnd; dim=time, info=sequenceEnd)
getobjinfo (targetYear[], \$targetYear; info=dataElement, default=2041)```

## TOOL Variables

Variable declaration syntax and example:

```varType \$var1Name, \$var2Name, ...
integer \$x, \$y, \$z```

Variable types: `integer, real, boolean, string`

## Object Display

display() examples:

table() examples:

`table (population[s,t,a], births[s,t,ma]; window1=1)`

graph() examples:

geomap() examples:

## Views & Scenarios

Structure of views.samm file, and types of views: `creview, disview`

```!type    view name   node        v. link file  tool file     view description
creview  creFertScn  population  creFertScn.v  creFertScn.t  "create fertility scenario"
disview  popRpt      population  popRpt.v      popRpt.t      "Population Report"
fbview   trackEU     compare     trackEU.v     trackEU.t     "Tracking Energy Use"  20  0.001```

Structure of variable link file (.v) for disview is:

```...
varName
...```

where `varName` takes the form `calculatorName/varName` for non-framework variables. For creview the file has the structure:

```...
varName {U F}
...```

where `U` is for Using type object and `F` is for Filling type objects.

Object array declarations in views `objectType objectArrayName[][]`
where objectTypes are: `view, creview, localview`

[List reserved TOOL variables]

quit() is called as `quit (return code)`