Mesquite Help: Learning how to use Mesquite

Table of contents

• Documentation and help facilities
• How to remember what you've done
• Why is Mesquite complex? (Understanding this may help you know what to do...)

Mesquite's documentation and other learning aids

Because of Mesquite's complexity we have provided various aids to help you discover and learn features:

Manual: This manual provides an introduction to Mesquite, including instructions for accomplishing some analyses. It resides in the docs subdirectory of the Mesquite_Folder directory, and is also available from the Help menu while Mesquite is running.

Search Features: Most windows have a small text box (usually near the top of the window) beside the words "Search Features" or "Search Data". When set to Search Features mode (which you can request by clicking on the little symbol until it shows "&" or "/"), you can use this to find features and how to use them. Enter text there and hit Return, and the text will be sought. There are several modes, marked by different symbols:

• — Search Features, AND: searches through information about Mesquite's features and returns a description of those features matching ALL of the search terms
• — Search Features, OR: searches through information about Mesquite's features and returns a description of those features matching ANY of the search terms

The results of the search are shown in the main Mesquite window (shared by the Log window). The results may list modules, tools or manual pages that match the search terms. If you touch on the name of a manual, you may get a list of the contexts in which this module can be used. (Please: we realize that the search results can sometimes be long and difficult to follow. Please give us your feedback as to what you would most want to know in response to a search, so that we can improve this feature.)

Example files: One of the best ways to learn about analyses is via the example files, which are distributed with the main Mesquite package and with various of the add-on packages. The example files are present in the "examples" folder of Mesquite_Folder. Some additional examples are outlined on the Studies page.

Explanation areas: Explanation areas at the bottom of each window may describe the window, its contents, or the function of a selected button or other object. If you hold down the Shift key as you select a menu item, an explanation for it will (usually) appear in the explanation area of the frontmost window. Explanations areas are also present in some dialog boxes.

Web Search: This menu item uses a web browser and the Google Search engine to search for terms entered by the user. Users may restrict their search to the Mesquite Manual if desired.

Mesquite FAQ: There is a preliminary Frequently Asked Questions page.

Window information bar: The small tabs near the top of each window allow you to select a view: Graphics, Text, Parameters, Modules and Citations. The Modules view in particular can help you learn about Mesquite calculations. It shows the set of modules currently active in the analysis and or graphics shown in the window. This is shown as a tree of modules employing other modules (a bureaucratic hierarchy!). If you pass the cursor over a module name, an explanation for it appears in the explanation area at the bottom of the window. If you touch on the name of a module, a menu will appear with choices to show more information (if available). If there is a special manual for the module, an extra label will appear that will link you to the manual.

Additional web pages: Mesquite surveys modules for information and composes a set of web pages. These web pages list all the modules loaded, brief explanations as to what these modules do, and the scripting commands these modules respond to. These Mesquite-composed HTML pages are in a directory called "Mesquite_Prefs" within a directory Mesquite_Support_Files, which may reside in different places depending on your operating system. If you can find these pages, you might want to store a bookmark, or alias, or shortcut to one of them so that you can find them again without going through Mesquite.

Menu & Control Explanations: The menu item Window>Menu & Control Explanations causes Mesquite to compose a HTML page summarizing the menu items or buttons for the current window, and to show it to you.

Keyword Search: This menu item in the Help menu of Mesquite provides a currently-primitive facility to search among the names and explanations of all of the installed and loaded modules to find a keyword. You could, for instance, search for "simulat" to find all of the modules that might have to do with simulations.

Thus, if you want to learn about:

• Modules:
  • Use the menu items in the Help menu to go to the appropriate HTML pages for modules or packages. You can also get to the HTML pages of packages by touching the banners in the Mesquite startup window (the window named "About Mesquite").
  • Use the Search Features facility in each window
  • Open the Modules view of the window of concern (using the tab in the information toolbar) and move the cursor over the names of the modules to see explanations in the explanation area, or touch on their names to go to their information pages composed by Mesquite.
• Menu items
  • Hold down Shift as you select a menu item to make an explanation for it appear in the explanation area of the frontmost window.
  • Use the Menu & Control Explanations menu item of the Window menu to make a web page summaring the functioning of the menus and buttons for the foremost window.
• Buttons and tools:
  • Touch on a tool in the tool palette to make an explanation for it appear in the explanation area of the frontmost window.
  • Use the Menu & Control Explanations menu item of the Window menu to make a web page summaring the functioning of the menus and buttons for the foremost window

How to remember or document what you have already done?

With an interactive program having as many options as Mesquite, it can be difficult to remember what options are currently in effect. Three facilities help you keep track of what you've done.

• Information bar of windows. The information bar has various tabs that control alternative views of a window's contents. Some of these give information about the current calculations, the parameters in use, and details about the modules in use by the window.
• The Log Window, available by selecting Mesquite Log in the Window menu, records commands given and messages relayed to the user. This text is also saved automatically to a file called "Mesquite Log" within the directory Mesquite_Support_Files.
• Auto-scripting for file saving. When Mesquite saves NEXUS files, it automatically constructs a script that attempts to return an analysis to its current state. This not only allows a user to save a snapshot of an analysis, but the script itself can also be inspected to determine current parameters (in case that's not evident otherwise). Snapshot scripts can also be seen for individual windows, by selecting the appropriate item in the Scripting submenu of the Window menu.

Why Mesquite is complex

Mesquite has many options depending on what modules are installed and loaded. Its modularity and flexibility allow for many possible analyses, but also create challenges for the user (and the manual writer). There are too many possible analyses for us to have yet written instructions specifically for each. If the user wants to perform some particular analysis, he or she may have to use his or her puzzle-solving ability to figure out how to achieve the analysis by combining Mesquite's various functions.

Why are so many choices? Why do some analyses assault you with a guantlet of many dialogs? These are consequences of Mesquite's flexibility. We have tried to protect you from complexity as much as possible.

You may find a slightly different rhythm of thinking will be needed when confronting Mesquite. For instance, suppose you wanted to see how much the likelihood for a character varies if random noise is added to the branch lengths of the phylogeny. If you were lucky, there would be a macro or some menu item that would build your desired analysis directly, but for this question there isn't currently such a shortcut. What you'd like to see is a frequency distribution of likelihoods calculated for the character over a series of trees, each tree derived from some given tree by adding random noise to the branch lengths. This sounds like a bar chart (histogram), but which bar chart? It seems to concern characters, so perhaps it is a Characters bar chart? No, each sample point is a tree, and thus you should ask for a Trees bar chart. When a dialog box asks you what value to calculate for the trees, what do you say? The likelihood concerns a character, and thus you respond "Tree value using character". In the next dialog, you can choose character likelihood. You will also be asked what source of trees. The trees are randomly modified by adding noise to the branch lengths; therefore, choose "Randomly Modify Tree" and for the particular modification, "Add noise to branch lengths". Although this may seem complex, it does allow you to design the analysis exactly as you wish. You may use the example files, instructions in this and other manuals, and the Mesquite discussion list in order to learn how to do the analyses you need.

Features that help reduce Mesquite's complexity to the user are: