General 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 1.3. Right hand menu options for Project edits.

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 on the Browse Projects page).  Prior to publication this information remains accessible only to you and your collaborators. Although you may begin your project with only a title, you must complete the other required fields 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. If starting from a published paper, you may begin by entering the DOI into the DOI field on this page, and clicking <Retrieve>. Bibliographic information except for the abstract will be automatically pulled in.

The project accession code

Each project is issued a unique MorphoBank project ID. These IDs are always the letter P followed by a number (Project 4063 is represented ast P4063). The project ID 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 and in the title bar of your browser window when you are editing or viewing a project. The project ID should be included in any e-mails to MorphoBank technical support. It is also used to construct PermaLinks to your project once it is published. Learn more about 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. Learn more about 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. You can add additional taxa, specimens and views at any time.

...

...

Media views

"Views" describe the anatomical view displayed by images (and other media) in your project. Some example views are "wing, lateral," "leaf venation," or "antenna".  A view is not the medium used to generate the image, a view is not "CT scan" or "light microscopy."  Views are the means of telling someone looking at the image what they are looking at.  Views provide a straightforward means to categorize project media (2D and 3D images) according to anatomical feature. 

...

Figure 1.4. Setting Up Media Views

Taxonomy

The next foundational step in setting up your project is assembling your taxonomy.  In MorphoBank you can use taxa of any rank that suits your project (e.g., species, genera, families, or even rankless taxa). As you enter taxa in your project workspace using the Taxa link in the project menu, MorphoBank builds a central taxonomic directory exclusive to your project. You may enter taxa in several ways:

...

All taxonomic editing features are located in My Projects > Taxa. More details found below in the Managing Taxonomy section.

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.

...

All specimen editing features are located in the Specimens section when editing a project. More details found below in the Specimens section.

Bibliography

You can attach bibliographic citations to taxa, characters, media, specimens, matrices and scores in matrices. In order to create a citation in a matrix, 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. More details found below in the Project Bibliographies section.

Adding Data

Once project options and context are established, you can start adding 2D and 3D media, characters, and matrices to your project.

...

Learn More about Using Matrices.

Inviting Collaborators

The Project Administrator - 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.

