Matrices

Build sophisticated matrices in TW. Use them to create keys, score images and observations, manage projects, and streamline creation of custom outputs and sharing of descriptors.

Nomenclature Quick Start

TW provides a suite of common tasks help you to manage your matrices, descriptors, observations and related data. This section assumes you have some familiarity with the TW user interface conventions and introduces new user interface features where needed. Next, please familiarize yourself with the kinds of tasks TW offers related to Matrices.

Understanding the data model

Extensive information exists about the TaxonWorks data model. Information is presented in text and searchable graphic formats. Few comments:

• Each matrix consistas of defined Rows and Columns.
• Rows are OTUs, Collection Objects and other objects in the database which could be added to a matrix. The same OTU or any other object could be added to as many matrices as needed.
• Columns are Descriptors (characters) which could be added to a matrix. The same descriptor could be added to sevaral matrices.
• TaxonWorks does not store the entire matrix, instead we store individual observations for each cell in the table. In practice this means, that if you have two matrices which include the same OTU and the same descriptor, the observations in the cell will be identical in both matrices, regardless in which matrix the original observation was made. This allow for the user to clone and combine matrices as needed, the observations will be replicated for each matrix and the combination of the Row object and Column object.

Curating data

Basic information

• In most cases, the work with matrices starts in Observation Matrix Hub task.
• Click New button to create a new matrix. Once the matrix is created, you are automatically in the Edit matrix mode.
• Alternatively, in the Observation Matrix Hub, find an existing matrix from the list and click Edit button.
• Also, in the Hub you can pin a matrix, so that it could be used as a default matrix in various interfaces.
• Once in Edit mode, rows and columns needs to be defined.

Adding a Descriptor to the Matrix

• Switch the Row/Column switch to Column position; Dynamic/Fixed switch to Fixed position. After that we can add a new Descriptor to the matrix
• To add a new Descriptor, click the New Descriptor link at the top off the interface. Select the descriptor Type. The available types are:
  • Qualitative - traditional phylogenetic descriptor with multiple character states
  • Presence/absence - similar to the previous one, but only two predefined states are possible
  • Quantitative - a single measurement character (a default measurement unit could be defined)
  • Sample - a numeric character, for which a min/max range could be scored (a default measurement unit could be defined)
  • Gene - ???
  • Free text
  • Media - a specialized descriptor designed for attachment of Depictions, which will serve as a visual observation in the image matrix
• Show more mode allows to add some additional details about the descriptor: Short name, Description name - which will be used for autogenerated description, Key name - which will be used in an interactive key, Weight - which will bring the descriptor close to the top in an interactive key.
• If the qualitative 'Descriptor' is selected, two or more character states need to be defined. Each Character state has two fields: Label - '0', '1', '2', and the Name, some additional information could also be provided when Show more is selector.
  • An example of a Qualitative descriptor: 'Body color' with two states: '0' - red, '1' - black.
• Once the information on the descriptor entered you can click one of the Create buttons. In all cases, newly created descriptor is added to the matrix as a Column.
  • Create will save the record, but you can continue editing the descriptor
  • Create and return to matrix, will return you back to the Edit matrix interface
  • Create and new could be used if multiple descriptors need to be defined.
• Alternatively, if descriptors do already exists in the database, they could be just added to an existing matrix in the Edit observation matrix interface by using the search interface on the low left side. Change the Row\Column switch to the Column, and use Search option. Alternatively, multiple descriptors could be copies from another matrix using From Another Matrix option.

Adding an OTU or Collection Object to the Matrix

• To add Rows to the matrix, change Row/Column switch to Row; Dynamic/Fixed switch to Fixed position. OTU, Collection Object, or Extract could be added to a matrix as a Row. Assuming that those objects already exist in the database, they could be added to the matrix using Search or From Another Matrix options, it will work very simillar to adding an existing Descriptor to the matrix.
• There is also an option to add a new Row to the matrix directly from the Browse OTU or Browse Nomenclature tasks. In either of tasks, select OTU radial button, in the Observation matrices sector, you can select a matrix to automatically add this OTU to it, and proceed directly to scoring mode.
• Addvanced option to add multiple OTUs to the matrix is using Dynamic option. This option allow to select either all OTUs marked with a specific Tag or select a parent taxon, for example a genus, to add all children taxa, for example species, if new species are added to a genus in the future, those should automatically be added to the matrix.

Reordering And Editing Rows and Collumns in the Matrix

• Select Sortable columns/rows checkbox on the top, after that the columns and rowns could be resorted by drugging each up and down the list.
• OTUs could also be sorted by their nomenclature, using Sort by nomenclature button.
• To delete a Row or Column from the matrix, use the Trash can button. Keep in mind, deleting each of those does not delete the corresponding object from the database, it only delete its association with a particular Matrix. Deleting Rows and Columns also do not affect the observations associated with those.
• To edit Row or column, for example to add a new character state to the descriptor, use Edit button next to this descriptor.

Adding scores to a Row

• In the Edit Matrix interface, select a 'Score' button second after an OTU or Collection object name in the list
• You will see the list of descriptors and all possible states, you can check applicable states or add values for numeric descriptors. All changes are saved automatically.
• Scores could also be cloned from an another object in the matrix using Clone and copy button. After cloning, only few changes may be required to separate one OTU or a Collection Object from another. It is recommended to select the most similar object for clonning.
• Destroy button could be use to clear all scores from a particular OTU or a Collection object.
• The Matrix Row Coder interface could also be accessed from the Browse OTU or Browse Nomenclature tasks. In either of tasks, select OTU radial button, in the Observation matrices sector, you can select a matrix to automatically add this OTU to it (if not added previously), and proceed directly to scoring mode.

