Modeling with Catacomb 3

A model Catacomb 3 is a structured document containing text and tables. The table contain parameter values, text and other tables. The individual values can be numbers, selections from a list of named options, or references to other models.

The structure that document takes (the types and labels for entries in the tables) is set by a framework that sets out what is possible for the particular class of model under construction. The framework also contains extra information about table entries. For example, it says what the units are for numeric quantities and what type of sub-table is appropriate in a particular place. Catacomb 3 allows you to edit models using existing frameworks and also to define new frameworks.

There are three ways that tables are presented in the user interface: they can be summarized as a page of text; they can be presented as a form to fill in the field values; or they can be shown as a combination of a diagram with a set of smaller forms for the separate components. Any table can be shown in any form - which one is best depends on the framework of the model.

When defining frameworks there are shortcuts built in that make Catacomb 3 particularly suitable for building models that can be represented as assemblies where the nodes can be connected to each other in a variety of configurations. Each node is a table and the framework defines plugs and sockets that go with the table. Building a model involves joining up nodes by connecting the plugs on one node to matching sockets on other nodes.

This document gives an overview of the main model building interfaces nd then briefly discusses the component building process. The latter is covered in more detail in Components.

Model building interface

The images shows the main windows in Catacomb. Clicking an image opens the full-sized version in a new browser window.

The areas are numbered as follows:

1 Model chooser - each model has its own file. These can be organized into folders however you choose. Although there are different files, a model can access any of the other models in the workspace.
2 Model structure browser - the internal structure of the selected model. You can expand the tree and select just a part of the model to examine, or you can edit the whole model in a single page.
3 Model display - when viewing a model this shows the parameters and their values and any tables or sets of subcomponents in the model.
4 Tabular editor - if you switch the model display into "edit" mode (instead of "view") then the parameters of the model can be changed by filling in the table entries.
5 Graphical editor - for many models, it is simpler to view them as diagrams, instead of as tables. Here you can add subcomponents, connect components together and set parameters. The side panel gives a tabular view of the selected component.
6 Information area - you can right-click on almost anything in the user interface to find out what it does. The information is displayed here. Any descriptive information entered by model designers is also shown here when you select a model.
7 Message area - reports what the system is doing and any problems with the current model.
8 Run controller - shows any calculations that are associated with the current model. You can pause and resume long calculations, and can even run several calculations at the same time.
9 Results - A few predefined views of the data generated by a calculation are normally provided. By selecting the "view composer" tab you can design views using any of the data recorded from the calculation.

Main window, viewing

Main window, editing

Running a model

Attaching probes to a cell

There are a lot of other dialogs and but these are the main ones for building and running models. You can find information about any component by right-clicking on it or using the help menu.

Assemblies - plugs and sockets

Assemblies are collections of components connected together. Unlike Catacomb 2, there are no special components that act as links. Instead, any component can have sockets for receiving connections and plugs for making connections to other nodes.

In this scheme, a simple link such as a wire is represented as a component with two plugs (for the two ends of the link) and no sockets.

Assembly editor

Component design interface

The model building interface described above is for making models using pre-defined components. For example, there is a pre-defined ion channel framework within which you can build models for a whole variety of different ion channels.

But if you want to define a framework for a new class of models, then you need the model design interface. This is accessed by switching to the "components" tab (top left) and is shown on the right.

The first thing about the component interafce is that it looks a lot like the model building interface. Designing a new component is very much like building a model, except that only certain built-in items can be put into a component. These are:

Text - the first items of any model or framework are always a short one-line tag for summarising what it is and then a longer description. These do not affect any calculations, but without them the framework is unlikely to be much use.
Fields - slots where the model builder will insert a value. They can be numbers, true-false values, items selected from a list or references to other models.
Tables - a another component of a different type.
Sets - the model builder can insert several tables of the same type.
Quantified Lists - quantities of other items, as in a recipe. When a quantified list is presented for model building you see all the models of the corresponding type in the workspace and can specify how much of each you want. A typical application is in channel densities on a cell: you can specify a mixture of channels as a quantified list where the quantities are the densities of each channel type.
Sockets - access points for connections from other components.
Plugs - access points to connect to other components.
Icon - the icon to use for the component in diagrams.

Components panel

Component as an assembly