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.
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 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.
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.
Remote references
Click on References in the main navigation bar
A list of available references will appear
Type a search term in the search bar
The list will be narrowed to references that contain the search term in their names.
Click on a reference to view detailed information about it.
One quick way to accomplish this is to install the official plant virus reference.
We provide a step-by-step tutorial on installing an official reference.
Navigate to the References view
Click the
buttonThe Create Reference dialog box will open. The Create is for making blank references and will be active by default.
Fill the form fields
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.
Click the
buttonYour new reference will now appear in the References Overview page.
Existing references can be cloned to create a new reference than can be modified without affecting the original.
Navigate to the References view
Click the
buttonThe Add Reference dialog will appear.
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.
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.
Click the
buttonThe 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.
Wait for the clone to finish
The reference card will look like this when the reference is ready:
An alternative way to clone a particular reference is by using the quick clone function.
Find the quick clone icon in the top-right of a reference card
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.
Continue with cloning as normal
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.
Navigate to the References view
Click the
buttonClick on the Import tab
Fill the import form
Upload a .json.gz
file containing a reference and give it and name and optional description.
Click the
buttonThe reference will be created and the import process will begin. You can see the progress on the reference card.
Wait for the import to finish
The reference card will look like this when it is complete:
Navigate to the References view
Click on the reference you want to export
The detail view for the reference will appear.
Click the icon in the top-right
The Export Reference dialog will appear.
Click the
buttonA file called reference.json.gz
will be downloaded. It may take some time for the download to start as the reference file is prepared.
The name and description of a reference has been created. Its data type and organism cannot be changed.
Navigate to the detail view for a reference
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.
Make your changes to reference
Here, we changed the name and added a description.
Click the
buttonYour changes will be applied to the reference.
Navigate to the references view
Notice that Clone of Plant Viruses is in the list of references.
Click on the reference you want to delete
You will be taken to the detail view for the reference.
Navigate to the Settings tab
Click the
button on the bottomDeleting 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.
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.
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.
Click the
button to install the updateThe update process will begin. The progress will be shown in the Remote Reference box.
Wait for the update to complete
Once the installation is complete, you will see an Up-to-date on the Remote Reference box.
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.
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.
Go to the detail view for the reference of interest
Go to the Settings tab
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.
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.
Click on the icon on a source type to remove it
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.
Adding a user to a reference will give them the right to browse the reference.
Go to the settings tabs for a reference
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.
Click on a user to add them to the reference
Check that the user is now in the users list.
Go to the settings tabs for a reference
Click the Add Group link
The Add Group dialog will appear
Click on a group to add it to the reference
Check that the group is now in the groups list.
Click on icon on the user or group you want to remove
This procedure is a exactly the same for users and groups.
Go to the settings tabs for a reference
Click on the icon on the user or group you want to modify
The modification dialog will appear.
Click on the checkbox next to the permissions you would like to assign the user or group