References

Overview

Virtool is built for detecting viruses and is capable of detecting other pathogens. Managing collections of pathogen sequences used for this purpose is a key feature of Virtool.

At least one non-empty reference must be created in order to start analyzing samples. One quick way to accomplish this is to install the official plant virus reference.

OTUs

The reference is a fully editable and tracked collection of pathogens, pathogen isolates, and their genome sequences. The data in the virus reference is used to identify potential viral infections in Illumina libraries derived from your samples.

In Virtool, pathogen records are called OTUs (organizational taxonomic unit). This leaves the organization of the reference up to the user. Generally, OTU is synonymous with pathogen species.

See the OTUs documentation for more information.

Indexes

Indexes are versioned snapshots of all of the OTUs in a reference at points in time. In the background, indexes are associated with optimized read mapping indices managed by Virtool.

When changes are made to OTUs, the index is rebuilt to include those changes in future analysis jobs. Each analysis is tied to a specific index (version) of its target reference.

See the Indexes documentation for more information.

Rights

Access to references can be controlled by user and group.

Users or groups must be assigned to a reference to gain access to it. The actions a user or group can perform on the reference can be tightly controlled.

Find a Reference

1. Click on References in the main navigation bar.

   A list of available references will appear.

   

2. Type a search term in the search bar.

   The list will be narrowed to references that contain the search term in their names.

   

3. Click on a reference to view detailed information about it.

Install the Official Reference

Instead of starting a virus database from scratch, you can use our official plant virus reference. Doing this will setup up remote connection to the reference on GitHub.

1. Go to the References view

   A message with a button for installing the official reference will be visible if you have not already installed it.

   

2. Click Install to begin the installation process.

   A new card should appear representing the official reference on your system. It will display a progress bar while the reference is being created locally.

   

   Once the installation process is complete, the reference card should look something like this:

   

3. Click the reference card to view a detail page for the reference.

   

Create an Empty Reference

1. Navigate to the References view

   

2. Click to open the reference creation dialog.

   

3. Give your new reference a name, the type of organism the OTUs are from (eg. viruses), and an optional description.

   Select a data type to tell Virtool if you will be entering whole genomes or barcode sequences.

   

4. Click Save .

   Your new reference will now appear in the References Overview page.

   

Clone a Reference

Existing references can be cloned to create a new reference than can be modified without affecting the original.

1. Navigate to the References view

2. Click to open the reference creation dialog.

   

3. Click on the Clone tab

   The clone form has a list of existing source references to chose from. The organism and data type are derived from the source reference and cannot be changed.

   

4. Fill the clone reference form

   Selecting a source reference will automatically generate a name for the reference, but this can be changed. Filling out the Description field is optional.

   

5. Click Clone

   The reference will be created and appear in the list. Cloning the source data takes time. The progress of this process is shown on the reference card.

   

6. Wait for the clone to finish

   The reference card will look like this when the reference is ready:

   

Quick Clone a Reference

An alternative way to clone a particular reference is by using the quick clone function.

1. Find the quick clone icon in the top-right of a reference card

   

2. Click the icon

   The Add Reference dialog will appear with the clone tab active. The form will have the reference you clicked pre-selected and a name will be auto-generated.

   

3. Continue with cloning as normal

Import a Reference

It is possible to export a reference from one Virtool instance and import it into another. This allows you to share you reference with other people.

1. Navigate to the References view

2. Click

   

3. Click on the Import tab

   

4. Fill the import form

   Upload a .json.gz file containing a reference and give it and name and optional description.

   

5. Click Import

   The reference will be created and the import process will begin. You can see the progress on the reference card.

   

6. Wait for the import to finish

   The reference card will look like this when it is complete:

   

Export a Reference

1. Navigate to the References view

   

2. Click on the reference you want to export

   The detail view for the reference will appear.

   

3. Click the icon at the top-right

   The Export Reference dialog will appear.

   

4. Click Export

   A file called reference.json.gz will be downloaded. It may take some time for the download to start as the reference file is prepared.

   

Edit a Reference

The name and description of a reference has been created. Its data type and organism cannot be changed.

1. Navigate to the detail view for a reference

   

2. Click on the icon in the top-right

   The Reference Edit dialog will appear. The current information for the reference will be in the form fields.

   

3. Make your changes to reference

   Here, we changed the name and added a description.

   

4. Click Save

   Your changes will be applied to the reference.

   

Delete a Reference

1. Navigate to the references view

   Notice that Clone of Plant Viruses is in the list of references.

   

2. Click on the reference you want to delete

   You will be taken to the detail view for the reference.

   

3. Navigate to the Settings tab

   

4. Click Delete on the bottom

   Deleting a reference is permanent! Make sure you want to delete the reference.

   You will be redirected to the references list when you delete a reference. It should be gone from the references list.

   

Update the Official Reference

The official reference is a collection of plant viruses that lets you get started using Virtool right away. It can be automatically updated from our repository on GitHub. When changes are made to the reference on GitHub, your official reference on Virtool also needs to be updated.

1. Go to the detail view for the official reference

   To view if any updates are required, click on your official reference. The Remote Reference box shows than update is available.

   

2. Click Install to install the update

   The update process will begin. The progress will be shown in the Remote Reference box.

   

3. Wait for the update to complete

   Once the installation is complete, you will see an Up-to-date on the Remote Reference box.

   

Build an Index

After updating the official reference there will be unbuilt changes that need to be included in an index before they can be used in analysis. Learn more about building indexes.

Manage Source Types

Isolate names comprise a source type and source name. Users can be forced to use certain allowed source type values when creating isolates.

Source type restrictions do not affect OTUs from import, remote, or clone sources.

1. Go to the detail view for the reference of interest

2. Go to the Settings tab

3. Click the Enable checkbox

   This will turn on source type restrictions for the reference. Users will only be able to use the source types listed here when creating isolates.

   

4. Enter a new source type in the input and click the icon

   This will add the entered source type to the allowed source types for the reference. It will be available as a choice for users when they add isolates.

5. Click on the icon on a source type to remove it

Rights

Reference rights control what users can do with a reference.

Access to references can be configured for individual users and user groups. Users and groups added to the reference will be able to read the reference and use it in analyses. Additional protected actions can be enabled for users and groups after they have been added.

Add a User

Adding a user to a reference will give them the right to browse the reference.

1. Go to the settings tabs for a reference

   

2. Click the Add User link

   The Add User dialog will appear. You can use the search input to filter the users on your Virtool instance.

   

3. Click on a user to add them to the reference

   Check that the user is now in the users list.

   

Add a Group

1. Go to the settings tabs for a reference

   

2. Click the Add Group link

   The Add Group dialog will appear

   

3. Click on a group to add it to the reference

   Check that the group is now in the groups list.

   

Remove a User or Group

1. Click on icon on the user or group you want to remove

Modifying Rights

This procedure is an exactly the same for users and groups.

1. Go to the settings tabs for a reference

   

2. Click on the icon on the user or group you want to modify

   The modification dialog will appear.

   

3. Click on the checkbox next to the permissions you would like to assign the user or group