Modules - giffordlabcvr/Parvovirus-GLUE GitHub Wiki

• What are modules?
• Creating, querying and deleting modules
• Module command mode
• Managing module configuration
• Associated resources

The GLUE module system attempts to strike a balance between built-in functionality provided by the GLUE engine and functionality which is configured specifically for an individual GLUE project.

GLUE's module types contain a significant part of the functional value of GLUE. Across all module types, different kinds of operations can be performed. For example, reading and processing data within a project, from the file system or from a web request, creating new data objects within the project, generating reports in tabular or other formats, or writing data to the file system.

In order to actually use the functionality, a Module must be first created within a project. Modules are themselves data objects, like Alignments or Sequences. They are stored in the database and there are commands to create, update, query and delete them.

Each module has a name and is of a specific module type. A Module object also contains an XML configuration document. XML is a text format for structured data (if XML is unfamiliar to you, try reading this basic introduction). The Module, including its configuration document, is stored in the GLUE database like any other project data object. The document configures the operation of the functionality of the Module, for example providing numeric paramater settings or rules for the Module to work with. In this way, built-in GLUE functionality may be used in slightly different ways from one project to another, or indeed within one project.

Modules are created using the create module command. Conventionally, there is a step in the project build which will create all the modules required in the project. For simple cases, a Module can be created simply by specifying the module type:

Mode path: /
GLUE> project example
OK
Mode path: /project/example
GLUE> create module --moduleType fastaUtility
OK
(1 Module created)

More commonly, a module is created by specifying an XML file containing the configuration document for the module. For example, within the exampleModules.glue file you will find this line:

create module --fileName modules/exampleRaxmlPhylogenyGenerator.xml

This references a file containing the XML configuration document shown below. Note that the root element name of the configuration document specifies the module type, in this case raxmlPhylogenyGenerator . A couple of settings are configured, setting the substitution model to GTRGAMMAI and the number of bootstrap replicates to 1000.

<raxmlPhylogenyGenerator>
	<raxmlPhylogenyRunner>
		<substitutionModel>GTRGAMMAI</substitutionModel>
		<bootstrapReplicates>1000</bootstrapReplicates>
	</raxmlPhylogenyRunner>
</raxmlPhylogenyGenerator>

Each module has a name, which is its unique identifier within a project. A project may contain multiple modules of the same type, with different names. You can optionally specify a name when executing the create module command, if you do not, the command will form a name based on the module type or the XML file's name. You can use the list module command to list the names and types of project modules. You can delete modules using the delete module command, typically specifying the module to delete by name.

Similar to other GLUE data objects, when a Module is created, a command mode associated with it becomes available. You can navigate from project mode to the module's command mode using the module command, supplying the module's name.

Within module command mode, there is a set of generic commands available to manage the configuration document of the module. Additionally, many (but not all) module types provide their specific functionality in the form of commands within their command mode. So in these cases there are module-type-specific commands available within the command mode, as well as the generic commands.

For example, in the example project there is a module 'exampleGenbankXmlPopulator' of type genbankXmlPopulator . If you navigate into the command mode for this module, you will see that the populate command is available. This command is specific to the genbankXmlPopulator module type.

Some functionality within module types is not provided by module mode commands. Instead the module name is supplied to some other GLUE module or command and the functionality is then used internally. An example would be the freemarkerObjectRenderer module type: it does not provide any module-type-specific commands, instead the name of a module of this type can be passed for example to the render-object command, in Sequence mode.

Part of developing GLUE projects is concerned with developing module configuration. As a GLUE project developer, you often want to make a small change to a module configuration document, see the effect of the change on the module's operation, make another small change, and so on. So managing module configuration is an important part of this process.

You can use the show configuration command in module mode to display the Module's current XML configuration document on the console. If you created the module by loading its configuration from a file, this document will be the same as the document in the file. However even if you created the document by simply specifying the module type, there is still a (simple) configuration document associated with it, as this example shows:

GLUE> create module --moduleType fastaProteinAlignmentExporter exporter1
OK
(1 Module created)
Mode path: /project/example
GLUE> module exporter1
OK
Mode path: /project/example/module/exporter1
GLUE> show configuration
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<fastaProteinAlignmentExporter/>
Mode path: /project/example/module/exporter1
GLUE>

As long as a module exists, you can reload its configuration from a file using the load configuration module mode command. So, one way to develop a Module's configuration is to have its XML configuration document file open in a text editor, make a change to this file, then reload it into GLUE and test the effect of the change, e.g. by running a command.

To streamline this process a little, you can manage certain simple properties within a Module 's configuration document using the set property , unset property and show property module mode commands. For example:

Mode path: /project/example/module/exporter1
GLUE> set property idTemplate "${alignment.displayName}/${sequence.sequenceID}"
OK
Mode path: /project/example/module/exporter1
GLUE> show configuration
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<fastaProteinAlignmentExporter>
    <idTemplate>${alignment.displayName}/${sequence.sequenceID}</idTemplate>
</fastaProteinAlignmentExporter>
Mode path: /project/example/module/exporter1
GLUE> show property idTemplate
moduleShowPropertyResult
  propertyPath: idTemplate
  propertyValue: ${alignment.displayName}/${sequence.sequenceID}
Mode path: /project/example/module/exporter1
GLUE> unset property idTemplate
OK
Mode path: /project/example/module/exporter1
GLUE> show configuration
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<fastaProteinAlignmentExporter/>

Mode path: /project/example/module/exporter1
GLUE>

Notice that the idTemplate XML element, which is a child of the fastaProteinAlignmentExporter root XML element, is updated directly within the GLUE database using the set property and unset property commands. If you have modified Module configuration in this way, you may save the XML document back to the file system using the save configuration command.

Certain module types require associated resources . These are additional files, outside the XML connfiguration document but referenced from within it. An example is the ecmaFunctionInvoker module type; its configuration document references one or more JavaScript program files. Another example is the freemarkerObjectRenderer module type which uses a FreeMarker template stored in a separate file.

For these module types, the associated resource is stored in the Module data object along with the XML configuration document. To ensure this is set up correctly, you need to use the --loadResources flag for these module types, both when creating the module from a file, or when reloading its configuration using the load configuration command.