Chapter 2 The phaseplane()
application
After starting the phaseplane()
application a new window opens up, which is shown in Figure 2.1. The application contains a sidebar at the left, which is used for:
specifying initial values for the state variables
specifying initial values for the parameters
Starting computations from the chosen initial state with the selected parameters
loading, saving and deleting curves that are computed with the
phaseplane()
application.
The remainder of the application window consists of an area with up to 6 tab sheets, called Time series
, Nullclines
, Steady states
, Vector field
, Trajectories
and Portrait
. Only the first 3 tab sheets (Time series
, Nullclines
and Steady states
) are shown if the system of ODEs consists of a single ODE. Switching between these tabs is achieved by clicking on the appropriate tab name. Each tab sheet includes a plot frame and a frame in which progress messages as well as errors will be reported. Notice that the plot frame differs between the different tab sheets.

Figure 2.1: Starting view of the phaseplane()
application. The red arrow indicates the gears icon that opens up the right sidebar.
In the following the Rosenzweig-MacArthur model presented in section 1.1 will be used to illustrate the different types of curves that can be computed and the different menus to adjust the computations and the graphical presentation of their results.
2.1 Time series
The first tab shows curves of the time dynamics as predicted by the system of ODEs that is being investigated. The dynamics are computed numerically through integration after pressing either the <<Compute
button or the >>Compute
in the left sidebar (see Figure 2.1). The program will integrate the dynamics from \(t=0\) till the maximum integration time when the >>Compute
button is pressed. See section 2.1.3 for how to change the value of the maximum integration time. When the <<Compute
button is pressed the integration will start at the maximum integration time and attempt to integrate backward in time till \(t=0\).
Numerical integration of the system of ODEs forward in time should always proceed without problems (if at least you specified the system of ODEs correctly), but numerical integration of the dynamics backward in time may cause problems as the values of the state variables in the ODEs may approach infinite values. Therefore, be careful with numerical integration backward in time, it is advisable to compute over a small time interval only. Hence, choose the value of the maximum integration time (see section 2.1.3) not too large.
Every time the <<Compute
or the >>Compute
button is pressed a new time series curve is computed from the current initial state with the current parameters. All computed curves are shown in the graph. Each curve furthermore gets a label and the first and last point of the curve are labeled as special points. These special points are added to the drop-down menu at the top of the left sidebar. Figure 2.2 shows the application window with two time series that have been computed from different initial states, while the special points drop-down menu is expanded. The drop-down menu shows the first and last point of the two computed time series (started from \(R=0.05, C=0.1\) and \(R=0.05, C=0.5\), respectively). These special points can be selected using the special points drop-down menu, in which case the values of the state variables and parameters of the special point are used as starting point for the next time series computation.

Figure 2.2: Two computed time series are shown in the phaseplane()
application and the special points menu is expanded, listing the first and last points of the two curves.
By default the plot in this tab shows the time variable on the x-axis and the values of all state variables defined in the model on the y-axis. Which state variables are used as y-coordinates in the plot can be customized as discussed in section 2.1.2.
2.1.1 Changing state variables and parameters
Clicking on the State variables
menu title in the left sidebar (see Figure 2.1) expands a sub-menu with a list of names of all state variables in the system of ODEs and input boxes that contain current values of these state variables. New values for the various state variables can be specified by editing the values in the input boxes. These new values take effect as soon as the Apply
button is pressed.
Similarly, clicking on the Parameters
menu title expands a sub-menu showing a list of names of all parameters and input boxes that contain the current values of the system parameters. New values of the parameters can be specified by editing the values in the input boxes. Also these new values only take effect once the the Apply
button is pressed.
2.1.2 Customizing the plot
Curves of the model dynamics that will be shown in the time series plot include as variables the time and the values of all state variables at each time. The plot frame on the Time series
tab sheet always shows the independent time variable on the x-axis with the x-axis ranging from 0 to 100. On the y-axis this plot frame shows by default the values of all state variables with the y-axis from 0 to 1. These default settings can be customized using the right sidebar, which can be shown by pressing the gears icon in the right-top corner of the application window (see Figure 2.1).

