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

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.

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.

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

Figure 2.3. An unvouchered specimen

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, TIFF 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 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

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 format file as a starting point. Regardless of how you begin, you can import the contents of additional NEXUS 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

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.

A character may have as many states as required. Each state has an associated name and number, as well as any number of exemplar images. Images may also be associated with the character independent of a specific state. Characters may also have bibliographic citations and member comments attached.

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.

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

There are four types of project membership:

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.

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

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.

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:

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.

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

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.

In addition to permalinks, published data is accessible:

Figure 2.9. Browse Projects list

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:

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

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.

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 ”

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”

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

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:

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.

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.

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.

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:

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

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.

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”

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.

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, cell notes and bibliographic references will be copied. 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.

Figure 9.3. Publishing Partitions

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

Figure 9.4. 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*'

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.

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.

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.

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

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

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

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

You can import existing references from any program that can output data in the EndNotes XML format. After you have exported your XML file, open your MorphoBank bibliography, click on the "Import Endnotes 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.

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

You can export your project bibliography as a tab-delimited file suitable for import into Microsoft Excel, EndNotes and other similar programs. Simply click on the "Export as Endnotes 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.

MorphoBank accepts a variety of image formats including JPEG, GIF, PNG, TIFF 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/).

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

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

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.

If the image is under copyright, be sure to check the "Is under copyright?" box and enter the copyright information (year, holder, contact information) into the "Copyright holder" text entry field (which will appear when box is checked).

You may add notes to the image using the "Notes" field. Notes are private to the project and are not published. If your image was obtained on the Internet you can note the URL from which it was obtained and any documentary information in the "URL of media" and "URL description" fields.

You may optionally attach a bibliographic reference to the image 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.

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

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

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.5. Media browser view modes

The media browser can sort 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.

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:

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

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.

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.

.

MorphoBank allows you to label regions of images using the Media viewer when it is accessed from the Matrix editor (but not from the media entry tab) . The labels are searchable, drawn above the image and do not modify the image in any way. Labels only appear when viewing the image in the specific 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.11. 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. Once you're in the pan-and-zoom image viewer, click on the triangle on the right side of the viewer control palette and select "labels," a new option which will appear in addition to the "navigator" function we explored in the previous section of this manual.

Figure 10.12. Opening the labeling tools palette in the image viewer

You should then see the labeling tools palette (shown below).

Figure 10.13. The labeling tools palette in the image viewer

Clicking on the "add label" button

Figure 10.14. The "add label" button

will add a label. Each label has a "stick" which indicates the point to which the label will adhere as the image is enlarged or reduced. Move the label to the desired location on the image by clicking and dragging the tip of its stick. When your mouse is over the tip of the stick a transparent circle (as shown in the figure below) will appear around the tip. When you click on the tip, the circle will turn red to indicate the label is selected.

Edit a label's text by clicking on its tip to select it and then clicking into the yellow text box and typing. Each label has two text elements: (1) a bold title that always appears when the label is visible and (2) a plain text description that only appears when the label is moused over.

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

Figure 10.15. Parts of a label

The two other buttons on the labels palette control visibility and editability of labels. If the "show/hide" button is active (yellow) then labels are visible. Click it to hide labels; the button will turn an inactive grey color. If the "lock" button appears unlocked and yellow, then labels are editable. Clicking on it will put the lock into a closed position and turn it a grey color, preventing all labels from being changed in any way.

Figure 10.16. The show/hide labels button

Figure 10.17. The lock labels button

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.

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.

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.

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

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.6, “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:

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.5. The character media tab

Figure 11.6. Attaching media to a character

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.7, “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 ???). 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.7. Character image viewer and labeling of character images

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.8. Adding a comment to a character

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.9. Adding a citation to a character

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.

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.

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:

Figure 12.5. The matrix editor in image display mode

The layout of the editor is shown in Figure 12.5, “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.6, “Matrix editor controls”

Figure 12.6. 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.1, “The character editor”) from within the matrix editor.

• The Search button allows you to find matching taxonomic or character names in the matrix editor. It supports partial matching of taxonomic names, character names and associated notes. To search, click on the button and enter your search in the search window that appears. Select either "taxa" or "characters" as your search type then click "find." The search will list all matches. Double-clicking on a match will scroll the matrix to the location of the match.

• The Batch button provides access to features allowing you to set the score, and/or attach media and bibliographic citations to a range of characters for a given taxon in a single action. 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.

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.26. 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.27. Choosing an image to add to a cell

Labeling images

Labeling images is described in ??? 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.

Figure 12.28. The matrix editor pan-and-zoom image viewer

The matrix editor provides tools for making changes to a range of cells for a given taxon in a single action. Supported actions include:

	Warning
	Changes made with batch operations cannot be undone. If you are not careful you can lay waste to entire rows of your matrix. Use care!

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

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

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.

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.

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.

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.

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

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

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: