Ready Reference Manual

Summary of controls

Roll the mouse over any control and information about the control will pop-up.

Models

• As a rule of thumb, growth rate * time step should be less than 0.01. It is possible for the diffusion processes to become unstable if the time step is too large - signals can oscillate. Reduce the time step and reduce the decay rate.
• Errors in the the interaction function will cause the system to stop.
  • To restart Reset the GUI.
  • To find the error
    • Set Matlab to always stop on error, Matlab:Menus:Debug:Stop:Always stop on errors. Reset the GFtbox GUI and Step to repeat the error.
    • Sometimes it is even better to set a break point on the line that fails - that way you can inspect values of variables before the GTtbox try/catch routine takes over.
    • 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.

Outputs

Plotting panel

To view

• Specified values, i.e. kapar or a particular morphogen (factor) select from drop down menu top right and tick Plot current factor.
  • To autoscale the axes. Panel:Plot Options:Auto axis range. To autozoom as well, click Menus:Plot:Auto zoom and centre. To fix the axes scale (to view growth). The best is to first grow with auto ranging on. Then click Panel:Plot Options:Axis From Picture and unclick the Auto axis range box. Alternatively, unclick the Auto axis range box and key in values you want - click elsewhere on the GUI to force a replot.
  • 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.

VRML, OBJ, FIG

To export the current mesh

• VRML, to interactively view the mesh using a web browser export the mesh as a VRML file, Menu:Mesh:Save VRML. We use such files to make 3D prints.
• FIG, for Matlab figure files.

Movies

By default movies are uncompressed and stored in the projects movies subdirectory

• To compress select Menu:Movie:Codec - we currently favour Motion JPEG avi
• To automatically convert the output to flash, .flv, select Menu:Movie:Convert to flash. This option requires the ffmpeg program to be on the current path.
• Click Record Movie to start creating a movie. The button will change to Stop Movie.

Web and PowerPoint

Writing web and PowerPoint pages is facilitated by:

• Output .avi for PowerPoint. Use Menu: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 Menu: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