Figure 2.3: The phaseplane()
application window with right sidebar expanded allowing for customizing the time series plot.
Figure 2.3 shows the phaseplane()
application window with the right sidebar visible. The drop-down menus allow for selecting which variables are used as x- and y-coordinates in the time series plots. As x-coordinate only the time variable can be selected. As y-coordinate it is possible to select all state variables, in which case as many curves will be plotted as there are state variables defined in the model. All state variables will then be plotted using the same y-axis at the left of the plot. The boxes and drop-down menus in the right sidebar allow for customization of the minimum and maximum values on the x- and y-axis as well as whether a linear of logarithmic axis scale should be used.
Alternatively, when a single state variable is selected as y-coordinate the right sidebar extends and offers the possibility to add a second y-axis on the right-hand side of the plot, on which the value of another state variable can be plotted. If a second state variable is selected to be plotted on the second y-axis at the right-hand side of the plot the right sidebar panel extends even further to allow for specification of the minimum and maximum value and the scale type to use on this second y-axis.
If state variables are selected to be plotted on both the primary and the secondary y-axis, the right sidebar also provides the option to plot the time series curve in a 3-dimensional perspective plot. If a 3-dimensional perspective plot is selected instead of a 2-dimensional plot, the right sidebar extends even further with a slider to adjust the viewing angle of the 3-dimensional graph.
Figure 2.4 shows the 4 different configurations of the right sidebar discussed above. Which one is shown depends on whether a single or all state variables are plotted on the primary, left y-axis, whether or not a second state variable is selected to be shown on the secondary, right y-axis and whether or not a 2-dimensional or 3-dimensional plot is selected.

Figure 2.4: The 4 different configurations of the right sidebar of the phaseplane()
application window depending on which state variables are selected to be shown on the primary and secondary \(y\)-axis.
Apply
button has to be pressed to finalize the changes made. Subsequently, the gears icon at the right-top corner of the application window can be pressed to hide the right sidebar again.
2.1.3 Numerical settings
In addition to the tab sheet for customizing the plot settings, the right sidebar contains a second tab sheet to customize numerical settings. This numerical options tab can be shown by pressing on the dial icon in the top-right corner of the right sidebar, whenever the latter is not hidden. Figure 2.5 shows the phaseplane()
application window with the right sidebar showing the numerical options tab.

Figure 2.5: The phaseplane()
application window with extended right sidebar showing the numerical options tab sheet. Here numerical settings for the time series calculations can be customized.
For the calculation of time series of the model dynamics the maximum integration time, the time step of the integration and the integration method can be adjusted. The numerical methods available for integration of the dynamics are lsoda
, ode23
, ode45
and rk4
, as provided by the deSolve
package (Soetaert, Petzoldt, and Setzer 2010).
If one of the tab sheets Steady states
, Vector field
, Trajectores
or Portrait
is selected in phaseplane()
the numerical settings in the right sidebar show an additional slider labeled Steady state search grid
. With this slider the number of starting points can be varied, from which searches are started for a steady state in the neighborhood of the starting point. Adjusting the slider to higher values therefore refines the search and hence will reduce the chance that a particular steady state remains undetected, at the expense of longer computation times.
If the tab sheet Portrait
is selected in phaseplane()
the numerical settings in the right sidebar show another additional slider labeled Portrait starting point grid
. With this slider the number of starting points can be varied, from which trajectories or orbits are computed and shown in phase plane. Adjusting the slider to higher values will show more trajectories and hence a phase portrait with higher resolution at the expense of longer computation times.
Apply
button has to be pressed to let them take effect. Subsequently, the gears icon at the right-top corner of the application window can be pressed to hide the right sidebar again.
2.2 Phaseplane analysis
The remaining tab sheets of the phaseplane()
application all plot a phaseplane of the systems of ODEs. The dimension of the system of ODEs that is being analyzed determines what this phaseplane looks like:
If only a single ODE is being analysed only 2 additional tab sheets are shown by the
phaseplane()
application, theNullclines
tab sheet and theSteady States
tab sheet. Both tab sheet show a plot where the value of the dependent variable of the ODE is plotted on the x-axis, while the value of the time derivative of this dependent variable is plotted on the y-axis. Taking the symbol \(N\) to refer to this dependent variable, the phaseplane plot hence is equivalent to a \((N, dN/dt)\)-plot.If the system of ODEs includes exactly 2 ODEs, the two dependent variables in the ODEs are plotted on the x- and the y-axis. Which dependent variable is plotted on which axis can be customized, but by default the first dependent variable is plotted on the \(x\)-axis, while the second dependent variable is plotted on the \(y\)-axis.
If the system of ODEs includes more than 2 ODEs, by default the first dependent variable is plotted on the \(x\)-axis, while the second dependent variable is plotted on the \(y\)-axis. The remaining dependent variables in the systems of ODEs are assigned constant values equal to the values that are currently given in the
State variables
sub-menu. Which dependent variable is plotted on which axis can be customized.
The phaseplane plot can be customized using the right sidebar, which can be shown by clicking the gears icon in the right-top corner of the application window (see Figure 2.1). Figure 2.6 shows the phaseplane()
application window with the Nullclines
tab sheet selected and the right sidebar visible. The drop-down menus allow for selecting which state variables are used as x- and y-coordinates in the phaseplane plot. The boxes and drop-down menus in the right sidebar also allow for customization of the minimum and maximum values on the x- and y-axis as well as whether a linear of logarithmic axis scale should be used.

