All project matrices are accessible using the matrix list, accessible by
clicking on the
Matrices tab in the project tool tab
bar. As shown in Figure 12.5, “The project matrix list”, the list includes for each
matrix summary information and a series of buttons implementing useful
Edit matrix opens the matrix for editing in the MorphoBank matrix editor application.
Edit info opens the matrix's
Info tab allowing you to edit matrix name and
access settings. It also makes available other matrix information
editing tabs include
NEXUS Blocks for
editing of unsupported blocks.
Add NEXUS opens the matrix's
Uploads tab allowing import of NEXUS format files
into the matrix.
Download as NEXUS lets you download the full matrix as a NEXUS file to your desktop. Note that the downloaded matrix will include everything except linked cell and character media, which are not formally supported by the NEXUS format.
Download NEXUS file without notes also lets you download the full matrix as a NEXUS file to your desktop, but with all notes stripped out. For some datasets this can produce a much smaller file for sharing with colleagues.
The matrix editor application allows project members to edit their matrix-based data sets collaboratively in an environment implementing many of the editing functions of familiar desktop software. There are a few significant differences between the MorphoBank matrix editor and desktop applications that you should keep in mind as you work:
There is no "save" button in the editor. All changes to the matrix are saved to the database as you make them.
There is no automatic "undo" button in the editor. All changes to the matrix are permanent. MorphoBank does track changes made to the matrix, however, and keeps version information. You can access this information to pinpoint when and by whom specific changes were made. The change history includes enough information for you to reconstruct most aspects of a matrix at any point in its development.
Changes you make are instantly visible to other project members. You don't have to send them files to make your work accessible. Everyone is always using the latest data.
Character states must be defined before use. You cannot simply enter the number "3" into a cell without first entering a definition of state 3 into MorphoBank.
You can always export your matrix as NEXUS for use with other NEXUS compatible software. However linked images will not be included as the NEXUS format does not formally support them.
The layout of the editor is shown in Figure 12.6, “The matrix editor in image display mode”. Buttons providing access to various tools to manage taxa, characters and views of your data are arranged across the top of the editor. The rest of the editor display area is reserved for the display of matrix data. As is traditional, characters are listed horizonally along the top of the matrix display; taxa are listed vertically along the left-hand side.
You can obtain additional information about a taxon, character or cell by placing your mouse point over the item of interest and waiting a second or so for an overlay "tooltip" to appear. To edit any character, taxon or cell, simply double click on it with your mouse. The various editing windows that appear on double-click are described in detail in the following sections.
When using the editor you are always in "edit" mode. That is, you can always double click on a taxon, character or cell and change them (assuming you have privileges to do so, of course). Other matrix functionality is accessible via a set of controls arranged along the top of the editor and show in Figure 12.7, “Matrix editor controls”
There are eight tools:
The Highlight drop-down menu lists options for highlighting of cells. Options other than "nothing" will color cells matching the highlight criteria in red. One exception: the "with colored cells" option will color cells in different colors based upon their states (0=red, 1=yellow, 2=blue, etc.).
The Taxa button will open the taxon control window described in futher detail below. The window allows you to reorder the taxa in your matrix, add new taxa to the matrix from your project's taxa list and remove taxa from the matrix.
The Characters button opens the character editing window, providing access to most of the features of the project character editor (see Figure 11.1, “The character editor”) from within the matrix editor.
The Search button allows you to find matching taxonomic or character names in the matrix editor. It supports partial matching of taxonomic names, character names and associated notes. To search, click on the button and enter your search in the search window that appears. Select either "taxa" or "characters" as your search type then click "find." The search will list all matches. Double-clicking on a match will scroll the matrix to the location of the match.
The Batch button provides access to features allowing you to set the score, and/or attach media and bibliographic citations to a range of characters for a given taxon in a single action.
The View drop-down menu lets you set the view mode for the matrix. By default the view includes state numbers and any associated images. Because the cells must be relatively large to accommodate images, the number of cells onscreen at one time is limited. Other modes provide denser displays with varying amounts of information displayed per-cell.
The Reload button will completely reload the matrix from the server. Use this when you want to refresh the data set from the database if you believe certain data may be out-of-date.
The Warning button will list any character editing warnings. These include indications that the states or name of a character that you have scored have changed since you last scored it.
To add a character to your matrix, click on the
characters button. You will see a window
like the one shown below. To add a character click on the character
after which you wish the new character to appear and then click on the
"new character" button. The remove a character click on it on the list
then click on the "delete character" button.
To edit a character in your matrix either double-click on its name in the matrix or click on the "characters" button and double-click on its name in the character list. The editing tools provides are similar in scope and function as those provided by the project character list editor.
Note that when you edit a character in the matrix editor you are editing its entry in the project character directory. This means that when you change the character in your matrix you are also changing it in all other matrices in your project that reference it. .
By default the order of characters in a matrix is that in which they were added or appeared in the imported NEXUS file. You can arbitrarily reorder them by dragging them into place in the character list in the characters editor. You can also reorder characters in a matrix using the project character list editor.
You can add comments to a character by editing it, then clicking on "comments", "media" or "citations" tabs in the editor. All of these functions operate similarly to those in the project character editor.
If you score a character in your matrix that is subsequently changed
by another user (either the character name or states are changed) the
editor will display a warning to let you know. As shown below, a red
exclaimation point will be displayed next to the character name. A
warning message will also appear in the "warnings" window when you click
warnings button at the top of the
editor. The warning indicator will display until you open a cell for the
character for editing.
In the information sciences an ontology is a formal representation of knowledge as a set of concepts and the relationships between those concepts. In bioinformatics ontologies are increasingly being employed to codify how data is recorded and structured across projects, with the ultimate objective of standardizing concepts in various domains. Such standardization would, in principal, allow data from different sources to be easily and effectively combined, compared and analyzeRules setting states other thd using software tools. Analyses that now require many hours of work by specialists could potentially be performed by software and powerful data mining techniques brought to bear on previously intractable problems.
Ideally, an ontology for morphological analysis would include all possible characters (referred to as concepts in many discussions of ontologies) in a given domain. If all researchers in a particular domain were using the same set of characters for their analyses combination and comparison of those analyses would become straightforward and amenable to automation.
Of course, if the entire range of characters and states for your project were already well-known and universally accepted then you probably wouldn't be using MorphoBank or reading this manual right now. The reality is that character selection is complex, fluid, and subjective. It is at the heart of most every project. In a number of ways the characters you choose define your work.
Morphobank understands the central role of characters in analysis and provides a full set of tools for creating and managing them. Ontologies in Morphobank are just another tool you can use to organize your characters and streamline your analysis.
Morphobank provides tools for creation of what we call ad-hoc ontolgies. In an ad-hoc ontology, characters are created and relationships established because they suit the analytical needs of the author. There is no pretense of formal or systematic knowledge capture in a specific domain.
Concepts in a Morphobank ontology are the characters and states you define for use in your matrix. The relationships (or "rules") between characters/concepts codify functional linkages. For example, one can create a "set state" rule between a "source" character and one or more dependent characters. When the source character is set to a specific state then the states of dependent characters can be automatically forced to another value. Similarly "set media" rules can be established that cause all media attached to source characters to be automatically attached to their dependent characters.
First and foremost, Morphobank ontologies are a productivity tool. Once rules between characters are established, scoring in repetitive cases can be made automatic. For example, a rule can be established that marks an entire block of dependent characters as inapplicable for a certain taxon when a source character is scored in a specific way. Application of media to matrix cells may be similarly streamlined. Rules can be established to cause media attached to a cell with a particular taxon and character to be automatically attached to any number of other cells in the same matrix row. In this way many mouse clicks (and hours) can be saved, particularly for larger matrices.
While ontology rules may appear on first inspection to be just a form of workflow automation they can be much more. Well-designed rule sets can capture valuable information about the nature of your characters and the analytical framework of your project. That certain characters are dependent upon other characters in specific ways can be used to infer patterns in characteristics across taxonomic units.
Further, the relationships between characters can be visualized graphically, providing a "birds-eye" view of your analysis than can be useful for collaborators, reviewers and future researchers.
To start building your ontology, open the character list window by clicking on the "chars" button in the button bar along the top of the matrix editor. Then click on the "ontology" button on the upper-right corner of the character list window, as show below.
After clicking on the "ontology" button you should see a Character ontology window like the one shown below. This window allows you to attach rules to any character in the currently opened matrix.
To attach a rule, first select the rule type on the tab bar along the top of the window, then click on the "Add rule" button. For "set state" rules you will see a window like the one below. To establish a "set state" rule select the source character and state from the "When setting this character to this state..." lists. You can only select a single source character and state for each rule you create. Then select the characters you wish to set scores for and the state to score with. You can select a range of characters by clicking on the first character and shift-clicking (clicking the mouse while the shift-key is depressed) on the last character in the range. Note that you can only target multiple characters with a single "set state" rule if the state you are setting is "inapplicable." Rules scoring to specific states other than "inapplicable" can target a single character only. Use multiple rules to set multiple characters to specific non-"inapplicable" states.
For "media" rules the "add" window will appear like the one below. As with "set state" rules, you first select the source character and then select one or more target characters by clicking and/or shift-clicking. Media rules can always target multiple characters.
You can delete a rule by clicking on it in the rule list and then clicking on the "Delete rule" button. Note that deletions of rules cannot be undone, but that only the rule will be deleted. Your project data will not be changed.
You can see a graphical representation of your rules by clicking on the "View rules as graph" button in the Character ontology window. The rule set is visualized as a directed acyclic graph. The large red dots represent "source" characters; the smaller grey dots represent dependent characters; and the orange lines represent "set state" rules between the characters. When viewing media rules, the lines will be green in color. You can zoom in and out of the visualization using the scroll wheel on your mouse. You can drag the visualization around the screen for easier viewing by clicking and dragging with your mouse. If the positioning of individual characters is not ideal (in large rule sets it is often impossible to position all characters for good readability) you can reposition individual characters dots by clicking and dragging on them.
Once established, ontologies can be used to check the validity of your data or, if desired, to automatically generate data. The default setting in MorphoBank is for automatic implementation of ontology rules to be blocked, in other words, even if the rules are established, the software will not automatically write the data into cells unless a Project Member selects to do so.
The "set state" rules you establish for your project are assertions as to how cells should be scored in certain situations. You can check your matrix data against your rules and highlight any deviations clicking the "check matrix" (symbolized by a check mark) button on the bar along the top of the matrix editor.
A window will appear like the one below and analysis of the matrix will begin. For very large matrices and rulesets the analysis may take a little while. Be patient! Once complete, a list of violations will be presented. Double-clicking on a violation in the list will scroll the matrix to the score in question.
You can automatically change your matrix data to resolve all violations by clicking the "fix violations" button at the bottom of the window. In many cases the "fix violations" feature can be a huge time saver, providing automated cleanup of existing data. Note, however, that changes to your matrix made by "fix violations" cannot be undone! Use caution and consider the implications before using this feature.
You can optionally have the matrix editor apply your rules automatically as you score. To enable this feature click on the "preferences" button in the bar along the top of the matrix editor. Then set the "Apply character rules while scoring?" option to "yes." Once enabled, that matrix editor will automatically change states in your matrix to conform to rules as a result of scoring changes you make. It will not make wholesale changes to your data as the "fix violations" does. Changes are only made in response to individual scoring events.
By default, automatic scoring will only occur in cells that have no existing score. That is, only "?" cells will be automatically scored. You can enable automatic scoring for all cells, populated or not, but setting the "Allow character rules to overwrite existing scores?" options to "yes."
You can turn automatic scoring on or off at any time using the preferences window. Any changes made while automatic scoring is enabled are permanent and cannot be undone.
You can add any taxon in your project taxon list to your matrix by
clicking on the
taxa button at the top of the
editor and then dragging the desired taxon from the "taxa in this
project but not in this matrix" list to the "taxa in this matrix" list.
Drag the taxon to the location in the list where you want it to appear
in the matrix.
You can edit taxon notes by double clicking on the taxa in the matrix and the clicking on the "notes" tab in the window that appears. Notes are saved once you close the window.
Editing of other aspects of a taxon, such as the name, must be done in the project taxa list outside of the matrix editor.
By default the order of taxa as displayed in the matrix is the order
in which they were added or appeared in the imported NEXUS file. You can
change the order by opening the taxa list (by clicking on the
taxa button) and dragging the taxa in the
"taxa in this matrix" list relative to one another.
To remove a taxon from a matrix drag the taxon in the taxa window from the "taxa in this matrix" list to the "taxa in this project but not in this matrix" list. Note that this will not delete the taxon from your project (that can be done in the project taxa list), only from the matrix.
When you delete a taxon from a matrix all of the scoring for that row of the matrix is deleted and cannot be recovered! Be sure you want to delete the taxon!
In a collaborative project is it often desirable to split scoring tasks on a matrix by taxon or group of taxa. To ensure that project members only have access to the taxa they are supposed to be editing MorphoBank provides a mechanism for associating particular taxa in a matrix with individual members or groups of members.
If a member does not have access to a taxon a small "lock" icon will appear next to the taxon name in the matrix, as shown below. Neither the taxon notes nor cells in that row will be editable.
Intentional access restrictions are not the only reason a taxon can be locked for a member. A taxon can be also locked for a member because the user lacks access privileges in the project (eg. they are an observer, bibliographic maintainer or anonymous reviewer).
To control access for a taxon double-click on the taxon and click on the "access" tab in the window that appears. If you wish to restrict access to a single user select the member from the "user" drop-down. To restrict access to a group of users select the group from the "group" drop-down menu. (Creating member groups in your project is described below). Access is additive. That is, if you choose both a group and a member, then both will have access even if the member is not in the group.
To set access control for a taxon you must be the project administrator or owner of the matrix.
To create a member group navigate to the "member groups" tab under "options" in your project. Click on "add new group name" in the upper-right-hand corner of the display. Then give the group a name and optionally a color and description. Repeat this process until all of the groups you require have been created.
Now you are ready to add members to their groups. Navigate to the "members" tab under "options" and edit the members you wish to add to the groups you have created. As seen in the figure below, the member's edit form will include checkboxes for each of the available groups. Check off the groups the member should belong to and click "save." Each member of your project may belong to as many groups as needed.
The OTU determines the rank in the taxonomic hierarchy that is displayed in the matrix editor. For taxonomy at or above the genus level, the rank you specify as OTU is the rank that is displayed. For example, if the OTU for the matrix is set to genus, then all taxa will display in the editor with genus only, even if other taxonomy is present.
If the OTU is set below genus then taxonomy from genus to the OTU is displayed. For species or subspecies this means a binomial or trinomial will be shown, respectively.
The OTU set in the matrix
Basic Info tab is
used for all taxa unless the OTU in the taxon itself is set, in which
case that OTU is used instead.
The term "cell" refers to the intersection of a taxon and character in a matrix. The term "score" refers to a state as applied to a cell. In MorphoBank a cell can have one score, many scores, or none at all.
To score a cell double-click on it in the matrix. A window will appear, shown below, allowing you to edit all aspects of the cell:
Scoring & Status - allows you to choose states for the cell and set the overall status value of the cell. Status values - "new", "in-progress" and "complete" - are intended as a simple tool for tracking the status of matrix scoring. Cells can be highlighted based upon the status to provide a quick view of scoring progress in a matrix.
Notes - allows you to edit text notes for the cell.
Media - allows you to link media from your project media browser to the cell and optionally add cell-specific labels to the media. Note that only media of specimens whose taxonomy matches that of the cell are displayed.
Comments - allows project members to add commentary to cells.
Citations - allows you to link a bibliographic reference from your project bibliography to the cell along with citation-specific page and comment values.
Change log - lists all changes to cell, including who, when and what.
If you do not see the state you need in the list, you may add it by editing the states of the character as described in the section called “Editing characters”.
You can double-click on any cell to edit it, even if the cell editor is already open for another cell. If another cell is already open then changes you have made to it will be saved before the new cell is opened. As an alternative to clicking you can also use the arrow buttons in the cell editor to move to adjacent cells. As with double-clicking, changes made to the currently open cell are always saved before moving to a new cell.
The cell currently open for editing is highlighted in blue.
To add media to a cell click on the "media" tab in the cell editor. A list of linked media is displayed. To remove media from a cell, click on the media and then click on the "remove media" button. Double-click on any of the media to label it in a pop-up browser window. Labels added to media in a cell apply to the media only in the cell. That is, you can have different labels on the same image in different cells.
The cell image labeling feature opens in a web-browser popup window. If you have popup-blocking software installed the window may fail to appear. Be sure you have any installed popup blocking software disabled or set to allow popups from MorphoBank if you want to label images!
To add media to a cell, click on the "add media" button. A list of media applicable to the taxon of the current cell will be displayed, as shown below. Click on the desired image and then click on the "add" button to add the media to the cell.
Labeling images is described in the section called “Labeling images” in the chapter "Using Media." There is no difference between labeling an image in the media editor and labeling it in the matrix editor, save that the labels you create in a cell are specific to that cell and will only appear when viewing the image in the cell.
The matrix editor provides tools for making changes to a range of cells for a given taxon in a single action. Supported actions include:
Changing of cell states - you can force the states of selected cells to "?" (no score), "-" (inapplicable) and "NPA" (not presently available). You can also set the status of cells in the same operation.
Assignment of selected media
Assignment of selected bibliographic citations
Changes made with batch operations cannot be undone. If you are not careful you can lay waste to entire rows of your matrix. Use care!
To perform a batch operation open the batch window (shown above) by
clicking on the
batch button at the top of the
editor. Then select the taxon for which you would like to perform the
operation (you can only batch process for a single taxon at a time). Select
the set of characters to include in the operation. Then click on the button
for the operation you wish to perform and choose the appropriate settings -
select a specific media, bibliographic reference or state and status value.
Then click the "add" button (for media) or "save" button (for bibliographic
citations and states).
To prevent you from inadvertently overwriting data in your matrix a warning will appear if there is at least one set score of any type (state, NPA or "-") in the cells you are about to change. The warning will include a numeric summary (eg. 5 set states, 2 NPA cells, 2 in applicable cells); if you want to actually see the content of the cells you can look at the specific cells in the editor.
You can download a copy of your matrix in NEXUS format at any time by clicking on the "Download as NEXUS" button at the bottom of the matrix editor or in the matrix list. You also have the option of downloading your matrix with all notes removed by clicking on the "Download NEXUS file without notes" button.
Note that NEXUS files do not support attached images, and your download will not include images attached in MorphoBank.