Module Collection

Module Collections are a specific subtype of the general Collection data type that can only contain Module objects. Module Collections are mainly used to limit the application of certain operations and analyses to subsets of modules, but they can also be used to import modules from a file or return results from a module discovery method.

All Module Collections will appear in the "Motifs" panel in MotifLab's GUI, provided that you have selected to display "Module Collections" using the drop-down menu in this panel. You can create new Module Collections by pressing the "+" button in this panel and then selecting "Module Collection" from the appearing menu, or you can go to the "Data" menu in the top menu bar and select "Add New ⇒ Module Collection".

Creating Module Collections

As described in the general section on collections, Module Collections can be created by explicitly listing the names of modules to include, using condititions to select modules based on property values or values in Numeric Maps, or importing module collections from files. In addition, Module Collections can also be based on sequence support in module tracks or be derived from interaction partner annotations in motif objects.

Collections based on module occurrences

Module collections can be based on modules that have a certain sequence support in a module track. By sequence support for a module we mean the number of sequences that contain at least one occurrence of that particular module. For example, one could create a collection with modules that occur in at least 20 sequences or in 80% of all sequences.
In the GUI you can create such collections by selecting "Add New ⇒ Module Collection" from the "Data" menu and then go to the "From Track" tab. First select the module track from the drop-drop down menu at the top, then select the comparator function (=,<,<=,>,>=,<>,in) and target value from the bottom menus. The target value can be an absolute number or a relative percentage number (in which case the value should be between 0 and 100), and the value can either be a literal number or a numeric data object (Numeric Variable or Module Numeric Map).
The general syntax for creating such module collections in protocols is the following:


Examples

Collections based on known TF interactions

Motifs can be annotated with lists of known interaction partners (i.e. other motifs) for the associated TF, which give rise to networks of motifs for interacting factors. This information can be used to derive modules based on TFs with known interactions. For a pair of motifs, A and B, it is sufficient that one of the motifs has an annotated interaction with the other for MotifLab to regard the two motifs as interacting (i.e. a one-way directional connection is regarded as being equal to a bidirectional connection). In the GUI you can create such collections by selecting "Add New ⇒ Module Collection" from the "Data" menu and then go to the "From Interactions" tab to specify a set of arguments controlling how the collection should be created. Note that this process will not only create a module collection object, but also create all the underlying modules in that collection. All the created modules will be unordered.

1) Defining module motifs
The first step in the module creation process is to define the potential module motifs (or meta motifs) that can form the constituent motifs of the modules. This is controlled by the "Group" argument, which can optionally specify a Motif Partition with clusters of motifs that should be considered equivalent to each other (e.g. because they represent the same transcription factor). A module motif (either single motif of cluster) is considered to be interacting with another module motif if at least one of the basic motifs in one of the module motifs are interacting with one of the basic motifs in the other module motif.
If the "Group" argument is left blank, each module motif will correspond directly to a single basic motif. However, if the motifs are grouped with a Motif Partition, each potential module motif will correspond to a cluster of motifs. If the "Group" argument is not used, it is possible to use the "Motifs" argument to specify a smaller collection of motifs to consider for this step. If both "Group" and "Motifs" are defined, the "Group" argument will take precendence and the "Motifs" argument will be ignored.

2) Selecting module configurations
The "Configurations" argument controls how MotifLab should search the motif interactions network to discover modules. To avoid generating an enormous number of modules from transitive interactions, only cliques in the interaction network will be considered. The cliques can be of size 2 or larger.

• Pairwise: The modules will be based on pairs of interacting motifs
• Maximal clique: A maximal clique is a subset of the nodes in the network where every node is connected to every other node in this subset, and the subset cannot be expanded with additional nodes without violating the clique property (i.e. there are no other nodes in the whole network that are connected to all of the nodes in the subset). The figure below shows a network with four maximal cliques highlighted in different colors.
• Maximum clique: A maximum clique is a maximal clique which also has the largest number of nodes in the whole network. There can be several maximum cliques but they must then all have the same size (and no other maximal clique can be bigger). In the figure below, the red maximal clique on the left is also a maximum clique.

3) Limiting module cardinality
If you have selected the "Pairwise" module configuration, all the created modules will have cardinality equal to 2. However, if you have selected the "maximal" or "maximum clique" configurations, the cardinality of the returned modules can be constrained with the "Cardinality limit" option. If this is set to either "at least", "at most" or "exactly", the "Cardinality" argument can specify a number to compare against to constrain the set of returned modules. For example, if "Cardinality limit" is set to "at least" and "Cardinality" to "3", only modules of cardinality 3 or higher will be created.

4) Self-interacting motifs
Some transcription factors can interact with other factors of the same type (homo-dimers), so a motif is also allowed to interact with itself. If the "Include self-interactions" option is selected, MotifLab may potentially create modules that consist of pairs of motifs of the same type, e.g. "M1–M1". However, larger modules than that are not allowed to contain duplicate motifs, so if motif "M1" interacts with itself as well as "M2", the modules "M1–M1" and "M1–M2" may be created but not "M1–M1–M1" and "M1–M1–M2". The algorithm that searches for maximal cliques considers cliques that only contain self-interacting motifs to be of size 1, so if M1 interacts with itself as well as M2 and the "maximum clique" configuration is selected, only the "M1–M2" clique will be returned (since this has cardinality 2 whereas "M1–M1" is considered to be of cardinality 1, which is not maximum). However, the "maximal clique" configuration will return both modules.

5) Limiting module span
The "Width limit" argument can be used to specify an optional size limit on the module (in bp). If "Width limit" is set to "Total width", the value of the associated "Width" argument defines the maximum length of the module. If "Width limit" is set to "Width per motif", then the width property of each module will be set to the value of the "width" argument multiplied by the cardinality of the module. If "Width limit" is set to "No limit", then no width propery is set. For example, if module M1 consists of 2 component motifs and module M2 of 3 component motifs, then if "Width" is set to 200 (bp) and "Width limit" to "Total width", the width limit of both of these modules is set to 200bp. However, if instead "Width limit" is set to "Width per motif", the width limit of module M1 is set to 200x2=400bp, whereas the width limit of module M2 is set to 200x3=600bp.

6) Limiting collection size
If the number of edges in the motif interaction network is large, the number of modules that will be created can potentially be huge. It is possible to limit the size of the returned collection with the "Collection limit" argument. If this is set to a value greater than zero, at most that many modules will be created. The modules are not prioritized in any particular order. In the GUI you can see how many modules MotifLab will create from the motif interactions network with the current argument settings by pressing the "How many modules will be created?" button at the bottom of the dialog. If you consider the number of modules to be too large, you can either set the "Collection limit" to an explicit number or try to limit the number of modules by tweaking the other arguments.

The general syntax for creating module collections from interactions in protocols is the following:


Examples