= Installing the Variant Search extension =

== Installation and updating ==

 1. Download the latest `varsearch-x.y.tar.gz` file from the [wiki:net.sf.basedb.varsearch Variant Search main page].
 2. Unpack the downloaded file to a directory of your choice.
 3. Copy the `varsearch.jar` file to your BASE plug-ins directory. Look in your 
    `base.config` file if you don't know where this is. There are not other
    configuration files.
 4. Log in to BASE as an administrator and go to the '''Administrate->Plug-ins & Extensions->Overview''' page.
 5. Run the installation wizard and select to install `varsearch.jar`.
 6. Refresh your menu entries with '''BASE -> Reload permissions'''
 7. Go to the '''Extensions -> Variant Search (admin)''' menu and then continue to the '''Installation wizard'''. It should display some warnings and error messages. Click on the `Create missing items` button to fix them.
 8. The installation is now complete, but before we can start searching the VCF files need to be indexed.

== Indexing VCF files ==

Before it is possible to search for variants, the VCF files need to be indexed. We can't just index any random VCF, but require things to be connected in a certain structure:

 * We need a raw bioassay with a  raw data type that include the VCF file type
 * The raw bioassay must have a VCF file linked via the '''VCF file type'''. This VCF is assumed to be the filtered VCF file.
 * The raw bioassay may also have a VCF linked via an any-to-any link named '''variants-annotated.vcf.gz'''. This VCF is assumed to be the unfiltered (raw) VCF.
 * The raw bioassay may also have more VCF files linked via any-to-any links with names that start with `genotype_`. These VCF files are assumed to be the results of targeted genotyping. 

Indexing is controlled via Item lists. The installation procedure created three item lists:

 * Variant index (filtered)
 * Variant index (all)
 * Variant index (targeted genotyping)

To index the VCF files we need to add raw bioassays to the item lists. Raw bioassays that are added to the ''Variant index (filtered)'' list will get the filtered VCF indexed, raw bioassays that are added to the ''Variant index (all)'' list will get the full VCF indexed, and raw bioassays that are added to the ''Variant index (targeted genotyping)'' will get the targeted genotyping VCF files indexed. Usually the indexing will start automatically once the Index Manager detects that there are things to index, but it may take 10-15 minutes. The raw bioassays are removed from the lists after they have been indexed.

== The Index Manager ==

As an administrator, it is possible to get information about and manage the index via the Index Manager. Go to the '''Extensions -> Variant Search (admin)''' menu and continue to the '''Index Manager'''.

It should display two tables with information. One table for the filtered index and one table for the full index.

|| '''Path''' || This is the path on the disk (relative the BASE userfiles directory) where the index is stored. It is possible to '''Delete''' the index. ||
|| '''Size on disk''' || Hard-disk space that the index is using. ||
|| '''Total variants''' || Total number of variants in the index. ||
|| '''Indexed raw bioassays''' || Number of raw bioassays that has been indexed. The '''Rebuild index''' action will re-index all VCF files. Since this may take a long time, the existing index is kept until the new index is complete. ||
|| '''Deleted raw bioassays''' || Number of raw bioassays in the index that no longer exists in BASE. The '''Remove from index''' action will remove them from the index. ||
|| '''Cached query results''' || Searches for variants that take a long time are cached for up to an hour. The cache is automatically cleared when the index is modified. Use the '''Clean cache''' action to manually clear the cache. ||
|| '''Item list''' || The item list that is controlling which raw bioassays that should be added to the index. ||
|| '''Auto-processing''' || If auto-processing is '''enabled''', the Index Manager will automatically index the VCF files for raw bioassays that are added to the list. Auto-processing can be '''disabled'''. ||
|| '''Items in queue''' || Number of raw bioassays in the item list that are waiting to be indexed. The '''Add to index''' action can be used to start the indexing ignoring the auto-processing setting. ||
|| '''Status''' || Typically '''IDLE''' if the Index Manager is not working at the moment, otherwise it will display a progress bar indicating the flow of the current action. ||