Learning+how+to+use+Mesquite

=Mesquite Help: Learning how to use Mesquite=

Table of contents

 * Documentation and help facilities
 * How to think like Mesquite (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.

(The Search Data feature searches the current data file or project and returns objects (e.g. taxa, characters, sequences) that match the search string.) 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.)
 * Search Features:** The Log window has a small text box at the bottom, 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:
 * [[image:searchFeaturesAND.jpg]] — Search Features, AND: searches through information about Mesquite's features and returns a description of those features matching ALL of the search terms
 * [[image:searchFeaturesOR.jpg]] — Search Features, OR: searches through information about Mesquite's features and returns a description of those features matching ANY of the search terms


 * 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 [[file:///Users/david/Documents/Mesquite_Workspace/MesquiteCore/Mesquite_Folder/docs/mesquite/studies/index.html|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 Option or Alt 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.


 * YouTube videos:** Watch some of the videos on the [|Mesquite Project YouTube channel].


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


 * \Window view modes:** The View Mode submenu is used 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.

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:
 * Menu & Control Explanations:** The menu item View>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.
 * 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 View 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 View menu to make a web page summaring the functioning of the menus and buttons for the foremost window

How to think like Mesquite
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:


 * Primary Choices: Submenus and dialogs boxes with lists of alternative choices may have a small number of choices listed then an item "Other Choices..." (if a submenu) or a check box "Show Secondary Choices" (if a dialog box). If these are selected, a larger number of choices is offered, including the "secondary" choices. This division of choices into the primary choices (the ones we expect will be most frequently selected) versus the secondary choices helps keep the commonly seen array of choices small. (This division can be turned off in the Defaults submenu of the File menu.)
 * Macros: Mesquite can be instructed by a scripting language. Macros can therefore be written or automatically generated to script complex calculations. Macros appear in submenus in the appropriate menu.
 * Configurations: Even if many packages of Mesquite modules are installed, you can ask Mesquite to load only a subset of them. This allows Mesquite to startup more quickly and to present a simpler interface (i.e., with fewer options). You can control configurations using the submenu File>Activate/Deactivate Packages>.
 * The Simplification system.