Ready Reference Manual
GFtbox For modelling the growth of shapes.
Details: what? How? Where?
Tutorials: from the beginning
Examples: from publications
Download from SourceForge
Types of morphogens
Types of morphogens and factors click here
Summary of controls
Roll the mouse over any control and information about the control will pop-up.
Models
- The larger the time step, the fewer iterations will be needed to simulate a given amount of time, but the less accurate the simulation will be. If the time step is too large, diffusion calculations may even become unstable. As a rule of thumb, the time step should be chosen small enough that:
- The product of growth rate and time step is everywhere less than 0.1 -- that is, no part of the mesh grows by more than 10% in a single iteration.
- In a single iteration, no part of the mesh rotates by more than 10 degrees.
- The product of time step and the relative rate of change of any morphogen should be no more than 0.1. The rate of change may derive from the decay rate you have set, or from interactions programmed in the interaction function.
- If k is the diffusion constant of a morphogen, D is the diameter of the mesh, and dt is the time step, k dt^2/D should be no more than 0.1.
- Errors in the interaction function will cause the system to stop, and the interaction function will be disabled. The controls in the Interaction Function panel will all turn red to indicate this.
- To re-enable the interaction function, click the Reset button at the top of the GUI.
- To find the error
- There will be a message on the Matlab console saying in which line of the interaction function it detected an error. Open the interaction function in the Matlab editor, find that line, and set a breakpoint there or shortly before (by clicking in the left margin -- a red dot will appear).
- The next time the interaction function runs, Matlab will suspend execution at the breakpoint and go into debug mode. You can then examine the values of variables and step through the code one line at a time in order to discover why the error is happening.
- Matlab provides extensive tutorials on how to program and there is much information on the web.
Running models
The normally green Run panel turns red whilst the model is running.
A yellow Run panel means that the model is running on a version of the GFtbox that is older than the model itself (look at the interaction header to see our source code version control number for the copy of GFtbox that created the model).
An interaction function error (or any other error) will stop the model from running. It is then necessary to Reset using the Reset key - which will have turned red.
To run a model from the GUI
- Step, execute one step of dt. A whole lot of information pours out at the command console. Sometimes it takes a while to solve the equations. The process is monitored by a series of dots . . . . . . . Further information is provided below the Plotting panel, e.g. Step number, time per iteration, time per finite element, growth, etc.
- Run for, and enter the number of steps into the box.
- Run until, and enter the model time to which you want to run.
- Run to, and enter the multiple of the initial area you want to run to.
- Stop, stops execution at the end of the current step.
- Call, makes a call to the interaction function but does NOT grow. This is useful for checking initial conditions - set patterns of morphogens. Having made a Call to the interaction function it is good practice to then Restart the model before running a model.
- Menu:Stages. We usually run models by setting up a set of, say 5, stages that we want stored. Then, having run the model we can revert back to any of the stages - make a change - and re-run starting from that point. The stages are stored in the project directory with the suffix *000# where # is the time. Stage times are stored with the project - and copied into the daughter project with Save As.
- Compute more stages, pops up a box asking for a set of times that you want stored then starts computing
- Request more stages, does the same but does not start computing.
- Save experiment stages, saves all the current stage files in a subdirectory.
- Import experiment stages, recovers a saved experiment. This pair of commands help document results and make figures. In addition, when the system runs on a cluster, the results are returned as experimental results to be accessed in this way.
- What to do when the running system gets stuck. Usually this is because the shape is too regular and cannot initiate a bulge.
- Interrupt processing using standard Matlab convention - Control-C. Then reset the GFtbox. Panel:Select Tool:Mesh Editor and slightly modify the Z shape a random amount: click Random.
Outputs
Plotting panel
To view
- Specified values, i.e. kapar or a particular morphogen (factor) select from the drop down menu at the top right, and tick the Plot Current Factor checkbox.
- To autoscale the axes, set the checkbox Panel:Plot Options:Auto axis range. To autozoom as well, click Menus:Plot:Auto zoom and centre.
- To autoscale the morphogen colours. Panel:Plot Options:Auto color range. To fix the colour range the easiest is to click From Picture and unclick the Auto color range. Alternatively, unclick the Auto color range box and key in values you want - click elsewhere on the GUI to force a replot.
- To find out the level of a morphogen at a particular point on the canvas. Select Tool:Simulation and select the morphogen of interest (top right pull down) and click on the point of interest. The value at that point will appear in bold just below the Panel:Timescale box.
- Output variables, e.g. growth rate, tick Plot output value and make selection from the two drop down menus.
- thickness, tick/untick Menu:Plot:Thickness.
To show/hide
- thickness, tick/untick Menu:Plot:Thickness.
- mesh, tick/untick FE edges.
- axes, tick/untick Menu:Plot:Show/Hide axes.
- legend, tick/untick Menu:Plot:Show/Hide legend - also Set legend to choose heading.
To set/modify values of morphogens (best done in the interaction function)
- Choose morphogen (list box), Click on Select Tool:Factors, '---' list box to select action and click on appropriate button (Add constant or Add radial, etc).
- at individual nodes (vertices). Choose morphogen (list box), Click on Select Tool:Factors, '---' list box to select action and click on node.
To clip the mesh (hide part of the mesh)
- Tick Clipping plane and choose the plane with Az (azimuth), El (elevation), D (distance from origin).
- Tick Clip and select the region to hide by using morphogen values (click on Mgens button).
Snapshots
Some video drivers do not support OpenGl in which case the screenshot can look wrong. The solution is to select GFtbox:Menus:Plot:Renderer:zbuffer (bottom of Plot menu).
Saved in png format in the project snapshots subdirectory
- Clicking Take snapshot makes a png file copy of the plotting screen. At the same time a copy of the interaction function (relabelled to have .txt as a suffix) is also made - to help document the snapshot.
- Publication quality screenshot is made by changing the action of the Snapshot button using Menu:Misc:Hi-res snapshots and choosing a number of dots per inch.
Exporting meshes for external use
The current mesh can be saved in various formats for use outside GFtbox, using the various Save... commands on the Mesh menu.
- VRML is a standard format for 3D graphics, for which there are free viewers (for example, BS Contact or ParallelGraphics' Cortona 3D Viewer). It is also a format supported by ZCorp's 3D printers. When you export to VRML, after providing a file name you will be presented with a dialog that allows you to rescale the object and also to change its thickness. Changing the thickness is only important for 3D printing, as a physical model will be too fragile if the mesh is too thin.
- OBJ is another standard format for 3D models, and can be imported into most 3D modelling software.
- FIG is the Matlab format for figure files. These files can be reopened in Matlab.
- MAT is Matlab's format for storing arbitrary Matlab objects.
MAT is the only format that saves the entire mesh structure. The other formats save only its current graphical representation.
Movies
Some video drivers do not support OpenGl in which case the screenshot can look wrong. The solution is to select GFtbox:Menus:Plot:Renderer:zbuffer (bottom of Plot menu).
By default, movies are uncompressed, since this is the only format that is sure to play on all machines. However, uncompressed movies can easily be gigabytes in size. Various compressed formats can be selected in the Movie:Codec menu. Several formats are available, although not all of them are supported on all Matlab installations, and where supported, the resulting movies may not play in all movie-playing software. You only need to select a codec once, and it will apply to all subsequently created movies.
- For recent versions of Matlab (2010 and later) we recommend the Motion JPEG AVI format. (Older versions of Matlab do not provide it.)
- Flash movie format cannot be created directly, but there is an option to convert completed movies to Flash automatically, with the menu Movie:Convert to Flash. This option requires the ffmpeg program to be present on the Matlab command path.
Conversion from .avi to .flv is achieved with the help of
MakeVideosAndFLV.m
- Click Record Movie to start creating a movie. The current picture of the mesh will be the first frame of the movie. The button will change to Stop Movie. Every time a simulation step is performed, the picture of the mesh will be added to the movie file. Click Stop Movie to stop recording and close the movie file. The movie file will also be automatically closed if you close the project, load a new project, or close GFtbox. When the movie file is closed, the final frame will also be stored as a PNG image file, as well as a copy of the interaction function (with extension .txt instead of .m).
- By default, the name of the movie file is chosen automatically, and consists of the project name followed by a numerical suffix. If you turn off the Auto-name checkbox below the Record Movie button, you will be prompted to given the movie a name. Movies (and the associated snapshots and interaction functions) are stored in a "movies" subdirectory of the project directory.
Useful interaction function programming constructs
Types of morphogens and factors click here
| Pre-defined variables |
| ||||||||||
| Pre-defined functions |
|
The patterns of morphogens A and B are often set up by using logical indexing, e.g.
id_a_p(m.nodes(:,1) < -0.03) = 1;
id_b_p(m.nodes(:,2) < -0.01) = 1;
where id_a_p is the vector of values of the A morphogen. m.node(:,1) refers to the x coordinates of all nodes (vertices) in the mesh.
The expression (m.nodes(:,1) < -0.03) means find all vertices with x coordinates that are less than -0.03.
Similarly, (m.nodes(:,2) < -0.01) means find all vertices with y coordinates that are less than -0.01.
And the pattern of polariser (P) is set up by
P((m.nodes(:,1) < -0.05) & (m.nodes(:,2) > 0.03)) = 1;
Where (m.nodes(:,1) < -0.05) & (m.nodes(:,2) > 0.03) means find all vertices with x coordinate less than -0.05 and y coordinate greater than 0.03.
Thus the full code describing the model is:
if (Steps(m)==0) && m.globalDynamicProps.doinit % Initialisation code.
id_a_p(m.nodes(:,1) < -0.03) = 1; % setup region for A where identity factor A is represented by id_a_p
id_b_p(m.nodes(:,2) < -0.01) = 1; % setup region for B
else
% @@KRN Growth Regulatory Network
kapar_p(:) = id_a_l .* inh(1,id_b_l); % growth rate
kaper_p(:) = kapar_p; % isotropic growth
kbpar_p(:) = kapar_p; % same on both sides of the sheet
kbper_p(:) = kapar_p; % same
knor_p(:) = 0; % thickness not growing
end