Files and Editing

Analytica Scripting GuideFiles and Editing

Module Files

Module files contain Analytica modules; they are collections of variables, functions, and other objects. There are two ways that you can create a module file: you can create variables and save them from within Analytica, or you can create module files outside of Analytica with a conventional text editor.

Format of ‘Regular’ Module Files

If you open a model using a word processor or text editor, or print the file, this is what it will look like:

  { From user korsan, Model Foxes_hares at Thu, Mar 23, 1995 4:25 PM}
  Softwareversion 1.0
  
  { System Variables with non-default values: }
  Typechecking := 1
  Checking := 1
  Saveoptions := 2
  Savevalues := 0
  
  { Non-default Time SysVar value: }
  Time := Sequence(1,20,1)
  
  Attribute Reference
  
  Model Foxes_hares
  Title: Foxes and Hares
  Description: A simple ecology, showing the population changes over time when the fox population is dependent on a single species' (hare) population.
  Author: Lumina Decision Systems
  Date: Thu, Mar 2, 1995 10:15 AM
  Saveauthor: korsan
  Savedate: Thu, Mar 23, 1995 4:25 PM
  Defaultsize: 44,20
  Diagstate: 1,40,50,478,327,17
  Diagramcolor: 32348,-9825,-8739
  Fileinfo: 0,-1,4162,Model Foxes_hares,Foxes and Hares
  Getresource Pagesetup,1
  
  Variable Hare_birth_rate
  Title: Hare birth rate
  Description: Birth rate of the Hare population.
  {etc.}

If you change any default settings during a session (see the System Variables chapter for more information about most defaults and modifications to them), Analytica will add these to the module file:

  { System Variables with non-default values: }
  Typechecking := 1
  Checking := 1
  Saveoptions := 2
  Savevalues := 0

  { Non-default Time SysVar value: }
  Time := Sequence(1,20,1)

When you restart a model from the executive level of the computer, you will return to the point at which you ended your last work session with one exception; Analytica will have to perform all computations again from scratch.

Editing

You can create models, add objects to models, and create sets of numerical data outside of Analytica with an editor such as Microsoft® Word. Model Files created by editing can also contain Commands to Analytica. When the model File is started up, Analytica treats all objects and Commands in the text file as if they were entered interactively during a work session.

The transcript below illustrates how to create a model with the Microsoft Word application. To use another editor, you must be in the Finder, and not running Analytica.

Note When you create a model file in another editor, be sure that the names of the new objects do not overlap with names of objects in already-existing models. The only exception to this rule is when you are using the Update Command, discussed later in this chapter.

Models created in another editor must resemble interactive input. The objects in the file must have unique names. If you use a name that is already in use, Analytica will issue an error message when it tries to read the new model. Suppose you have started up Microsoft Word and typed in the following:

  model Misc
  Description: to demonstrate creating models in an editor
  variable CarType
  Title: car brands
  Units: names
  Description:  Three popular car companies
  Definition: ['vw', 'honda', 'bmw']
  variable Newmpg
  Title: mileage
  Units: mi./gal.
  Description: mileage, corresponding to brands in CarType
  Definition: array(cartype, [30, 35, 40])
  variable Price2
  Title: car prices
  Units: $
  Description: average car prices, corresponding to brands in CarType
  Definition: array(cartype, [5K, 10K, 15K])
  variable Ins
  Title: insurance
  Units: $/yr
  Description:  insurance rates for each brand in CarType
  Definition: array(cartype, [.5k, 1k, 1.5k])
  variable Car_comp
  Title: comparisons
  Description: a table showing the various factors related to CarType
  Definition: [ppy, newfuelcost, ins]
   
  variable Ppy
  Title: price per year
  Description: average amount paid per year for a car (life span of 8 yrs.)
  Definition: price2/8
  variable Newfuelcost
  Units: $/yr.
  Description: The amount for fuel, based on 15K mi/yr, $1.20 per gallon.
  Definition: (15K*1.2)/newmpg
  Close Misc	''All model Files must end with a "close" statement.''

Start up file Misc.mod in Analytica.

If the nodes do not have Nodelocation attributes, Analytica will give nodes non-overlapping default locations.

Adding Modules

There may be circumstances under which you may want to add a linkmodule or linklibrary not already contained in the model. Linkmodules and linklibraries can be added to a model using the Include command. The parameters to the Include command resemble the contents of the Fileinfo attribute (See Objects and their Attributes, File Info).

