MorphoBank v3.0 Users Guide (September 2015 revision)

The MorphoBank Project


                Stony Brook, NY
                USA
            


Table of Contents

I. Overview
1. What is MorphoBank?
A Short Description
Advantages over desktop phylogenetics software
Why use MorphoBank?
Peer-review Policy
2. Basic Concepts
The "Project" Workspace
Creating a project
Types of Data You Can Deposit
Taxonomic names
Specimens
Media
Matrices
Characters
Other data
Tools for Collaboration
Membership
Reveiwer Access
Managing access to data
Tracking changes to your data
Publishing
Deleting a Project
Copyright considerations
Selectively publishing project content
Linking to a published project using permalinks
DOIs for MorphoBank Projects
Other ways to access published data
Project summary information
Folios
3. Common Types of Projects
Phylogenetic Projects with Matrices
Image-only Projects
Collaborations Fusing Large Lists of Characters and Taxa from Many Matrices
4. Navigation
5. How to Get Access
Resetting the Password for an Existing Account
Duration of login
6. Funding for MorphoBank
7. Citing MorphoBank in your publications
8. MorphoBank API
II. Using MorphoBank
8. Workflow
Creating a New Project
Setting Project Options
Naming your project
The project accession code
Setting citation information
Setting Up Context for Your Project
Media views
Taxonomy
Specimens
Bibliography
Adding Data
Media
Existing matrices
Creating new matrices
Inviting Collaborators
Editing Project Data
Publishing Your Data
9. Establishing Context for your Project
Media Views
Character and Taxon Partitions
Publishing Partitions
Managing Taxonomy
Finding taxa
Adding new taxa
Editing taxa
The Operational Taxonomic Unit (OTU)
Specimens
Finding specimens
Adding and editing specimens
Project Bibliographies
Adding bibliographic references by hand
Importing bibliographic references from EndNote
Searching
Exporting bibliographic data
10. Using Media (Images, Video, Sound)
Uploading Media
Supported media formats
Uploading and Viewing CT Scan Data
The add new media file button
Copyright Tools
Copyright Settings for Project Data: Matrices and Documents
Batch uploading media with the Batch Media Upload Tool
Batch Media Delete Feature
Using the Media Browser
View modes
Sorting
Filtering
Searching media
Importing Media from EOL.org and iDigBio.org
Using the MorphoBank Image Viewer and Annotator
Editing Media
Updating media
Labeling images in the Matrix Editor
11. Managing Characters
Character editor overview
Adding Characters
Adding a single character
Batch adding characters using a NEXUS file
Viewing lists of characters
Searching for characters
Moving characters
Editing characters
Edit basic character information ("character" tab)
Adding media to a character or character states ("media" tab)
Labeling media associated with characters
User comments for characters ("comments" tab)
Add Citation ("citation" tab)
Change history ("change history" tab)
12. Using Matrices
Starting a New Matrix
Importing a Matrix from a NEXUS Format File
NEXUS import caveats
Merging Several NEXUS Files into a Single Matrix
Editing
Tree-building Options
Editor overview
Characters
Character ontologies
Character Ordering in MorphoBank
Taxa
Cells
Making changes to your matrix data en-masse
Downloading a NEXUS-format copy
Deleting a Matrix
13. Folios
Creating Folios
Adding Media
Changing the Order of Media
Public Access
14. Project Documents
Adding a Document to Your Project
Document Folders
Public Access to Project Documents
15. Managing Access
Adding Members to a Project
Types of access
Removing a Member From a Project
Anonymous Reviewer Access
Item-level Access Control
Who Gets to Edit What?
16. Backing Up Your Data
The Download Package
Project media
Matrices in NEXUS format
Project documents
Uploaded NEXUS files
Project data in SDD format
17. Publishing Your Data
Project Information Fields
Accessing Published Data on MorphoBank
Citing Your MorphoBank-Hosted Data
18. Project Duplication
Contacting MorphoBank
Duplicating Published Projects
Duplicating Unpublished Projects
19. Staging a MorphoBank Project for the Evolution Project

List of Figures

1. Morphobank
2.1. Selecting the new project option from the project list
2.2. A vouchered specimen
2.3. An unvouchered specimen
2.4. Add Media Buttons
2.5. Matrix editor/viewer
2.6. Membership type menu
2.7. Access control menu
2.8. Item-level publishing status menu
2.9. Project DOI
2.10. Matrix DOI
2.11. Browse Projects list
4.1. MorphoBank main navigation bar when not logged in
4.2. MorphoBank main navigation bar when logged in
4.3. Typical side navigation bar
8.1. Creating a new project
8.2. Portion of Project Information form
8.3. Matrix "Preferences"
9.1. The partitions button in the matrix editor button bar
9.2. The partition editor
9.3. Publishing Partitions
9.4. Portion of the taxonomic directory
9.5. Portion of the specimen directory
9.6. Specimen entry form for vouchered specimens
9.7. Project bibliography list
9.8. Deleting the bibliographic reference that is used in citations
9.9. Editing a bibliographic reference
10.1. Portion of new media upload form
10.2. Media editing form with specimen match menu visible
10.3. Media editing form with copyright tools
10.4. Copyright Permission Upload Form
10.5. Click the "copyright preferences" button
10.6. Check box and click "save"
10.7. Copyright notice
10.8. Matrices marked with CC0 have this symbol:
10.9. Documents marked with CC0 have this symbol:
10.10. Portion of the media batch upload tool
10.11. Batch Deletion
10.12. Restore/delete
10.13. The media browser
10.14. Media browser view modes
10.15. The media browser filter setup screen
10.16. and iDigBio Buttons
10.17. Select Taxa
10.18. Results
10.19. Import Complete Screen
10.20. Curate Media Page
10.21. Basic image viewer
10.22. Basic image viewer
10.23. Image viewer tool palette
10.24. Zoomed-in image with highlighted area
10.25. Image viewer with labeling controls and label visible
11.1. The character editor button
11.2. The character editor
11.3. The character list
11.4. Moving characters using the "move char" button
11.5. Editing of basic character information
11.6. Selecting a character
11.7. Character editor with ID
11.8. The character media tab
11.9. Attaching media to a character
11.10. Character image viewer and labeling of character images
11.11. Adding a comment to a character
11.12. Adding a citation to a character
11.13. Using the Change History Tab
12.1. New matrix form
12.2. Successful NEXUS Upload
12.3. Merging a NEXUS file with a Matrix (Portion of Edit Matrix Description Page)
12.4. The project matrix list
12.5. Tree-building options
12.6. The matrix editor in image display mode
12.7. Matrix editor controls
12.8. The in-matrix editor character editor list
12.9. The in-matrix editor character editor
12.10. Warning about changed character in the matrix
12.11. Warning about changed character in the Warnings window
12.12. The ontology seventh from the left in the matrix editor window
12.13. List of "set state" scoring rules for a matrix
12.14. The "add rule" window for "set state" rules
12.15. The "add rule" window for "media" rules
12.16. Visualization of a set of "set state" scoring rules
12.17. Matrix editor button bar
12.18. Checking a matrix against a rule set
12.19. Preferences Button
12.20. Setting matrix editor preferences
12.21. Character button
12.22. Matrix editor taxa list
12.23. Taxon Notes Field
12.24. Taxon/matrix row to which user does not have access
12.25. Setting access restrictions for a taxon in the matrix editor
12.26. The project member groups list
12.27. Adding a member to a group
12.28. The matrix cell editor window
12.29. Choosing an image to add to a cell
12.30. Matrix setup button
12.31. Cell media automation checkbox
12.32. Cell media automation arrow
12.33. Add Media to Character States
12.34. Cell media automation confirmation
12.35. "Rule Check" in the Matrix Toolbar
12.36. The batch operations window
12.37. Batch Row Score Editor
12.38. Copy a Row
12.39. Batch "Undo" Feature
14.1. Adding a project document
15.1. The project member list
15.2. Adding a new member to a project
15.3. Granting anonymous reviewer access
15.4. Access control menu
19.1. Crowdsourcing Option
19.2. Evolution Project dashboard
19.3. Dashboard tools
19.4. Edit profile link
19.5. Crowdsource Character
19.6. Crowdsource Taxon

List of Tables

11.1. Character media search summary
17.1. Project information options

Part I. Overview

Chapter 1. What is MorphoBank?

A Short Description

MorphoBank (www.morphobank.org) is a web application with tools and archives for evolutionary research, specifically systematics (the science of determining the evolutionary relationships among species). Study of the phenotype, which is often visually-based, is central to contemporary systematics and taxonomic research. MorphoBank was developed specifically to provide much needed tools for the expansion and modernization of phylogenetic work on the phenotype. MorphoBank provides four interrelated toolsets for researchers:

  • one for management of uploaded images and affiliation of data with those images (labels, species names, etc.)

  • another that allows researchers to manage uploaded morphological data and affiliations with phylogenetic matrices.

  • supporting tools for managing the taxonomic names, characters and states, specimens and views used to classify images and populate phylogenetic matrices.

  • administrative tools for managing access, publishing and backing up your data.

MorphoBank is project-centered, meaning teams of researchers can create project-specific workspaces and share images and other data with each other in a password-protected environment. Because MorphoBank is web-based, team members can easily and efficiently work together no matter where they are located. Furthermore, MorphoBank's web-centric foundations make it a natural tool for online publishing of project data once a paper associated with the project goes to press in a peer-reviewed scientific journal.

The phylogenetic matrix capabilities of MorphoBank are designed to aid systematists working alone or in teams to build large phylogenetic trees using morphology (anatomy, histology, neurology, or any aspect of the phenotype). In contemporary systematic methods in which morphology is used to build trees of species (or higher taxa), one starts by constructing a matrix made of characters and taxa. Characters are features of an organism that appear in different forms. Examples include "eyes: blue, green or brown" or wings: present or absent. To convert these to a form that fits in a matrix, one might translate these as, for example, "eyes: state 1 (blue), state 2 (green), state 3 (brown)." Traditionally this has been done with desktop programs such as MacClade or Mesquite, which encode this information in files adhering to a standard format such as NEXUS (arguably the most popular format in use today).

Desktop software cannot accommodate images associated with character states or matrix cells in a robust fashion, something that is becoming essential for researchers actively studying the phenotype and for later researchers trying to understand the anatomical basis of some comparisons that might have been made decades ago. MorphoBank allows researchers to upload and download their NEXUS files, and to collaboratively edit them in the MorphoBank online workspace. It also allows researchers to upload high-quality images affiliated with each cell in a matrix, to zoom in on these images for details, to collaboratively label the images and to affiliate various kinds of metadata with an image (e.g., species, specimen number, notes, etc.).

Data in MorphoBank have been deposited by professional scientists and the students supervised in their laboratories. Once a MorphoBank project is published on-line, however, these data are made accessible to the public.

Advantages over desktop phylogenetics software

Previous generations of desktop systematics software - MacClade in the 1990's and Mesquite, NEXUS Data Editor, etc. in this decade - were a boon to the community, greatly enhancing researcher productivity. However, in the last several years, with the explosive growth of the World Wide Web and the increasing sophistication of web-browser software, a new category of software has emerged, the "web-application." Web-applications leverage existing web-based data services (mapping, taxonomic lookups, and access to specimen and bibliographic databases, for example) and enhanced user interface techniques to produce software that combines many of the best features of desktop software with the ever increasing capabilities of the Internet.

MorphoBank was designed to address shortcomings in existing desktop systematics software using modern web-application techniques. Areas of concern included:

  1. Seeing the images that document the basis for a character state is enormously helpful to researchers both during and after the research process. This is particularly important if the matrices are large, with hundreds of taxa and thousands of characters. Before MorphoBank there was little support for inclusion of imagery in phylogenetics software. A researcher would have had to trust her memory as she made comparisons among hundreds or thousands of species. It is much more effective to store an image of a character with labels to refer to repeatedly while adding new data.

  2. A large quantity of documentary information - and the majority of visual documentation - was being lost when morphologists produced phylogenetic trees. No archive existed for morphologists to store the images that backed up their character designations. This was wasteful and incurred a lot of repeated work due to lost information. The field of morphological systematics could subsequently not grow as fast (in terms of numbers of characters) as molecular systematics, the latter being well-databased in GenBank.

  3. Single-user file-based systems are wholly unsuitable for collaborative work, whether team members are dispersed across the hall or across the globe. For all but the smallest and most disciplined of teams, file version control and conflicts quickly becomes untenable, with copies of files proliferating in e-mail inboxes and on FTP sites with no one certain as to what the "real" dataset is. MorphoBank provides a central database for project data, ensuring that all team members are using the same dataset at all times. Changes made by one member are instantly visible to the rest of the team. Further, all changes are logged making it possible to determine how any element of a project's dataset arrived in its current state.

  4. Many valuable phylogenetic datasets are available on the Internet only in truncated form (typically lacking images and other context) or not at all, in part because there is no simple mechanism with which to publish data from most desktop applications to the Web. Treebase has been a useful site for archiving matrices but is not a tool-based application for collaborating on and viewing phylogenetic matrices and does not store images. MorphoBank is inherently web-based, and publishing of project data is a matter of pushing a button.

Why use MorphoBank?

Here is a hypothetical case: you are working on a morphological phylogenetic matrix with a team of investigators. Because MorphoBank is a web application, your team can work on exactly the same data at the same time. All collaborators can see contributions from members of the team, including images associated with homology statements, as soon as they are made. Since everyone is always using the most up-to-date data, e-mailing of files and reconciliation of file versions is completely unnecessary.

All project information is kept private to the team, protected by password, until the team chooses to make it public. In conjunction with a peer-reviewed scientific paper, you may need to allow reviewers to access your data. MorphoBank provides the ability to allow anonymous, password protected, reviewer access to your data.

When a paper is in press or published in a journal is often the time an investigator wishes to place online his morphological matrix (including labeled images of your homology statements), images, lists of specimens and taxa, etc. that you have assembled in a form that is easy for your readers to access. Morphological data collection increasingly requires visual documentation of homology, but journals cannot always publish all images that support the research in a project. MorphoBank provides tools to simplify the online publishing of data resources including:

  • Publishing of project data via a simple online form

  • Ability to hold back publication of project data on a per-item basis

  • Automatic conversion of images to web-viewable formats

  • Built-in advanced image viewing client supporting efficient "pan and zoom" viewing and annotation of high-resolution imagery

  • Online viewing of matrix data using a full-featured web-matrix software interface

  • Virtually unlimited number of images and matrices

  • Support for persistent URLs for MorphoBank-hosted data resources

Note that you do not need to be working with a matrix to use MorphoBank. Many investigators have other scientific reasons to store media online in association with an upcoming publication, with associated information such as the repository and specimen number. MorphoBank welcomes these contributions.

Peer-review Policy

MorphoBank permits the posting of peer-reviewed scientific research. Exceptions may be made (generally labeled "MorphoBank Exclusives") at the discretion of the Executive Committee. These studies have typically been conducted under the supervision of research scientists. Use of MorphoBank for educational and popular initiatives is in the planning stages. Users whose research has not been peer-reviewed may use the site for organizational purposes, but are asked not to make their projects live.

Chapter 2. Basic Concepts

The "Project" Workspace

Workspaces on MorphoBank exist as separate "projects," completely independent from all others and accessible only to the creator of the workspace and those to whom the creator has explicitly granted access. As we shall see, a workspace contains all of your project data - taxa, characters and states, specimens, bibliographic references, media (typically images, but also video and sounds) and matrices. These data are completely private to the workspace and cannot be modified or, prior to publication, accessed by those outside of the project.

You are free to develop your dataset in any way you choose. While use of character ontologies, taxonomic authories and specimen databases is in general good practice and highly encouraged, MorphoBank does not mandate their use. How you conduct your research in your workspace is entirely up to you.

Creating a project

You can create as many projects as you need; in general you should create a project for each discrete research problem or paper you are working on. Remember that workspaces are completely independent from one another and do not interact in any way. There is no sharing of data between project workspaces, and each workspace is only accessible to those to whom you explicitly grant access. If you have multiple workspaces with identical member lists and/or need of shared data, then you should consider consolidating them into a single project workspace.

Figure 2.1. Selecting the new project option from the project list

Selecting the new project option from the project list


To create a new project, login to MorphoBank and navigate to the My Projects section. You will see an orange "Create New Project" button at the top of the page. This will display a New Project form, which includes fields for project title and abstract, publication information and settings for allowing anonymous reviewer access to your data. To start you need only to specify a title, although an abstract is strongly suggested. You may edit this information at any time, many users provide provisional information at the start.

Types of Data You Can Deposit

Once your project workspace is established you and your collaborators can deposit various types of data to share amongst project members, edit collaboratively, or use in phylogenetic matrices. MorphoBank can accept the following kinds of data:

Taxonomic names

Your project workspace has a single "directory" of taxonomic names with which you can identify specimens (and by extension media) or populate a matrix. You may load your taxa by hand, one at a time, using the taxon entry forms or in a batch process using a tab-delimited file from a database, Microsoft Excel or a similar application. For more information on adding taxa see the section called “Managing Taxonomy”.

Each distinct taxon is represented once, and only once, in your taxonomic directory. When you use a taxon to identify specimens and in matrices, you are doing more than just tagging those items with a taxonomic name. Rather, you are actually linking your specimens and matrices to a taxonomic concept. If you subsequently change the taxon, your changes will automatically propagate to all of the specimens and matrices that reference the taxon.

Specimens

As with taxa, your workspace has a directory of specimens that are referenced in your project. Specimens can (and should) be associated with a taxonomic identification. They may also be depicted using uploaded media.

There are two types of specimens: vouchered and unvouchered.

For vouchered specimens – specimens from a formal collection – you must at a minimum provide an institution code and catalog number for each specimen. Both of these values should conform to the standards of the institution from which the specimen originates. If you are not sure of the formats for these values, contact the institution's collections manager. Typically, the institution code will be a 2-4 letter abbreviation of the institutional name (e.g., AMNH = American Museum of Natural History, YPM = Yale Peabody Museum). Whenever possible a collection code should be provided. As with the institutional code and catalog number, this should conform to institutional standards. Many, but not all, institutions use collection codes.

Unvouchered specimens are those obtained from sources other than formal collections, including literature and the Internet. You are encouraged to provide detailed notes about the origins of the specimen in the "notes" field. You can also attach a formal bibliographic citation to a specimen.

A taxonomic identification of the specimen should be provided for all specimens. The identification is used by MorphoBank's matrix editor to retrieve relevant media, and by the search/filtering system to organize your media. Unidentified specimens will be much less useful than identified ones.

Figure 2.2. A vouchered specimen

A vouchered specimen


Figure 2.3. An unvouchered specimen

An unvouchered specimen


Media

You can upload any number of media documenting specimens to MorphoBank. Most uploaded media are images, although video and audio formats are also supported. (Thus our use of the more neutral "media" terminology).

You will typically upload an image and tag it with a specimen identification, any pertinent copyright information and a view description (eg. "dorsal", "lateral", "palatal").

MorphoBank accepts a variety of image formats including JPEG, GIF, PNG, PLY,STL, ZIP, TIFF, DCM, and Photoshop. Note that Photoshop files that use layer effects may not render properly on MorphoBank. For consistent results we recommend converting these files to TIFF format before uploading. All image files should be in RGB mode. Files in CMYK mode and color manipulations may not render properly.

You should upload image files at the highest resolution that makes sense for your project. MorphoBank will automatically create sized versions for use on the site as well as a full-resolution version optimized for online viewing. The original uploaded file will be retained and can be made available for download.

