JAL-1563 User documentation for Uniprot FTS
[jalview.git] / help / html / features / uniprotsequencefetcher.html
diff --git a/help/html/features/uniprotsequencefetcher.html b/help/html/features/uniprotsequencefetcher.html
new file mode 100644 (file)
index 0000000..55b4d71
--- /dev/null
@@ -0,0 +1,161 @@
+<html>
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ * 
+ * This file is part of Jalview.
+ * 
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License 
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *  
+ * Jalview is distributed in the hope that it will be useful, but 
+ * WITHOUT ANY WARRANTY; without even the implied warranty 
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
+ * PURPOSE.  See the GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ -->
+<head>
+<title>The Uniprot Free Text Search Interface</title>
+</head>
+<body>
+
+  <strong>The Uniprot Free Text Search Interface</strong>
+  <p>
+    Jalview provides a specialised interface that allows fast and
+    efficient discovery and retrieval of data from the Uniprot database.
+    It allows
+    interactive querying of Uniprot metadata with free text and structured
+    queries, so sequences can be located without prior knowledge of
+    their database accessions, or <em>via</em> manual cross-referencing
+    from Uniprot or other bioinformatics websites.
+  </p>
+  <p>
+    To open the UniProt Sequence Fetcher, select UniProt as the database from
+    any <a href="seqfetch.html">Sequence Fetcher</a> dialog (opened <em>via</em>
+    <strong>&quot;File &#8594;Fetch Sequences&quot;</strong>).
+  </p>
+  <p>
+  <img src="uniprotseqfetcher.png" align="left"
+    alt="Uniprot sequence fetcher (introduced in Jalview 2.9.1)"
+  />
+  </p>
+
+  <p>
+    <strong>Searching the Uniprot Database</strong>
+  </p>
+  <p>
+    To search the Uniprot, begin typing in the text box. The results of your
+    query are shown in the search results tab, which queries Uniprot after 1.5secs every time
+    you type in the search text box. You can sort results according to
+    the displayed columns, and select entries with the mouse or
+    keyboard. Once you have selected one or more entries, hit the <strong>OK</strong>
+    button to retrieve and visualise the sequences in Jalview Alignment interface.
+  </p>
+  <ul>
+    <li><strong>Searching a specific Uniprot field </strong> If you
+      want to find sequences based on a specific Uniprot metadata field,
+      you can select it from the drop-down menu.</li>
+      
+
+               <li><strong>Bulk Uniprot retrieval</strong><br>
+      Firstly, switch the search target to Uniprot Id, then enter multiple IDs by separating them with a semi-colon.
+      e.g. fila_human; mnt_human; mnt_mouse<br />Hitting Return or OK will automatically
+      fetch those IDs, like the default Sequence Fetcher interface.</li>
+      
+            <li><strong>Advanced / Custom querying</strong>  
+      The table below provides a brief overview of the supported Uniprot query syntax (see <a href="uniprotqueryfields.html">query fields for UniProtKB</a>):
+               <table border="1" width="95%">
+                               <tr>
+                                       <td><code>human antigen</code></td>
+                                       <td rowspan="3">All entries containing both terms.</td>
+                               </tr>
+                               <tr>
+                                       <td><code>human AND antigen</code></td>
+                               </tr>
+                               <tr>
+                                       <td><code>human &amp;&amp; antigen</code></td>
+                               </tr>
+                               <tr>
+                                       <td><code>"human antigen"</code></td>
+                                       <td>All entries containing both terms in the exact order.</td>
+                               </tr>
+                               <tr>
+                                       <td><code>human -antigen</code></td>
+                                       <td rowspan="3">All entries containing the term <code>human</code>
+                                               but not <code>antigen</code>.
+                                       </td>
+                               </tr>
+                               <tr>
+                                       <td><code>human NOT antigen</code></td>
+                               </tr>
+                               <tr>
+                                       <td><code>human ! antigen</code></td>
+                               </tr>
+                               <tr>
+                                       <td><code>human OR mouse</code></td>
+                                       <td rowspan="2">All entries containing either term.</td>
+                               </tr>
+                               <tr>
+                                       <td><code>human || mouse</code></td>
+                               </tr>
+                               <tr>
+                                       <td><code>antigen AND (human OR mouse)</code></td>
+                                       <td>Using parentheses to override boolean precedence rules.</td>
+                               </tr>
+                               <tr>
+                                       <td><code>anti*</code></td>
+                                       <td>All entries containing terms starting with <code>anti</code>.
+                                               Asterisks can also be used at the beginning and within terms. <strong>Note:</strong>
+                                               Terms starting with an asterisk or a single letter followed by an
+                                               asterisk can slow down queries considerably.
+                                       </td>
+                               </tr>
+                               <tr>
+                                       <td><code> author:Tiger*</code></td>
+                                       <td>Citations that have an author whose name starts with <code>Tiger</code>.
+                                               To search in a specific field of a dataset, you must prefix your
+                                               search term with the field name and a colon. To discover what
+                                               fields can be queried explicitly, observe the query hints that are
+                                               shown after submitting a query or use the query builder (see
+                                               below).
+                                       </td>
+                               </tr>
+                               <tr>
+                                       <td><code>length:[100 TO *]</code></td>
+                                       <td>All entries with a sequence of at least 100 amino acids.</td>
+                               </tr>
+                               <tr>
+                                       <td><code>citation:(author:Arai author:Chung)</code></td>
+                                       <td>All entries with a publication that was coauthored by two
+                                               specific authors.</td>
+                               </tr>
+                       </table>
+               </li>
+</ul>
+  <p>
+    <strong>Result pagination</strong>
+  </p>
+  The query results returned from the Uniprot server are paginated for performance optimisation. 
+  The button labelled <strong>' << '</strong> and <strong>' >> '</strong> can be used to navigate to the next or previous result page respectively. 
+  The page range is shown on the title bar of the Free Text Search interface. Jalview's pagination implementation supports multiple selection of entries across multiple pages. 
+  
+  
+ <p>
+    <strong>Customising The Uniprot Sequence Fetcher</strong>
+  </p>
+  <p>
+    To change the displayed meta-data in the search result, click the
+    'Customise Displayed Options' tab, and select the fields you'd like
+    to displayed or remove. 
+  </p>
+  <p>
+    <em>The Uniprot Free Test Search Interface was introduced in
+      Jalview 2.9.1</em>
+  </p>
+</body>
+</html>
\ No newline at end of file