Getting started with Morpheus

So, you want to understand how cells or tissues behave? You think a computational model may be the right way to explore your questions and hypotheses. And you feel Morpheus may be the tool to help you do this?

To help you decide, in this post, we’ll take a first glance at Morpheus. In particular, we will take a look at the user interface and run some example models.

Have a look around

After downloading and opening Morpheus, you’ll see the model construction interface:

Model construction interface

From left to right, we see the Models where you see all the opened models and their main sections. Below, you have the Job archive where you can see the progress of running simulations and browse through all simulation results. In the middle, we have the Editor where you’ll spend most of your time adding and removing model elements, which are listed in the Plugins panel to the right. Next to that, in the Attributes panel you can enter parameter values and mathematical expressions using the Symbols listed below. In addition, we see the context-sensitive Documentation panel that shows the description of the currently selected model component.

When you start a simulation by pressing the Start button in the top menu, you’ll switch to the simulation interface:

Simulation interface

Now, in the middle, you’ll see the Simulation output with e.g. the simulation schedule, current time and performance stats. The Output file browser above shows the simulation output files, i.e. csv files, plots, images, etc. If you select a text or image file, it will open in the Preview panel to the right.

With the Tools above, you can open the folder in a file browser or terminal, or create a movie from a sequence of output images.

Try the examples

To explore the potential and modeling features, probably the best is to learn by example. Morpheus comes with a range of fully functional example models showcasing a number of model formalism and modeling features. You can open these models from the Example menu:

Use the Examples menu try out some models

There are models showing ordinary differential equations as well as reaction-diffusion systems in 1D, 2D and 3D and cell-based simulations with the cellular Potts model. Moreover, there are several multi-scale models in which the above models are combined and some other miscellaneous models.

Some example models provided with Morpheus

We recommend that you have try out a few models, change parameters, add or remove some things, change the visualization, etc. to get a feel of what modeling with Morpheus is like.

At least, check out these ones

We suggest that you at least take a look at the following three basic models. Run them, look at how the models are defined. And take the chance to change some parameters and see what happens.

ODE PredatorPrey

This model implements an extension of the well-known Lotka-Volterra system.

Output of ODE/PredatorPrey.xml example model

If you look at the model itself, you’ll see that it first specifies the Space and Time of a simulation, here defined as a single lattice site and 5000 arbitrary time units (atu). In Global (see figure below), two Variables for predator and prey densities are set up. The differential equations themselves are specified in a System which consists of a number of Constants and three DiffEqn, differential equations, and are computed using the runge-kutta solver.

Global section of ODE/PredatorPrey.xml

Output in terms of a text file as well as a plot is created by a Logger plugin in the Analysis section.

Try: Bring the system into a stable steady state (fixed point, no oscillations) by changing parameters in Global/System/Constant.

PDE ActivatorInhibitor

This is the classic Gierer-Meinhardt model of pattern formation.

Output of PDE/ActivatorInhibitor_2D.xml example model

In Space, it sets up a square lattice of 150x150 with periodic boundary conditions. The model itself is defined in the Global section where two diffusive Fields are created. The reaction step of the reaction-diffusion is specified in a System containing Constants and DiffEqns.

Global section of PDE/ActivatorInhibitor_2D.xml

The plot above is created using the Gnuplotter plugin in the Analysis section, showing the concentrations of the two interacting species.

Try: Change the diffusion coefficients in Global/Field/Diffusion to get finer patterns or no patterning at all.

CPM CellSorting

This reproduces the first cellular Potts model that Graner and Glazier used to study cell sorting model based on the differential adhesion hypothesis.

Output of CPM/CellSorting_2D.xml example model. Cells are color-coded based on their `CellType` (left), number of neighbors of different type (center) and length of boundary to cells of other type (right).

Apart from specifying Space and Time, it specified a number of CellTypes that have a VolumeConstraint to regulate the size of the cells (the rest is only track the cell-cell boundary lengths).

