Documentation of Software for Qualitative Loop Analysis
CAVEAT: Loop Analyst is a work in progress. The GUI version may be slightly buggy in the user interface, and there are scads of functionalities still left to implement, but it's quite usable at present. So use at your own risk. I would love your insight.
The core of the method involves the representation of a system in both a graphical form using signed digraphs, and in matrix form using square (-1, 0, 1) matrices. These representations are used to qualitative describe direct causal effects (including self-effects) between the component variables of the system as increases, decreases, or has no effect, under and assumption that the turnover of each variable is within approximately an order of magnitude. The community effect formula below is then applied to create a table of predictions of the indirect effect on each variable given a positive signal to any particular variable.
for L(m,n) = m disjoint loops (simple cycles) spanning exactly n variables.
I am happy to take feedback, respond to requests for assistance, and consider feature requests. I can be contacted at:
Unzip the Loop Analyst.zip archive, and move the Loop Analyst folder to your hard drive. Double-click on the program icon to launch the program.
If you would like to use Loop Analyst's graphing capabilities, you will need to have a working copy of graphviz installed on your system. This can be done using MacPorts, although Ryan Schmidt makes a very nice pre-built version available for free download. If Loop Analyst does not find your version of graphviz's dot command by itself, you can enter the pathway in Preferences.
Loop Analyst is distributed under the terms of the GPL version 2 or higher.
Loop Analyst was validated against loop analyses in numerous published studies (you can examine some in the Published.cml document). The weighted feedback functions have been validated against results from the analysis of 30 randomly-generated community matrices (five in each size category ranging from three variables to eight variables) with moderate connectance using Jeffrey Dambacher's software for Maple in Revision 2 of Ecological Archives E083022-S1, Supplement 1 to Ecology 83:13721385. The results matched exactly. Here are the 30 matrices in Rdata format, and the results from the analysis using Dambacher's software in pdf.
The interface of Loop Analyst is straightforward. The left side of the program window lists the loop models in the currently loaded library of loop models. This list is blank when starting the program. Above the library list are three buttons used, as labeled, to add a new community matrix, or edit or delete the currently selected community matrix. To the right, occupying most of the program window, is the output area. The output area has tabs along the top which permit the user to select a particular aspect of the analysis to present.
The commands are all accessed through the menus, with appropriate keyboard shortcuts listed in each menu. One may also edit a specific community matrix by double-clicking on it. Clicking on each tab at the top of the output area brings the appropriate page to the front. The up and down arrow keys can be used to move through the list of community matrices, and the output area will change accordingly.
This image to the right shows the new community matrix/edit a community matrix interface. Each system can be given a name in the top row, data defining the system are entered in the middle row, and (optionally) the system variables are named in the bottom row. Details about the format used for entering the data and the variable names are found in the New CM portion of the File Menu section below.
This is a basic tutorial intended to introduce you to the use of Loop Analyst. It covers the creation of a new community matrix and describes the components of the analyses, editing a community matrix, and building a library of community matrices. This tutorial is not intended to substantively introduce the method of loop analysis, how it is used, or the assumptions upon which its validity is contingent. I assume that you are familiar with the most basic loop analysis terminology (e.g. "self-effect," "loop," "path," etc.).
Creating a new community matrix
Now let's put some data in the matrix. We'll start with one of the simplest possible systems by reproducing the one used in the Loop Analyst logo. This is a system of two variables, A and B. A has a negative self-effect (i.e. is self-damping), and a positive direct effect on B. B has a negative direct effect on A. A detailed description of the constraints of the data in a community matrix is given in the File Menu section. For now we'll note that the data should be represented in a nested list format using square brackets like this: [[-1,-1],[1,0]]. The first list is [-1,-1] and qualitatively represents the direct effects of all variable in the system on the first variable, which is A. In plain language "A is qualitatively a function of negative A, and negative B." The second list [1,0] represents the direct effects of all the variables in the system on B. Note that the number of lists and the number of elements in each list must be exactly the same, and must equal the number of variables in the system.
Let's leave the variable names blank for now, and just click the "OK" button (or type return). Back on the main screen Loop Analyst, if everything was entered correctly should now display:
(If you got an error message, just go back and try again) Notice that Loop Analyst chose the default names A and B for the variables.
If you have graphviz installed, and there is a valid path to it's dot command in Preferences, when you click on the "Graph" tab at the top of the window, you should see a picture that looks similar to the Loop Analyst logo. It may be in color, where the node representing each variable and the paths emanating directly from it are colored uniquely. This coloration method can make large systems and highly connected systems easier to read (see, for example, the graph for the community matrix "Fig 6 Dambacher 2002 Ecology 83(5)" in the library Published.cml provided with this software). You can change the coloration of graphs in Preferences.
Now click on the "Predictions" tab at the top of the window. You should see:
This is the prediction matrix (also called the "table of predictions", and the "community effect matrix" in the literature). Each element aij represents the predicted direction of change in the value of variable j, given a steady positive input at variable i, where i is the row, and j is the column. The values of these elements may be positive "+", no effect "0", negative "", or ambiguous "?". (ambiguous results have sometimes been represented by "+/" in the published literature.
The remaining tabs provide various extensions to the classical loop analysis given in the first three tabs. Following Dambacher et al., (2003), the Adjoint and T matrices represent the net feedback and total feedback respectively. The weighted feedback matrix is equal to the element-wise absolute value of the Adjoint divided by the value of the corresponding value of T. The weighted predictions matrix applies a decision criterion (default is weighted feedback >= .5) to ambiguous predictions in the predictions matrix to estimate the likely direction of change. Recent work extending loop analysis Dambacher et al., (2005) permit qualitative change in life expectancy predictions, which are found under the "Life Expectancy" tab.
Editing a community matrix Click on the "Edit" button to pop up the Edit the Community Matrix window. Go ahead and change the name of variable A to "plants", and variable B to "herbivores". Click OK, and look at the graph and matrix output to see the changes reflected there.
Building a library of community matrices We can add additional matrices by clicking on the "New" button, as described above. We can also cut and paste existing matrices using the commands in the Edit Menu. In the Library List, click on the matrix you made above, and select "Duplicate" from the Edit Menu. Now edit this matrix, by changing the data to [[-1,-1,0],[1,0,-1],[0,1,0]], adding a third name "predators", and clicking the "OK" button. Examine the output, and use the up and down arrows to move between different matrices. You can save and reopen your library as a .cml document.
These behave as you would expect.
Users can customize the way Loop Analyst works, for example:
Undo and Redo step through the edit history of the library since it was opened, reverted, or created.
New CM pops up a dialog which requests the optional name of the new community matrix, the data describing it, and the optional names of the system variables. A community matrix specified without a name will be named "Matrix" by default. If no variable names are specified the letters of the alphabet will automatically be used to label the variables.
The data describing a community matrix are entered as follows:
The names of the variables in a community matrix are entered as follows:
The program will automatically calculate font size adjustments so that names fit within the circle representing each variable in the graph.
Be sure you have saved your previous work, as New Library does not make a backup before clearing existing community matrices and analyses.
Append loads the community matrices from a saved community matrix library (.cml) document that you select. The names of the appended community matrices are not adjusted, and may duplicate community matrices in the already open library.
Saves changes to the currently opened community matrix library. If you try to Save a previously unsaved community matrix library a file dialog will appear for you to name the document, and indicate where on your system you would like to save it.
Save As will make a file dialog appear for you to name the document, and indicate where on your system you would like to save it.
Save Graph saves the currenxitly selected community matrix's graph decription in png file format (.png) to a location in your system that you specify through the pop-up dialog.
Export analyses saves the output from the Community Matrix, Predictions, Adjoint and T, Weighted Feedback, Weighted Predictions, and Life Expectancy tabs for the currently selected community matrix to a document you specify through the pop-up dialog in plain text format.
Export Graph saves the currently selected community matrix's graph decription in dot file format (.dot) to a location in your system that you specify through the pop-up dialog. This document is a description of a graph (useable, for example, with graphviz), not the actual visual representation of the graph (which you can get using Save Graph under the File menu, or Copy Graph under the Edit menu).
Reverts to the last saved version of the open community matrix library. All changes made after the last save are lost.
Copies the currently selected community matrix to Loop Analyst's clipboard, and removes it from the library.
Copies the currently selected community matrix to Loop Analyst's clipboard.
Pastes a copied community matrix into the library just after the currently selected community matrix.
Deletes the currently selected community matrix from the library.
Makes a duplicate of the currently selected community matrix and puts the duplicate immediately after it.
Opens a dialog that permits the editing of the currentlyt selected community matrix's name, data, or variable names.
Copies the currently selected community matrix as represented on the Community Matrix tab to the clipboard for pasting into other programs.
Copies the image appearing on the Graph tab for the currently selected community matrix (png file format) to the clipboard for pasting into other programs.
Copies the table of predictions (community effect matrix) for the currently selected communityt matrix to the clipboard for pasting into other programs.
Copies the Adjoint of the negative of the current community matrix and the total feedback matrix to the clipboard for pasting into other programs. NOTE: The adjoint and total feedback matrices are transposed by convention from the orientation of the prediction and community matrices.
Copies the weighted feedback matrix from the Weighted Feedback tab for the currently selected community matrix to the clipboard for pasting into other programs.
Copies the weighted prediction matrix from the Weighted Predictions tab for the currently selected community matrix to the clipboard for pasting into other programs.
Copies the community matrix, table of predictions, adjoint and total feedback matrices, weighted feedback, weighted predictions, and change in life expectancy matrices for the currently selected community matrix to the clipboard for pasting into other programs.
The following references may serve to help ground one in the theory, mechanics and application of loop analysis. The text by Puccia and Levins is out of print, but can be special ordered from Harvard University Press. The paper by Justus gives an excellent overview of the method's limitations. Extensions to loop analysis using weighted feedback were developed by Dambacher, and he, Levins and Rossignol produced the life expectancy methods.