Changes between Initial Version and Version 1 of net.sf.basedb.varsearch/using

Timestamp:

Feb 23, 2021, 1:54:47 PM (4 years ago)

Author:

Nicklas Nordborg

Comment:

Started to write documentation about searching for variants

net.sf.basedb.varsearch/using

@@ +1 @@
+= How to use the Variant Search extension =
+
+== Introduction ==
+The current search functionality is integrated directly in BASE. Go to the raw bioassays list page and add the **Variant (filtered)** column to the table using the **Columns...** dialog, or right-click on the title row and enabled it from the popup menu. 
+
+By default, the column displays **Yes** or **No** depending on if the VCF file has been indexed or not. If **Yes**, the number of variants is also displayed.
+
+== Searching ==
+
+The variant database uses Apache Lucene instead of PostgreSQL. Thus, the
+search field for this column behaves differently from other search fields 
+in BASE. 
+
+It is possible to search for raw bioassays that have been indexed or not
+and the number of variants:
+
+ * `%`: Find all indexed raw bioassays
+ * `<>%` or `=`:  Find all raw bioassays that are not indexed
+ * `=0`: Find indexed raw bioassays with 0 variants
+ * `>=500`: Find indexed raw bioassays with at least 500 variants
+
+**Note! ** This syntax is similar to the regular BASE syntax, but is for example, not possible to use a list of values: `=1|2` (will not work)
+
+== Searching for variants ==
+
+A typical search in a Lucene database consists of a **field name** and **query string** separated by a **colon** (:). Here are a few examples:
+
+ * `gene:TP53`: Find variants in the TP53 gene
+ * `chr17:7675189`: Find variants at the specified genomic location
+ * `c:423C>G`: Find variants at the given transcript position
+ * `p:C141W`: Find variants causing the specified protein change
+ * `cosmic:COSV52706449`: Find variants for the COSMIC ID
+ * `rsid:rs1057519977`: Find variants for the dbSNP ID
+
+**Tip! ** The prefix can in many cases be skipped since it is almost always possible to automatically make an educated guess about the field with some pattern matching on the query string. The **gene:** field is the default and will be used if a field can't be automatically guessed.
+Here are the same examples as above:
+
+ * `TP53`: Since **gene:** is the default field
+ * `423C>G`: Numbers followed by [ACGT] and >
+ * `C141W`: Single-letter with numbers in-between
+ * `COSV52706449`: 'COSV' follwed by numbers
+ * `rs1057519977`: 'rs' followed by numbers
+
+**Note! ** If a query don't return the expected result always try again 
+with explicit field prefixes.
+
+It is possible to specify multiple conditions with **AND** and **OR**. 
+
+ * `TP53 AND 423C>G`
+ * `TP53 AND (423C>G OR 742C>T)`
+
+The **AND** and **OR** keywords are case-sensitive and **OR** is implicit if not specified. Thus, the query string `TP53 and 423C>G` will not return the expected results since it is interpreted as: `gene:TP53 OR gene:and OR c:423C>G`.
+
+For more information about Lucene query syntax see https://lucene.apache.org/core/8_8_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description
+
+== Indexed fields ==
+
+The variant database currently contains the following indexed fields:
+
+ * `gene:` Gene name from the **ncbiRefSeq** annotation the !SnpEff **Gene_Name** column. Case-insensitive.
+ * `type:` Type of variant. Can be one of **SNV**, **Insertion**, **Deletion**, **Complex**.
+ * `cosmic:` ID of the variant in the [https://cancer.sanger.ac.uk/cosmic COSMIC database].
+ * `rsid:` ID of variant in the [https://www.ncbi.nlm.nih.gov/snp/ dbSNP database].
+ * `c:` Transcript change. Taken from the **cosmic_CDS** annotation and !SnpEff **HGVS.c** column.
+ * `p:` Expected amino-acid change in the protein. Taken from **cosmic_AA** annotation and !SnpEff **HGVS.p** column. **Note! ** COSMIC uses single-letter notation for amino acids, while !SnpEff uses three-letter notation. To make things simple, all values have been converted to single-letter notation in the index. See https://www.hgvs.org/mutnomen/codon.html for a table with translations.
+ * `ref:` Reference allele
+ * `alt:` Alternate allele
+ * `chrom:` Name of chromosome(eg. ''chr1'', ''chr2'', etc)
+ * `pos:` Location within the chromosome. The location is also indexed using the chromsome name as a field name. Thus, the query string `chrom:chr17 AND pos:7675189` can be written as `chr17:7675189` (recommended).
+