Include alias, class object, formatID, platformID, pathID, isXML, pathname
Read in a module or library from the specified file's location on a disk.

alias refers to a Macintosh File alias (type ‘alis’) resource ID, or 0 if none is specified. If a non-zero value is specified and the resource exists, Analytica uses the Alias manager to resolve the location of the file and ignores the additional information in this attribute. If a zero value is specified or if the resource doesn't exist, Analytica uses the additional information stored in this attribute to locate the file. For Windows, this value should always be 0.

class and object are this object's class and identifier, respectively, used to check consistency.

formatID set to 2 to indicate the format for the fields in this attribute

platformID represents the platform the fileinfo is saved on, and may have the following values:

  value     platform
  1             Macintosh (HFS)
  2             Windows

pathID is used by the MacOS at runtime to identify a working directory for the file.

isXml flag (0 or 1) indicating whether the included file is in XML format (1) or standard Analytica format (0)

pathname is a path name which is relative to the including file.

Note
When you add a Linkmodule or Linklibrary to a model, it doesn't actually become a part of that model; only a link is created. If the model is saved with this file reference information, it will automatically embed Include commands so that the next time the model starts up, it automatically includes the specified linkmodules.

To transform a Linkmodule or Linklibrary into a non-filed module or library, change it class after reading it in and before saving any changes.

Updating an Existing Model

There are two ways to use a text editor to update an already-existing model. First, you can edit a model that is in your directory. Or, you can create a new File that contains objects to be included a model at some later time. If you choose to create a separate File, you must begin the File with the keyword, update and end it with end update. You can then start up another model and Read in the Update File, as illustrated below:

(An editor is opened. The user types the following:)

update

model Test

variable Price

Title: car prices

Units: $

Description: average car prices, corresponding to brands in CarType

Definition: array(cartype, [10k, 15k, 20k])

close

end update

(Save the model and quit the editor)

(Start up model Misc. in Analytica)

  
  Misc> show price
  variable Price
  Title: Car prices
  Units: $
  Description: average price paid for a car.
  Definition:  10K
  Misc>readfile test	(The user asks Analytica to "read in" model Test.)
  Reading from test
  
  #

the definitions of all variables and functions are OK.

  
  Misc>show price  ( Analytica refers to the Version of that was defined in model Test.)
  variable Price	  
  Title: car prices	
  Units: $	
  Description: average car prices, corresponding to brands in  CarType
  Definition:  array(cartype, [10k, 15k, 20k])
  Misc>

Data Files

If you create a data file outside of Analytica, you must format the file to resemble Analytica input- for example, sets of numerical data must be formatted as variables. You should also begin the file with the term update and end it with end update. By using the Update Command, you can read this file into any other model. As noted above, the Update Command tells Analytica to look for object names that are shared between the already-existing model file and the File to be read. If Analytica finds overlapping objects, it will replace any attributes in the already-existing model with the new ones from the file that is being read. As noted above, the Read Command causes Analytica to treat an input file in the same way it treats "live" input from the terminal.

Models and Editing: Summary

Commands:

Readfile model
To "load in" a model File while working in Analytica, adding it to the current project.

Include alias, class object, formatID, platformID, pathID, isXML, pathname
Read in a module or library from the specified file's location on a disk.

alias refers to a Macintosh File alias (type ‘alis’) resource ID, or 0 if none is specified. If a non-zero value is specified and the resource exists, Analytica uses the Alias manager to resolve the location of the file and ignores the additional information in this attribute. If a zero value is specified or if the resource doesn't exist, Analytica uses the additional information stored in this attribute to locate the file. On Windows, alias should always be 0.

class and object are this object's class and identifier, respectively, used to check consistency.

formatID should be 2

platformID represents the platform the fileinfo is saved on, and may have the following values:

        value            platform
        1                Macintosh (HFS)
        2                Windows

pathID is used by the MacOS at runtime to identify a working directory for the file. Under Windows, this value is always 0.

isXml should be 1 for an xml file, 0 for a non-xml file.

pathname is a path name which is relative to the including file.

Concepts:

Close
Statement at end of model when updating it in a text editor.

Readfile
Incorporates a model File in the current model.

Update
Statement that begins a model File that is updated in a text editor.

End Update
Statement that ends a model File being updated in a text editor.