MorphoBank also accepts the following video file formats: MPEG-4, QuickTime and WindowsMedia. The preferred video file format for upload to MorphoBank is MPEG-4. Files in QuickTime and WindowsMedia format will usually work so long as the compression method used is supported by MorphoBank's video processor. In general, videos compressed with WindowsMedia will work, as will most QuickTime compression methods (some very old and rarely used methods like GIF compression are the notable exceptions). AVI files usually will not work and should be converted to MPEG-4 prior to upload. In general if your uploaded file is being rejected by MorphoBank it is recommended that you try re-encoding the file in MPEG-4 format using one of the many video conversion tools available for Mac OS X, Windows and Linux.

Audio files may be uploaded to MorphoBank in MP3, AAC, AIFF or WAV format. Other formats are not supported. If you need to convert or edit your audio files use a sound editing application such as Audacity (http://audacity.sourceforge.net/).

MorphoBank does not support the PowerPoint file format. If you need to upload images from a PowerPoint presentation, you should export them from PowerPoint in a supported format such as JPEG and then upload those files.

Media may be uploaded one file at a time using the "Add new media file" button. For large numbers of files, the Batch Media Upload tool may be more efficient. It is accessed with the "Add media batch" button and allows you to enter all the information on the standard media form for a group of media files that are uploaded as an archive in either Zip or Tar format. For more information about using the Batch Media Upload Tool, including how to prepare you archive for upload, see the section called “Batch uploading media with the Batch Media Upload Tool.

Figure 2.4. Add Media Buttons

Add Media Buttons


Morphobank also allows users to directly reference the Encyclopedia of Life (EOL.org) and Integrated Digitized Biocollections (iDigBio.org), to find and upload media for projects. Simply click the button that says: "Import EOL.org Media" or "Import iDigBio.org Media" from within the Media editor (or, alternatively, the Taxonomy editor), and select the Taxa for which you wish to search. A more complete description of this tool can be found in Chapter 10, Chapter 10, Using Media (Images, Video, Sound)

Matrices

Project members may create, edit and publish phylogenetic matrices using MorphoBank's matrix viewer/editor application. A matrix's axes are composed of characters (see the section called “Characters”) and taxa (see the section called “Taxonomic names”). The cells of the matrix contain character states and, optionally, media (see the section called “Media”) with (also optionally) labels. Labels applied in a matrix cell are specific to that cell and automatically include text describing the cell's character and taxon. Cells may also have attached bibliographic references, member comments and research notes.

You can start a matrix from scratch and populate it solely using the MorphoBank matrix editor or you can use an existing NEXUS or TNT format file as a starting point. Regardless of how you begin, you can import the contents of additional NEXUS or TNT format matrix files (produced by applications like MacClade or Mesquite) into your MorphoBank matrix at any time. All taxa and characters that do not already exist in your project will be automatically created when the file is imported, and states for existing taxa/character pairs merged with the existing data.

In projects with multiple matrices taxa, characters and media are shared across all matrices in your project. A change made to a taxon, character or media item in one matrix, or in the item-specific editing screens, will instantly be reflected in all matrices where the item is used.

It is possible to download your matrix from MorphoBank as a NEXUS or TNT file at any time. The file will include all characters, taxa, cells and notes, but not images since they are not formally supported in the NEXUS or TNT format. Images can, however, be downloaded as a zipped folder to the desktop by clicking on the "Download Project" link on the Project Overview page. The archive will contain SDD XML format data files with associated matrix, character, taxon and specimen data. Note, however, that these images will not be viewable associated with cells in desktop programs reading the NEXUS or TNT file.

Figure 2.5. Matrix editor/viewer

Matrix editor/viewer


Characters

As with taxa, your project has a single directory of characters and their associated states. Each distinct character is represented once, and only once, in your project's character list. When you use a character in a matrix, you are doing more than just bringing in the character's name. Rather, you are actually linking a characteristic concept to your matrix. Consequently, if the character is changed in one place, the change will propagate to all other places where the character is used.

Unlike taxa and other deposited data, characters cannot exist independently of matrices. That is, to exist in your project at least one matrix must reference the character. Put another way, if you delete a matrix all characters referenced only by that matrix will be removed as well.

Both discrete and continuous characters are supported in Morphobank. Discrete characters describe a feature as a finite number of analytical states. Examples include "eyes: blue, green or brown" or "wings: present or absent". Continuous characters describe a feature using a decimal quantity or pair of quantities defining a range. Because these quantities are decimals, they can represent any real value and are thus mathematically continuous. (Well, not quite: Morphobank limits precision to 10 significant digits, but this should be more than enough for most analyses). Examples of continuous character values include "pH: 6.7" or "temperature range: 40.54C - 42.85C".

For discrete characters each state is assigned a name as well as a number, as well as any number of exemplar images. For example one might implement our previous example as "eyes: state 1 (blue), state 2 (green), state 3 (brown)." These numbers are used when scoring. For continuous characters a single specific quantity or a pair of quantities defining a range must be specified. The units for the quantity are specified in the character description. Each score is simply a decimal value, or pair of values defining the minimum and maximum of a range.

Characters may also have bibliographic citations and member comments attached. Images may also be associated with the character independent of a specific state.

Other data

Any number of documents can be added to a project. Documents may be in any format, and can document aspects of the project or provide data in formats that are not directly supported by MorphoBank. Each document may include an optional title and description, and may be published along with other data (media, matrices, etc.) or kept private to the project.

When a project is published, all documents with a "publish when project is published" status will be listed and made available for download on the project's MorphoBank project page, accessible from the project browser and through the site search.

Tools for Collaboration

MorphoBank provides many advantages over traditional desktop software for collaborative workgroups. As a web-based system, it is available to anyone with internet access and reasonably modern web browser software, including Internet Explorer versions 8 and 9, FireFox versions 5.0 or better and Safari 5.0 or better. There is no need for specialized software; virtually every modern operating system is supported (Windows, Mac OS X and Linux/Unix). Furthermore, because all project data are centrally stored in the MorphoBank database, collaborators are always using the most up-to-date data. This is in marked contrast to collaborative projects using traditional desktop software where versioning issues often quickly become frustrating and time-consuming. Upgrades and bug-fixes to the MorphoBank software are done on a central server ensuring that all users are always benefiting from the most up-to-date version of the software.

Membership

Up until the project is published, a project's creator (who is also known as its' "project administrator") may grant collaborators access. Any number of collaborators can be invited and they need not already be registered MorphoBank members to receive an invitation.

Figure 2.6. Membership type menu

Membership type menu


There are four types of project membership:

  • Full members may add, edit and delete project data, subject to access restrictions on individual data items discussed below.

  • Observers may view all project data but are not allowed to add or change data in any way.

  • Character annotaters may add, edit and delete all project data except characters and character states, subject to access restrictions discussed below.

  • Bibliography maintainers may only edit bibliographic entries. The can also view project data.

Reveiwer Access

Project Administrators can enable an anonymous reviewer login for their project in the Project Info form accessed through the "Edit project info" link on the Project Overview page. Once enabled, reviewers can login by entering the project number in the email address field and the reviewer login password entered by the Project Administrator in the Project Info form. Don’t forget – you have to tell editors and reviewers your project number and reviewer password when you invite them to review your project.

Managing access to data

MorphoBank adopts a streamlined approach to data access within a project. All primary data items (taxa, characters, specimens, media and matrices) are "owned" by the member who created them. The owner has the option of reserving editing access for themselves or allowing all full project members to edit. (Editing access includes the ability to delete an item.) By default all newly created items are editable by all; restricted access must be explicitly set by the creator.

Figure 2.7. Access control menu

Access control menu


Tracking changes to your data

Changes to all data items and their constituents (taxa, characters and states, specimens, media and matrices including cells, taxa and characters and states) are logged by MorphoBank. Detailed change histories for any item, including the nature of the change, the time and date and who executed the change, may be accessed by project members.

Publishing

Newly created project workspaces are unpublished. Their contents are available only to members of the project, and to anonymous reviewers if anonymous reviewer access is enabled. When your research is completed you can publish your project, which will have the following effects:

  1. Data will be publicly accessible via the MorphoBank search engine and project browser.

  2. Data will be accessible using MorphoBank PermaLinks (see the section called “ Linking to a published project using permalinks). Permalinks are unchanging, easy-to-cite URLs that will always lead to your project data. They are a convenient way to cite data hosted on MorphoBank in a published paper.

  3. Your project is effectively frozen, just as with a traditionally published scientific paper. Data can no longer be modified and members no longer added. However, building on your data simply requires the creation of a new project.

The last item is particularly important. As with a paper or book, a project shouldn't be published until you are sure all elements are as you and your collaborators wish them to be.

Deleting a Project

Project administrators can delete entire projects if they are no longer useful and will not be published. Simply navigate to "Edit Project Info" on the right-hand side of the Project Overview screen, and then scroll to the bottom of the page where the options "Save," "Cancel," and "Delete" appear beneath the publishing switch. "Delete" will only be visible to Project Administrators.

Copyright considerations

MorphoBank does not own or assert any copyright on project data. Once a project is published, it becomes publicly accessible and the copyright status of the constituent data becomes a concern. In general, before uploading an image (or other data) to your project, make sure that one of the following applies:

  1. You own the rights to the image (usually meaning that you created the image yourself).

  2. You can prove that the copyright holder has licensed the image under a free license.

  3. You can prove that the image is in the public domain.

  4. You believe, and state, a fair use rationale for the specific use of the image that you intend.

  5. You have obtained the required clearances from the copyright holder that specifically allow you to use the image on MorphoBank.

When cataloging media you will have the opportunity enter information about the copyright status of the media file you are uploading. You will first be asked to indicate if the media is under copyright by checking the "Is under copyright?" checkbox. Leave this box blank if the owner of the media you are loading wants to release those media to the public domain (a CC0 designation). Checking the checkbox will add additional elements to the form to allow you to apply a different copyright license, indicate who the copyright owner is and that they have granted you permission to use the media in MorphoBank.

Selectively publishing project content

By default, when a project is published all data in it are made publicly accessible. It is possible, however, to keep specific media, matrices, folios and documents in a published project un-published. To hold back an item you must change the item's status from publish when project is published to never publish to project prior to publishing the project. The item status drop down, shown below is present in the primary editing forms for media, matrices, folios and documents.

Warning

Once a project is published you cannot change the status of any items in that project.

Figure 2.8. Item-level publishing status menu

Item-level publishing status menu


Linking to a published project using permalinks

Each MorphoBank project is issued a unique identifier beginning with the letter 'P' for project. This identifier is displayed in many places throught the site, for example it is next to your project title in the My Projects list and in the breadcrumbtrail at the top of the page when editing a project. Once your project is published you may link to your project with a URL in the format http://morphobank.org/permalink/?P00 where 'P00' is replaced with your project identifer. This URL will always lead to your data and is a reliable way to cite MorphoBank-hosted datasets in published papers.

An alternative linking scheme based upon the Life Sciences Identifier (LSID) standard is in the works and will be available in an upcoming software revision.

Warning

For unpublished projects, the only way to access data is by logging into MorphoBank.

DOIs for MorphoBank Projects

Beginning in Spring 2014, MorphoBank will issue DOIs (Digital Object Identifiers) for each project and for each individual matrix within a project at the time of publication. Once the project is made public, the DOI number for the project as a whole will displayed below the abstract on the Project Overview page:

Figure 2.9. Project DOI

Project DOI


and the matrix DOIs will appear on the Matrices detail page:

Figure 2.10. Matrix DOI

Matrix DOI


This feature is not retroactive and will only apply to projects published after April 2014.

Other ways to access published data

In addition to permalinks, published data is accessible:

  • as lists of published matrices, media, views for media, folios, specimens, taxa, bibliographic citations and documents linked to from a project summary displayed in the Browse Projects section of MorphoBank. All published projects on MorphoBank are displayed in the Browse Projects section. You can browse projects by Publication Date, Project Number, Project Title, Author, Publication and Taxonomy. When browsing by Publication date, icons are displayed to provide direct access to project home page, 2D/3D/audio/video media, matrices and documents. The lists of project data are similar to those found in the MorphoBank editing interface, but without editing capabilities.

  • in the MorphoBank search engine. Your media and matrices will be included in the results of searches on the MorphoBank.org site.

Figure 2.11. Browse Projects list

Browse Projects list


Project summary information

It is important that as much information as possible about a project is provided before it is published. In addition to project preferences and review login information, the project information form contains fields for the following information that is used to display a summary of your project in the Browse Projects section of the site and on the Project Overview page:

  • Title. The title of your project, not necessarily the same as your article's title.

  • Abstract. The abstract for your project. This is often, but not necessarily, the same as that of your published article.

  • Exemplar Media. The media file you would like to feature in your project summary.

  • Journal title. If the project data serves as the basis of a published article, this and the following fields should be filled in with citation information.

  • Journal url. Address of your published article online.

  • Journal volume. The journal volume in which your article appears.

  • Journal number. The journal number in which your article appears.

  • Journal year. The year of the journal in which your article appears.

  • Journal logo image. For journals already appearing in MorphoBank, a journal logo will automatically appear when the journal title is selected. If you are entering a new journal in MorphoBank, curators will add a journal logo at the time of project publication. Feel free to contact support to ask for the journal logo to be added to MorphoBank.

  • Article authors. The list of article authors as it should appear in a citation.

  • Article title. The article title as it should appear in a citation.

  • Article pagination. The article pagination as it should appear in a citation.

Many of these fields are used on the project summary page when the project is published. If you fail to fill in these fields your summary page will be incomplete and will improperly cite your article. Be sure to fill out all fields fully and accurately.

Warning

You must specify at least a working title for your project. An abstract is strongly recommended for all projects at all times and must be provided before the project is published.

Folios

Folios are a useful mechanism for publishing annotated groupings of selected project media. Using the folios tab, you can create as many named folios as needed. You can then select specific media to add to your folios by clicking the "Edit folio media" link in your list of folios or by using the "Folio options" tool on the Media page. This tool allows you to add multiple media to a folio directly from media search results. Once you have added items to your folio you can return to the folios tab to change the order of the media and preview the resulting folio. Folios are published when the project is published, unless you set your folio's access dropdown to "never publish to project" and may be linked to using a permalink URL in the format: http://morphobank.org/permalink/?F00 where 'F00' is your folio identifier. Folio identifiers always begin with the letter 'F' and appear next to the folio name in the project folios tab. Your project must be published for folios to be accessible to the public.

An example of a folio in use: you want to reference a sequence of images in a paper but there is not enough space, so you opt to publish the images online and print the URL in the paper. If those images are in your published MorphoBank project you can create a new folio (complete with title and introductory text), add the relevant images and place them in the proper order. When readers go to the URL printed in the paper they will see your introductory text and be able to click through to each image in the proper order.

Chapter 3. Common Types of Projects

MorphoBank provides a generally useful set of tools to assist you with your research. While no particular workflow is mandated, many MorphoBank projects tend to fall into one of the three categories, described in the following sections. Your work need not conform to these examples, but they should give you an idea of the types of project for which MorphoBank can be useful.

Phylogenetic Projects with Matrices

MorphoBank's most important innovation is the support of collaborative editing of phylogenetic matrices and associated data (taxa, characters and states, cells with or without images, bibliographic citations), thus it includes a full-featured browser-based matrix viewing and editing application. This, combined with its ability to integrate annotated media with matrix cells, characters and character states make MorphoBank a natural fit for projects developing matrices.

MorphoBank is able to import and consolidate existing matrices contained in NEXUS files. This means you can take existing datasets created in MacClade, Mesquite, NEXUS Data Editor, or any other NEXUS-capable application and bring them into MorphoBank for collaborative editing, addition of media and, ultimately, online publishing.

MorphoBank can also output matrices in NEXUS, allowing MorphoBank to be integrated into an analytical workflow that includes NEXUS consuming programs such as PAUP.

Image-only Projects

While its matrix tools are a major asset, you don't need to be developing matrices to use MorphoBank. MorphoBank also provides a robust set of tools to view, annotate and classify (taxonomically and otherwise) large sets of images.

A Batch Media Upload tool allows you to upload large numbers of images for streamlined tagging with metadata. Many file formats are supported, including most popular image and video formats, and all files are automatically converted into web-viewable formats and sized appropriately. A media browser allows you to filter by taxonomic name and/or view, or to search for specific items. And MorphoBank's built-in pan-and-zoom viewer allows users to view high-resolution images online efficiently by preserving the full resolution of the uploaded file and only downloading the portions of an image that are actually visible on screen.

Its media handling features, its support for collaborative workgroups and web-based nature make MorphoBank an ideal plaform for:

  • sharing images with your colleagues in a password-protected environment

  • developing an image-based dataset with colleagues

  • publishing media online in support of a manuscript

Collaborations Fusing Large Lists of Characters and Taxa from Many Matrices

For projects merging many source matrices into one large matrix where there may be a subsequent need to evaluate, merge or edit extensive lists of characters and taxa by consensus, MorphoBank's taxonomic and character directories can provide useful services.

In a typical super-matrix project, a group of experts convene to survey existing literature for characters and, perhaps, taxa to be included in a single "super-matrix" covering all significant aspects of area of taxonomy. MorphoBank's central character list provides a tool for managing large lists of characters, annotating them with notes, reordering them arbitrarily, and attaching exemplar images to characters and specific character states.

It is particularly critical in projects of this type that all participants have access to the most up to date data at all times. MorphoBank's centralized database and web-based access ensures that this is always the case.

Chapter 4. Navigation

One navigates among the various tools and options in MorphoBank using the main navigation bar at the top of the screen and the left, sub-navigation menu available on some site sections. The main navigation bar is composed of links which lead to a specific section of the site or tool.

The top-level set of links, as shown in the figure below, is the most general and provides access to the following features:

  • Home: a link to the home page of MorphoBank.org. This link is only available when you are not logged in to MorphoBank.

  • My Projects: once you have logged in to MorphoBank, the Home link is replaced with the My Projects link. The My Projects section of the site is where you will find a list of your current projects, have the ability to make new projects and get access to all project-specific setup and editing tools. This is where you will spend most of your time when using MorphoBank. This link is only available when you are logged in to MorphoBank.

  • Browse Projects: a list of project summaries for all published MorphoBank projects.

  • FAQ: A list of frequently asked questions and answers.

  • About: general information about the MorphoBank project.

  • Documentation: contains tutorials and guides, including this document.

  • Contact Support: contains a form for contacting MorphoBank system administrators. You can use this form to submit questions, bug reports and requests for new features.

  • Search: a search form you can use to search published projects, and when logged in, data in projects for which you are a member, no matter their status.

  • Log In: a form allowing existing members to log in to their account. This link is only available when you are not logged in to MorphoBank.

  • Register: a form allowing new members to register for access to MorphoBank. This link is only available when you are not logged in to MorphoBank.

  • Logout: a link to logout of MorphoBank. This link is only available when you are logged in to MorphoBank. It is displayed in place of the Log In link.

  • Profile: a form allowing members to update the information they provided during the registration process and change their account password or email address. This link is only available when you are logged in to MorphoBank. It is displayed in place of the Register link.

Figure 4.1. MorphoBank main navigation bar when not logged in

MorphoBank main navigation bar when not logged in


Figure 4.2. MorphoBank main navigation bar when logged in

MorphoBank main navigation bar when logged in


When editing a project in the My Projects section of the site or exploring a published project in the Browse Projects section, there will be additional sub-navigation options on the left-hand side of the screen resembling the menu shown in the figure below:

Figure 4.3. Typical side navigation bar

Typical side navigation bar


Chapter 5. How to Get Access

There are two ways to join Morphobank: through invitation or registration. To register fill out the form at http://www.morphobank.org/index.php/LoginReg/form/showRegister/1. Don't forget to include a brief and accurate description of your project. Registrations are immediately activated. Invitations to join MorphoBank can also be given out by current members who are the project administrators of a particular project and who wish to invite collaborators. To add a member to your project, click the Manage Members link at the right side of the Project Overview page. You will then see an Add New Member button that allows you to link existing MorphoBank users to your project or invite new memeber to join your project on MorphoBank. Once a new person has joined by either means, he or she is free to create his own new, separate projects.

