JAL-1551 spotlessApply
[jalview.git] / help / help / html / features / uniprotsequencefetcher.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
8  * Jalview is free software: you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License 
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *  
13  * Jalview is distributed in the hope that it will be useful, but 
14  * WITHOUT ANY WARRANTY; without even the implied warranty 
15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
16  * PURPOSE.  See the GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
20  * The Jalview Authors are detailed in the 'AUTHORS' file.
21  -->
22 <head>
23 <title>The UniProt Free Text Search Interface</title>
24 </head>
25 <body>
26
27   <strong>The UniProt Free Text Search Interface</strong>
28   <br /> Since version 2.10 (October 2016), the Jalview Desktop
29   provides a search interface for interactive discovery and retrieval of
30   sequence data from UniProt. This dialog enables UniProt sequence
31   metadata to be searched with free text and structured queries, which
32   allows sequences to be located via gene name, keywords, or even
33   <em>via</em> manual cross-referencing from UniProt or other
34   bioinformatics websites.
35   <br />
36   <br />
37   <strong>Please Note:</strong>UniProt updated their API in July 2022.  Versions of Jalview older than 2.11.2.4 will not work with the July 2022 UniProt free text search.
38   <br />
39   <strong>The new UniProt API has a different search syntax</strong> for ranges of dates and numbers, and different query fields for advanced searches.  The general syntax of combining queries remains the same.  Because of these differences, your previously saved searches will not appear in the dropdown list next to the search box.  If you need to access these old searches they can be found in your <code>~/.jalview_properties</code> file with the label <code>CACHE.UNIPROT_FTS</code>.  If you want to transfer them to the new API search then copy the values to the <code>CACHE.UNIPROT_2022_FTS</code> label (or rename the existing label if the new one does not exist) (see the <a href="uniprotqueryfields.html">UniProtKB query fields</a> page).
40   <br/>
41   <strong>A change in accepted formats for number and date ranges</strong> means that number ranges should now always be entered as <em>e.g.</em><code>[1 TO 100]</code> or <code>[2020-01-01 TO 2022-07-26]</code> although a <code>*</code> wildcard can be used for half-open ranges, <em>e.g.</em><code>[2020-01-01 TO *]</code>.  See the <a href="uniprotqueryfields.html">UniProtKB query fields</a> page for more examples.
42   <p>
43     To open the UniProt Sequence Fetcher, select UniProt as the database
44     from any <a href="seqfetch.html">Sequence Fetcher</a> dialog (opened
45     <em>via</em> <strong>&quot;File &#8594;Fetch
46       Sequences&quot;</strong>).
47   </p>
48   <p>
49     <img src="uniprotseqfetcher.png" align="left"
50       alt="UniProt sequence fetcher (introduced in Jalview 2.10)" />
51   </p>
52
53   <p>
54     <a name="uniprotfts"><strong>Searching the UniProt Database</strong></a>
55   </p>
56   <p>To search UniProt, simply begin typing in the text box. If the
57     'autosearch' check box is enabled, then after a short delay (about
58     1.5 seconds), results will be shown in the table below. Results are
59     also updated whenever you press Enter, and you can access previous
60     searches by pressing the 'Down' arrow or clicking the drop-down menu
61     icon at the side of the search box.</p>
62   <p>You can sort results by clicking on the displayed columns,
63     and select entries with the mouse or keyboard. Once you have
64     selected one or more entries, hit the <strong>OK</strong> button to
65     retrieve the sequences.
66   </p>
67   <ul>
68     <li><strong>Searching a specific UniProt field </strong> To
69       find sequences with particular UniProt metadata, you can select a
70       field to search from the drop-down menu.</li>
71
72
73     <li><strong>Bulk UniProt record retrieval</strong><br> To
74       retrieve sequences for a list of Uniprot accessions, please enter
75       them via the 'Retrieve IDs' tab.</li>
76
77     <li><strong><a name="text-search">Complex queries
78           with the UniProt query Syntax</a></strong> The text box also allows complex
79       queries to be entered. The table below provides a brief overview
80       of the supported syntax (see the <a href="uniprotqueryfields.html">UniProtKB query fields</a> page for more details):
81       <table border="1" width="95%">
82         <tr>
83           <td><code>human antigen</code></td>
84           <td rowspan="3">All entries containing both terms.</td>
85         </tr>
86         <tr>
87           <td><code>human AND antigen</code></td>
88         </tr>
89         <tr>
90           <td><code>human &amp;&amp; antigen</code></td>
91         </tr>
92         <tr>
93           <td><code>"human antigen"</code></td>
94           <td>All entries containing both terms in the exact order.</td>
95         </tr>
96         <tr>
97           <td><code>human -antigen</code></td>
98           <td rowspan="3">All entries containing the term <code>human</code>
99             but not <code>antigen</code>.
100           </td>
101         </tr>
102         <tr>
103           <td><code>human NOT antigen</code></td>
104         </tr>
105         <tr>
106           <td><code>human ! antigen</code></td>
107         </tr>
108         <tr>
109           <td><code>human OR mouse</code></td>
110           <td rowspan="2">All entries containing either term.</td>
111         </tr>
112         <tr>
113           <td><code>human || mouse</code></td>
114         </tr>
115         <tr>
116           <td><code>antigen AND (human OR mouse)</code></td>
117           <td>Using parentheses to override boolean precedence
118             rules.</td>
119         </tr>
120         <tr>
121           <td><code>anti*</code></td>
122           <td>All entries containing terms starting with <code>anti</code>.
123             Asterisks can also be used at the beginning and within
124             terms. <strong>Note:</strong> Terms starting with an
125             asterisk or a single letter followed by an asterisk can slow
126             down queries considerably.
127           </td>
128         </tr>
129         <tr>
130           <td><code> author:Tiger*</code></td>
131           <td>Citations that have an author whose name starts with
132             <code>Tiger</code>. To search in a specific field of a
133             dataset, you must prefix your search term with the field
134             name and a colon. To discover what fields can be queried
135             explicitly, observe the query hints that are shown after
136             submitting a query or use the query builder (see below).
137           </td>
138         </tr>
139         <tr>
140           <td><code>length:[100 TO *]</code></td>
141           <td>All entries with a sequence of at least 100 amino
142             acids.</td>
143         </tr>
144         <tr>
145           <td><code>(lit_author:Arai) AND (lit_author:Chung)</code></td>
146           <td>All entries with a publication that was coauthored by
147             two specific authors.</td>
148         </tr>
149       </table></li>
150   </ul>
151   <p>
152     <strong>Result pagination</strong>
153   </p>
154   The query results returned from the UniProt server are paginated for
155   performance optimisation. The button labelled
156   <strong>'&nbsp;&lt;&lt;&nbsp;'</strong> and
157   <strong>'&nbsp;&gt;&gt;&nbsp;'</strong> can be used to navigate to the
158   next or previous result page respectively. The page range is shown on
159   the title bar of the Free Text Search interface. Jalview's pagination
160   implementation supports multiple selection of entries across multiple
161   pages.
162
163
164   <p>
165     <strong>Customising The UniProt Sequence Fetcher</strong>
166   </p>
167   <p>To change the displayed meta-data in the search result, click
168     the 'Customise Displayed Options' tab, and select the fields you'd
169     like to be displayed or removed.</p>
170   <p>
171     <em>The UniProt Free Test Search Interface was introduced in
172       Jalview 2.10.0 and updated to the July 2022 API in Jalview 2.11.2.4</em>
173   </p>
174 </body>
175 </html>