Ready Reference Manual

GFtbox For modelling the growth of shapes.
Details: what? How? Where?
Tutorials: from the beginning
Examples: from publications
Download from SourceForge

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), ti (tilt), D.
• Tick Clip and select the region to hide by using morphogen values (click on Mgens button).

Snapshots

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 to VRML, OBJ, and FIG format

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.
• 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. This is the only format that saves the entire mesh structure; the other formats save only the current graphical representation.

Movies

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. For recent versions of Matlab (2010 and later) we recommend the Motion JPEG AVI format. You only need to select this option once, and it will apply to all subsequently created movies.

• 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 on the Matlab command path.
• 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.

Web and PowerPoint

Writing web and PowerPoint pages is facilitated by:

• Output .avi for PowerPoint. Use Movie:Codec: Motion JPEG avi. This does not play properly on PowerPoint 2007 unless you run PowerPoint in 2003 compatibility mode. The movie is saved into the project movies subdirectory together with an image (.png) of the final frame and a copy of the interaction function (renamed .txt - to document the results).
• Output flash (.flv) movies for web. Select Movie:Convert to Flash. This option requires the ffmpeg program to be on the current path. The movie is saved to the project directory together with an image (.png) of the first frame (for last frame see above).
• Output web compatible copy of the interaction function use webify_interaction_function.m which outputs a txt file with comments marked up in HTML to appear in green and sections in blue.

Useful interaction function programming constructs

Types of morphogens and factors click here

Pre-defined variables

dt computational step size realtime virtual time of the model

Pre-defined functions

Steps(m) current step number in Mesh m pro(k,id) promote by k in regions designated by factor, id (pro(k,x)=1+kx, i.e. promote by k=0 and the value of pro() is 1). inh(k,id) inhibit by k in regions designated by factor, id (inh(k,x)=1/(1+kx), i.e. inhibit by k=0 and the value of inh() is 1). local_setproperties( m ) initialise Mesh properties leaf_*( m, ... ) A large library of functions for manipulating the Mesh data structure, m. All of them are listed in the main Help menu of the GFtbox GUI, both in alphabetical order and categorised by topic.

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,y coordinates that are less than -0.05 and greater than 0.03 respectively

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