Figure 2.6: The phaseplane()
application window showing a phaseplane diagram with the right sidebar expanded allowing for customizing the phaseplane plot.
The different phaseplane tab sheets provide different types of information about the dynamics of the system of ODEs:
The
Nullclines
tab sheet plots the nullclines (also called isoclines) of the ODEs, which represent those combinations of state variable values for which one of the right-hand sides of the ODEs equals 0. If only a single ODE is analyzed this tab sheet shows the value of the dependent variable in the ODE on the x-axis, while the value of the time derivative of this dependent variable is plotted on the y-axis. Taking the symbol \(N\) to refer to this dependent variable, the phaseplane plot hence is equivalent to a \((N, dN/dt)\)-plot.The
Steady states
tab sheet shows in addition to the nullclines (or isoclines) the location of all equilibrium points of the system of ODEs that have been detected in the range of the state variables that is being shown in the plot. If only a single ODE is analyzed these equilibrium points correspond to the points where the curve of \(dN/dt\) as a function of \(N\) crosses the x-axis, while for systems of ODEs the equilibrium points are the intersections of the nullclines. Stable and unstable equilibrium points are labeled differently and the eigenvalues characterizing the dynamics in the neighborhood of the equilibrium point are reported in the console window below the plot.The
Vector field
tab sheet, which is only shown for systems of ODEs, plots in addition to the nullclines and the steady states the vector or flow field, which indicates the direction of the dynamics from the various positions in the phaseplane.The
Trajectores
tab sheet, which is only shown for systems of ODEs, plots in addition to the nullclines and the steady states the time series of the system dynamics that are also shown in theTime plot
tab sheet. In this tab sheet these time dynamics are plotted in the phaseplane. Only those time series will be shown that have the identical parameter values as is currently used for the phaseplane plot in theTrajectores
tab sheet. From this tab sheet it is also possible to initiate the computation of a time series of the systems dynamics by pressing the<<Compute
or>>Compute
button for backward and forward integration in time, respectively.The
Portrait
tab sheet, which is only shown for systems of ODEs, plots in addition to the nullclines and the steady states a phase portrait characterizing the model dynamics, which is visualized by plotting a number of trajectories or orbits from a regularly spaced set of initial points in the phaseplane.
Clicking on the State variables
menu title in the left sidebar (see Figure 2.1) expands a sub-menu with a list of names of all state variables in the system of ODEs and input boxes that contain current values of these state variables. New values for the various state variables can be specified by editing the values in the input boxes. Similarly, clicking on the Parameters
menu title expands a sub-menu showing a list of names of all parameters and input boxes that contain the current values of the system parameters. New values of the state variables and the parameters can be specified by editing the values in the input boxes. Also these new values only take effect once the the Apply
button is pressed. Once, the Apply
button is pressed the phaseplane plot is redrawn with the new values of the state variables and parameters.
2.3 Saving graphs
All tab sheets of the phaseplane()
program show at the top-right corner of the plot frame a button that allows you to download an image of the current graph. Clicking this download icon will open up a file dialog box in which you can specify the name of the PNG or PDF file, in which to save the image of the plot. Whether the plot is saved to a PNG or a PDF file can be determined with the command-line argument saveplotas
(see section 2.6). More elaborate graphs can of course be constructed by exporting the computed curves as explained below and using other packages in R to visualize the results.
2.4 Curve management
The bottom part of the left sidebar of the phaseplane()
application shows 3 sub-menus that allow for manipulation of the computed curves. Curves can be read into the phaseplane()
application from variables that are present in the global R environment from which the application was started, computed curves can be saved to variables in this global R environment and curves can be deleted. Figure 2.7 shows 4 snapshots of the left sidebar with the different sub-menus expanded and in different states.