...

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 Project Administrator 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 (e.g., 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.

...

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 Project Administrator 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 (located on the right side of the Project Overview page) to publish their project.

...

Establishing Context for your Project

"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. A View should indicate both the orientation and element in your 2D or 3D image, for example, 'dorsal skull' or 'cross-section of leaf' or 'CT scan of insect body'. A View should never be simply a description of the tool used, i.e., 'light microscopy" - it should always tell the reader what this is a picture of.   MorphoBank anticipates that you will use the same Views over and over and, to save you time, creates 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 one of the most useful tools for matrix data exploration.  If your project consists of a single large matrix or supermatrix, you can then create any number of Partitions, which are your chosen subsets of characters and taxa from that matrix.  You can download partitions and use them for analyses. Using partitions is a much less error-prone work flow than having many separate, free-standing matrices. Partitions simply grab, in real time, from your single, overarching supermatrix, taxon and character subsets as separate, smaller matrices. You can create as many partitions as needed, and a taxon or character may belong to as many partitions as exist.

...

Figure 2.3. The partition editor showing the tool to select and display a partition

Publishing Partitions

Because 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 (you must be Project Administrator to do this). 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 2.4. Publishing a partition can be achieved by selecting the fourth choice shown above

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 unpublished project. This directory is specific to your project and not shared across the project workspaces of other scientists. 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.

...

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 Checkers

MorphoBank links to two online taxonomic authorities: NCBI Taxonomy and the Paleobiology Database. Validation of your taxa against NCBI Taxonomy occurs automatically in the background and does not change your data in any way.  If the taxon you entered has no match to the NCBI Taxonomy hierarchy, an orange asterisk will appear next to it.  The purpose of this validation is to improve navigation of MorphoBank's publish projects.  Additionally, when adding taxa by hand (or reviewing taxa after a batch import) you can employ the "Validate Taxonomy" tool to look for additional higher taxonomy matches for a given taxon at the Paleobiology Database. This tool will introduce new higher taxonomy terms into your project if you choose to use it. The Validate Taxonomy tool searches the Paleobiology Database and allows you to pick and choose among the hits to affiliate your taxa with higher taxonomy.

...

Figure 2.6. The taxonomic directory showing the Validate Taxonomy tool and the orange asterisk indicating that a taxon is not listed in NCBI Taxonomy

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 taxon batch" link and using the displayed form to upload a properly formatted taxon file.

...

Batch adding taxa using a TNT or NEXUS file

When uploading a TNT or NEXUS matrix 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.

...

You should always spot check your taxa after upload but clicking on some of them to see that the taxonomy has been appropriately assigned to rank.

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. If your taxon is extinct it is important to indicate that.

Editing extinct status of taxa

To batch update the extinct status of taxa in your project, click on the Taxa tab and then on the "Edit extinct taxa" button (Fig. 2.5). You can drag and drop taxa from one list to the other and move taxa in batches from one side to the other.

Image RemovedImage Added

Figure 2.7. Editing taxon extinct status in batch

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 then make adjustments by hand for taxa that do not fit that rank.

Image Modified

Figure 2.8. The taxon editing page showing the form fields for ranks.  Here only the genus and species are completed.

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.

Finding specimens

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

Image Modified

Figure 2.9. Portion of the specimen directory.  Note examples of unvouchered (top arrow) and vouchered (bottom arrow) specimens, the latter have a collection and catalog number.

...

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 one at a time

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.

...

Figure 2.10. Specimen entry form for vouchered specimens

Vouchered vs. Unvouchered specimens

In the above figure the button "Type of Specimen Record" lets you distinguish to the database whether you are entering data from a vouchered and unvouchered specimen record.

...

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.

Adding a batch of specimens

Click on the 'Add specimen batch' button in Fig. 2.9. You will be taken to a page where you can upload a tab- or comma-separated file with your specimen information from your computer. Instructions on the fields and their contents are on this page as well.

Image Added

Figure 2.11. Batch upload page for specimens

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 a bibliography from the popular EndNote citation management software or any other software that can export in EndNote XML format. Once references are in your bibliography may be attached (with specific page numbers and comments) to taxa, characters, specimens, media, matrices and matrix cells in your project.

...

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 2.13. Editing a single bibliographic reference

Importing bibliographic references from external reference management programs

...

You will be presented with the results of the import when it is complete. When uploading a new Endnote XML file to an existing project bibliography, the new file will generally append itself to the list of references. However, if one uploads an EndNote XML file which contains citations that are already present, the related citations are updated. For example, if one 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.

Using Media (Images, Video)

Supported media formats

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

...

Uploading Media

Media (2D and 3D images, video, or sound) should be a key component of any MorphoBank project. All MorphoBank projects include at least one media item, and many contain hundreds or thousands of media items. MorphoBank allows you to upload as many media as needed for your scientific research, to use these media to document scorings in your matrices and to assemble these media into annotated groupings (see Folios) for online publication.

...

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.

Uploading and Viewing CT Scans and 3D Media

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. The TIFF format is recommended for images in stacks intended for reuse by other researchers.

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 3D media.” You can upload and label your CT stack, 3D surface or animation with specimen information, views, and copyright restrictions just as you would with other media upload formats.

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.

Image Removed

Figure 3.2. MorphoBank's symbol for a 3D image, e.g., PLY or STL file.

Viewing CT Scans and 3D Image Files

You can view a sample frame of an image stack from within MorphoBank prior to download. 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.

Image Removed

Figure 3.3. A 3D image with its associated data on specimen, view and copyright

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.

Image Removed

Figure 3.4. A 3D image surface rendered on MorphoBank.

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.

Image Removed 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:

Uploading 2D Media

To add a media file to your project, click on Media in the left-side sub-navigation.  If it is a single 2D Media, make that selection.

Image Removed

Figure 3.5. Adding and editing a single media item

Image Removed

Figure 3.6. Portion of upload form to add new media

Several fields need to be completed when loading media so that future users of your data understand what this is image is of.  A media item may show left or right and the side can be indicated. 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.

Image Removed

Figure 3.7. 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. Remember a View should tell the user what this image is a picture of (e.g., leaf, skull, cell wall, etc...)

Adding a Batch of 2D Media Batch


You can upload batches of 2D media directly into your project using the Add Batch of 2D Media upload tool, which will add any number of media directly to your project in a single step, provided all the media items have been compressed into a single archive file (e.g., a Zip file). 

To upload a batch of media first compress those media on your desktop as a ZIP, TAR, TAR+gzip, or TAR+bzip archive. Then click 'Add Batch of 2D Media".

You will then see a screen like the one shown below.

Image Removed

Figure 3.8. Portion of form to add a batch of 2D media at one time.

Under the header "Choose a ZIP, TAR, TAR+gzip, TAR+bzip archive or individual file" click on the Browse button and select a batch of media that you have already compressed. Fill in any of the other fields for which you have data or preferences, including  specimen, 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 media batch " text. When the upload and processing is complete you will be presented with a summary of results from batch processing.

...

Uploading 2D Media

To add a media file to your project, click on Media in the left-side sub-navigation.  If it is a single 2D Media, make that selection.

Image Added

Figure 3.2. Adding and editing a single media item

Image Added

Figure 3.3. Portion of upload form to add new media

Several fields need to be completed when loading media so that future users of your data understand what this is image is of.  A media item may show left or right and the side can be indicated. 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. If you have not defined any media, use the Add New Specimen link (Fig. 3.3 in orange) to create a new one without having to exit the add media screen.

Image Added

Figure 3.4. 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. Remember a View should tell the user what this image is a picture of (e.g., leaf, skull, cell wall, etc...)

Adding a Batch of 2D Media Batch


You can upload batches of 2D media directly into your project using the Add Batch of 2D Media upload tool, which will add any number of media directly to your project in a single step, provided all the media items have been compressed into a single archive file (e.g., a Zip file). 

To upload a batch of media first compress those media on your desktop as a ZIP, TAR, TAR+gzip, or TAR+bzip archive. Then click 'Add Batch of 2D Media".

You will then see a screen like the one shown below.

Image Added

Figure 3.5. Portion of form to add a batch of 2D media at one time.

Under the header "Choose a ZIP, TAR, TAR+gzip, TAR+bzip archive or individual file" click on the Browse button and select a batch of media that you have already compressed. Fill in any of the other fields for which you have data or preferences, including  specimen, 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 media batch " text. When the upload and processing is complete you will be presented with a summary of results from batch processing.

Uploading and Viewing CT Scans and 3D Media

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. The TIFF format is recommended for images in stacks intended for reuse by other researchers.

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 3D media.” You can upload and label your CT stack, 3D surface or animation with specimen information, views, and copyright restrictions just as you would with other media upload formats.

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.

Image Added

Figure 3.6. MorphoBank's symbol for a 3D image, e.g., PLY or STL file.

Viewing CT Scans and 3D Image Files

You can view a sample frame of an image stack from within MorphoBank prior to download. 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.

Image Added

Figure 3.7. A 3D image with its associated data on specimen, view and copyright

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.

Image Added

Figure 3.8. A 3D image surface rendered on MorphoBank.

Copyright Tools for Any Uploaded Image

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 Creative Commons reuse license, and space to enter the copyright holder’s name and the relevant bibliographic reference.

...

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

Matrices and Documents on MorphoBank can be marked with a CC0 license, distinct from Media copyright settings.

...

Figure 3.14. Notification prior to download of Matrices, Character lists and Ontologies

Delete Multiple Media Feature

Occasionally a user 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 Ass Batch of 2D or 3D Media Upload feature, MorphoBank has a Delete multiple media feature to allow efficient deletion of multiple media. To use the Delete multiple media tool, navigate to the “Media” tab, and then select the orange button “Delete multiple media” 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 check mark 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.

...

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

...

Figure 3.18. Media editing form.  Note the Download link directly under the media item.

View modes

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

...

Figure 3.19. Media browser view modes

Sorting

The browser under the Media tab, accessible for unpublished projects when logged in, has several tools to sort media items by a number of criteria.  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.

...

Figure 3.20. The tool for ordering media in unpublished projects

Filtering

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

...

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.  This function is found in the upper right corner of all MorphoBank pages except the matrix editor. While logged-in the search function 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 and may be useful to the scientific endeavors of investigators building content. 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.

...

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.

...

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

...

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

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.

...

Figure 4.2. Accessing the Character Editor through the Matrix main tab

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 word "Characters" button on Matrix page, you will see a screen called "Character List," a list of characters from the current matrix. The characters are displayed in the same order in which they appear in the matrix.

...

Figure 4.4. The Character Editor

Adding Characters

Adding a single character

To add a new character click "+ Add new" in the upper-left corner of the Character List. A new screen will appear called "Add character." Enter the name of the character, its type and where it should be positioned.  Then click "Add".

...

Figure 4.6. The add character form fields

Batch adding characters using a NEXUS or TNT file

When uploading a NEXUS or TNT 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 or TNT format.

...

The workflow we recommend is creating one large supermatrix and using the partitions feature (described elsewhere) to examine or export subsets of the matrix.

Searching for characters

To find for a character, click on the Search button in the Character List window and enter your search terms into the box.  This action will return all characters that match your terms.

...

The Character List 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 "Done" button 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 of characters in a matrix is that in which they were added (or appeared in the imported NEXUS/TNT file.) However, project members may arbitrarily reorder characters in a matrix by drag and drop in the character editor.

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:

...

The editor is divided into six 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.

"Character states" tab

The "character states" 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.

To add a state, click on the "+ Add new" text above the existing states. 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, and then click the "x" button that appears on the right.

"Media" tab

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

...

Figure 4.10. 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 below. You may add labels to the image in this window in the same manner as is done in the matrix editor (see Media view). 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 (e.g., in a matrix cell, or as a depiction of the specimen) these labels will not be visible.

...

Figure 4.11. Character image viewer and labeling of character images

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

...

Figure 4.13. Selecting whether a comment applies to a character or a state

"Citations" 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 4.14. Adding a citation to a character

"Partitions" tab

Partitions are subsets of taxa and characters in your matrix.  These are one of the most useful tools for examining parts of your data.  You can display a partition on screen or download a partition for analysis.  It is an excellent workflow to create a single large matrix and then use several partitions to publish subsets from that matrix. You can create as many partitions as you wish.

...

Figure 4.15. The Partitions tab showing three sample partitions

"Change Log" 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 Log" tab. Each change is noted with date and time, the identity of the member committing the change, and the precise value of each field after the change.

...

Figure 4.16. Using the Change Log Tab

Using Matrices

MorphoBank supports editing and display of dynamic phylogenetic matrices of morphological characters with labeled images and other metadata 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.

...

MorphoBank also permits team collaboration on a single copy of the matrix, analogous to several authors editing a single manuscript in Google Docs.

Adding new matrices

You may create matrices in MorphoBank from scratch or upload an existing Nexus or TNT file that has been created in a desktop program like MacClade, Nexus Data Editor, Winclada or Mesquite. When you import a NEXUS or TNT file, all of the taxonomy, characters and states, cell scorings and notes, are imported into a matrix in your MorphoBank project. MorphoBank does not have tools for manipulating trees or sequence data. Therefore any 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.

...

Figure 5.1. Two different options for adding a matrix

Starting a New Matrix from Scratch

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.

...

If you simply fill in the Title, 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 TNT or NEXUS format File

If you have existing matrices, whether created in software such as Mesquite or MacClade or in a text editor, that are in NEXUS or TNT format, you can import those directly into MorphoBank as a starting point for your MorphoBank matrix. To do so, click on the Browse button and select your data file. You can also specify text to add to the notes data of each taxon and character imported from the file.

...

Figure 5.4. Review screen for taxon list prior to database save.

File import caveats

NEXUS is a loosely defined format that has never been definitively standardized (see Vos et al. 2012 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 file first look over the list of advice below. If your file is still unusable, then contact us via the "Ask Us" link in the header for assistance.

Only morphological data is accepted

MorphoBank only accepts files containing morphology data. It is possible to create NEXUS files with a mixture of morphological and sequence data, or with sequence 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 sequence data before uploading the file to MorphoBank.

If you need to keep sequence 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.

...

Merging Additional Matrices into an Existing Morphobank Matrix

MorphoBank allows you to upload TNT or NEXUS files and to 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 procedure provides a mechanism for consolidating multiple TNT or NEXUS format datasets into a single Morphobank matrix. To upload one or more TNT or NEXUS files to an existing matrix, click on the small grey button entitled "Set up this Matrix" 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 can add a TNT file after you have added a NEXUS file or vice versa.

...

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 matrices in a project appear as a list accessible by clicking on the Matrices tab in the left-side navigation. As shown in the figure below, the list includes summary information for each matrix and a series of buttons implementing useful functions, from editing to downloading:

...

Figure 5.13. Force streaming a large matrix

Tree-building Options

MorphoBank partners with CIPRES (Cyberinfrastructure 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 without leaving the MorphoBank environment. 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.

...

Figure 5.16.  Access to analysis results via 'Download' button

Editor overview

The matrix editor is a web application that allows project members to edit a phylogentc matrix 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:

...

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 5.7, “Matrix editor controls”

...

• The Partitions button allows you to create partitions of characters and taxa and to select a partition to view.  The page displays in individual boxes, the characters and taxa that are currently in (and not in) a given partition. You can drag and drop characters and taxa to add or remove them from partitions.  Finally, this window includes a drop-down list at the bottom of the window Show partition in matrix editor 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 rules" and "media rules" in two separate tabs. Beside each rule you can also add an associated action. You can also choose to View rules as graph, which will display the rules in graphic format in a separate window.

• The Go to button allows you to type an intersection of a character and taxon to go to quickly and directly.

• 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.  These changes would be those made by you or other members of your collaborative team.

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

• The circular arrow button reloads the matrix in your web browser.

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 5.20. 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. The editing tools provided are similar in scope and function to those available when you choose the "Edit characters" button from the basic Matrices screen.

...

Figure 5.21. 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 or TNT 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 5.23. 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. Creating a basic form of ontologies is not required in MorphoBank, it is an option provided should researchers find it useful.

...

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.

...

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.

...

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

...

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" tab in the bar along the top of the matrix editor .

...

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

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.

...

Figure 5.33. 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 5.34. Matrix editor taxa list

Treatment of Multistate Taxa in Matrices

MorphoBank recognizes that Nexus and TNT formats allow the user to distinguish between polymorphisms and ambiguities for multistate taxa.

...

If a pre-existing Nexus or TNT 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.

...

Figure 5.35. 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 or TNT 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.

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.

...

Figure 5.36. 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 5.39. Adding a member to a group

The Operational Taxonomic Unit (OTU)

The OTU determines the rank in the taxonomic hierarchy that you choose to use in a row 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.

...

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  (e.g., 0, 1, 2, etc..., or a continuous value) entered into a cell. In MorphoBank a cell can have one score, many scores, or none at all (i.e., "?").

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 a cell with an image). A window will appear, shown below, allowing you to edit all aspects of the cell:

...

Figure 5.40. 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.

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.

...

Figure 5.41. Choosing an image to add to a cell

Cell Media Automation Tool

...

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 Ontologies in Morphobank.

Labeling images

Labeling images is described in Labeling images in the Matrix Editor. 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:

...

Figure 5.48. The batch operations window set to the Barch Batch Row Score Editor

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

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.

...

Figure 5.52. Final Step in Deleting a Matrix

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 (see 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 https://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.

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

...

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.

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.

...

Figure 8.1. 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 8.2. Adding a new member to a project

Types of access

The Project Administrator can grant full membership, "character annotator," "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 annotators are in-between: they can edit everything but characters and states, subject to item-level access restrictions. Bibliography maintainers may edit only bibliographic data.

...

Figure 8.3. Editing access for members of a project.

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. 

...

Figure 8.5. Anonymous reviewer login

Image AddedImage Added

Figure 8.6. Publishing Status/Status setting for anonymous reviewer access

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.

Who Gets to Edit What?

Access control rules in MorphoBank reduce down to this:

• The public (i.e. users without logins) can only see those items in published projects that are marked to "publish when project is published." They 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.

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 AWS. The database and media files are backed up on a weekly basis.

...

To create a backup your project, go to the Project Overview then click on the "Download Project SDD File" 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 Documents tab 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 (httphttps://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

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. Users whose research has not been peer-reviewed may use the site for organizational purposes, but are asked not to make their projects live.

...

Figure 10.3. Success Screen after Publishing

Project Information Fields

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

...

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 https://morphobank.org/permalink/?P44 where 'P44' is replaced with your project identifier. 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 https://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.

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.

...

A duplicate is an exact and a 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.

...