Difference between revisions of "Modules and Libraries"
m |
|||
| (20 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[Category: Function libraries]] | ||
[[Category:Doc Status D]] <!-- For Lumina use, do not change --> | [[Category:Doc Status D]] <!-- For Lumina use, do not change --> | ||
| − | [[ | + | A Module in Analytica is a collection of variables and other objects. Each module has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. A Module may contains subModules, defining a hierarchy of modules. A [[Model]] is a type of Module, at the top level of a module hierarchy. A Library is a type of module that is designed to be easily reusable in Models , usually offering a set of [[Functions|Functions]] that extend the functionality of Analytica. |
| − | = Types of Modules = | + | == Types of Modules == |
| − | There are six types of '' | + | There are six types of ''module'' in Analytica: |
| − | * Module | + | * '''Model''': A top level Module, saved in a separate file. |
| − | * | + | * '''Module''': A plain Module that is embedded in a 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 Library is a type of Module that contains Functions and/or other objects available for use in multiple Models. | |
| − | + | * '''Filed Library''': A library saved in its own file. Analytica is distributed with a wide range of function libraries, in the Libraries folder. You can add these to your own Models as needed. You can also create your own Libraries for reuse. When you add a Library into a Model, you have the choice of leaving it as a filed library, or embedding it as Library in the same file. The advantage of embedding it is that you don't have to remember to include separate Library files when you move the Model or share it with other people. | |
| − | ** Form | + | ** Form Module: A Form module is a special type 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. |
| − | + | Model and Library are subclasses of Module and share the properties of a Module. A Model, Filed Module, and Filed Library are saved as separate files. An unfiled Module, Library, or Form Module is embedded in its parent Module file. . | |
| − | + | == 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 filed module or filed 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 filed 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 "Filed Module", and specify a new filename. Then add that newly saved module to your new model. | |
| − | + | == (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. | |
| − | + | == Filed Module == | |
| − | + | A '''''filed module''''' is a module that is stored in its own file. This has at times been called a ''linked module''. | |
| − | + | A filed 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 filed module and re-use this module in other models. When a module links to a filed module, then changes made within the filed module are inherited by all models that use the filed module (the changes take effect the next time the model is re-loaded). | |
| − | + | Filed modules are also useful for collaborately building models. Each model builder can take ownership of one filed module. Typically you'll include a model wrapper that everyone has a copy of containing all of the filed modules. When anyone updates their module, everyone automatically obtains those changes the next time the load or re-load the model. Filed module files also work nicely with source control systems (such as VSS or SubVersion). | |
| − | + | Filed module files do ''not'' include system variable settings or preferences. Thus, adding a filed module to your existing model will not reset system variables [[Time]], [[Run]], [[SampleSize]], your [[Preferences|Preference Settings]], etc. | |
| − | + | When you use a previously saved filed 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 filed module, you can add it again and select ''Merge''. | |
| − | |||
| − | |||
== Library == | == Library == | ||
| Line 44: | Line 43: | ||
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 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. | ||
| − | + | The key functional distinction of a library, compared to a plain module, is that any library module in a model appears in the ''Definition Menu'' and in the ''Object Finder'', below the system function libraries. This makes it easy to find and use user-defined Functions (and other Objects) in Definitions. (Note: An empty library will not appear in the Definition menu.) | |
| − | == | + | == Filed Library == |
| − | A | + | A '''''filed library''''' is a library located in its own file. It has at times also been called a ''linked library''. It inherits both the properties of a filed module and the properties of a library. A filed libraries is a common way to share custom [[User-Defined Functions]] between models. Analytica provides about a dozen filed libraries, which you can use from your own models by selecting [[File menu|File]] → '''Add Library...'''. |
== Form == | == 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 | + | A form is a module intended to contain a control panel (a collection of user inputs and outputs). Any module can contain inputs and outputs, and a form is not limited to these. The only difference between a Form and a Module is that you can add a [[User Input nodes|User Input node]] into a Form simply by drawing an arrow from a Form Node to the corresponding Variable node; and you can add a [[User output nodes|User Output node]] simply by drawing an arrow from a Variable node to the Form node. (You can also add [[User input nodes and user output nodes|User Input and Output nodes]] into any type of Module, including a Form node, simply by selecting a node and selection '''Make User Input''' or '''Make User Output''' from the [[Object menu]]. You can move any kind of node, including User Input and User Output nodes simply by dragging the nodes from one module to another (including a Form node). |
| − | + | == Sharing Filed 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: | ||
| + | #Open M1 up. | ||
| + | #In Edit mode, select '''Add module...''' from the [[File menu]], and select model M2. | ||
| + | #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: | |
| + | #Open M2 and move the parts of M2 you would like to copy into a module. | ||
| + | #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. | ||
| + | #Select module with the variables you want to copy, and change the [[Attribute panel]] to the ''Class'' view. <br>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. :[[File:SelectClass.jpg]] | ||
| + | #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). | 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 | + | Browse-only models (or filed modules) are models (or filed 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. | 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 | + | == History == |
| − | + | 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 filed modules) are obfuscated and/or browse-locked. In Analytica 4.2, obfuscation and browse-locking are applied on a filed-module-by-filed-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 filed modules, described in more detail at [[Obfuscated and Browse-Only Models]]. | |
| − | |||
| + | == See Also == | ||
| + | * [[Tutorial: Dynamic system model#Creating_a_module|Tutorial: Creating a module]] | ||
* [[Using Add Module... to import a Model file]] | * [[Using Add Module... to import a Model file]] | ||
| + | * [[Import a module or library]] | ||
| + | * [[Obfuscated and Browse-Only Models]] | ||
| + | * [[Making a browse-only model and hiding definitions]] | ||
| + | * [[Filed modules and libraries]] | ||
| + | * [[Working with Models, Modules, and Files in ADE]] | ||
| + | * [[Combining models into an integrated model]] | ||
| + | * [[Analytica Libraries and Templates]] | ||
| + | * [[Example Models and Libraries]] | ||
Latest revision as of 18:00, 7 February 2024
A Module in Analytica is a collection of variables and other objects. Each module has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. A Module may contains subModules, defining a hierarchy of modules. A Model is a type of Module, at the top level of a module hierarchy. A Library is a type of module that is designed to be easily reusable in Models , usually offering a set of Functions that extend the functionality of Analytica.
Types of Modules
There are six types of module in Analytica:
- Model: A top level Module, saved in a separate file.
- Module: A plain Module that is embedded in a 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 Library is a type of Module that contains Functions and/or other objects available for use in multiple Models.
- Filed Library: A library saved in its own file. Analytica is distributed with a wide range of function libraries, in the Libraries folder. You can add these to your own Models as needed. You can also create your own Libraries for reuse. When you add a Library into a Model, you have the choice of leaving it as a filed library, or embedding it as Library in the same file. The advantage of embedding it is that you don't have to remember to include separate Library files when you move the Model or share it with other people.
- Form Module: A Form module is a special type 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.
Model and Library are subclasses of Module and share the properties of a Module. A Model, Filed Module, and Filed Library are saved as separate files. An unfiled Module, Library, or Form Module is embedded in its parent Module file. .
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 filed module or filed 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 filed 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 "Filed Module", and specify a new filename. Then add that newly saved module to your new model.
(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.
Filed Module
A filed module is a module that is stored in its own file. This has at times been called a linked module.
A filed 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 filed module and re-use this module in other models. When a module links to a filed module, then changes made within the filed module are inherited by all models that use the filed module (the changes take effect the next time the model is re-loaded).
Filed modules are also useful for collaborately building models. Each model builder can take ownership of one filed module. Typically you'll include a model wrapper that everyone has a copy of containing all of the filed modules. When anyone updates their module, everyone automatically obtains those changes the next time the load or re-load the model. Filed module files also work nicely with source control systems (such as VSS or SubVersion).
Filed module files do not include system variable settings or preferences. Thus, adding a filed module to your existing model will not reset system variables Time, Run, SampleSize, your Preference Settings, etc.
When you use a previously saved filed 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 filed module, you can add it again and select Merge.
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.
The key functional distinction of a library, compared to a plain module, is that any library module in a model appears in the Definition Menu and in the Object Finder, below the system function libraries. This makes it easy to find and use user-defined Functions (and other Objects) in Definitions. (Note: An empty library will not appear in the Definition menu.)
Filed Library
A filed library is a library located in its own file. It has at times also been called a linked library. It inherits both the properties of a filed module and the properties of a library. A filed libraries is a common way to share custom User-Defined Functions between models. Analytica provides about a dozen filed 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 user inputs and outputs). Any module can contain inputs and outputs, and a form is not limited to these. The only difference between a Form and a Module is that you can add a User Input node into a Form simply by drawing an arrow from a Form Node to the corresponding Variable node; and you can add a User Output node simply by drawing an arrow from a Variable node to the Form node. (You can also add User Input and Output nodes into any type of Module, including a Form node, simply by selecting a node and selection Make User Input or Make User Output from the Object menu. You can move any kind of node, including User Input and User Output nodes simply by dragging the nodes from one module to another (including a Form node).
Sharing Filed 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:
- Open M1 up.
- In Edit mode, select Add module... from the File menu, and select model M2.
- 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:
- Open M2 and move the parts of M2 you would like to copy into a module.
- 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.
- 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. :
- 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 filed modules) are models (or filed 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.
History
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 filed modules) are obfuscated and/or browse-locked. In Analytica 4.2, obfuscation and browse-locking are applied on a filed-module-by-filed-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 filed modules, described in more detail at Obfuscated and Browse-Only Models.
See Also
- Tutorial: Creating a module
- Using Add Module... to import a Model file
- Import a module or library
- Obfuscated and Browse-Only Models
- Making a browse-only model and hiding definitions
- Filed modules and libraries
- Working with Models, Modules, and Files in ADE
- Combining models into an integrated model
- Analytica Libraries and Templates
- Example Models and Libraries
Enable comment auto-refresher