Adding scores to a Collumn

• In the Edit Matrix interface, select a 'Score' button second after a Descriptor in the list
• You will see the list of OTUs and Collection object associated with this particular Descriptor. You can check applicable states or add values for numeric descriptors. All changes are saved automatically.
• On the top of the form, there are options to Destroy all observations, Populate column with one particular character state,

Using a Matrix

• From the Observation Matrix Hub task, you can click View button next to the name of the matrix. In the view mode, you can preview entire matrix, download the matrix in TNT, nexus, NeXML, CSV formats, to be used, for example in phylogenetic recontstuction or be uploaded into a Lucid builder.
• Once the matrix is completed, it could be used for species determination as an Interactive Key, which is accessible from the Observation Matrix Hub.
• Before using the matrix for identification, it is recommended to validate the matrix. A matrix could be validated in the Edit mode by selecting the checkbox Validation. Each row of the matrix will be evaluated if it has enough resolution to separate this particular row from all other rows in the same matrix. If a row does not pass validation, the matrix could still be used for interactive identification, but adding some additional descriptors may improve the resolution.

Interactive key interface

• The Interactive key interface is divided into 4 frames: the top one with the title and options; the middle one with the list of descriptors; the lower two frames include the list of rows which could be identifier, and eliminated rows which will be populated once the identification is started.
• The descriptors are sorted by their weight and separating power. The order of the descriptors could be changed in the preferences on the top.
• To start the identification, select one character state from any descriptor. It is possible to select more than one state in a case of uncertanty, to do this, click on the descriptor name, and make multiple selection.
• By default the rows which do not have scores for selected descriptor are not eliminated from the list, it is assumed that any character state is possible, but this behavior could be changed in the settings on the top of the page, if it is needed, for example, for the matrix evaluation.
• If a particular row in the matrix does not have a score matching selected character state, this taxon or collection object is moved to the list of Eliminated rows. The behavior could be slightly changed by adding error tolerance. The tolerance equal '1' means that a single error in identification is permitted, the row will be eliminated only when 2 or more errors exists.
• To clear the interactive key, and start the identification from the beginning, use Reset button.
• If the matrix is large, it could be more convenient not to eliminate the row after selection of each descriptor, since the wait time could be several seconds, before you can select a next descriptor. It is possible to use Refresh only taxa option. The list of descriptors will not be updated before the Refresh button is clicked.
• After the refresh, the taxa not matching the search criteria are moved to the right, and the list of descriptors also updated to bring more useful once closer to the top of the list.
• Continue determination before only one or few rows still present in the list of Remaining.
• It is also possible to use Select button, to reduce the list of rows to be identified from the very beginning. If the list of entities is reduced, the list of descriptors will also be optimized to identify the remaining entries.
• To make the interactive key more functional, you can add depictions to each character state of each descriptor. To do this, go back to the Edit Matrix interface, select one of the descriptors, click edit button next to it. In the Edit mode, you can use the radial annotator next to each character state to add a depiction.

Image matrices

Image matrix is a specialized matrix which has defined descriptors and row, but does not have any scores. Instead of scores, images are added as a depiction to each cell of the table. The image matrix could also be used as a pictorial key for taxon identification, the images from the matrix are also viewed in the Browse OTU page. So instead of adding images directly to each OTU, they could be added to the image matrix instead to get additional functionality.

• To work with an image matrix, create a new matrix as described above.
• Add rows to the matrix, OTUs for example.
• Add new descriptors to the matrix, all of them should be Media type descriptors. Usually this matrix has fewer descriptors than typical morphological matrix, and each descriptor will represent a standard view of the organism or a particular structure useful to determination of taxa. For example, 'dorsal view', 'lateral view', 'head', 'wing venation'.
• Once the rows and columns are defined, the most convenient way to work with the image matrix would be to use the Observation Matrix Dashbord task.
• In the Observation Matrix Dashbord task, select a parent taxon and rank of the children taxa which you would like to see, for example, select a genus name, and select species rank to see all the species-level taxa from this particular genus. Once selected, click the Search button.
• You will see the table of OTUs with some summary, how many observations has each, and how many depictions are added to a particular OTU in an image matrix.
• Use Open in a matrix button next to one of the OTUs to add OTU to a matrix. Select the image matrix from the list. Once the matrix is selected, you get redirected to an editing interface, which looks like a table, where the descriptors are the headers of each column.
• To add an image to a particular cell of the table, simly drug and drop it from a folder on your computer to that cell. The images could also be moved from one cell to another.
• Once the image added, you can provide some metadata. Click on the image to add caption. Click the Radial Annotator button, to add citation and/or attribution.
• Adding images to multiple OTUs: in the 'Observation matrices dashboard', once you filtered the list of OTUs, select few of tham and click the Edit image matrix buttom. The table for editing multiple OTUs will be opened. WARNING: do not select all OTUs for editing, since ALL of tham will be added to a matrix as separate Rows.
• Use the previous step to add multiple OTUs to any given matrix, not only to Image matrix, that could be another fast way to add multiple rows, for example adding rows for a future ineractive key.
• Image matrix for any given OTU could also be accessed with the OTU Radial button, in the Browse OTU, or Browse Nomenclature tasks.

Viewing images in the Image Matrix

• In the Observation Matrix Dashbord task, select a parent taxon and rank of the children taxa which you would like to see, for example, select a genus name, and select species rank to see all the species-level taxa from this particular genus. Once selected, click the Search button.
• In the filtered results, Select All or few OTUs using checkboxes before the names, and click the View image matrix button. A table will be open to display all illustrations, so that OTUs could be compared to each other.
• In the View mode, you can hide some rows but clicking a checkbox before each row, or you can quickly switch to the Edit mode.