Figure 2.7: The phaseplane()
application window with the left sidebar showing the Load curves
submenu, the Save curves
submenu, the Delete curves
submenu with the curve choice drop-down menu expanded and the Delete curves
submenu with the All
option selected. The action buttons in each submenu allow to load, save or delete the selected curves.
2.4.1 Load curves
By expanding the Load curves
sub-menu an input box shows up in which you can enter the name of a variable (do not use any quotes!) that is present in your global R environment (see Figure 2.7). This variable should contain time series curves. As long as the global variable you want to load has been saved by the phaseplane()
application, it should be possible to be read in. But this is of course only taking effect if the curves stored in the global variable pass some tests. For example, the curves in the global variable should contain all the same state variables and parameters as the state variables and parameters in the system of ODEs that is currently being analysed with the phaseplane()
application.
Independent of which of the application tabs is active when you load curves from a global variable, all the valid curves in this global variables will be read in.
The two action buttons in the Load curves
sub-menu allow you to either append the curves in the global variable that you are loading to the current set of curves stored by the application or replace the entire set of curves that is currently stored by the phaseplane()
application. The console box below the plot frame will report on the success or failure of the load operation.
2.4.2 Save curves
Expanding the Save curves
sub-menu reveals a curve selection drop-down menu, an input box in which you can enter your name of choice for the variable in your global R environment, in which to store curves, and an action button to execute the save action (see Figure 2.7). The curve to save can be selected via the curve selection drop-down menu. This drop-down menu lists in addition to the options None
(the default choice) and All
(the last choice) the labels of all the time series that have been computed. Either one specific curve can be selected for saving or all curves. It is not possible to save 2 out of 3 curves at the same time. In the input box you have to enter a valid name (do not use any quotes!) for a variable in the global R environment from which the phaseplane()
application was started. Take care with specifying this variable name, the application will overwrite an already existing variable.
Pressing the Save
button will save the selected curve or all curves to the variable with the specified name.The console box below the plot frame will report on the success or failure of the save operation. The variable will, however, only show up in your Rstudio Environment panel that shows the list of variables in your global R environment after the phaseplane()
application has exited. I have not found a way to update the contents of this Rstudio Environment panel while the phaseplane()
application is still active.
2.4.2.1 Delete curves
Expanding the Delete curves
sub-menu reveals a curve selection drop-down menu and an action button to execute the delete action (see Figure 2.7). The curve to delete can be selected via the curve selection drop-down menu. This drop-down menu lists in addition to the options None
(the default choice) and All
(the last choice) the labels of all the computed time series. Either one specific curve can be selected for deleting or all curves. It is not possible to delete 2 out of 3 curves at the same time.
Pressing the Delete
button will delete the selected curve or all curves currently stored by the program.The console box below the plot frame will report on the success or failure of the operation.
2.5 Saving program settings on exit
Whenever the program exits all the curves that the phaseplane()
application has computed and has currently stored in memory are saved in a global variable <model>PhaseCurves
, where the sub-string <model>
is the name of the function describing the dynamics, which is passed as first argument to phaseplane()
. Similarly, all programs settings, such as the plot settings on the different tabs and the numerical settings for the time integration are saved in the global variable <model>PhaseSettings
. These two global variables will show up on return to your R environment after the programs has ended. When present, the global variables <model>PhaseCurves
and <model>PhaseSettings
will be read by the phaseplane()
application the next time you start it up. They will only take effect, however, if the variables pass some tests successfully. For example, if the variable <model>PhaseCurves
does not contain the correct set of state variables and parameters it will be ignored when you start up the phaseplane()
application.
The variables <model>PhaseCurves
and <model>PhaseSettings
are overwritten every time the phaseplane()
application ends. Therefore, if you want to save a particular set of curves and the application settings, you have to copy these variables to new variables with your own unique names. At a later time these saved variables can be assigned to the variables <model>PhaseCurves
and <model>PhaseSettings
again to start the phaseplane()
application at the point where you left off.
The variables <model>PhaseCurves
and <model>PhaseSettings
will be ignored completely if the phaseplane()
application is started with the command-line argument resume = FALSE
. The default of this command-line argument is resume = TRUE
.
2.6 Optional command-line arguments
The phaseplane()
application allows for a number of additional arguments that can be included at the command line to tweak graphical default values used by the application. These arguments are all optional and adopt default values when not specified on the command line.
The arguments that can be included on the command line are:
lwd
: The line width used for plotting computed curves. The default value is 3.cex
: The base font size for labeling axes and legends in the plots. The default value is 1.2.tcl.len
: The length of ticks on the axes. The default value is 0.03.saveplotas
: Either “pdf” or “png” to save the plot to a PDF or PNG file. The default value is “png”.