We welcome and encourage students to join and use MorphoBank in their studies. It is the policy of MorphoBank, however, to request that the student's advisor be made a member of any student project.

Resetting the Password for an Existing Account

If you already have an account but have forgotten your password, click on the "Forgot your Password?" link on the login page. You will be presented with a page explaining how to reset your password. Simply enter your e-mail address on that page, click the "go" button and a message will be sent with a link to another page where you may enter a new password for your account.

If you are still having trouble after resetting your password, or you fail to receive the reset password e-mail, contact us via the Contact Support form linked to in the main navigation.

Note that once logged in you will remain logged in for up to 72 hours, unless you explicitly log out.

Duration of login

Note that once logged in you will remain logged in - even if you close or quit your browser - for up to 72 hours, unless you explicitly log out.

Chapter 6. Funding for MorphoBank

MorphoBank was built with funding to Maureen A. O'Leary from 2001 to the present. The work performed was prepared by the MorphoBank project, in part, under an award from the National Oceanic and Atmospheric Administration, U.S. Department of Commerce. This funding came from:

  • National Science Foundation, Division of Environmental Biology

  • National Science Foundation, Division of Geosciences

  • Stony Brook University, School of Medicine, Medical Informatics

  • National Oceanographic and Atmospheric Administration, U.S. Department of Commerce

  • NESCENT

The statements, finding, conclusions, and recommendations are those of the authors and do not necessarily reflect the views of the National Oceanic and Atmospheric Administration or the Department of Commerce.

Chapter 7. Citing MorphoBank in your publications

When you use MorphoBank please cite the software:

O'Leary, M. A., and S. G. Kaufman. 2012. MorphoBank 3.0: Web application for morphological phylogenetics and taxonomy. http://www.morphobank.org.

You may also be interested in citing the conceptual paper describing the the database and tool:

O'Leary, M. A., and S. Kaufman. 2011. MorphoBank: phylophenomics in the 'cloud'. Cladistics. 27:1-9.

Chapter 8. MorphoBank API

The MorphoBank public API supports HTTP GET requests for published resources. API documentation is available here.

Part II. Using MorphoBank

Table of Contents

8. Workflow
Creating a New Project
Setting Project Options
Naming your project
The project accession code
Setting citation information
Setting Up Context for Your Project
Media views
Taxonomy
Specimens
Bibliography
Adding Data
Media
Existing matrices
Creating new matrices
Inviting Collaborators
Editing Project Data
Publishing Your Data
9. Establishing Context for your Project
Media Views
Character and Taxon Partitions
Publishing Partitions
Managing Taxonomy
Finding taxa
Adding new taxa
Editing taxa
The Operational Taxonomic Unit (OTU)
Specimens
Finding specimens
Adding and editing specimens
Project Bibliographies
Adding bibliographic references by hand
Importing bibliographic references from EndNote
Searching
Exporting bibliographic data
10. Using Media (Images, Video, Sound)
Uploading Media
Supported media formats
Uploading and Viewing CT Scan Data
The add new media file button
Copyright Tools
Copyright Settings for Project Data: Matrices and Documents
Batch uploading media with the Batch Media Upload Tool
Batch Media Delete Feature
Using the Media Browser
View modes
Sorting
Filtering
Searching media
Importing Media from EOL.org and iDigBio.org
Using the MorphoBank Image Viewer and Annotator
Editing Media
Updating media
Labeling images in the Matrix Editor
11. Managing Characters
Character editor overview
Adding Characters
Adding a single character
Batch adding characters using a NEXUS file
Viewing lists of characters
Searching for characters
Moving characters
Editing characters
Edit basic character information ("character" tab)
Adding media to a character or character states ("media" tab)
Labeling media associated with characters
User comments for characters ("comments" tab)
Add Citation ("citation" tab)
Change history ("change history" tab)
12. Using Matrices
Starting a New Matrix
Importing a Matrix from a NEXUS Format File
NEXUS import caveats
Merging Several NEXUS Files into a Single Matrix
Editing
Tree-building Options
Editor overview
Characters
Character ontologies
Character Ordering in MorphoBank
Taxa
Cells
Making changes to your matrix data en-masse
Downloading a NEXUS-format copy
Deleting a Matrix
13. Folios
Creating Folios
Adding Media
Changing the Order of Media
Public Access
14. Project Documents
Adding a Document to Your Project
Document Folders
Public Access to Project Documents
15. Managing Access
Adding Members to a Project
Types of access
Removing a Member From a Project
Anonymous Reviewer Access
Item-level Access Control
Who Gets to Edit What?
16. Backing Up Your Data
The Download Package
Project media
Matrices in NEXUS format
Project documents
Uploaded NEXUS files
Project data in SDD format
17. Publishing Your Data
Project Information Fields
Accessing Published Data on MorphoBank
Citing Your MorphoBank-Hosted Data
18. Project Duplication
Contacting MorphoBank
Duplicating Published Projects
Duplicating Unpublished Projects
19. Staging a MorphoBank Project for the Evolution Project

Chapter 8. Workflow

MorphoBank provides a set of tools that can be employed in many combinations to solve a wide variety of research problems. With this flexibility comes complexity, which can make it daunting to get a project started and populated with data. This section outlines a typical workflow that has proven to be efficient and effective for most projects.

All project-specific tools are in the My Projects section.

Creating a New Project

All data in MorphoBank must belong to a project workspace, so the first step is always to create a new project.

Figure 8.1. Creating a new project

Creating a new project

To create a new project workspace click on the "Create new project" button at the top of the "My Projects" page. This will display a new Project Information form, which includes fields for project title, abstract, exemplar media, and citation information (fields for article and journal information.) You can also choose to allow reviewer login from this page, and set the reviewer login password. The Project Administrator can edit the Project Information form at any time by clicking "Edit Project Info" from the left side of the Project Overview page.

Figure 8.2. Portion of Project Information form

Portion of Project Information form

The creator of a project is by default its Project Administrator (PA). The PA has a few abilities beyond that of other project members:

  • Only the PA can invite new members to join a project.

  • Only the PA can change project information such as title and citation information.

  • Only the PA can publish a project.

    The Project Administrator can edit the Project Information form at any time by clicking "Edit Project Info" from the left side of the Project Overview page.

Setting Project Options