In the CPM section, the Interaction energies are specified that control the “adhesion” between cells of different cell types (note: smaller energy = larger adhesion). CPM-specific parameters such as the temperature of the MetropolisKinetics are also set here. To specify the spatial arrangement of cells in the lattice, in CellPopulations two Populations are specified. These are initialized randomly in a circle using the InitCircle plugin.

A Gnuplotter is set up to visualize cells and a Logger is used to log and plot the boundary lengths.

Try: Get the cells to mix, such that a pattern of alternating red and green cells emerges, by changing the interaction energies in CPM/Interaction.

Wrapping up

You may have noticed some similarities and differences among these three models.

Clearly, each model defined the Space and Time of a simulation – even the non-spatial predator-prey model. These sections are indeed required. The Analysis section is not obligatory, yet all models use it because a simulation without any output does not make sense.

Other sections such as CellTypes and CPM are optional and only appear when necessary. These are only used in the CPM example and do not appear in the ODE and PDE examples. Note that you could also have a model with cell specified in CellTypes but without using a cellular Potts model and therefore no optional CPM section (e.g. see ODE/LateralSignalling.xml).

The models above also show some useful ways to generate output from the simulations using the flexible Logger and Gnuplotter plugins.

Behind the scenes

Morpheus encodes models in its own XML format, MorpheusML. Although you don’t need to read or write XML when using Morpheus, it is good to look behind the scenes once in a while.

To see the XML of a model, right-click on the model name and select Show XML:

Show XML of a model

If we do this for the predator-prey model above (omitting Analysis), we see that it pretty directly reflects the model as it appears in the model construction interface. It also shows that model descriptions in Morpheus are rather concise and straightforward:

<MorpheusModel version="3">
    <Space>
        <!-- set up simulation domain -->
        <Lattice class="linear">
            <Size symbol="size" value="1, 0, 0"/>
        </Lattice>
    </Space>
    <Time>
        <!-- set up simulation time -->
        <StartTime value="0"/>
        <StopTime  value="5000"/>
    </Time>
    <Global>
        <!-- declare variables and initial values -->
        <Variable symbol="N" value="0.1" name="prey"/> 
        <Variable symbol="P" value="0.5" name="predator"/>
        <System solver="runge-kutta" time-step="0.1">
            <!-- define constants -->
            <Constant symbol="a" value="0.5"  name="halftime"/>
            <Constant symbol="r" value="0.1"  name="growth rate"/>
            <Constant symbol="c" value="0.1"  name="consumption rate"/>
            <Constant symbol="b" value="0.05" name="conversion rate"/>
            <Constant symbol="m" value="0.01" name="mortality rate"/>
            <Constant symbol="K" value="0.8"  name="carrying capacity"/>
            <!-- define the model equations: dN/dt and dP/dt -->
            <DiffEqn  symbol-ref="N"> 
                <Expression> r*N*(1-N/K) - c*N / (a+N)*P </Expression>
            </DiffEqn>
            <DiffEqn  symbol-ref="P"> 
                <Expression> b*N / (a+N)*P - m*P </Expression>
            </DiffEqn>
        </System>
    </Global>
</MorpheusModel>

You can immediately forget about this. In practice, you won’t deal with this XML.

That’s it, for now

I hope you enjoyed your first encounter with Morpheus and that you are now at ease with the user interface and you have tried out and changed some of the basic example models. Hopefully, you got to see a glimpse of what is possible with Morpheus. If you are still here, then perhaps Morpheus is the right tool for you. But there are still a few things to cover before you can start creating models from scratch.

What’s next?

Next time, we will look in model detail at:

In posts to follow, we will also explore:

  • batch processing and parameter sweeps

  • multithreading and parallel computing

  • symbols, and math expressions

  • lexical and spatial scoping

  • computational graphs and automatic scheduling

comments powered by Disqus