Filed modules and libraries
A Model may contain Modules and Libraries. A Library contains functions and other objects for use in other models. Usually, Modules and Libraries are embedded in the file of their parent Model, but it is also possible to include them in separate files, known as filed (or linked) Modules and Libraries. This page describes these different classes of Module, and how to create, save, import, and remove them.
Technically, Module is a Class of Object. Model and Library are subclasses of the Module class. Each Module (including a Model or Library) is simply a collection of variables and other objects. It has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. It may contain submodules, defining a nested hierarchy of Modules. The Module hierarchy provides a convenient way to organize a complex model, perhaps with hundreds or thousands of variables and other objects.
There are six types of modulea:
- Model: A top level Module, always saved in a separate file.
- Module: A plain Module that is embedded in its parent Model or other Module.
- Filed Module: A Module used in a parent Model or other Module, but saved in its own file.
- Library: A Module that contains Functions and/or other objects designed for use in multiple Models.
- Filed Library: A library saved in its own file. Analytica is distributed with a set of standard libraries of this kind. You can also create your own Libraries for use by yourself and others.
- Form: A special class of Module that makes it easy to add User Input nodes, and User Output nodes, simply by drawing arrows from a variable to the Form Node, or from the Form Node to a variable, respectively.
The only difference between a Filed Module or Library and a Module or Library embedded in its parent Model is that it is saved as a separate file. When you add a filed Module or Library into a Model, it gives you the choice of keeping it in a separate file or embedding it in the Model file. It's usually best to embed it so that you don't have to remember to include the separate files when you move the Model or share it with other people.
If you leave it a separate file, any changes you make to it will also affect any other Models that also link to this filed Module or Library. Sometimes this is useful, for example when several people are working on a Model in parallel, and you want them all to benefit from your improvements. For the same reason, it is dangerous because any change that you or anyone makes to the same copy of filed Module will affect all Models that use it.
Add a Module or Library to a Model
To add a filed Module or Library to the active Model, use the Add Module dialog from the File menu. It prompts you for the directory and file. If instead, you select Add Library from the File menu, the file dialog defaults to the directory containing the Standard libraries distributed with Analytica.
Either way, it gives you the choice to embed the Module or Library into the parent Model or to link to the file.
Remove a filed Module or Library from a Model
To remove a Module or Library from a Model, first select it. Then, select Cut or Clear from the Edit menu, or press the delete key. If it was embedded, it deletes it. If it was filed, it deletes only the node and link from the parent Module, but not the separate file.
To create a library or filed module or library
The Node toolbar offers only a standard embedded Module. To make a separately filed Module, Library, or Form, you first create a standard Module and then change its class to what you want.
- Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
- Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
- Change the class of the module
- If you change the class to a separately filed Module or Library , a file browser dialog prompts you for a directory and file name.
- If you want the parent Model to load the new filed Module or Library the next time it is opened, use the Save command from the File menu to make sure it saves the link to the new file.
Changing Module Class
You can change the Class of a Module to another Module Class, including from embedded to filed or vice versa, in the same way that you change the Class of a Variable. (You can't change a Module into a Variable or other non-Module class, or vice versa.) Show its Class in its Object Window, or Attribute pane. In Edit mode, press on the Class menu and select another Class.
If you change from an embedded to Filed Class, e.g. from Library to Filed Library, it a File browser prompts you to select the file name and directory.
After you have linked to a filed module or library, the Save command saves every filed module and library that has changed, as well as the model containing them, in their corresponding files. The Save As and Save A Copy In commands save only the active (topmost window’s) model, filed module or filed library.
Using a Module to Copy stuff from one Model to Another
Analytica doesn't let you copy and paste objects directly from one Model to another. Here is a way to copy variables, functions, modules, or any objects from a model M1 into another model M2:
- Open Model M1.
- Create a new Module by dragging from the Toolbar, and give it a title, say "From M1".
- Drag all the objects you want to copy into that Module.
- Open the Attribute panel (if needed) by clicking on the key icon at the bottom left corner of the window.
- Select the node for module "From M1"
- Change the Attribute panel to the Class view, to show its current class "Module"
- Open the Class menu and select Filed Module (with page icon inside the module icon)
- When it prompts to save the Module, select the file name (or use the default).
- Now open Model M1
- In Edit mode, select Add module... from the File menu, and select module "From M1.ana".
- In the Add module or library dialog, select Embed a model, but leave Merge contents unchecked.
This reads "From M1.ana" to become a new module into M2. With "Merge contents" unchecked, if any imported object has the same identifier as an existing object in M2, it adds a digit at the end of its identifier, to make no existing object gets overwritten.
Managing multiple versions of a model
There are several reasons you might need to manage multiple versions of a model:
- While you are developing a model, you want to explore two or more different ways to structure it. In this case, it's a good idea to make sure the parts for which you want to try different versions are all in the same module, and the parts that won't change are outside it. That way, once you've explored the variations, you can more easily remember what's changed and what's haven't.
- A similar situation arises when two or more modelers are working on a model in parallel. It's best if you agree when you fork the model (start multiple versions), who can make changes to which module(s). Then you can change those modules to be separately filed. Usually one person retains responsibility for the parent model. Analytica doesn't have a built-in way to prevent "unauthorized" changes to a module, except by saving it as "Browse-only". But you can lock a module using the Windows explorer (see below.) When you recombine the modules (merge them) you can simply copy the changed modules into the same folder as the parent model. When you restart the parent model it will automatically read in the new module versions. At that point you can decide if you want to change them back from separately filed to integrated modules.
- If you, or other modelers, make changes to the same module(s), things get a bit trickier. You may need to go through each module to see who made what changes and decide which to adopt. Some people use Github, the widely used software source code management tool, with Analytica. In this case, Github's tools make it easy to compare different versions of a model or module. It lets you merge them and decide which version of each change you want to use.
- Sometimes you want to create several versions of a model for different applications . One approach is to put all the variables, functions, and so on that are common to all the applications into a separately filed module, and keep the things that change from one version to another in the parent model.
Each Module has standard attributes common to any Object, including Identifier, Title, and Description, plus Author(s). If it is a separately filed Module or Library, it also contains Created date, Last Saved date, and File info, containing its file path and name, like a Model object. You can see these in its Object Window.
Locking a filed module or library
You can use the Windows explorer to lock a filed module or library to prevent users from modifying it, even which they can modify things in a parent model that uses it:
- Close the filed module or library, or close Analytica.
- In Windows Explorer, select the filed module or library.
- Select Properties from the File menu.
- Check the Read-only checkbox.
- Close the Properties window
- Modules and Libraries
- Standard libraries
- Additional libraries
- User Libraries
- User-defined Functions and Libraries
- Analytica Libraries and Templates
- Example Models and Libraries
- Obfuscated and Browse-Only Models