When you publish your project on MorphoBank, information from the Project Information form, including your abstract and citation information, will be used to describe it (see examples at http://www.morphobank.org/index.php/Projects/Index). Prior to publication this information remains accessible only to you and your collaborators. Although you may begin your project with only a title, it is strongly suggested that you include an abstract before publishing it. Don't worry if you do not have all of the information at the start of your project; you may update it at any time prior to publication.

Naming your project

When starting your project, give it as descriptive a title as possible. Prior to publication you will need to revise your title to reflect the published title of your findings.

The project accession code

Each project is issued a unique MorphoBank accession code. These codes are always the letter P followed by a number. The code for your project is displayed in many locations throughout the site. For example, it appears next to your project title in the list of your projects in the My Projects section of the site, in the breadcrumb trail at the top of the page, in the title bar of your browser window when you are editing a project, and in the title bar of your browser window. This code should be included in any e-mails to MorphoBank technical support. The project accession code is also used to construct PermaLinks to your project once it is published. You can learn more about PermaLinks in the section entitled the section called “ Linking to a published project using permalinks

Setting citation information

As your project proceeds toward publication you should fill in the other fields in the Project Information form. As mentioned, the project information form is available to the Project Administrator by following the "Edit Project Info" link on the right side of the Project Overview page. This information will be used to construct a citation and to present your project publicly on MorphoBank. For a description of all Project Information fields see the the section called “Project Information Fields”

Setting Up Context for Your Project

After creating your project and filling out the project title and abstract, the next step is to enter context. "Context" in MorphoBank takes the form of media views, taxonomy and specimen information, all of which provide a framework for your analysis.

It is usually best to load in all of your contextual information before loading analytical data. Of course, you can add additional taxa, specimens and views at any time.

For detailed information on using the contextual setup tools see Chapter 9 Chapter 9, Establishing Context for your Project.

Media views

"Views" are simple descriptors that are used to indicate the anatomical view displayed by images (and other media) in your project. They provide a straightforward means to categorize project media according to anatomical feature. MorphoBank lets you set up a drop-down list of views specific to your project using the Views for Media link in the project sub-navigation on the left-hand side of your window. You should establish the list of views used in your project early on, and definitely prior to uploading media.

Taxonomy

The next foundational step in setting up your project is assembling your taxonomy. As you enter taxa in your project workspace using the Taxa link in the project sub-navigation, MorphoBank builds a central taxonomic directory for your project. You may enter taxa in several ways:

  • one at a time using the taxon editor form.

  • in bulk using the Upload Taxa Batch feature.

  • in bulk by uploading a NEXUS-format matrix. All taxa contained in the NEXUS file will be automatically loaded into your project if they do not exist already. Note that NEXUS treats taxonomic identifiers as simple text. This precludes MorphoBank from establishing an accurate taxonomic hierarchy when extracting names from NEXUS files. You may need to perform some manual clean-up after uploading a NEXUS-format matrix.

Note that each taxon exists only once in a project, even if it is used by many specimens and/or matrices. Changes made to a taxon automatically propagate to all specimens and matrices that reference it.

Because entry of specimen and matrix data rely upon taxonomy being established, it is generally best to establish taxonomy early on in the project. You will not be able to create matrices unless taxa are defined, and specimen records will be incomplete.

All taxonomic editing features are located in My Projects > Taxa.

Specimens

As with taxonomy, MorphoBank provides a master directory of specimens used in your project. Because uploaded media need to be tagged with the specimen they depict, it is usually best to define specimens early on, but after taxonomy is established.

Note that each specimen exists only once in a project, even if it is used by many images or other media. Changes made to a specimen automatically propagate to all media that reference it.

All specimen editing features are located in the Specimens section when editing a project.

Bibliography

You can attach bibliographic citations to taxa, characters, media, specimens, matrices and scores in matrices. In order to create a citation your bibliographic references must already exist in the database, so it is generally best to enter these as early in your project as possible.

Once established, any subsequent changes made to the reference are automatically propagated to all citations that use it.

All bibliographic editing features are located in the Bibliography section when editing a project.

Adding Data

Once project options and context are established, you can start adding media and/or matrices to your project.

Media

Media are imagery, video or audio that document specimens. You can upload media in a variety of formats and at virtually any resolution. MorphoBank will automatically convert and resize the media to a web-viewable format with suitable dimensions, so unless you are creating media in an unsupported format you should be able to simply upload the files you have on hand. (For a list of supported media formats see the section called “Supported media formats”) In addition to the web-viewable versions of your upload that MorphoBank creates, your original file is retained and may be downloaded at any time.

Because media document specimens, it is important that your specimen information be entered before you start adding media. You can enter media without associating a specimen, but this is not recommended.

Media may be added to your project in two ways:

  • using the Add new media file button at the top of the screen.

  • using the Add media batchtab to upload batches of media.

Adding media using the add media button is described in detail in ???. Adding media using the Batch upload tool is described in detail in the section called “Batch uploading media with the Batch Media Upload Tool.

Existing matrices

As mentioned in the introductory portion of this manual, MorphoBank allows you to create matrices to visualize and organize your data. You can import existing matrices from NEXUS or TNT-format files. You can create NEXUS files using desktop programs such as MacClade (http://www.macclade.org), Mesquite (http://www.mesquiteproject.org) and NEXUS Data Editor (http://taxonomy.zoology.gla.ac.uk/rod/NDE/nde.html). When you import a NEXUS or TNT file, all of the taxonomy, characters and states, as well as cell scorings and notes, are imported into a matrix in your project. Once the matrix is imported, you can open the matrix editor and set your matrix preferences to reflect its format. For example, if you're importing a TNT file, you can set your matrix preferences to "TNT" so that your TNT project will remain intact upon project publication and numbers will start from zero.

Figure 8.3. Matrix "Preferences"

Matrix "Preferences"


MorphoBank does not have tools for manipulating trees or genetic data. Therefore any NEXUS data blocks present in the file that are not supported by MorphoBank (trees in a TREE block, for example) are imported as-is and exported untouched. It is possible to edit directly the text of imported NEXUS blocks, but you should only do this if you know what you're doing.

You may merge several NEXUS or TNT files into one MorphoBank matrix by importing them sequentially into the same matrix. Simply create a new matrix using one file, then click the "Edit matrix description" link in the list of project matrices. At the bottom of this form, you will see the option to " Merge a NEXUS or TNT file with this matrix". Selecting this checkbox will present with a file upload field to merge a NEXUS or TNT file with the exisitng matrix. As additional files are successfully imported MorphoBank will give you taxon, character and cell scoring totals for both the current file and the merged matrix. Any characters and taxa present in the uploaded NEXUS or TNT file but not in the matrix will be added to the matrix. Cell scores for existing taxa/character pairs will be merged with the existing matrix data. If you want to upload a NEXUS or TNT file without merging into an existing matrix, create a new matrix using the Add New Matrix button at the top of the page.

In some cases an existing NEXUS or TNT file can serve as an "instant project." Because MorphoBank can import all taxonomy and characters from a matrix, if your data are already in NEXUS format you can accomplish a good part of your project setup with a single file upload. (Note that you would still have to enter specimen information, which has no formal representation in NEXUS, separately).

The NEXUS format treats taxonomic names as simple strings of text. There is no formal delineation of taxonomic hierarchical rank. Because hierarchy information is not present in NEXUS files MorphoBank assumes that the first word in each taxa is the operational taxonomic unit, and that each subsequent word is one level below in the hierarchy. For example, if the OTU is set to genus, then all names will be interpreted as genus/species/subspecies. This is an admittedly imperfect system, but for many data sets it does an adequate job. What this means in terms of workflow is that unless your taxonomic ranks are uniform, you will need to do some clean up after importing a NEXUS file into MorphoBank. Also if the predominant OTU in your project is above the species level be sure to set the OTU for that level (e.g., Family)

Note that NEXUS is a loosely defined format that has never been definitively standardized (see https://www.nescent.org/wg_phyloinformatics/Supporting_NEXUS_Documentation for an interesting discussion about NEXUS limitations). Various software applications import and export NEXUS in subtly inconsistent and incompatible ways. MorphoBank tries to accommodate as many features and oddities as possible but there are still a number of caveats. These are discussed in detail in the section called “Importing a Matrix from a NEXUS Format File”

Creating new matrices

You may also create matrices in MorphoBank from scratch. Simply click on the Add new matrix button at the top of the Matrices page, enter a title for the matrix (and any other pertinent data the form asks for) and click "save." Then you may click "edit matrix" to begin editing. You may merge NEXUS or TNT files into your matrix at any time, if needed, by using the option ("Upload an existing NEXUS or TNT file as the basis of your project") at the bottom of the Create a Matrix from Scratch form.

Inviting Collaborators

The Project Administrator (PA) - the creator of the project - may invite anyone with a valid e-mail address and web access to join their project. If the invitee is already a registered member of MorphoBank they will receive an e-mail notification and the project will appear in their My Projects list the next time they login. If the invitee is not a registered member of MorphoBank, they will receive an e-mail notification with login instructions and a pre-issued password.

In a typical workflow, the PA will create the project, setup the context and preload a basic set of data, and then invite collaborators to start editing the dataset.

When inviting collaborators, the PA can grant full membership, character annotator, bibliography maintainer or observer status. Full members may edit any item in the project, subject to item-level access restrictions. Observers may not modify anything in the project, no matter the access restrictions on items. Character annotators are prevented from editing characters and character states. Bibliography maintainers are limited to editing bibliographic data only.

The controls to invite collaborators are located in the Members form accessed by the PA from the link in the right bar of the Project Overview page.

Note that an additional type of access - anonymous and read-only - is possible using the reviewer login settings on the Project Information form accessed by the PA from the link in the right bar of the Project Overview page. As the name suggests this type of access is designed to accommodate anonymous publication reviewers.

Editing Project Data

Once you've established your data set and granted project members access, collaborative editing can begin. All full-access members can add data elements (taxa, characters, matrices, media, etc.) to the project as needed. Access control for individual elements in MorphoBank is simple: the creator of a data element "owns" it and can either elect to allow anyone in the project to modify it, or reserve that right for themselves. This form of control is subject to a user's overall access level. An observer cannot edit elements, no matter the items's access setting, even if the observer had created the element at a time when they had full access.

All changes to data elements are logged by MorphoBank. A change history for any object can be viewed by selecting the Change History tab or side bar element in the element editor. The change history log will include the date and time of each change, who made it, and the nature of the change - enough information to undo the change if necessary.

Every project includes a Project Overview page that summarizes the state of the project, the number of changes that have been made in the past day, weeks and month, and the relative contributions of each member of the project.

Publishing Your Data

Typically, MorphoBank is used to document research that supports a paper published in a peer-reviewed scientific journal. When the time comes to make your data public, the PA should complete the Project Information form with final citation information (including an abstract, exemplar media, article information, and journal information.) They can then use the Publish Project link (also located on the right side of the Project Overview page) to publish their project. Once the Publish Project form has been completed, the project will be publicly accessible on MorphoBank via the site search, the Browse Projects list and by "PermaLink." PermaLinks are stable web addresses (URLs) that can be used to cite MorphoBank-hosted data in papers and in online postings. More on using PermaLinks is available in the section called “Citing Your MorphoBank-Hosted Data”.

Warning

Once you change the project status to "published" you cannot change it back, nor will you be able to further edit your data. Be sure your project is complete before publishing it! If you accidentally publish your project and need it unpushlished, contact technical support via the online form available from the Contact Support link in the main navigation.

Remember - if your matrix was created from an imported TNT or Nexus file, it is important to check the matrix preferences before publishing. Because you will no longer be able to make changes to a project once it is published, you must be sure that your “character and taxon numbering mode” is set to “Nexus” if you want \numbering to start with 1, and “TNT” if your numbering should start at 0.

Chapter 9. Establishing Context for your Project

As we have seen, "context" in MorphoBank refers to the views, taxonomy and specimen data that provide a framework for your analysis. The MorphoBank tools for managing the data are explained in the following sections.

Media Views

Views are simple descriptors used to indicate the anatomical view displayed by images (and other media) in your project. They provide a straightforward means to categorize project media according to anatomical feature. MorphoBank lets you setup a drop-down list of views specific to your project in the Views for Media section.

To see a list of existing media views, add a new view or edit or remove an existing one, click on the Views for Media link in the sub-navigation on the left side of your window when editing a project. "Edit" and "delete" buttons next to each view allow you to manage existing views. To create a new view click on the "Add new media view" link on the top of the page.

Character and Taxon Partitions

Partitions are organizational groups for taxa and characters. You create as many partitions as needed, and a taxon or character may belong to as many partitions as exist.

Character and taxon partitions are managed through the MorphoBank matrix editor. To create new partitions open a matrix in the matrix editor and click on the Partitions button on the button bar at the top of the editor.

Figure 9.1. The partitions button in the matrix editor button bar

The partitions button in the matrix editor button bar

Figure 9.2. The partition editor

The partition editor

To create a new partition click on the "add partition" button. To remove an existing partition first click on it once to highlight it, then click on the "delete partition" button. Note that deleting a partition is permanent and cannot be undone. However, only the partition itself is deleted. The characters or taxa that were part of the partition are not removed from the database.

To rename an existing partition double-click on it. An editing window, in which you can alter the partition name and/or description, will appear.

To add characters or taxa to a partition click on the partition once to highlight it, then drag characters or taxa from the "not in partition" list to the "in partition" list. To remove characters (or taxa) reverse this operation by dragging from the "in partition" list to the "not in partition" list.

The "Show partition in matrix editor" drop-down lets you refine the matrix editor so that it displays only one partition at a time. When selected only the characters or taxa in the partition are visible and editable, thus enabling a more streamlined editing experience. All changes to the matrix editor display are applied when the "done" button is clicked.

Publishing Partitions

Since a partition represents a discrete portion of your project, you may choose to copy (or "publish") a partition while keeping the rest of your project private. To do this, select the Publish a Partition link from the right-hand side of the Project Overview page. This link will take you to a screen entitled "Partition Publishing" with a drop-down list that displays all of the partitions in your project. Select the partition you wish you isolate, and all of the taxa and characters in your partition along with any associated matrix data, media, specimens, views, labels, character notes and cell notes will be copied. All bibliographic references and documents from the project, regardless of partition, will be copied as well, as will any media related to project bibliographic references. The result will be a new project separate and independent from the initial project containing only the partition-defined subset. Subsequent changes made in either this project or the published partition will not be reflected in the other. This tool is useful if you wish to focus on refining a specific portion of your data, or if you wish to make one portion of a large project publish while keeping the rest private. Note that when you use this tool – the daughter partition does not go live immediately. It is entered into your queue of unpublished projects. This way you can set the partition to be anonymously reviewed if you wish, and can enter the new project number into your publications.

Figure 9.3. Publishing Partitions

Publishing Partitions


Managing Taxonomy

Taxonomy is a critical part of any MorphoBank project; it is the basis for your context and analysis. You cannot create specimen records or matrices from scratch without loading taxonomic names. The sections below describe MorphoBank's tools for taxon loading and management.

MorphoBank maintains a central directory of the taxonomic names you enter for each project. This directory is specific to your project and not shared across project workspaces. The directory lists each taxon once - no duplicates are allowed. Matrices and specimens using the same taxon are actually referring to a single entry in the taxonomic directory. This means that if you modify a taxon, the change will be reflected everywhere it is used in your project.

Finding taxa

To view the taxonomic directory click on the Taxa link in the project sub-navigation bar.

Figure 9.4. Portion of the taxonomic directory

Portion of the taxonomic directory


Taxa are browsable in a variety of ways as shown in the above figure. You can use the search function to find a specific taxon, you can browse alphabetically, and you can limit the displayed taxa to a specific partition or matrix. Taxa may also be edited or deleted using the respective buttons. When you click "edit" you will see the same form you would use to enter a taxon in the first place, which will be described in further detail in section 9.3.2 Note that if you delete a taxon, it will be removed from all matrices and specimen records that refer to it.

Warning

Think before you delete a taxon! Deleting a taxon will cause it to be removed from all matrices and specimen records that refer to it. It will also cause all matrix scores, cell images and cell media labels associated with the taxon to be deleted.

You can search taxa by entering any part of the taxon name into the search box and clicking on the "search" button. Partial matches can be made by using the asterisk ("*") wildcard character. For example, to find all taxa starting with the letters 'aeto' search on 'aeto*'

Adding new taxa

In this section, we will discuss the steps you must take to add a new taxon or taxa to your project as you build your taxonomic directory.

Minimum data requirements

At least one element of the taxonomic name must be specified. While some users may prefer to express complete names, from kingdom to subspecies, this is not required. All fields are optional.

Adding a single taxon

To add taxa one at a time, click on the "Add new taxon" button on the top-left of the Taxa page, then fill in all applicable fields in the new taxon form and click on the "save" button. In addition to defining the fields in this taxon, you can also use this page to define who can edit the taxon, and how the taxon author's name should appear in citations. In addition, if the taxon is extinct check the "is extinct" checkbox.

The Taxonomic Authority Checker

When adding taxa by hand (or reviewing taxa after a batch import) you can employ the "Taxonomic Authority Checker" to look for possible matches for a given taxon. Several online taxonomy sources will automatically be searched, and you can pick and choose among the hits at these sources to do such things as affiliate your taxa with higher taxonomy. Note - as of 2014 this tool is undergoing an upgrade. Check back here for updates.

Batch adding taxa using a tab-delimited file

You can add a set of taxonomic names to your project in one go by clicking on the "Upload taxa batch" link and using the displayed form to upload a properly formatted taxon file.

A taxon file is simply a specially formatted tab-delimited text file. Each line of a taxon file represents a single taxon and is split into several columns, one for each component of the taxon, separated by TAB characters. The first line of the file is reserved for column labels. You must label your columns using the following labels: Kingdom, Phylum Class, Subclass, Order, Suborder, Superfamily, Family, Subfamily, Genus, Species, Subspecies, Author, Year and Notes.

The labels must be entered exactly as displayed above or your file will be rejected. You may omit any column not used by your data - all columns are optional. However, at least one of the name columns must be defined. The "notes" column is intended for taxon-specific notes you wish to associate with the new taxon. You may enter the author with year separated by comma (eg. "Schwartzenegger, 1879"), or you may place the year in the separate "year" column. Surround the author's name with parentheses if you wish it to display that way.

Although any text editor may be used to create taxon files, it is usually more convenient to employ spreadsheet software such as OpenOffice or Microsoft Excel and a sample file to get you started. Note that you cannot upload Excel files to MorphoBank. You must save your Excel files as tab-delimited text before uploading them to MorphoBank.

Batch adding taxa using a NEXUS file

When uploading a NEXUS file to create a matrix, all taxa present in the file are automatically added to the taxonomic directory. This is a collateral effect of importing a matrix but can be used to batch add taxonomy and is especially convenient if your data is already in NEXUS format.

The NEXUS format treats taxonomic names as simple strings of text. There is no formal delineation of the hierarchical elements present in a taxon. Because hierarchy information is not present in NEXUS files MorphoBank assumes that the first word in each taxa is the operational taxonomic unit, and that each subsequent word is one level below in the hierarchy. For example, if the OTU is set to genus, then all names will be interpreted as genus/species/subspecies. Although this is an admittedly imperfect system, it performs acceptably for many data sets. Unless your taxonomy is uniform you may need to do some clean up after importing a NEXUS file into MorphoBank.

Editing taxa

To edit a taxon, find it using any of the provided tools - search, browse by first letter of name or list by matrix or partition - and click on the taxon's "edit" button. You can then change any of the values of the taxon using the provided form. Note that changes made to a taxon will affect all matrices and specimens that refer to it.

The Operational Taxonomic Unit (OTU)

In MorphoBank, the OTU function allows you to set a rank for the taxa in your matrix. Each matrix in your project has a default OTU that applies to all taxa without an otherwise specified OTU. If you want to ensure that a taxon always has a specific OTU you must set it in the taxon form when adding or editing. If you have OTUs of different ranks and are starting a project by uploading a matrix, select the rank most commonly found and the then make adjustments by hand for taxa that do not fit that rank.

Specimens

As with taxonomy, MorphoBank provides a central directory for specimens used in your project. Each specimen record contains catalogue information, a reference to a taxon in the project taxonomy directory and, optionally, notes and metadata tags (the latter primarily taken from the Darwin Core standard).

Finding specimens

To view the specimen directory click on the Specimens tab in the project tool tab bar.

Figure 9.5. Portion of the specimen directory

Portion of the specimen directory


You can view lists of all the specimens for a given taxon by first letter of their taxonomic name using the "Show specimens whose [x] begins with..." bar as shown in the above figure. Specimens may be edited or deleted using the respective buttons. Note that if you delete a specimen, it will be removed from all media records that refer to it.

You can search project specimens by entering any part of the taxon name, catalogue number or notes into the search box and clicking on the "search" button. Partial matches can be made by using the asterisk ("*") wildcard character.

The "show unidentified specimens" button in the upper-right hand corner of the specimen list will restrict the list to show only those specimens without an associated taxon.

Adding and editing specimens

To add a specimen, click on the "Add new specimen" link in the upper-right hand corner of the tab, then fill in all applicable fields in the new specimen form and click on the "save" button.

To edit a specimen, find it using any of the provided tools - search or browse by first letter of name - and click on the specimen's "edit" button. You can then change any of the values of the specimen using the provided form. Note that changes made to a specimen will affect all media that refer to it.

Figure 9.6. Specimen entry form for vouchered specimens

Specimen entry form for vouchered specimens


Minimum data requirements

MorphoBank requires differing information for specimen data obtained from various sources. The specimen reference source drop-down determines which fields appear in the specimen entry form. The form shown in Figure 9.6, “Specimen entry form for vouchered specimens” is for vouchered specimens. Two types of specimen data sources are possible:

  • Vouchered specimens - specimens in a collection with a formal numbering and (ideally) accessioning system.

  • Unvouchered specimens - specimens cited in past literature, for which there is no actual vouchered specimen, specimens cited on the Internet at a specific URL or some other un-numbered source.

For vouchered specimens, at an absolute minimum you must provide the institution code and catalog number for the specimen. Both of these values should conform to the standards of the institution from which the specimen originates. If you are not sure of the formats for these values, contact the institution's collections manager. Typically, the institution code will be a 2-4 letter abbreviation of the institutional name (eg. AMNH = American Museum of Natural History, YPM = Yale Peabody Museum). Whenever possible a collection code should be provided. As with the institutional code and catalog number, this should conform to institutional standards. Many, but not all, institutions use collection codes. As you type codes into the institution and organization fields, MorphoBank will suggest possible values based upon previous user input. If possible you should use a suggested value.

For specimens cited from a manuscript, either provide as much of the citation information as possible or link to a reference in your project bibliography

For internet references, at an absolute minimum the URL (ideally a persistent URL, LSID or handle) must be provided.

A taxonomic identification of the specimen should be provided for all specimens and is used by the matrix editor to retrieve relevant media, and by the media search/filtering system.

Project Bibliographies

MorphoBank provides a facility for managing bibliographic references for your project, including, most importantly, the paper to which your project primarily refers. You can import from your bibliography from the popular EndNote citation management software or any other software that can export in EndNote XML format. References in your bibliography may be attached (with specific page numbers and comments) to taxa, characters, specimens, media, matrices and matrix cells in your project.

Unlike most other MorphoBank data, project bibliographies can be shared across multiple projects. Thus you can establish a single bibliography and cite it across all of your MorphoBank-hosted workspaces. The process of linking projects together so they can share a bibliography is described below.

Figure 9.7. Project bibliography list

Project bibliography list


The bibliography can be navigated alphabetically by author's name or searched. If you edit an existing reference that is already used in citations for your project data, then any changes made will automatically propagate to the citations. As shown below, if you try to delete a reference that is used by existing citations you will be shown the list of items (taxa, characters, media, etc.) that cite the reference and given the option to shift the citations to another reference.

Figure 9.8. Deleting the bibliographic reference that is used in citations

Deleting the bibliographic reference that is used in citations


To shift citations from a to-be-deleted reference simply type the first few letters of the title or author name for the reference to which you wish to switch. A list of possible matches will appear. Pick the relevant reference and click on the "delete" button.

Adding bibliographic references by hand

You can add a reference to your bibliography by clicking on the "Add new bibliographic reference" button in the upper-right-hand corner of the bibliography display. You will see a form like the one below. Follow the data-entry guidelines shown on the form and in the tips visible when mousing over the "(help)" buttons above each form field, filling in as much information as you can. Then click the "save" button.

Figure 9.9. Editing a bibliographic reference

Editing a bibliographic reference


Importing bibliographic references from EndNote

You can import existing references from any program that can output data in the EndNote XML format. After you have exported your XML file, open your MorphoBank bibliography, click on the "Import Endnote XML file" button in the upper-right-hand corner of the bibliography display, then choose the XML file on your computer using the file-browse button. You will be presented with the results of the import when it is complete. When a project bibliography is already populated with an endnote file and someone uploads another one, the new file will generally append itself to the list of references. However, if a user imports another EndNote file which contains citations that were present in a previously imported EndNote, the related citations are updated. For example, if a user adds another EndNote file that has 3 new citations and 2 citations, which were previously added, the import will add the 3 new citations to the database and update the 2 citations to reflect the new information.

Searching

The bibliography is fully searchable. Simply type in a word or words and click on "search." The search covers all fields in the bibliography.

Exporting bibliographic data

You can export your project bibliography as a tab-delimited file suitable for import into Microsoft Excel, EndNote and other similar programs. Simply click on the "Export as Endnote TAB-delimited file" in the upper-right-hand corner of the bibliographic display. A file containing all of your project's references will download to your computer's desktop.

Chapter 10. Using Media (Images, Video, Sound)

Uploading Media

Media should be a key component of any MorphoBank project. Virtually all MorphoBank projects include media, and many contain hundreds or thousands of media items. (Because MorphoBank supports video and audio files as well as imagery, the more general term "media" is used in place of "images.") MorphoBank allows you to upload as many media as needed, to use media to document scorings in your matrices and to assemble media into annotated groupings ("folios" - see Chapter 13, Folios) for online publication.

Regions of uploaded images may be labeled using tools integrated into MorphoBanks's high-resolution pan-and-zoom image viewer. If the labels are added to an image in a matrix cell the labels will be associated specifically with that cell and automatically include the taxon and character names.

Uploaded media can (and should) be tagged with the specimens they depict as well as a view descriptor (see the section called “Media views”), relevant citations from your project bibliography and Darwin Core-compatible metadata. A media browser allows project members to conveniently browse and filter large quantities of multimedia data.

Original uploaded media files are always retained by MorphoBank and may be downloaded at any time. Thus, you should always upload your media at a resolution and quality suitable for research work, even if that file is too large for convenient use on the web.

MorphoBank will automatically convert uploaded media to web-viewable formats at appropriate resolutions and quality for web use. This largely frees you and your collaborators from tedious media conversion tasks. If your files are in any of a number of mainstream formats no pre-processing on your part should be necessary.

MorphoBank includes a built-in image viewer that, in addition to providing labeling tools, allows users to pan-and-zoom over a full-resolution version of your images. Because it sends only the portion of the image that is actually visible, even very high-resolution imagery is usable on a normal internet connection in MorphoBank. The image viewer also supports image labeling functions.

Supported media formats

MorphoBank accepts a variety of image formats including JPEG, GIF, PNG, TIFF, .PLY, .STL, .ZIP, .DCM and PSD (Photoshop). Note that Photoshop files using layer effects may not render properly on MorphoBank. For the most consistent results we recommend converting these files to TIFF format prior to upload. All image files should be in RGB mode. Files in CMYK mode may not render properly. You should upload image files at the highest resolution that makes sense for your project. MorphoBank will automatically create sized versions for use on the site as well as a full resolution version optimized for online viewing. The original uploaded file will be retained and made available for download. MorphoBank also accepts QuickTime, WindowsMedia and MPEG-4 video files, as well as MP3, WAV, AIFF and AAC audio files. MorphoBank does not accept Microsoft Word, PowerPoint or Excel files. If you need to use images from a PowerPoint presentation, you should export them from PowerPoint in a supported format such as TIFF or JPEG and then upload those files.

The preferred video file format for upload to MorphoBank is MPEG-4 (with or without h.264 compression). Files in QuickTime and WindowsMedia format will usually work, although some older compression formats may not be supported. In general if your uploaded file is being rejected by MorphoBank it is recommended that you try re-encoding the file in the MPEG-4 format using one of the many video conversion tools available for Mac OS X, Windows and Linux.

Audio files may be uploaded to MorphoBank in MP3, AIFF, WAV or AAC format. Other formats are not supported. If you need to convert or edit your audio files use a sound editing application such as Audacity (http://audacity.sourceforge.net/).

Uploading and Viewing CT Scan Data

Uploading CT Scan Files

MorphoBank can accept CT scans and derived 3D surfaces for inclusion in your project. A CT scan is a series (“stack”) of images created along a single axis. You may upload a CT stack, comprised of hundreds or thousands of individual images, to Morphobank as a single ZIP-format archive. Your ZIP file should include only images with no extraneous files or sub-directories. All images in the stack should be TIFF or DICOM format and must be numbered sequentially. Any file with a missing number will be skipped during upload, resulting in an error or inaccurate 3D image.

Please remember that ZIP-format stack uploads should be used for CT data only and not as a batch upload method for individual specimen images.

You may also upload media derived from CT data to Morphobank, including 3D surfaces in PLY and STL format and pre-rendered 3D animations in QuickTime, MPEG-4 and WindowsMedia formats.

To upload a CT scan or derived media, go to the Media tab of your project. Click on the button titled “Add new 2D/3D media file”

Using this form, you can upload your CT stack, 3D surface or animation and label it with specimen information, views, and copyright restrictions just as you would with other media upload formats.

You can upload your files in PLY, STL, ZIP, TIFF and DCM, file formats, as well as any acceptable video format.

* The TIFF format is recommended for images in stacks intended for reuse by other researchers.

File uploads are limited to 2GB per file. If you need to upload media larger than 2GB please contact us via the Ask Us form linked to in the main navigation. If you attempt to upload a file larger than 2GB an error message will display.

When a PLY or STL 3D surface is uploaded, this icon will be shown in place of a thumbnail wherever the file appears in your project.

Viewing CT Scans and 3D Image Files

You can view a sample frame of an image stack from within Morphobank prior to download. To view the preview is detail click on the image thumbnail, as you would with any other image in Morphobank.

You can view uploaded 3D surfaces interactively within Morphobank using the 3D viewer. To access the viewer, click on “Zoom” underneath the icon on the uploaded media page.

Once you click on “Zoom”, you will see the 3D rendering of the surface data displayed in a pop-up viewer. Large surfaces may take a while to load.

You can use your mouse to click and drag to rotate the object in 3 dimensions,. Use your mouse wheel or track-pad zoom gestures to change viewing magnification. Alternative you may use the on-screen zoom slider and directional buttons to control the view.

The up/down arrows may be used to spin the image vertically, and the left/right arrows may be used to spin the object horizontally.

Clicking and dragging on the slider will zoom in and out of the image.

Since the surface is generated from CT scan layers, you can zoom in and see all surfaces of the object, including the interior as shown below:

The add new media file button

To add a media file to your project, click on Media in the left-side sub-navigation. You will be presented with two buttons: Add New Media File and Add Media Batch. Click on the former to display a form like the one below.

Figure 10.1. Portion of new media upload form

Portion of new media upload form


Use the "Choose media file to upload" file browse button to pick a file to upload. It must, of course, be in a supported format or it will be rejected. To pick the specimen from the project specimen directory that this media item represents, type the first few letters of the taxonomic name catalogue number or institution code into the "Specimen" text entry box. A menu will appear with all possible matches, as shown below. The more you type the more specific the list of possible matches will become.

Figure 10.2. Media editing form with specimen match menu visible

Media editing form with specimen match menu visible


You can tag your image with one of the views as configured in the Media Views tab by choosing it from the "View" drop-down menu. Choose "- NONE -" if no view is applicable.

Copyright Tools

Copyright Tools

If an image is under copyright, be sure to check the "Is under copyright?" box, When this is checked, new fields appear that allow you to specify copyright information. These include drop-downs describing the status of the permission and the reuse license, and space to enter the copyright holder’s name and the relevant bibliographic reference. If the box remains unchecked, the image will automatically be marked "public domain." Please be careful to set appropriate copyright settings, as images that have been previously published are often subject to the copyright restrictions of the publishing journal. Correct copyright attribution is the responsibility of the particular MorphoBank user.

Figure 10.3. Media editing form with copyright tools

Media editing form with copyright tools


If at all possible, use images to which you own the rights and set the Media reuse license of your choosing. The licensing options are as follows:

  • CC0 - Relinquish copyright. This option will place your media in the public domain. you will waive all copyrights and related or neighboring rights that you have over your work, such as your moral rights (to the extent waivable), your publicity or privacy rights, rights you have protecting against unfair competition, and database rights and rights protecting the extraction, dissemination and reuse of data.

  • CCBY - This license lets others distribute, remix, tweak, and build upon your work, even commercially, as long as they credit you for the original creation. This is the most accommodating of licenses offered. Recommended for maximum dissemination and use of licensed materials.

  • CC BY-SA - Sharealike. This license lets others remix, tweak, and build upon your work even for commercial purposes, as long as they credit you and license their new creations under the identical terms. This license is often compared to “copyleft” free and open source software licenses. All new works based on yours will carry the same license, so any derivatives will also allow commercial use. This is the license used by Wikipedia, and is recommended for materials that would benefit from incorporating content from Wikipedia and similarly licensed projects.

  • CC BY-ND - Attribution-NoDerivs. This license allows for redistribution, commercial and non-commercial, as long as it is passed along unchanged and in whole, with credit to you.

  • CC BY-NC - Attribution-NonCommercial. This license lets others remix, tweak, and build upon your work non-commercially, and although their new works must also acknowledge you and be non-commercial, they don’t have to license their derivative works on the same terms.

  • CC BY-NC-SA - Attribution-NonCommerical-ShareAlike. This license lets others remix, tweak, and build upon your work non-commercially, as long as they credit you and license their new creations under the identical terms.

  • CC BY-NC-ND - Attribution-NonCommerical-NoDerivs. This license is very restrictive, only allowing others to download your works and share them with others as long as they credit you, but they can’t change them in any way or use them commercially.

  • Media Released for One-Time Use, No Re-Use Without Permission. The copyright holder has released the media for use in one MorphoBank project only at present. To honor the copyright holder's wishes MorphoBank only allows such Media to exist in one project. If you have a question about this please send a message to using the Contact Support form on the MorphoBank home page.

CC0 or CC-BY licenses allow maximum flexibility and data sharing online because they (and only they) are Open Data licenses. Please be aware that choosing an NC (non-commercial usage only) license may prevent your Media from being used on Open-content only websites such as Wikipedia. We do not recommend choosing this license. When you have obtained permission (unless you, the person uploading the material, have granted it yourself) you will need to upload a signed document proving this. MorphoBank automatically prompts this when you select "Permission to use meda on MorphoBank granted by copyright holder" from the Copyright Permission drop-down list shown above. When you choose this option, the following form pops up:

Figure 10.4. Copyright Permission Upload Form

Copyright Permission Upload Form


You can simply attach the relevant document using the "Choose File" button and it will automatically be saved to the Documents section of your Project Workspace. If you have already uploaded a Copyright Permission document, you can simply select it from a list of all available documents within your project. You can then exit the form uploader and return to the Media Editing page to save your work. Please be sure to clearly state the copyright holder on the Media Editing form by typing the name into the text box labeled "Copyright Holder."

As an additional layer of copyright documentation, you may wish to attach a bibliographic reference to the Media by typing in the first few characters of the reference title or author name(s) into the "Add bibliographic reference" box. You will be presented with a list of possible matches from your project bibliography from which you can choose the appropriate reference. Remember that you must first create the reference in the project bibliography before you can attach it here.

The only data absolutely required is the media file itself. You are strongly encouraged to attribute a specimen from the specimen directory to each media item. The matrix editor uses the specimen taxonomy to suggest relevant media for placement in cells. Thus media without specimen data will not be usable in matrices.

You must also specify copyright information for your media, if applicable. The earlier this is done the fewer copyright clearance problems you will encounter later as you move towards publication.

Copyright Settings for Project Data: Matrices and Documents

As of 2014, Matrices and Documents on MorphoBank can be marked with their own copyright settings, distinct from Media copyright settings. As noted above, for Media MorphoBank offers a range of licenses. For Matrices and Documents, MorphoBank offers either the setting CC0 (see below) or the oprtion to simply leave the copyright status unspecified.

The purpose of storing data on MorphoBank is to make those data available to the scientific community and the public so that data may be reused in the service of research and education. Standards of good scholarship dictate that when reusing prior work the authors of that prior work shout be cited. Thus, although the data on MorphoBank are by definition intended for sharing, some users may wish to emphasize freedom for others to reuse by formally relinquishing all copyright claim to deposited published work. Those users can do so by placing a CC0 tag on Matrices and Media. CCO is the Creative Commons Public Domain license which:

enables scientists, educators, artists and other creators and owners of copyright-or-database-protected content to waive those interests in their works and thereby place them as completely as possible in the public domain, so that others may freely build upon, enhance and reuse the works for any purposes without restriction under copyright or database law.

In contrast to CC’s [Creative Commons’ other] licenses that allow copyright holders to choose from a range of permissions while retaining their copyright, CC0 empowers yet another choice altogether – the choice to opt out of copyright and database protection, and the exclusive rights automatically granted to creators – the “no rights reserved” alternative to our licenses.

“Non-media data copyright preferences” or “Matrix copyright preferences” can be accessed from a few locations in your Project workspace, and allow you as a Project Administrator to place a CC0 tag on data, thereby releasing it to the public domain.

For unpublished projects, you can select copyright preferences from within the Matrix tab or from within the Documents tab. If you access the copyright preference button from either area, the CC0 license will be applied to all data (except Media) in your project. In other words, Project Matrices, Documents, Characters and Ontologies will all be included in the designation, regardless of the tab from which you access the setting. You need only select the setting once.

Figure 10.5. Click the "copyright preferences" button

Click the "copyright preferences" button


Figure 10.6. Check box and click "save"

Check box and click "save"


When a Project is later published, there are several possible actions by visitors browsing MorphoBank that will trigger a reminder about copyright and a possible CC0 license. Users will see the notice in the screenshot below.

Figure 10.7. Copyright notice

Copyright notice


This notice appears in the following locations:

  • When downloading an entire Project from the Project Overview page, users will select “Download Project” from the right-hand navigation. On the resultant Download page, an orange “Download Project” button will appear. When selected, a notification explaining the CC0 settings will appear.

  • When downloading an individual Document from the Documents tab, a similar notification will appear.

  • Finally, when downloading a Matrix, Character List, or Ontology, users will also receive a notification describing the CC0 setting.

Figure 10.8. Matrices marked with CC0 have this symbol:

Matrices marked with CC0 have this symbol:


Figure 10.9. Documents marked with CC0 have this symbol:

Documents marked with CC0 have this symbol:


Batch uploading media with the Batch Media Upload Tool

You can upload batches of media directly into your project using the media batch upload tool, which will add any number of media directly to your project in a single step, provided it has been compressed into a single archive file.

Figure 10.10. Portion of the media batch upload tool

Portion of the media batch upload tool


To use the batch upload tool, click on the add media batch button (to the right of the add media file button). You will see a screen like the one shown in ???. Under the header "Choose a ZIP, TAR, TAR+gzip, TAR+bzip archive or individual file" click on the file browser button and select a batch of media compressed as a ZIP, TAR, TAR+gzip (.tgz) or TAR+bzip (.tar.bz2) file. Fill in any of the other fields for which you have data or preferences, including Url of media, access settings, media notes, and publishing status. To select a specimen type the first few letters of the specimen's name into the text entry to display a list of possible matches. Similarly, if you wish to link a bibliographic citation to the uploaded media, type the first few letters of the reference's title or author and then pick the relevant reference from the resulting list of possible matches. You can also choose views for the media, if appropriate.

When you are done click on the "upload archive" button. When the upload and processing is complete you will be presented with a summary of results from batch processing.

Batch Media Delete Feature

Occasionally a Project Administrator will upload a large number of images only to discover that, for one reason or another, they simply aren’t right for the current project. As a corollary to the Batch Media Upload feature, MorphoBank has a Batch Media Delete feature to allow efficient deletion of multiple media. To use the “Delete media batch” tool, navigate to the “Media” tab, and then select the orange button “Delete media batch” from the top of the screen. You will then see a new button, just above the image thumbnails themselves, that reads “Trash Media.” Any project member can then begin the batch deletion process by clicking on each unwanted image. A small checkmark will appear in the upper-left-hand corner of each selected thumbnail. When you’ve made your selections, click “Trash Media.” You can click through multiple pages of media making your selections or you can add continuously to your media recycling bin. The small recycling bin to the right of the “Trash Media” button will change shape to indicate that it contains the discarded images. This feature ensures that you have the opportunity to re-think your deletions before it is too late.

Figure 10.11. Batch Deletion

Batch Deletion


To complete the process, click the recycling bin icon. The resultant screen will display all of the trashed media. Select once more to either permanantly delete or restore the images.

Figure 10.12. Restore/delete

Restore/delete


Using the Media Browser

The media browser, accessible by clicking on Media in the left-hand navigation, lets project members conveniently view, sort and filter through previously uploaded project media. Unless filtering is enabled, the browser shows all media in the project as icons. Clicking on an icon opens up the basic media editing form, which includes copyright information, and a larger version of the media. Clicking on the larger version will open the largest web-viewable version of the media (for images, a pan-and-zoom version of the image, for video or audio, a playable version). The original media file can be downloaded by clicking on the "download" button on the basic editing form.

Figure 10.13. The media browser

The media browser


The “restore” feature is only available while your project remains unpublished. All media in the recycling bin will be deleted upon publication. When media is deleted it is permanently removed from all aspects of your project, including matrices.

View modes

The media browser supports two different ways of viewing sets of media:

  • Thumbnail mode displays twenty-five items per page at lower high-resolution with only MorphoBank number and taxonomic name.

  • Mosaic mode displays one-hundred items per page at low high-resolution without any additional information. Images in mosaic mode are cropped to be square, so portions of rectangular images may be missing in this view.

A set of view mode buttons is present in the upper-right hand corner of the media browser. Clicking on a button changes the view mode.

Figure 10.14. Media browser view modes

Media browser view modes


Sorting

The media browser can sort items by a number of criteria:

  • MorphoBank number

  • specimen number

  • name of user who submitted media

  • phylum

  • class

  • order

  • suborder

  • superfamily

  • family

  • subfamily

  • view

  • genus

By default, items are sorted by MorphoBank number. You can change the sort order using the "Order by" drop-down menu in the media browser.

Filtering

By default the media browser displays all project media. For projects with lots of media this can get unwieldly, so the browser offers two ways to filter what you see.

The "Show" drop-down menu in the top-left section of the media browser navigator allows you to easily display only those media items meeting some basic criteria:

  • identified displays only media items that are associated with a specimen.

  • unidentified displays only media items that are not associated with a specimen.

  • copyrighted displays only media items that have their "is under copyright?" checkbox set.

  • non-copyrighted displays only media items that do not have their "is under copyright?" checkbox set.

  • all displays all media items. This is the default.

You can also filter media items by taxonomy, view, submitter, copyright license, copyright permission, specimen repository, status, or any combination of these by clicking on the "Filter Media" button towards the right of the media browser. Check off your desired filters on the set up screen, shown below, and click on the "filter" button. Multiple filters can be used at the same time to create specific lists of media to show, for example, a list of copyrighted materials that were uploaded by a specific member.

Figure 10.15. The media browser filter setup screen

The media browser filter setup screen


To clear filtering, select "Clear All." Once you have cleared your filters, be sure to click the "Filter" button beside the "Clear All" button to complete the action.

Searching media

You can also use the Search function to search for media. While logged-in the search engine will find media in both published projects and any unpublished projects in which you have membership.

Importing Media from EOL.org and iDigBio.org

The Encyclopedia of Life (EOL.org) and Integrated Digitized Biocollections (iDigBio.org) are growing sources of specimen and media available for re-use under Creative Commons licensing. You may wish to import media en masse from EOL.org or iDigBio.org to illustrate character states, cell scores or taxa in your MorphoBank matrix. Morphobank makes this very easy.

MorphoBank allows you to pull groups of images from EOL.org and iDigBio.org and load the associate data (e.e. species name) automatically. You can access these tools through both the "Media" tab and the "Taxa" tab. From either of these pages, click on the orange button that says "Import EOL.org images" or "Import iDigBio.org images"

Figure 10.16. EOL and iDigBio Buttons

EOL and iDigBio Buttons


Clicking on the button will open a window that lists all of the taxa in your project alongside checkboxes. Use the checkboxes to select which taxa to search in EOL.org or iDigBio.org. If your project has many taxa, you may want to be selective and do just a few at a time to avoid long load times. Once you've made your selection, click the large orange button that says "Search EOL.org."or "Search iDigBio.org"

Figure 10.17. Select Taxa

Select Taxa


When your data has been retrieved, you will see an image thumbnail along with copyright information. You can either choose to import this image, or you can see what else EOL.org or iDigBio.org has to offer by clicking the orange "Check for more media on EOL.org" or "Check for more media on iDigBio.org" button. Once you're satisfied with an image or images, check "Select for Import,""Use image as taxon exemplar," or both, and then click "Import."

If you choose to use the image as a Taxon Exemplar, it will immediately appear as a part of your matrix when the import process is complete. It is associated with the taxon names in rows. Typically the Taxon Exemplar is a picture of the whole organism. If you're importing images without selecting "taxon exemplar," then it will simply be added to the "Media page in your project. Either way, all imported media are available to you as you work and can be linked to cells, characters and states or taxa.

Figure 10.18. iDigBio Results

Results


Once you import the chosen media, you'll see an intermediary window telling you how many images were imported and directing you to further "curate" your media:

Figure 10.19. Import Complete Screen

Import Complete Screen


The "curate media" page allows you to associate Media Views (these are orientations and descriptors that you design such as "lateral skull," "body," "stamen," and "cross section) with your newly imported images. MorphoBank automatically creates an "unvouchered" specimen record for all media imported from EOL, but if you want to use a different, already extant specimen record, you may do so by typing its first few letters in the "Specimen" lookup (seen in the figure below). When importing media from iDigBio.org, specimen records will be created based upon the data available in iDigBio. You must also pick a View from the drop-down of all of the Views existing in your project. If you don't see the appropriate View, you must create a new one in the "Media Views" tab. If the "curate media" page has more than one image, you must select the appropriate one(s) by clicking the checkbox in the upper-right-hand corner of each thumbnail. When you've finished curating an image, click "Save." An orange border will surround the completed media. To complete the process, click "Release Curated Media to my Project."

Figure 10.20. Curate Media Page

Curate Media Page


You'll notice that there's another orange button, reading "Release All Media to my Project" that's available throughout the curation process. If you click this button, Media with no associated specimen or views will be released into the main body of your project. You'll see a warning pop-up asking you to confirm this choice.

Using the MorphoBank Image Viewer and Annotator

All images uploaded to MorphoBank are automatically converted into a format that allows efficient pan-and-zoom viewing at full resolution. This means you can upload very high resolution imagery and view it online on MorphoBank with full detail using a normal internet connection.

To efficiently display high resolution imagery, MorphoBank takes your original image, breaks it up into small pieces and stores those pieces at various resolutions, from full resolution down to thumbnail resolution. Special browser-based software built into MorphoBank requests only those pieces that are actually visible on the screen, and at the lowest resolution possible. The result is that even the highest resolution imagery can be viewed online using a standard connection. No detail need be lost.

If you are a scientist or student building a matrix, The only requirement to use this feature is that your browser have the Adobe Flash version 10 or better plugin installed (although development of a non-Adobe Flash-based matrix editor is planned for the future). Most modern browsers and operating systems come with this software pre-installed.

To use the image viewer and annotator, first click on the image in the media browser. You will be taken to a media editor page with a version of your media on the right side of the screen. To use pan and zoom features, either click on the image itself or select "zoom" below the image:

Figure 10.21. Basic image viewer

Basic image viewer


A window which looks something like the figure below will then appear:

Figure 10.22. Basic image viewer

Basic image viewer


Figure 10.23. Image viewer tool palette

Image viewer tool palette


The palette above includes tools that allow you to view and label your images. In addition to these, you will also see a slider at the top of the image that allows you to zoom in and out incrementally. Let's take a look at each of these tools:

  • To annotate your image with boxes that highlight key areas, you can click this square icon. Once it is selected, click the area of the image you'd like to annotate, and a rectangle with a text box beneath it will appear. You can drag the rectangle anywhere on the image, and resize it by clicking and dragging the corner. To save any text that you enter into the text box, simply click outside of the annotation. To remove the annotation, click inside the text box once more, and then click the small "x."

  • The polygon tool has been added to the tool bar in the shape of a hexagon. Once selected, as you click on the image you will be adding points to draw your shape. The shape is always closed, and you can add as many points as you like. You can click on points you've already added to move them, alt+click on existing points to remove them, and alt+click on the line to add new points. To remove the shape, Click on the "X" in the label box.

  • The scrollbar on the right hand side of the image is the rotation tool. You can rotate your image by moving the bar up to go clockwise and down to go counterclockwise.

  • To annotate an image by drawing a line to indicate a specific area, click this icon. Like the box annotation above, you must first select the tool, and then click on the part of the image where you wish the line to point. The line will connect the selected portion of the image to a text box. The orientation of the box can be adjusted by clicking inside the box and holding the button down while dragging it. As described in regards to the box annotation, to save text simply click outside of the text box area. To delete the annotation, click inside the text box again and then click the small "x."

  • To move around an image that is too large to fit on the screen select the pan tool from the tool bar (or press the 'p' key on your keyboard), then click on the image, hold the button and drag the mouse until the region of interest is visible.

  • Clicking on this icon will restore the image to its original zoomed-out, centered position.

  • You can use this button to prevent accidental movement or deletion of labels while navigating the image. When locked it will not be possible to move, edit, create, or delete labels on the image. You can still use the zoom and pan tools when the labels are locked.

  • This button opens a guide to all of the image viewer tools, along with a list of helpful keystroke shortcuts.

  • In order to keep track of where you are within a zoomed-in image, you can use this tool to highlight the visible area within a smaller inset of the whole image. See example below.

Figure 10.24. Zoomed-in image with highlighted area

Zoomed-in image with highlighted area


Notice, in the above image, the presence of the slider at the top. In this example the slider is at the top end of the scale, right at the "+" to indicate that the image is all the way zoomed in.

You can hide all of the viewer's on-screen controls, allowing one to view the image in an uncluttered window, by pressing the TAB key on your keyboard. Once hidden, pressing TAB again will make the controls reappear. All mouse and keyboard controls continue to work normally while the on-screen controls are hidden.

Other keyboard shortcuts include:

  • "space": to activate image panning

  • "r": to select the rectangle label tool

  • "p": to activate the point label tool

  • "n": to toggle visibility of the image overview

  • "h": to return the image to the centered, zoomed-out "home" position

  • "c": to toggle visibility of viewer controls

  • "+" or "]": to zoom in in small increments

  • "-" or "[": to zoom out in small increments

  • "?": to pan the image in small increments

  • "d": to delete the selected annotation

  • "l": to lock and unlock annotations

Editing Media

Updating media

You can update a media file at any time by finding the media in the media browser or search, clicking on its "edit" button, and then uploading a new file into the existing record. This is handy when you need to correct errors or replace an existing file with a higher quality version.

Labeling images in the Matrix Editor

.

MorphoBank also allows you to label regions of images using the Media viewer when it is accessed from the Matrix Editor. The labels do not modify the image in any way. Labels only appear when viewing the image in the specific matrix cell in which the labels were added. In addition, labels are automatically tagged with the taxon and character of the cell to which they are attached.

Figure 10.25. Image viewer with labeling controls and label visible

Image viewer with labeling controls and label visible


To label an image in the matrix editor, first open the matrix, then click on the cell displaying the image in question. This will open the pan-and-zoom viewer, similar to what you would see if you clicked on an image in the media browser. You will see the same tool palette, including the annotation buttons discussed above

Changes made to a label's text or location are automatically saved. You do not have to explicitly hit a "save" button.

Chapter 11. Managing Characters

As with taxonomic names and specimen data, MorphoBank maintains a central directory of characters for each project. The directory lists each character once - no duplicates are allowed. Matrices using the same character are actually referring to a single entry in the character directory. This means that if you modify a character, the change will be reflected everywhere it is used in your project.

While it is possible to perform rudimentary editing of characters in MorphoBank's matrix editor, most management of character data in your project will be performed using the character editor. However, unlike taxa and specimens, the character editor does not have its own button on the left-hand navigation panel. To access the character editor, enter the Matrix page via the left-side navigation, and then click the "edit characters" button at the top of the page.

Figure 11.1. The character editor button

The character editor button


Character editor overview

As shown in the figure below, the character editor provides a number of useful features designed to streamline the management of character data. When you select the "Edit characters" button on the Matrices page, you will see a list of characters from the first matrix in your project. The characters are displayed in the same order in which they appear in the matrix. You may display characters from other matrices in your project by using the matrix drop-down menu located on the upper left-hand corner of the editor. You can make changes to a character (assuming you have project-level privileges to do so) by double clicking on its number or name. You may delete or move a character by clicking on it once and then using the "del char" or "move char" buttons. To select a range of characters, click on the first character in the range, then click on the last character in the range while simultaneously depressing the shift key on your keyboard. The delete and move functions work on single or multiple character selections. To add a new character, select the character under which you wish the new character to appear and then click on the "new char" button.

If you need to move a character or set of characters a relatively short distance in your list you may drag the selection to its new location by clicking on a selection of characters and, with the mouse button held down, dragging it with your mouse to its new location.

Figure 11.2. The character editor

The character editor


Adding Characters

Adding a single character

To add a new character, first select the character after which you wish the new character to be placed, then click on the "new char" button in the upper-right hand corner of the editor. A blank character will appear in the list. Double-click the blank character to set its name and states. For a state to be useful, you must set a name and at least one character. See the section called “Edit basic character information ("character" tab)” for more information.

Batch adding characters using a NEXUS file

When uploading a NEXUS file to create a matrix, all characters and states present in the file are automatically added to the character directory. This is a collateral effect of importing a matrix but can be used to batch add characters and is especially convenient if your data is already in NEXUS format.

Because characters are shared across matrices in a project, you can load a matrix from a NEXUS file, then use the characters from the imported matrix in other matrices created directly in MorphoBank.

For projects that need to consolidate characters from disparate NEXUS format datasets into a single set, using MorphoBank's NEXUS import capability may be a convenient option. Uploading multiple NEXUS files into a single MorphoBank matrix will result in a matrix with a character list that is the sum of those in the constituent files. You can then use MorphoBank's character mangement tools, described below, to edit the list into its final form.

Viewing lists of characters

The character editor provides tools for viewing a project's characters by matrix. Editing of character and state names and descriptions can take place directly in the list, allowing for fast editing of basic character information.

Figure 11.3. The character list

The character list


As discussed, to view the character editor click on the Edit characters button at the top of the matrix page. The character list will display as a pop-out window. When your project has more than one matrix, the matrix drop-down menu in the upper-left hand corner of the tab provides a means to select the matrix whose characters you want to display.

The characters will be ordered as they are in the matrix itself. This order, by default, is the order in which the characters were created. If the characters were imported from a NEXUS file then the order will match that of the file. Project members may make arbitrary changes to character order in the matrix editor or using the "move" tools described in the section called “Moving characters”.

Searching for characters

To search for a character enter your terms in the search box located at the top of the editor and click the "search" button . The editor will substitute a list of all characters whose name or description contain the search terms in place of the full list of characters. Found characters are always displayed in the order in which they appear in the matrix. You can search for matches that begin or end with some text using the wildcard asterisk ("*") character. So, for example, to find all characters whose name, number or description contains the word "pavement" you would simply search on "pavement." To find characters having words beginning with "pave", for example, you would search on "pave*" When you are done with the results of your search click on the "back to list" button at the top of the editor to return to the full character list for the selected matrix.

Moving characters

Each matrix has its own sorting order for characters. By default the order is that in which the characters were added to the matrix. However, project members may arbitrarily reorder characters in a matrix using the matrix editor or in the character editor. The matrix editor is described in the section called “Changing the order of characters”. The character editor supports two methods of moving characters: by dragging and dropping characters in a list or by selecting characters and using the "move char" button to specify, by number, the character under which the selected characters should be moved. Either method will support the movement of both single characters and blocks of characters. To select a single character simply click on it once. Selected characters will turn blue (as shown in the figure below). To select a block of characters, click on the first character in the block, then with the shift key on your keyboard depressed, click on the last character in the block.

Figure 11.4. Moving characters using the "move char" button

Moving characters using the "move char" button

Once you have selected the desired character(s), click on the "move char" button which will bring up a window asking for the number of the character under which you wish to move the selected characters. If you are moving your selection across a large set of characters this method will be the most convenient. For shorter moves, you may also click on and drag your selection in the list.

Editing characters

To change any aspect of a character in the list, double click on the character number or name. A window, shown in the figure below, will open enabling you to edit all aspects of the selected character including:

  • edit the character's notes.

  • add, edit and remove character states.

  • link media to characters and character states.

  • add labels to media linked to characters and character states.

  • add citations to a character.

  • view member comments associated with a character and its states.

  • view the change history for a character.

Figure 11.5. Editing of basic character information

Editing of basic character information


The editor is divided into five screens which may be accessed using the navigation tabs at the top of the editing window. The functions present on each screen are described below.

Edit basic character information ("character" tab)

The "character" tab lets you change basic character information such as character name and the notes for the character as well as add, edit and delete character states. Beginning in Summer 2014, when you open an individual character for editing its unique ID number will appear in the upper right-hand corner of the editor.

Warning

Currently MorphoBank does not distinguish between upper and lower case characters - all names are case-insenitive. This can be an issue for some types of characters, dental characters for example, where upper and lower case names have historically been used to represent different characters.

To open an individual character for editing, double-click that character in the "Matrix character list editor":

Figure 11.6. Selecting a character

Selecting a character


In the resulting character editing window, notice the ID (circled below):

Figure 11.7. Character editor with ID

Character editor with ID


To add a state, click on the "add state" button or on the blank area in the state list under the last state. A new state will appear in the list. Click on the name to edit it. To reorder states click on and drag the state in the list by its number to the desired position. The states will automatically renumber themselves such that they are always sequentially numbered starting from zero. To remove a state, click on the state in the list, highlighting it, and then click on the "remove state" button. Character editing will be discussed at greater length in the section entitled the section called “Characters”

Adding media to a character or character states ("media" tab)

Any number of project media may be attached to either a character or character state using this screen.

The screen lists all character states. To add an image to a specific state, click on the "add" button for the state. A media selector window, as shown in the figure below, will appear allowing you to locate and link media from your project.

To find media for a character or character state, type a search into the "search for" text entry and click on the "find media" button. As shown in Figure 11.9, “Attaching media to a character” a list of relevant media will be displayed. Click on the desired media and click on the "add" button to link it to the selected state or the character in general.

The search performed by the "media" field to find relevant media is broad, searching on the following data:

Table 11.1. Character media search summary

Project itemItem fields searched
Taxa Phylum, class, order, suborder, superfamily, family, subfamily, genus, species, subspecies, author, year, notes
Specimens Institution code, collection code, catalogue number
Views View name
Media Media accession number, Copyright information, notes, extended information fields (Darwin Core and others)


You can search for partial matches by using the asterisk ("*") wildcard character. For example, to find all media associated with words starting with the letters 'dent' search on 'dent*' Similarly, to find media associated with words ending is 'ism' search on '*ism'

Figure 11.8. The character media tab

The character media tab


Figure 11.9. Attaching media to a character

Attaching media to a character


Labeling media associated with characters

You may add character-specific labels to images associated with specific characters. To do so click on the thumbnail of the image in either the character editor "media" tab or on the small thumbnail images appearing next to characters and states in the character list. A new window will appear, as shown in Figure 11.10, “Character image viewer and labeling of character images” below. You may add labels to the image in this window in the same manner as is done in the matrix editor (see the section called “Media views”). Note that labels added in this window will only appear when the image is displayed for the selected character. When the image is used in other contexts (eg. in a matrix cell, or as a depiction of the specimen) these labels will not be visible.

Figure 11.10. Character image viewer and labeling of character images

Character image viewer and labeling of character images


User comments for characters ("comments" tab)

All project members - full or observer - may add comments to any character or state in a project. Comments are recorded with the date and time they were made and the identity of the commenter and are displayed in the "comments" tab listed with the most recent first. You may also add a comment to the character or a specific state by clicking on the "add comment" button at the bottom of the screen.

The number of comments associated with the character and its states is displayed in the character list in a column labelled "#C". Numbers in bold indicate characters for which there are unread comments. You can bring up the comments tab for a character directly from the character list by clicking on the comment count for that character.

Comments are a permanent part of the project record and cannot be changed or deleted once made.

Figure 11.11. Adding a comment to a character

Adding a comment to a character


Add Citation ("citation" tab)

You can use the "Citation" tab to add, edit, or remove citations from a character or state. To add a citation, choose the "add citation" button from the bottom-left corner of the screen. A new window will appear which will allow you to search for a reference from within your project's bibliography. Type a search term next to the "find" button on this page, and select a bibliographic reference from the list that appears. You will also be able to add page numbers and any specific notes pertaining to that reference in relation to the character in this window, or in the "Edit citation" window after the fact. Press "Save" when you are satisfied with your citation.

Figure 11.12. Adding a citation to a character

Adding a citation to a character


Change history ("change history" tab)

Morphobank keeps a log of changes made to a character and its constituent parts - states, media, notes, etc. - which may be viewed in the "change history" tab. Each change is noted with date and time, the identity of the member commiting the change, and the precise value of each field after the change.

Figure 11.13. Using the Change History Tab

Using the Change History Tab


Chapter 12. Using Matrices

MorphoBank supports editing and display of dynamic phylogenetic matrices of morphological characters with labeled images demonstrating homology statements. It implements many of the data editing functions of widely used desktop programs such as Mesquite and Nexus Data Editor in a networked, collaborative environment.

Unlike previous systems for phylogenetic research which focused primarily on the development of text-only matrices and trees, in MorphoBank media - and particularly images - are first class citizens. MorphoBank matrix development features are fully integrated with media management features. You may place images - intelligently selected based upon taxonomy - into cells with cell-specific labels to document your homology statements. High resolution imagery is supported with continuous pan and zoom and labels that maintain their scale and position as images are enlarged and reduced for inspection. This makes it possible to include detailed visual documentation of each assertion in your matrix dataset.

Starting a New Matrix

When creating a new matrix in MorphoBank you have two choices: you can start from scratch and enter characters, states, taxa and cell scorings one at a time, or you can import an existing matrix (or matrices) created in some other application.

No matter which path you plan to take, clicking on the Create Matrix button in the button bar will get you started.

Figure 12.1. New matrix form

New matrix form


As can be seen in Figure 12.1, “New matrix form”, there are many options, but the only required field is "name," which is simply a working title used to refer to your matrix. The operational taxonomic unit drop-down, which defaults to "Genus," should also be set, and is described in detail in the section called “The Operational Taxonomic Unit (OTU)”.

If you simply fill in the name, set the OTU and click on "save" you will create a new matrix with a single "dummy" taxon and character (all matrices must have at least one character and one taxon). You can open this matrix in the editor, change the dummy character and taxon to suit and begin adding additional character, taxon and scoring data.

Importing a Matrix from a NEXUS Format File

If you have existing matrices, created in software such as Mesquite or MacClade, that are in NEXUS format, you can import those directly into MorphoBank as a starting point for your MorphoBank matrix. To do so, click on the file browse button under "NEXUS file to add to matrix" in the new matrix form and select your data file. You can also specify text to add to the notes data of each taxon and character imported from the NEXUS file. If you have taxon or character partitions in your project, you will also see checkboxes for each partition. If checked, all taxa or characters will be added to the selected partition as they are imported.

When you are ready, click on "save." Importation of a NEXUS file can take some time so be patient. Most files take well under a minute to import, but very large data sets have been known to take five minutes or more. Once the import is completed, a statistical summary of the import process will be displayed and you will be shown the new matrix's basic information editing form, as shown in Figure 12.2, “Successful NEXUS Upload”. Note that matrices can be uploaded in any language.

Figure 12.2. Successful NEXUS Upload

Successful NEXUS Upload


NEXUS import caveats

NEXUS is a loosely defined format that has never been definitively standardized (see https://www.nescent.org/wg_phyloinformatics/Supporting_NEXUS_Documentation for an interesting discussion about NEXUS limitations). Various software applications import and export NEXUS in subtly inconsistent and incompatible ways. MorphoBank tries to accommodate as many features and oddities as possible but there are still a number of caveats to keep in mind as you gather data to import into MorphoBank.

If MorphoBank rejects your uploaded NEXUS file first look over the list of advice below. If your file is still unusable, then contact us via the "Contact Support" at the top of the page for assistance.

Only morphological data is accepted

MorphoBank only accepts NEXUS files containing morphology data. It is possible to create NEXUS files with a mixture of morphological and genetic data, or with genetic data alone. These files will be rejected by MorphoBank. Unless one uses non-standard extensions to the NEXUS format, such as the MIXED datatype, it is not always clear what is morphological data and what is not. If you have mixed matrices, remove the genetic data before uploading the file to MorphoBank.

If you need to keep genetic data with your project, for publication or convenience or both, you can upload files containing the data to MorphoBank as a document. Unlike NEXUS or TNT file uploads MorphoBank simply stores documents - it does not attempt to manipulate or verify the uploaded non-morphological data in any way.

Supported NEXUS blocks

MorphoBank extracts data from the TAXA, CHARACTERS, DATA, ASSUMPTIONS and NOTES blocks. All other blocks are extracted as-is and retained. When you export a MorphoBank matrix as NEXUS, these blocks are reincorporated into the output file.

This allows files with tree data (for example) - data which cannot be manipulated with MorphoBank tools - to be uploaded. Data not usable in MorphoBank are preserved, although of limited use while using the system.

Bad data

Most desktop programs are quite forgiving of NEXUS data irregularities and errors, such as having two characters (or taxa) in the same matrix with the exact same name. MorphoBank employs a relational database with a more formal data model and is less forgiving of errors. In some cases it will reject your data outright, and in other cases it will revert to default values in an attempt to make the data work. After importing a NEXUS file, you should always give the resulting MorphoBank matrix a quick look-over to make sure everything is as it should be. In general, if it looks good, it is.

Note

If MorphoBank is rejecting a NEXUS file that works in some other program let us know. We will work to resolve the problem and make your file compatible with MorphoBank. Send a note via the "Contact Support" link at the top of the page with the details of the problem. Don't forget to attach a copy of the NEXUS file!

Common errors in NEXUS files that should be avoided if at all possible are:

  • Blank characters or taxon data: all characters, character states and taxa should have names defined. Blank data will be filled with default data ("Character 1", "Character 2", ... for characters, for example).

  • Poorly formed NEXUS files: don't modify your NEXUS by hand unless you really know what you're doing. It rarely works. If a NEXUS file lacks internal consistency, as many hand-modified files do, it will be rejected. Examples of inconsistency include MATRIX blocks with characters and/or taxon counts that differ from the number of character and/or taxon counts present in other blocks, partitioned data with mismatched lengths or names, etc.

  • Give unique names to your taxa and characters: in desktop programs where each file is its own self-contained universe, using duplicate names is an error that doesn't usually have a major effect. In MorphoBank, where taxa and characters with the same name are considered the same thing duplicates can have strange and unintended side-effects. Make sure duplicates are resolved before importing into MorphoBank.

Merging Several NEXUS Files into a Single Matrix

MorphoBank allows you to upload NEXUS files and concatenate them with an existing matrix at any point after the matrix has been created. The contents of each uploaded file are merged with those of the existing matrix. This provides a mechanism for consolidating multiple NEXUS format datasets into a single Morphobank matrix. To upload one or more NEXUS files to an existing matrix, click on the small grey button entitled "edit matrix description" directly below the matrix summary information. Note that you will only have access to this editor if you are the Project Administrator or the user who created the original matrix. You will be presented with a new screen, from which you can choose to "Add New Matrix," "Edit Matrix," or "Edit Characters," as well as make changes to the title info, notes, access settings, OTU, and publishing status. At the bottom of the screen, you will see a checkbox that says "Merge a NEXUS or TNT file with this matrix." Once the box is checked, you will have the option to choose a file to add to the existing MorphoBank matrix. You will also be able to choose an OTU for the imported data and add descriptive text to each character and taxon added to the project from this file.

Figure 12.3. Merging a NEXUS file with a Matrix (Portion of Edit Matrix Description Page)

Merging a NEXUS file with a Matrix (Portion of Edit Matrix Description Page)


When you merge two matrices, MorphoBank will concatenate the rows and columns in all cases where the characters are not identical. Note - If the characters are identical MorphoBank will merge them, even if there are different cases (cat, Cat, and CAT would all be considered duplicate characters). Keep in mind that this is different from the behavior of desktop programs like Mesquite where duplicates are allowed. If the character names are identical but the states are different, the new states will be added to the existing list of states for a given taxon. In other words, when identical characters and identical taxa are merged, a polymorphic score for that taxon is created in the new concatenated matrix.  The same applies to taxa (identical taxa are merged). As a result of this functionality, care must be taken to ensure that characters and taxa names in both data sets match exactly, or differ to ensure the desired results. All punctuation, including periods, colons, and semicolons, will be taken into account when determining whether or not characters are exact matches. A mismatched character or taxon (due to differences in punctuation) will result in a newly created character in the merged matrix, with its scores in a column or row independent from the character or taxon that has different punctuation.

There are a couple of common issues to be aware of when utilizing this feature. First of all, note that while Morphobank supports non-alphanumeric characters (i.e., characters other than letters) in character and taxon names, TNT files do not support these. When exporting matrices as TNT from Morphobank, punctuation will be stripped from the names of all taxa, characters and character states (otherwise MorphoBank would not be outputting functional TNT files). Attempting to merge data so exported with other Morphobank matrices (that retain characters like punctuation) may cause unintended duplication of characters and taxa due to punctuation present in Morphobank but stripped from the TNT file. You may wish to use Nexus format when merging to avoid such problems. Secondly, when merging matrices MorphoBank only looks at the character name, not the character sequence, to assess duplicates.  For example, if you have a 3 character matrix on Morphobank in which characters 1-3 are:  1. Tall; 2. Round; and 3. Aquatic and you merge another matrix containing these same three characters in a different order (1. Aquatic; 2. Tall; 3. Round), MorphoBank will identify these characters as duplicates of the first matrix and will merge them in the new combined matrix.

Editing

All project matrices are accessible using the matrix list, accessible by clicking on the Matrices tab in the left-side navigation. As shown in Figure 12.4, “The project matrix list”, the list includes summary information for each matrix and a series of buttons implementing useful functions, from editing to downloading:

  • Edit matrix opens the matrix for editing in the MorphoBank matrix editor application, which will appear as a new window. This option is distinct from Edit Matrix Description

  • Edit Matrix Description allows you to adjust access and publishing settings, as well as giving you the option to merge another NEXUS file with the existing matrix. This screen is also another entry point from which you can click on buttons that will enable you to add a new matrix, edit the matrix, or edit characters.

  • 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.

  • Download NeXML NeXML is (as the name implies) an xml format that represents phylogenetic data. It’s inspired by NEXUS, but more flexible and designed to facilitate exchange.

  • Download character list allows you to download only the characters in your matrix as a text file to your desktop.

  • Download data partition allows you to download a specific partition from the list of partitions that you create.

  • The Matrix Preferences icon (to the right of the "Edit matrix" button) allows you to enable streaming for your matrix. This is important particularly in the case of large matrices. Based on the size of your matrix MorphoBank calculates automatically whether to stream your matrix while you work or load it all at once. Click the arrow to change the setting. MorphoBank will tell you if the matrix is too large to load at once. Choice of streaming vs. an upfront load is not based on the size of media in a project but on the size of the matrix. Matrices with greater than 50,000 cells will be streamed to ensure optimal server performance for the entire MorphoBank community.

Figure 12.4. The project matrix list

The project matrix list


Tree-building Options

As of August 2014, MorphoBank is partnering with CIPRES (Cyberinrastructure for Phylogenetic Research) to allow users to run a matrix and search for a tree (or trees) using the Parsimony Ratchet. The Parsimony Ratchet improves your ability to find shortest trees during heuristic searches on datasets. You will be able to run your matrix on the Web by sending it to the online algorithms at CIPRES. There are several settings you must define from within your MorphoBank project for the process to work. First, you will need to create a name for the job and add any helpful notes. Then, you will need to set parameters. Choose a Branch-swapping Algorithm to inform a heuristic search for a starting tree. Then PAUP will perform two searches for each of whatever number of iterations you specify. In the first search a subset of your characters will be assigned a weight of 2, and in the second all characters will be equally weighted. You must choose the number or percent of characters to permute. After your chosen number of iterations, CIPRES will return the resulting file to the MorphoBank Matrices page. Your underlying matrix will remain unchanged.

Figure 12.5. Tree-building options

Tree-building options


Editor overview

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.

Figure 12.6. The matrix editor in image display mode

The matrix editor in image display mode


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 which appear when double-clicked are described in detail in the following sections.

Tools

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 shown in Figure 12.7, “Matrix editor controls”

Figure 12.7. Matrix editor controls

Matrix editor controls
Matrix editor controls


There are ten 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.2, “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. To do this, select a taxon, select one or more characters, and then click on one of the "set" buttons. You can also use the Batch editor to reduce duplication of effort by copying scores in rows and columns. Be forewarned that changes made with the batch editor can easily affect large swaths of data and cannot be undone.

  • The Partitions button allows you to select a partition and view, in individual boxes, the characters and taxa that are currently in (and not in) that partition. You can drag and drop characters and taxa to add or remove them from partitions. You can also open the partition editor from this window, and so add or delete partitions here. Finally, this window includes a drop-down list from which you can choose which partitions (if any) to display in the matrix editor.

  • The Ontology button allows you to add or delete ontological rules to or from "set state" and "media" in two separate tabs. Beside each rule you can also add an associated action. You can also choose to view these rules as a graph, which will open in a separate window.

  • The View as 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 ! 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.

  • The check button allows you to search for inconsistencies between your matrix and your character rules. When violations are detected, you will be provided with the rule, character, taxon, nature of the violation, and option to edit it or autocorrect all violations. Remember before you choose autocorrect that you cannot undo changes to large swaths of data.

Characters

Adding characters to or removing characters from your matrix

The character editor that appears within the matrix window is similar to the one that opens when you choose "Edit Characters" from the main Matrices page. The primary difference is that there are fewer options for moving or searching characters. 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. To remove a character highlight it and then click on the "delete character" button.

Figure 12.8. The in-matrix editor character editor list

The in-matrix editor character editor list


Editing characters

To edit a character in your matrix either double-click on its name in the matrix or click on the "characters" button and choose it from the character list. Again, the editing tools provided are similar in scope and function to those provided when you choose the "Edit characters" button from the basic Matrices screen.

Note that when you edit a character in the matrix editor you are editing that character's entry throughout Morphobank. 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.

Figure 12.9. The in-matrix editor character editor

The in-matrix editor character editor


Changing the order of characters

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.

Adding comments, media and bibliographic citations to characters

You can add comments to a character by editing it, then clicking on the "comments", "media" or "citations" tabs in the matrix editor.

Character warnings

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 exclamation point will be displayed next to the character name. A warning message will also appear in the "warnings" window when you click on the warnings button at the top of the editor. The warning indicator will display until you open that character's cell for editing.

Figure 12.10. Warning about changed character in the matrix

Warning about changed character in the matrix


Figure 12.11. Warning about changed character in the Warnings window

Warning about changed character in the Warnings window


Character ontologies

About ontologies

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 analyzed. Analyses that now require many hours of work by specialists could potentially be performed by software and powerful data mining techniques could be brought to bear on previously intractable problems.

Ideally, an ontology for morphological phylogenetic 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.

Ontologies have not been widely used in phylogenetic analysis of morphological characters. MorphoBank introduces tools that allow researchers to establish relationships among phylogenetic characters such as character interdependency

Ontologies in Morphobank

Ontologies in Morphobank are just another optional tool you can use to organize your characters and streamline your analysis.

Morphobank provides tools for creation of what we call ad-hoc ontologies. An ad-hoc ontology is a set of rules that a researcher creates within his or her project to establish relationships among characters (e.e. if one character is scored "absent" another character is always scored "-" [inapplicable]." These ontologies are project specific and are independent of initiatives across the Tree of Life to establish formal ontologies for particular taxa. What they can do is help researchers score more efficiently and to find mistakes in their coding.

A Morphobank ontology describes the relationships that you specify between the characters and states in your matrix. The relationships (or "rules") between characters/concepts work as in the following 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, 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.

The relationships among characters can also be visualized graphically, providing a "birds-eye" view of your analysis than can be useful for collaborations, publications and future research.

Creating an ontology

To begin, click on the "ontology" button, at the top of the matrix editor window, as shown below. At the end of this chapter we will discuss how to ensure that your ontology rules work properly and can be applied either automatically as you score cells, or after you have already scored. First we will look at the rules themselves.

Figure 12.12. The ontology seventh from the left in the matrix editor window

The ontology seventh from the left in the matrix editor window


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.

Figure 12.13. List of "set state" scoring rules for a matrix

List of "set state" scoring rules for a matrix


To attach a rule, first select tab for the rule type (i.e. 'Set State' Rules or Media Rules) 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 for which you wish to set scores and the state they should contain. 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. Note that Media Rules, which plot the application of media to certain characters and states, are different from but complementary to “Batch Media Automation,” discussed here: the section called “Cell Media Automation Tool”. To add media to cells using Media ontologies, first select "Add rule" (seen at the bottom of the above figure), then choose "Add Media." Choose a primary character from the top list and dependent characters from the bottom list to create a rule that says "When adding media to character X, automatically add the same media to characters Y and Z."

Figure 12.14. The "add rule" window for "set state" rules

The "add rule" window for "set state" rules


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.

Figure 12.15. The "add rule" window for "media" rules

The "add rule" window for "media" rules


You can delete a rule by clicking on the rule 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.

Visualizing the structure

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 them.

Figure 12.16. Visualization of a set of "set state" scoring rules

Visualization of a set of "set state" scoring rules


Using the ontology

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 the Project Administrator elects to do so.

Checking data using an ontology

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 by clicking the check mark button on the bar along the top of the matrix editor. You may also need to click this "check rules" button for your rules to start taking effect (if your matrix is not already set up to automatically apply ontology rules).

Figure 12.17. Matrix editor button bar

Matrix editor button bar


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 of the rules will be presented. Double-clicking on a violation in the list will scroll the matrix to the score in question.

Figure 12.18. Checking a matrix against a rule set

Checking a matrix against a rule set


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. Violations can also be checked by hand, which can be a useful exercise if characters are still being revised. Just hit the “Recheck” button to refresh your screen as you eliminate violations of the rules (or change the rules if you need to do so).

Generating data using an ontology

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 (located to the far right of the window.)

Figure 12.19. Preferences Button

Preferences Button

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. In other words, 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."

Figure 12.20. Setting matrix editor preferences

Setting matrix editor preferences


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 will not be undone unless you manually overwrite them.

Character Ordering in MorphoBank

Character ordering (also called additive binary coding) is a practice by which researchers assign a cost to certain character changes in multistate characters. For example, if a character has three states, 0, 1 and 2, and it is "unordered" it is equally costly to go from state 0 to either state 1 or state 2. If the character is ordered, it adds two steps to tree length rather than one step to go from state 0 to 2.

Character ordering is a common feature of Nexus and TNT files in practice, and you can now write commands (also called “assumption blocks” in Nexus terminology) to order characters in MorphoBank’s matrix editor so that matrix files can be exported from MorphoBank and retain these commands. Then when the researcher goes to run an analysis in an algorithmic program like TNT or PAUP, he or she does not need to specify those commands again. The commands are embedded in the matrix file. Similarly, if a Nexus or TNT file with ordering commands is imported into MorphoBank, the commands will display in MorphoBank’s Character Editor.

The MorphoBank Matrix editor currently displays whether a character is “ordered” and “unordered”. This characterization is specific to each character, and thus need only be defined once in a project. To order characters in a MorphoBank matrix (in other words, to choose the command “Ordered” which indicates that the “cost” of change between two states is the absolute value of the difference in their state numbers), open the matrix editor and select “Chars” from the top row of buttons, as you would do for any other character-related function.

Figure 12.21. Character button

Character button


This will open the Matrix character list editor, which has many uses including the ability to set ontologies, edit individual characters, and, of course, to set ordering. Click on the “Ordering” button on the top right of the character list editor to open the character ordering editor.

Taxa

Adding taxa to a matrix

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.

Figure 12.22. Matrix editor taxa list

Matrix editor taxa list


Treatment of Multistate Taxa in Matrices

MorphoBank recognizes that Nexus format allows the user to distinguish between polymorphisms and ambiguities for multistate taxa.

Under the Preferences in the Matrix Editor, the user can select whether to treat multistate taxa as "polymorphic" or "uncertain". The default condition is "polymorphic". This choice applies matrix-wide but can be modified on a per-cell basis using the cell editor. Changing a selection in the cell editor affects only that cell.

The multistate taxa tool will be grayed out (disabled) if only one state has been scored for a given cell.

For display purposes on screen in the MorphoBank matrix editor, multistate taxa that are scored as polymorphic by the user appear as separated by a comma, like this "0, 2". Multistate taxa that are scored as uncertain by the user appear as separated by a slash, like this "0/2" or this "1, 4, 6"

The underlying Nexus file that MorphoBank produces will download such that a cell containing multistate taxa that are polymorphic will be represented as "{0, 2}" in the Nexus file, and multistate taxa that are uncertain will be represented as "(0, 1)".

If a pre-existing Nexus file contains the distinction of polymorphic vs. uncertain multistate taxa and is loaded to MorphoBank, the distinction will be preserved and will display as such. Any new changes to the matrix that the user enters will be preserved in future downloads.

Editing taxa notes

You can edit taxon notes by double clicking on the taxa in the matrix (in the main window of the editor; not under the "Taxa" button) and then 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.

Figure 12.23. Taxon Notes Field

Taxon Notes Field


Changing the order of taxa

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.

Removing taxa from a matrix

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.

Warning

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!

Controlling access to cells by taxa

In a collaborative project it is 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.

Note

Intentional access restrictions are not the only reason a taxon can be locked for a member. A taxon can also be locked for a member because the user lacks access privileges in the project (eg. they are an observer, bibliographic maintainer or anonymous reviewer).

Figure 12.24. Taxon/matrix row to which user does not have access

Taxon/matrix row to which user does not have access


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.

Note

To set access control for a taxon you must be the project administrator or owner of the matrix.

Figure 12.25. Setting access restrictions for a taxon in the matrix editor

Setting access restrictions for a taxon in the matrix editor


Creating member groups

In order to understand how to use the access controls for taxa editing, let's digress for a moment and look at Member Groups. To create a member group click on the the "Edit member groups" link in the right-hand navigation on the Project Overview screen. Click on the "add new project member group" button at the top of the new screen. Then give the group a name and optionally a description. Repeat this process until all of the groups you require have been created.

Figure 12.26. The project member groups list

The project member groups list


Once you've established names for your groups, you can begin organizing members. Click on the "manage members" link on the Project Overview screen 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 to which the member should belong and click "save." Each member of your project may belong to as many groups as needed.

Figure 12.27. Adding a member to a group

Adding a member to a group


The Operational Taxonomic Unit (OTU)

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 screen (reached by clicking "Edit Matrix Description" in the Matrices screen is used for all taxa unless the OTU in the taxon itself is set, in which case that OTU is used instead.)

Cells

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.

Scoring

To score a cell double-click on it in the matrix (being sure to click on the area outside of the media thumbnail in the cell.) 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 a 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”.

Figure 12.28. The matrix cell editor window

The matrix cell editor window


Navigating cells

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 the 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.

Note

The cell currently open for editing is highlighted in blue.

Managing cell media

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.

Warning

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.

Figure 12.29. Choosing an image to add to a cell

Choosing an image to add to a cell


Cell Media Automation Tool

To make your work easier, MorphoBank now offers a tool that allows you to place Media in many cells at once. This tool does not score or label Media but, like the batch tool which works in rows, it works matrix-wide to put many Media in place at once.

The Cell Media Automation Tool populates cells with Media by using the Views (orientations) tagged to media. If Media with Views have been linked to character states (in a column), MorphoBank can populate similar Views in the cells of the matrix in that column. If the Cell Media Automation Tool previously placed media that doesn't match a new rule, the old media will be deleted from each cell. If, however, the media was place in a cell by hand, it will remain unaffected.

You can activate this feature at any time during your work if (and only if) you are the Project Administrator or the Project Member who uploaded or created the matrix. To do so, navigate to "Set up this matrix," a small grey button under the title of the matrix. Please note that cell media automation is automatically switched-off at the start of a project, so you must follow these steps in order to use it.

Figure 12.30. Matrix setup button

Matrix setup button


On the resultant screen, you will have the option to check "Enable Cell Media Automation?"

Figure 12.31. Cell media automation checkbox

Cell media automation checkbox


Once checked, a new button will appear in the toolbar at the top of your matrix editor. It will look like a small arrow, and the text "cell media automation" will appear when you hover over it with your cursor. Please note that if you are working with a laptop or smaller screen you may need to expand the size of the matrix window in order to see this arrow.

Figure 12.32. Cell media automation arrow

Cell media automation arrow


Once you have activated your cell media automation tool, how can you put it into effective use? First, you must be certain that your Media - both those destined for cells and those that are with Character States - all have Views (see "the section called “Media views”"). Then, affiliate exemplar Media with your character states and upload Media tagged with the same Views for all of your taxa (you can do these steps in different order if you like). As a reminder, in order to affiliate Media with character state you must open the Matrx editor, click on "chars" along the top row of buttons in the Matrix editor window, OR simply click on "Edit Characters" on the top of the Matrix overview tab. The, in the Character Editor window that appears, double click on the character you wish to edit. You will see another window with several tabs, including one that says "Media." Click on that tab, and you will see a list of that character's states, with an option to upload media to each:

Figure 12.33. Add Media to Character States

Add Media to Character States


If you then activate the abovementioned arrow, the tool will first check what media Views are affiliated with your character states. If the taxa in your matrix rows have the same Media Views in the database, the tool will automatically populate cells with the appropriate Media. In its simplest expression, often a single View is adequate for all states of a character. In such cases the Cell Media Automation tool will know to insert that same View in all the cells below. In some cases, however, scientists use different Views for different states. In cases like this both images will be inserted until you score and then the one that does not pertain will be removed. The tool will not score, label, or overwrite media that were inserted by hand. You can use the tool more than once and it will keep updating. Before the automatic cell population occures, however, you will have the opportunity to confirm your choice. A box that looks like the figure below will appear:

Figure 12.34. Cell media automation confirmation

Cell media automation confirmation


If you decide not to follow-through on the cell media automation, you can choose "cancel." If you go ahead with the process and later determine that you want to remove media, there is an "undo" tab (visible in the figure above.) When this is selected, you are given a list of past actions with Status, Description, and the date they occurred. You can select the one you wish to undo and press "Undo" at the bottom of the window. This feature will remove all the media inserted by the cell media automation as well as any media inserted by the corresponding character media ontologies, discussed below.

As mechanisms for streamlining your work, one might confuse Cell Media Automation with Media Ontology Rules. However, they are actually diferent tools that are designed to work in tandem. Like Cell Media Automation, Media Ontology Rules are disabled at the start of a project and must be actively enabled by the Project Administrator Ontologies are representations of the relationships between concepts in your matrix. Therefore, the Cell Media Ontology rules work like this: you can create a Rule that says "If Character W has a particular Media associated with it, always apply that Media to Character X, Y, and Z. This action will be triggered, for example, as you score, if you happen to add Media to W. Alternatively, if you already have an entire column with Media for Character W and you then run a "Rule Check," (the small checkmark from the top row of your matrix editor) MorphoBank will copy Media from column W into columns X, Y and Z according to your rule. Cell Media Automation, on the other hand, is based simply on the Media Views rather than on Character rules. To use both tools, be sure that Cell Media Automation is turned on (as described earlier in this section) and check "Apply character rules while scoring" under "Matrix Preferences."

Figure 12.35. "Rule Check" in the Matrix Toolbar

"Rule Check" in the Matrix Toolbar


Any media that was added using the Cell Media Automation feature will also be applied to the Media Ontology feature. This means that when Cell Media Automation is applied to characters that have rules, the media are then inserted into the "daughter" characters. In other words, Cell Media Automations allows you to add media to any cell associated with a chosen character, but ontology rules allow you to impact other cells not in that column. By employing both tools you can maximize batch Media functions by adding the same media to additional characters according to the automatic framework you've established using Ontologies. See the section called “Ontologies in Morphobank”.

Labeling images

Labeling images is described in Chapter 10, Using Media (Images, Video, Sound) 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.

Making changes to your matrix data en-masse

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

  • Ability to undo batch actions

Figure 12.36. The batch operations window

The batch operations window


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).

Figure 12.37. Batch Row Score Editor

Batch Row Score Editor


While you are working in a matrix, you may find that you need to add another representation of a taxon that is closely related to one already in your analysis. With this in mind, the batch editor includes a tool that allows you to duplicate an existing taxon in your matrix, and then make changes to character states as needed. This saves time and effort by eliminating the need to re-enter scores and notes. To duplicate a taxon in a matrix, select "Copy a Row" tab in the batch editor. When you click this button, you will see a checkbox that allows you to decide whether or not you will include notes in your copy. This tool allows you to duplicate an entire row of scores (and notes, if you wish) from one taxon to another taxon. You can then edit the parent or daughter row.

Figure 12.38. Copy a Row

Copy a Row


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.

Batch functions could potentially be risky without an "undo" feature. The last tab in the Batch Editor allows you to choose a batch function that you wish to reverse. Under the "Undo" tab, you'll see a list of all the batch functions performed in your matrix with a date, a description, and a status of "done" or "undone." To undo a batch edit, select it from this list and simply click "undo." Altered cells will revert to their original state. To double-check undone media affiliations, you can refresh the Project Information page to see how many total cells have affiliated media. You can also change the matrix setting to color cells with media to get an overview of where the changes were made.

Figure 12.39. Batch "Undo" Feature

Batch "Undo" Feature


Downloading a NEXUS-format copy

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.

Deleting a Matrix

To delete a Matrix from your project, first click on the “Matrices” tab on your project. Once on the Matrices screen, you must click on the “Set Up this Matrix” button on the Matrix you wish to delete.

Once you click on this button, you will see a screen where you can edit information on the matrix such as the title, access, and other details. On the top and bottom of this form, there are “Save” and “Delete” buttons. You can click on either “Delete” button to fully delete your matrix.

Chapter 13. Folios

Folios are annotated groupings of media selected from your project. Your project can include as many folios as necessary and each folio can contain any media item in your project, in any order and with attached notes.

Folios are a useful tool to organize and present your data. Prior to publication of your project, folios are only accessible to project members. After publication all folios become publicly accessible (unless they are explicitly set to not publish) and can be accessed using "PermaLinks". These stable, easy to publish URLs (described in the section called “Public Access”) are suitable for publication in a paper or online.

Creating Folios

To create a folio, click on the Folios tab in the left-side navigation. You will be presented with a list of existing folios. You may edit the name and description of an existing folio by clicking on its "edit" button. You may remove a folio by clicking on its "delete" button. To create a new folio click on the "Add new folio" link in the upper-right hand corner of the tab.

When you create a new folio in the Folios tab you are only creating an empty container. To add or remove media to or from a folio, you need to use the folio tabs under the matrix and media tools.

Adding Media

To add media to a folio, click on the Folios tab in the left-hand navigation, choose (or create) a folio, and click on the "Edit Folio Media" button . You will be presented with a list of media already present in the folio, along with three buttons: "Back to list," "Edit folio info" and "Add media to folio." Select "Add media to folio" and enter the first few letters of the taxon in the desired image in the type-ahead field. A list of matching images should appear; choose one and then click on the "save" button. As an alternative or to add a batch of media to a folio, go to the Media tab and click the "folio options" button. A box instructing you to "use checkboxes below to select media to add to the following folio" will then appear. Choose a folio from the drop-down list, mark the checkboxes in the upper right-hand corner of your desired media, and click the "Add Media to Folio" button.

Changing the Order of Media

By default media are displayed in the folio in the same order as they were added. You can change the order by clicking on the Folios tab in the side-navigation, then clicking on the "edit" button next to the desired folio. You can then drag and drop the media in your folio in the desired order.

Public Access

Folios are published when the project is published (unless explicitly set not to) and may be linked to using a URL in the format: http://morphobank.org/permalink/?F20 where 'F20' is your folio identifier. Folio identifiers always begin with the letter 'F' and appear next to the folio name in the project folios tab. Your project must be published for folios to be accessible to the public.

Chapter 14. Project Documents

Members with full access may add any number of documents to a project. Documents may be in any format, and can document aspects of the project or provide data in formats that are not directly supported by MorphoBank. Each document may include an optional title and description, and may be published along with other data (media, matrices, etc.) or kept private to the project.

Figure 14.1. Adding a project document

Adding a project document


Adding a Document to Your Project

To add a document, select the docs tab in the project tab bar, then click on "add new project document" and fill out the new document form, displayed above. You are encouraged to fill in the title and description fields to better describe the file, although they are optional. If you wish to publish the document when the project is published, be sure to set the status drop-down to "publish when project is published." Documents with a status of "never publish to project" will never be made public.

Published documents are listed on the MorphoBank project page once the project is published.

As with other project data items, you may restrict editing access for the document to the owner (the member who added the document to the project) or allow all full project members to edit by setting the access drop-down.

Document Folders

If you wish to group documents together, you can also create document folders in your project. To do so, simply choose the "Create Document Folder" button, and give your folder a name, description, and access settings in the resultant screen. You will then have the option of adding new documents to this folder as an organizational tool.

Public Access to Project Documents

When a project is published, all documents with a "publish when project is published" status will be listed and made available for download on the project's MorphoBank project page, accessible from the project browser and search tab.

Chapter 15. Managing Access

The creator of a project, who is also by default the Project Administrator (PA), has sole access. At any time the PA can elect to invite collaborators to join the project. Collaborators don't have to be registered with MorphoBank to join. If the invitee is already a registered member of MorphoBank then they they will receive an e-mail notification and the project will appear in their project list the next time they login. If the invitee is not a registered member of MorphoBank, they will receive an e-mail notification with login instructions and a pre-issued password.

The current membership list for a project can be accessed via the "Project Overview" screen. To the far right of that screen, the PA has a list of multiple options, including "Manage Members" and "Edit Member Groups." Clicking on "Manage Members" will display a list of all of the current members of that project, their status, and an option to edit any of that information.

Figure 15.1. The project member list

The project member list


Adding Members to a Project

To invite a collaborator to your project, click on Manage Members from the Project Overview screen and click on the "add new member" button. You will then be prompted to enter an email address for the new member. Enter the address, and click "go." You will then see a form like the one below. Be sure to choose the appropriate access level for the new member. Note that once the invitation is sent the member has access to the project. There is no confirmation process.

Figure 15.2. Adding a new member to a project

Adding a new member to a project


Types of access

The PA can grant full membership, "character annotater," "bibliography maintainer" or observer status to collaborators. Full members may edit any item in the project, subject to item-level access restrictions. Observers may not modify anything in the project, no matter the access restrictions on items. Character annotaters are in-between: they can edit everything but characters and states, subject to item-level access restrictions. Bibliography maintainers may edit only bibliographic data.

Removing a Member From a Project

To remove a member from a project, go to the Members tab and click on the "delete" button next to the member you wish to remove.

When you remove a user from your project their data will remain - they just can't access the project any longer. Users marked as "deactivated" have had their MorphoBank login suspended across the board by the MorphoBank administrators for some reason. In this case the user cannot login at all, to any project, but when their login is reinstated they will once again have access to your project.

Anonymous Reviewer Access

Anonymous, read-only access may be enabled by the project Administrator using the reviewer login settings on the Project Info form accessed through the "Edit project info" link to the far right of the Project Overview page. As the name suggests, this type of access is designed to accommodate anonymous reviewers from publications. Once enabled, reviewers can login by entering the project number in the email address field and the reviewer login password entered by the Project Administrator in the Project Info form. Don’t forget – you have to tell editors and reviewers your project number and reviewer password when you invite them to review your project.

Figure 15.3. Granting anonymous reviewer access

Granting anonymous reviewer access


To enable anonymous access, check the "Allow reviewer login?" button in the Project Info form and enter a password in the "Reviewer login password" field, then hit the "save" button (not visible in figure).

Item-level Access Control

MorphoBank adopts a simple approach to data access within a project. All primary data items (taxa, characters, specimens, media and matrices) are "owned" by the member who created them. The owner has the option of reserving editing access for themselves or allowing all full project members to edit. (Editing access includes the ability to delete an item.) By default all newly created items are editable by all; restricted access must be explicitly set by the creator using the access control menu present on the basic editing screens for each type of data item.

Figure 15.4. Access control menu

Access control menu


Who Gets to Edit What?

Access control rules in MorphoBank reduce down to this:

  • The public (ie. users without logins) can only see those items in published projects that are marked to "publish when project is published." The can never see unpublished project data.

  • Anonymous reviewers and members with observer status can never change anything in a project. They can only view project data in the projects to which they have been granted access.

  • Full members of a project can always edit items that they created.

  • Full members of a project can edit items that others created only if those items are marked as "Anyone may edit this item".

  • No one can edit project data once the project has been published.

Chapter 16. Backing Up Your Data

One advantage of a web-based system like MorphoBank is that time-consuming maintenance tasks such as data backup can be centralized. MorphoBank runs on servers hosted by the San Diego Supercomputing Center at the University of California, San Diego (http://www.sdsc.edu). These servers are backed up nightly and serviced by a professional full-time staff of system administrators.

This is all well and good, but how do you know that your data is safe? Sometimes there's nothing more reassuring than having a copy of your data on your own machine, or even several of your own machines. And maybe a few copies on DVD as well.

This is where the MorphoBank data backup tool comes in. The tool allows you to download a copy of your project data at any time. The copy is a snapshot of the project data at the time the backup was initiated.

The backup includes copies of all the originally uploaded media files, so for some projects the download will be quite large. You should balance your need for an up-to-date backup with the required download time. However, we encourage all projects to perform a backup on a monthly basis, or more frequently if required.

To backup your project, go to the Options tab and then click on the Data Backup tab. Then click on the "Download Project Data" button, which will initiate the creation and download of a ZIP-format archive. For large projects, be patient. The creation of the ZIP archive can take some time.

The Download Package

The ZIP archive contains the following items:

Project media

The originally uploaded files for all project media are included in the backup. To minimize the size of the download, files derived by MorphoBank from uploaded media are not included, only the originals. These missing files can, of course, be regenerated from the originals.

Matrices in NEXUS format

All project matrices are included as NEXUS format files. Note that these are "straight" NEXUS files and do not include any links to media that have been added in MorphoBank.

Project documents

All files uploaded into your project using the docs tab are included.

Uploaded NEXUS files

Copies of all NEXUS files uploaded into project matrices are included..

Project data in SDD format

Most, but not all, project data are included in an XML-format file conforming to the Structure of Descriptive Data (SDD) standard (http://wiki.tdwg.org/twiki/bin/view/SDD/WebHome).

A single SDD file is generated for the project and includes:

  • Project information (title, abstract, citation, etc.)

  • Media views

  • Taxonomic names

  • Specimen information, with references to taxonomic names

  • Media, including extended information and references to specimens

  • Characters and states, including references to media

  • Matrices, including references to media

Chapter 17. Publishing Your Data

MorphoBank permits the posting of peer-reviewed scientific research. Exceptions may be made (generally labeled "MorphoBank Exclusives") at the discretion of the Executive Committee. These studies have typically been conducted under the supervision of research scientists. Use of MorphoBank for educational and popular initiatives is in the planning stages. Users whose research has not been peer-reviewed may use the site for organizational purposes, but are asked not to make their projects live.

Prior to publication, you need only specify a title and abstract for your project which are visible only to you and your collaborators. Things change when your article is to be published. In order to present your work publicly, enough information must be provided to construct a citation and an informative description on the MorphoBank project list and search engine.

You can set the project information by entering your project, then clicking on the Project Info tab and then clicking on the "update" link.

Warning

Remember that once your project is published, you will not be able to change project description information yourself. If an error becomes evident after publication contact MorphoBank via the online form available from the bottom of the MorphoBank homepage for assistance.

Project Information Fields

The Project Information tab contains the following information fields and controls:

Table 17.1. Project information options

InformationDescription
TitleTitle of project, used to identify the project to all members. Once the project is published this title will be displayed to the public as the primary label for your data set, so be sure to formalize it prior to publication. eg. Phylogenetic analysis of the Sironidae (Arachnida:Opiliones: Cyphophthalmi)
AbstractYour project abstract. Although this is optional, and only accessible to project members and MorphoBank staff prior to publication, you are strongly encouraged to formalize this text as soon as possible. MorphoBank staff members periodically read project abstracts and may question those projects lacking one.
StatusDetermines whether a project is published or not. Once you set this to published and click the "save" button, your project is public and cannot be modified. So think before you change this!
Journal TitleThe name of the journal in which the article based upon your dataset was published. Required if the data set has been published. eg. Invertebrate Systematics
Journal URLA valid URL leading to your published article on the publisher's web site. This is optional and should only be filled in if your data base been published. This should only point to a publisher's web site. Do not use this link to point to personal web sites. This is optional but strongly encouraged. eg. http://www.publish.csiro.au/paper/IS03029.htm
Journal VolumeThe volume number of the journal in which your data set was published. Required if the data set has been published. eg. 12
Journal NumberThe number of the issue in which your data set was published. Required if the data set has been published. eg. 1
Journal Logo ImageJournal logo will automatically appear when the journal title is selected. If you are entering a new journal in MorphoBank, curators will add a journal logo at the time of project publication. Feel free to contact support to ask for the journal logo to be added to MorphoBank.
Journal YearThe year of the issue in which your data set was published. Required if the data set has been published eg. 2006.
Article authorsA list of authors of the published article. Names should be separated by commas. The primary author should be listed with last name first; subsequent authors should be listed with first name first. Required if the data set has been published. eg. Sues, H.-D., E. Frey, D. M. Martill, and D. M. Scott
Article TitleTitle of article, as it appeared in the published journal. Required if the data set has been published.
Article PaginationPagination of article as published. Required if the data set has been published. eg. 5-15
List on active projects page?If checked your project will be listed on the active projects page (http://morphobank.org/index.php?g=about&s=projects). This page lists all ongoing unpublished projects on MorphoBank. No information beyond title and the name and institution of the project administrator are given. We encourage you to leave this checked.
Allow Reviewer Login?If checked, anonymous logins are allowed using the project number and the password entered in the Reviewer Login Password field. This feature enables you to grant anonymous read-only access to your data set to reviewers. Read-only access without anonymity is also possible. See the Managing Access chapter for more information.


Accessing Published Data on MorphoBank

Once published your data will be accessible in three ways:

  • as lists of published media and matrices linked to from a project summary page. These lists are similar to the matrix list and media browser in the MorphoBank editing interface, but without editing capabilities. The project summary can include an abstract, citation, links to the published article, and other relevant information.

  • in the MorphoBank search engine. Your media and matrices will be included in the results of searches on the MorphoBank.org site.

  • as folios. Folios are groupings of selected project media. Using the project folios tab, you can create as many named folios as you need. You may then select specific media to add to your folios using the folios tab within the media or matrices tabs. Once you have added items to your folio you can return to the project folios tab and change the order of the media, add annotations, and preview the resulting folio. Folios are published when the project is published and may be linked to using a "PermaLink" URL whose format is described below.

Citing Your MorphoBank-Hosted Data

Each MorphoBank project is issued a unique identifier beginning with the letter 'P' for project. This identifier is displayed next to your project title in the project list and on the project info tab in your project options. Once your project is published you may link to your project with a URL in the format http://morphobank.org/permalink/?P44 where 'P44' is replaced with your project identifer. Always precede your project number with the question mark and the letter P. For unpublished projects, the only way to access data is by logging in to MorphoBank.

You can cite individual folios using a URL in the format: http://morphobank.org/permalink/?F20 where 'F20' is your folio identifier. Folio identifiers always begin with the letter 'F' and appear next to the folio name in the project folios tab. Your project must be published for folios to be accessible to the public.

These PermaLink URLs will remain stable and unchanged no matter how many projects are added to MorphoBank, making them suitable for inclusion in published papers.

Chapter 18. Project Duplication

Contacting MorphoBank

Investigators can request that a published or an unpublished project be duplicated for reuse. While MorphoBank aims to meet the needs of all users, storage is finite and some projects with media are quite large. Therefore, we ask that researchers consider best practices prior to submitting a request for duplication.

Duplication is only performed by MorphoBank administrators upon request. Requests should be made via the online form at the bottom of the home page where it says “suggestions/ideas/project duplication requests HERE”. Requests for duplication should include justification for duplication and project id. If you do not need particular features copied please tell the system administrators in the request.

A duplicate is an exact and full copy of the original project with the exception that character and cell comments and character and cell logs are not duplicated. Project duplication efforts isolate parent and children data. There is no cross sharing of data. When users edit various parts of the duplicate projects the changes do not have any effect on the master project. Users will be contacted by MorphoBank once the duplication request has been fulfilled. Derived projects will appear at the bottom of the project list with the same name as the parent. The user can log in and change the name of the duplicated project.

Duplicating Published Projects

If the project to be duplicated is published, the person requesting the duplication should state in the request who the Project Administrator of the duplicate should be and whether or not the old members of the project should be deactivated. New members can then be added to the duplicate copy by the person who requested the duplication. Requests for duplication of published projects can be received from any MorphoBank member.

Duplicating Unpublished Projects

If the project is unpublished, after duplication the daughter project will appear in the list of active projects of all members of the original project. If one does not wish to make the duplicate available to all members, the Project Administrator should simply delete those other members from the duplicate project.

If the project is unpublished and the person requesting the duplication is not the Project Administrator, that person can request that he or she be made the Project Administrator of the duplicate copy. These kinds of project duplications will be done in consultation with the Project Administrator of that project.

Requests for duplication of unpublished projects will always result in the notification of the Project Administrator of that project before any action is taken. 
Preferred candidates for duplication are projects that:

  1. are intended to serve as a common base of data for two or more distinct sub-projects. Duplication allows your project data to be "branched" into sub-projects.
  2. are scheduled for partial publishing at different times. Branching allows you to create "snaphots" of your project for publication, which you continue working on the primary copy.

Chapter 19. Staging a MorphoBank Project for the Evolution Project

MorphoBank users can now maximize the impact of their projects by sharing them on the Evolution Project. Despite the importance of using phenomic (morphological, behavioral, etc…) data for phylogenetic tree-building, scientists have often found the data collection to be a slow process.  The Evolution Project is an NSF-sponsored experiment by a team of scientists to make data collection go faster by using crowdsourcing to work toward building the evolutionary Tree of Life. Users are asked to score cells in matrices that you've partitioned for this explicit purpose. "Tasks" in the Evolution Project's lexicon imply "characters" - you are publicly sharing characters to be described via crowdsourcing. To enable crowdsourcing, you must first contact a member of the MorphoBank team (use the Ask Us form linked to in the main navigation for more information). Then you will have access to tools that allow you to unlock your project - simply navigate to your "Project Info" screen and scroll down. You will see a section of the screen under the heading "Crowdsource this Project" with a checkbox labeled "Crowdsource your project on the Evolution Project?." Checking this will enable Evolution Project tools throughout your project. The Evolution Project is under development as of 2014. The MorphoBank community will be notified when it is released.

Figure 19.1. Crowdsourcing Option

Crowdsourcing Option


You will then have access to your Evolution Project "dashboard." This is located to the right of your Project Overview page, with other commonly used tools such as "Edit Project Info" and "Manage Members." The dashboard will display those elements of your project that will be publicly visible on the Evolution Project, and it will provide links to pertinent editors within MorphoBank.

Figure 19.2. Evolution Project dashboard

Evolution Project dashboard


When you click on the dashboard link, you will see your project name and description as they will appear on the site, the names and bios of project members, the matrices marked for crowdsourcing, the relevant taxa, and the characters (tasks).

Figure 19.3. Dashboard tools

Dashboard tools


If you wish to make changes to your profile as it appears on the dashboard and elsewhere, you may do so at any time by clicking on "Profile" above the global search bar on the top right of your screen:

Figure 19.4. Edit profile link

Edit profile link


Now let's talk about how to prepare each component of your project for the Evolution Project. First, you must create a partition in your matrix that includes the characters you wish to crowdsource. This allows you to prepare your MorphoBank project for a layperson's eyes without compromising the data as a whole within MorphoBank. Once you have created a partition, you will see a checkbox in the lower right corner of the partition editor that reads "Enable partition for crowdsourcing in the Evolution Project?" Check this when you are ready to make the partition public.

You may also want to make adjustments to the characters and taxa within the partitions to make them more accessible to the general public. MorphoBank also recommends using ontologies to organize your characters and streamline your analysis, thereby clarifying tasks and increasing the utility of crowd sourcing. See the section called “Ontologies in Morphobank” for more information. Remember that users will be tasked with identifying character states, so they will need clear descriptions and pictures. You can access the character editor from your Evolution Project dashboard by clicking “Edit Project Characters” (in orange). Once within the character editor, you will see a tab labeled "crowdsource" (provided you have project administrator status).

From within this tab you can determine how the character is perceived on the Evolution Project site without compromising your matrix as it appears in MorphoBank. For example, you can use this space to write a user-friendly name and description for your character, which may be more appropriate than your internal name and notes. This is what will appear as a “task” for the Evolution Project user. You can also designate the difficulty-level of the task – how experienced does a user need to be to score this cell?  Do you want to lock this task so that only more experienced users can access it? Choose beginner, intermediate, or advanced.

Figure 19.5. Crowdsource Character

Crowdsource Character


Taxa can also be individually prepared to suit the purposes of the Evolution Project. You can access the Taxon editor either through the left-side navigation on MorphoBank, or by clicking “Edit Project Taxa” on your Evolution Project dashboard. Select the taxon you want to crowd source, click on it, and scroll down to the bottom of the screen. You will see an option to “crowd source this taxon,” which must be checked to enable Evolution Project fields. When this is activated you will be able to enter a brief, user-friendly description of the taxon and upload an exemplar image.  

Figure 19.6. Crowdsource Taxon

Crowdsource Taxon


Remember that although you will probably want to spruce-up individual characters and taxa in this way, you do not actually need to check each individual one to stage your project on the Evolution Project. If characters and taxa are acceptable as-is, you can simply check the crowd-sourcing option on the revelent partition, as described above. Once your partition has been crowd sourced, it will appear on the Evolution Project site and users will be able to log in and complete tasks. As they score more taxa, users will rise in rank and have access to those tasks deemed more advanced by project administrators like you.

It is absolutely necessary to use MorphoBank's media features when preparing Evolution Project tasks. Without a visual representation of the character, users will have nothing with which to work. It is also helpful to include Media Views, so users will have more context for understanding the character.