4. Getting started
Prev   Next

4. Getting started

This section shows how to get started using a simple example model. The section will walk the user through the main functionalities available in the Simmune Modeler software. Some more realistic examples are provided in the example section.

  1. Start the "Simmune Modeler".

  2. Creating a new model.

    Click the "Model" menu and then select the "New" menu. A file dialog asks the user to enter the name of the new model file.

    Click the "Save" button and the modeler application will add a suffix ".dbf" as default to the new model file. The "Model Summary" page will appear and show the current (empty) model.

  3. Creating a molecule.

    Click the "Molecule" in the tool bar and the click "New" button at the top left of the window.

  4. Adding a molecule component.

    Click the "Add Component" button in the "Molecule Composition" window section to add a new molecule component. A message window permits to customize the width and the height of the new component. Click the "OK" button.

  5. Molecule editing window section after the molecule component has been added.

  6. Adding binding sites.

    Select "Molecule Component 1" in the tree view of "Molecule Composition" window section and then click the "Add Binding Site" Button to add a binding site to the molecule component. Repeat this process for 2 more times. A total of 3 binding sites have been added so far.

  7. Changing the molecule color.

    Click the "Molecule Color" button to change the color of the whole molecule, including the molecule component and the binding sites. Select a color of your choice and click the "OK" button.

  8. Adding molecule component state tags.

    Select "Molecule component 1" in the tree view of the "Molecule Composition" window section or by clicking on it in the molecule display. Then, click the "Add/Modify/Remove" button in the line of "States" in the window section "Properties of Molecule Component".

  9. Adding a new molecule component state tag.

    Type "s1" in the text field next to "New Tag" and click the "Add" Button.

  10. Select/change the color of the new molecule component state tag.

    Note

    In models in which a molecular component can assume multiple different states, for instance Tyrosine / Threonine phosphorylations etc., the use of multiple colors for the different states facilitates identifying the various possible combinations in the Modeler interface.

    The message window allows choosing a color for the new state tag. Click "Yes" and pick a color

    Click the "OK" button after selecting the color.

  11. Finish adding molecule component states. Click the "Done" button.

    Click the "Done" button.

  12. Save the new molecule.

    Assign a molecule name: click the"Molecule" item in the tree view window section of "Molecule Composition", enter the short name for the molecule as "A" in the window section "Properties of Molecule".

    To save the molecule: click the "Save" button. The modeler automatically assigns the molecule component with default name "A_component_1" and the binding sites with default names "A_site_1", "A_site_2" and "A_site_3" repectively.

    Note

    From version 2.1.0, the modeler has the default function to create the single molecule complex species at the time of saving a new molecule. There is a warning message at the bottom of the "Molecule Composition" window section showing "Related items found, can NOT add/remove" because the newly added molecule interaction is related to the current molecule "A". A button "Related Item(s)" also appears. Removing or adding structural properties to the molecule is disabled to prevent the creation of inconsistent models. This function may be disabled in the "Preferences" window.

  13. Creating molecule interactions

    Note

    Interactions between molecular binding sites can be defined before they are used to create multi-molecular complexes or they can be defined during the process of connecting molecular complexes through associations. Assigning interactions using the full molecule interface as shown here can add a layer of control to the definition of your model. During the process of connecting molecular complexes through associations between molecular binding sites the modeler application will create new binding possibilities for pairs of binding sites that did not yet have them, after asking the user to confirm the new binding possibilities.

    Click the "New" button at the top right of the "Molecule Interactions" window. Molecule "A" will be displayed in the molecule interaction editing window section.

  14. Add a partner molecule to define a molecule interaction.

    Double click molecule "A" in the "Molecule List" window section on the left. A second molecule "A" is added.

  15. Add binding site interaction and save.

    In the graphics layout editing window section, draw a line between the binding site "2" of the left molecule and the binding site "1" of the right molecule. The information about the interacting binding sites will be automatically loaded into the fields on the top right. Define a name for the association or just click "Save".

  16. Back to the molecule editing window.

    Click "Back" button to make the application return to the molecule window for molecule "A". The new molecule interaction "[A].[A]-interaction" appears in the list at the right side of the window.

  17. Go to the complex species editing window.

    Click the "Complex" menu at the top menu bar to go to the complex species editing window. The complex species "A" appears in the left "Complex List" side window section.

  18. Viewing a complex species.

    Double click "Species A" and load it in the complex species editing window.

    Note

    The single molecule complex species saved in the process of saving a new molecule has the same name as the molecule. One exception is that the complex default name is its internal ID such as "cps-00001" when the molecule has its internal ID such as "mol-00001" as the molecule name. The user can change the name later.

  19. Creating a new complex.

    Note

    The modeler application distinguishes between Complex Species and Complexes. A Complex Species is defined by the molecules and the bonds between them. However, the components of the molecules may exist in a variety of different possible states. By defining what the values of the states of the molecular components of a Complex Species are one defines one particular "version" of the Complex Species. This particular version is called a Complex. Thus, all Complexes of a common Complex Species have the same molecular components and the same binding structure but they differ with regard to the states of the components. Note that state tags can have the value "don't care" meaning that the Complex containing such a tag effectively stands for a group (or class) of Complexes.

    Click the "New" button in the right "Relations" side window section. The user will be prompted to select what should be created for the complex species (complex, transformation or association).

  20. Got to the complex editing window.

    Choose "Create/Edit Complex" if not selected. Click the "Go" button to create a new complex. The complex species "A" will be loaded into the complex editing window with all molecule component state set to "Off" and all "free" binding site (not involved in any binding within the complex) to "Unbound". In the graphical display of the complex the unbound binding sites are indicated as empty circles.

    Note

    The graphical displays for tags in complexes and others (complex species, molecule, etc) are different. See the detailed explanantion in section "tag".

  21. Change a molecule component state and save the complex.

    Click "Off" molecule component state in the tree view and select "On" from a dropdown menu. Alternatively, you can right-click the state tag and select the state on. Click the "Save" button and the complex is saved with its default name "A_1".

    Note

    The complex default name automatically generated by the modeler is in the format "[complex species name]_[number]" (without square brackets). The "number" will be the a smallest integer to make the name unique. In our example, the complex species is "A" and the default name for its first complex is "A_1".

  22. Creating a transformation.

    Click the "New" button in the right "Relations" side window section to define a transformation rule for complex "A_1". A window with a selection menu appears. Choose "Create/Edit Transformation" if not already selected.

  23. Editing the properties of the new transformation.

    Click the "Go" button.

    A transformation editing window is opened with the complex "A_1" as the "Source Complex", which should have an "On" for the state tag "s1" of its only molecule component.

    The "Result Complex" should have a default "Don't Care" molecule component. Change it to "Off". Click the "Save Complex" button for the "Result Complex" with the default name "A_2.

    Define the transformation rate as "1" and click the "Save" button at the top.

    Note

    The binding statuses are not displayed in the tree view of the "Result Complex". The "Result Complex" has the same binding statuses as the "Source Complex".

    The default name for a transformation is in the format "[source complex name]-transformation(.[number])" (without square brackets and parentheses). The part in the parentheses is optional to generate a unique transformation name.

  24. Go back to the complex editing window.

    Click the "Back" button.

  25. Go back to the complex species editing window.

    Click the "Back" button.

    A note "Related Items found, can NOT add/remove" will appear because related complexes and the transformation exist. They are shown in the "Relations" side window section at the right.

  26. Creating a complex association.

    Click the "New" button within the "Relations" side window section. Choose "Create/Edit Association".

  27. Go to the complex association editing window.

    Click the "Go" button. The complex species "A" is loaded as the first complex with the default "Don't Care" molecule component state and binding status. Don't care binding site statuses are indicated graphically by circles filled with the molecule color and outlined with a dotted line.

  28. Add the partner complex.

    Double click "Species: A" in the left "Add Complex" side window and the complex species "A" is loaded as the second complex with default "Don't Care" molecule component state and binding status.

  29. Create the binding site interaction for the association.

    Draw a line between the binding site "2" of the first complex (left) and the binding site "1" of the second complex (right).

    The "Result Complex" window section at the bottom-right highlights the "Define Result Complex Species" button because this interaction results in a new complex species that has to be specified.

    Save the source complexes "A_3" and "A_4" by clicking the "Save Complex" buttons in the sections "Source Complex 1" and "Source Complex 2".

  30. Go to the complex species editing window to create a new result complex species

    Click the "Define Result Complex Species" button. The application shows the complex species editing window with the 2 binding sites highlighted.

    Note

    The 2 binding sites are always highlighted to indicate which pair of binding sites should be used to make a new complex species. The modeler does not allow to create a new complex species with binding sites other than these two highlighted binding sites since these were selected for the association defined in the previous window.

  31. Edit the graphical layout of the new result complex species.

    Move and change the layout so that the two highlighted binding sites contact each other.

  32. Create a new result complex.

    Click the "Save and Back" button. The new result complex species "A.A" is loaded with molecule component states and binding statues consistent with the source complexes and with the binding sites used for the new association listed as bound. Click the "Save Complex" button to save the result complex with the default name A.A_1.

  33. Set association rate and save.

    Set the "Assoc Rate" as "1" and leave the unit selection as "3D". Click the "Save" button at the top-right with the default name "[A_3].[A_4]-association".

  34. Back to the complex species editing window.

    Click the "Back" button. The modeler application returns to the complex species editing window. The right "Relations" side window section is updated with the newly created complexes "A_3" and "A_4" as well as association rule "[A_3].[A_4]-association".

  35. Load a complex species to define a dissociation.

    Double click the complex species "A.A".

  36. How to create a dissociation.

    Click the "New" button in the "Relations" section to the right. Select "Create/Edit Dissociation".

  37. Go to the dissociation editing window.

    Click the "Go" button. The application displays the "Complex Dissociation" editing window.

  38. Select a binding interaction within the source complex to split.

    In the "Source Complex" window, clicke the "Save Complex" button to save a new complex with default name "A.A_2". Select "bst-000001 -- bst-000002" from a dropdown menu with the title "Select Binding Site Interaction to Split". Click the "Split" button on its right. The two result complexes are loaded with default molecule component states and the "Split" button turns into a "Reset" button.

  39. Set the dissociation rate and save.

    Enter the "Dissoc Rate" as "1". Click the "Save" button with the default name "[A.A_1]-dissociation".

  40. Back to the complex species editing window.

    Click the "Back" button. The newly created dissociation rule appears in the updated "Relations" window section to the right.

  41. Creating a "ring" tetramer.

    To illustrate the use of tools that permit users to specify mappings between the molecules of complexes undergoing transformations we will now build a tetramer with four A molecules.

    Click the "New" button in the middle of the complex species editing window. Double click the molecule "A" to add it to the current complex. Adjust the layout of the molecule "A" by using the "Rotate +90o", "Rotate -90o" and/or "Flip" buttons.

  42. Add the second molecule to the complex species.

    Double click the second molecule "A" in the molecule list at the left of the window. Click the "Rotate +90o", "Rotate -90o" and/or "Flip" buttons until achieving a layout similar to the one shown in the screenshot below.

  43. Bind molecules and confirm the new binding interaction.

    Move molecule(s) to make the binding site "1" in the both molecules to contact. A message window asks the user to confirm the new binding interaction.

    Note: The interaction between two binding sites with index 1 had not been defined at the molecular level (unlike the 1-2 interaction). We can nevertheless use such an interaction for the definition of a multi-molecular complex but have to confirm that we want to to add the 1-1 interaction to the binding possibilities of molecule A. Prompting users for confirmation may prevent users from inadvertently using binding sites they had not intended to mediate interactions.

    Click the "Yes" button.

  44. Add the 3rd and 4th molecule.

    Repeat the similar process to add 2 more molecules. Change the layout until obtaining a "ring" structure complex species as below. Specify its name as "A.A.A.A.ring" and click the "Save" button.

  45. Create an open tetramer complex species.

    Similar to the "close" complex above, create an "A.A.A.A.open" complex species as shown below.

    Note

    The user could alternatively simply "Create A Copy" from "A.A.A.A.ring" complex species and then delete one binding site interaction to create an "open" complex.

  46. Creating a transformation between equivalent complexes.

    Load the ring tetramer complex species by double clicking it in the complexes list.

    Click the "New" button in the right "Relations" side window section. Select "Create/Edit Transformation".

  47. Select a complex species from a list of equivalent complex species.

    Click the "Go" button. A new message window will display candidate transformation complexes. Select the first complex "A.A.A.A.open" and click the "OK" button.

  48. Define complexes if not yet defined.

    The complex species A.A.A.A.ring" is loaded into the "Source Complex" window section and the complex "A.A.A.A.open" is loaded into the "Result Complex" with default "Don't Care". Save both "Source" and "Result" complexes by clicking "Save Complex" buttons respectively.

  49. Define the molecule mapping relationship.

    Note

    Transformations can be defined between any pair of equivalent complexes. Sometimes, it is necessary to specify exactly which molecules within a complex correspond to each other in the Start- and Result complex. For example, the molecules (2) and (4) below might (in a more complicated model than this) experience state changes as a result of the transformation that, here, creates an internal bond in the complex.

    Check the "Molecule Mapping" checkbox to show the molecule mapping relationship of this transformation. Change the molecule layout mapping by using the "<" and/or ">" buttons.

    Note

    The index displayed in your application may not be the exactly same as shown here. This is ok as long as you obtain the mapping you expect to have.

  50. Define the transformation rate and save

    Enter the "Transformation Rate" as "1". Click the "Save" button.

  51. Back to the model summary page.

    Click the "Model" menu in the menu bar at the top. The summary of the newly created model is listed in the model summary window.

    For detailed descriptions of the functionalities of individual windows of the modeler application, please refer the corresponding sections in this manual.

  52. Export model to SBML and/or ODEs.

    From the model menu, select "Export Simmune Model..."

  53. Set seed complexes.

    Note: To export a model as a set of reactions described in a SBML file one has to specify which complexes of the model will be used to generate the network of interacting complexes. Based on the interactions between these seed complexes, the network generator in simmune will determine which complexes result from the interactions and what the rates are for the reactions between them.

    select all complexes in the list and give all values as 1.

  54. Export SBML.

    Click "Export SBML" button and go to the window to show the SBML in a clipboard. The user can select which versionof SBML the exported network should be compatible with (2.1, 2.4 or 3.1). The output can be copied to the system clipboard or saved to a file.

  55. Export ODEs.

    Click the "Back" buton and click the "Export ODEs" button.

Prev   Next
3. Conventions and concepts applied in the Simmune Modeler Home 5. Using the modeler application and managing models.