Modules and Libraries

Revision as of 01:26, 20 June 2015 by Karenlee (talk | contribs)


Types of Modules

There are six types of modules in Analytica, written here in a "is-a" tree:

  • Module
    • Linked Module
      • Model
    • Library
      • Linked Library
    • Form

In other words, a model is a type of module (and thus has the properties and behavior of a module and then some), a linked library is a type of library, which is a type of module, etc. One additional "is-a" not evident here is that a linked library is also a subclass of linked module (i.e., has all the properties of a linked module as well as all the properties of a library).

All of these subclasses of module can contain other Analytica objects. You can think of these modules as "sub-models" -- i.e., minature models contained within your larger model. This containment creates a hierarichal organization that forms the dominant organizing principle in an Analytica model. At a given level, it is best to keep the number of objects (often called nodes) to a manageable number -- between 5 and 20 -- grouping related objects into sub-modules to adhere to this stylistic guideline. This contributes to the transparency of models, allowing users to understand the big picture at each level visually.

(Embedded) Module

The embedded module, or just module, is the simplest container. It has a few attributes, such as its description, title, and identifier (like all Analytica objects). It also has an author attribute. It appears in its parent influence diagram as a rounded rectangle with thick borders. By double clicking on a module node, you open its diagram, displaying its contents.

Linked Module

A linked module is a module that is stored in its own file.

A linked module may be shared among multiple models, which is often a convenient way to share portions of your model. For example, if you've developed a model of the economy, you could store this in a linked module and re-use this module in other models. When modules are linked, then changes made within the linked module are inherited by all models that use the linked module (the changes take effect the next time the model is re-loaded).

Linked modules are also useful for collaborately building models. Each model builder can take ownership of one linked module. Typically you'll include a model wrapper that everyone has a copy of containing all of the linked modules (as linked). When anyone updates their module, everyone automatically obtains those changes the next time the load or re-load the model. Linked module files also work nicely with source control systems (such as VSS or SubVersion).

Linked module files do not include system variable settings or preferences. Thus, adding a linked module to your existing model will not reset system variables Time, Run, SampleSize, your Preference Settings, etc.

When you use a previously saved linked module, you will be given the option to link or embed. If you embed, you will disconnect from the original, so that changes made to the module file in the future won't effect your model, and changes you make to it from your own model won't effect other models. If you later decide you want to update with the latest changes to the linked module, you can add it again and select Merge.

Model

The top-level in your own model will usually be a model-object. Typically, this will be the only model object in your project. However, neither are required. You can load a linked module or linked library file directly as the top-level object, with no model object at all, and it is possible to have multiple model objects present at the same time.

A model object inherits the properties of a linked module -- i.e., it is stored in its own file. However, in addition to the information stored with a module, a model file also contains system variable settings, including Preferences, system variables Time, Run, SampleSize, and defaults for uncertainty settings and graph settings. Thus, if you wish to share your preferences and system variable settings between models, include a shared model object. If you do this, be particularly aware of the Time variable -- this does require that your models utilize exactly the same definition for Time.

While building a new model, you may realize that you want to include a previously built model as a "module" in this new model. You can do that either by linking or embedding, but when you do so, remember that if you use Add Module... directly, you'll load in the system variable settings from your earlier model. If you want everything except the system variable settings, load the earlier model into Analytica first, change its class from "Model" to "Linked Module", and specify a new filename. Then add that newly saved module to your new model.

Library

A library is a module that normally contains User-Defined Functions; however, there are no limitations requiring libraries to contain UDFs, nor do UDFs have to be in a library, nor are there any limitations on other types of objects that can appear within a library.

A functional distinction of a library, compared to a plain module, is that Analytica displays the library on the Definition Menu and in the Object Finder, along side all the system function libraries. (Note: The library will not appear there if it is empty).

Linked Library

A linked library is a library located in its own file. It inherits both the properties of a linked module and the properties of a library. Linked Libraries are a common way to share custom User-Defined Functions between models. Analytica provides about a dozen linked libraries, which you can use from your own models by selecting File → Add Library....

Form

A form is a module intended to contain a control panel (a collection of inputs and outputs). Any module can contain inputs and outputs, and a form is not limited to these. The difference between a Form and a Module is that Analtyica's User interface treats certain operations differently. For example, if you draw an arrow from a variable to a form node, an output (result) control is automatically added to the form. Likewise, if you draw an arrow from a form to another variable, an input control is added.

Note: This section could be refined to describe all the differences in user-interface for a Form.

Sharing Linked Modules or Libraries

Using Modules to Copy One Model to Another

Suppose you have two models M1 and M2, and would like to copy the contents of M2 to M1. You can do this by following the steps:

  1. Open M1 up.
  2. In Edit mode, select Add module... from the File menu, and select model M2.
  3. In the Add module or library dialog, Select Embed a model, but leave Merge contents unchecked.

This will read all of model M2 as a module into M1. Any variables or other objects in M1 with identifiers the same as identifiers in M2, will be modified, by adding a digit at the end of the identifiers to make sure that they are all unique.

To copy parts of M2 into M1 without copying the entire model:

  1. Open M2 and move the parts of M2 you would like to copy into a module.
  2. If it is not already open, open up the Attribute panel by clicking on the key icon at the bottom left corner of the window.
  3. Select module with the variables you want to copy, and change the Attribute panel to the Class view.
    • The Class should be Module, with the empty Module icon selected as in the image below. Select the Module with the icon with a page in it instead.
    • SelectClass.jpg
  4. Analytica will prompt you to save the Module as a separate Analytica file. Save this file.

Now you can follow the previous instructions on how to copy the contents of the entire model M2 to M1, embedding the module you just saved containing parts of M2 into M1.

Obfuscated and Browse-Only Copies

Obfuscation means that your models or modules are saved in an encrypted form, so that users who view the model file cannot see the contents of your model or module. Obfuscation also locks in any definitions that have been hidden, so they can no longer be viewed or unhidden. (Definition hiding is a feature of Analytica Enterprise that allows you to hide proprietary definitions from end-users).

Browse-only models (or linked modules) are models (or linked modules) that have been saved in a form that disallows any changes to be made to any object, except those containing input nodes. When you distribute a browse-only copy of your model, your users can only change those inputs that you have specified (by creating input nodes).

Whenever you obfuscate or lock to browse-only, you always want to save the locked copy in a separate file from your master copy. These are irreversible operations. You will keep the unlocked master for yourself, so you can make future changes, and send your end-users the locked copies. Do not replace your master copy with a locked copy, because locking is irreversible.

In Analytica releases 2.0 through 4.1, obfuscation and browse-only locking apply to the model as a whole -- i.e., the entire model (and all its linked modules) are obfuscated and/or browse-locked. In Analytica 4.2, obfuscation and browse-locking are applied on a linked-module-by-linked-module basis. This means that you can distribute a linked library that is obfuscated with hidden definitions, that other people can use, without having to reveal the implementation of your secret algorithms (i.e., the function definitions). Once you use obfuscated or browse-only models from within a non-obfuscated model (Analytica 4.2 or later only), there are numerous limitations with what you can do with the objects in those locked linked modules, described in more detail at Obfuscated and Browse-Only Models.

See Also

Comments


You are not allowed to post comments.