Merge branch 'features/mchmmer' into features/mchmmer_merge_JAL-1950
[jalview.git] / src / jalview / ext / ensembl / EnsemblLookup.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.ext.ensembl;
22
23 import jalview.bin.Cache;
24 import jalview.datamodel.AlignmentI;
25 import jalview.datamodel.GeneLociI;
26 import jalview.util.MapList;
27
28 import java.io.BufferedReader;
29 import java.io.IOException;
30 import java.net.MalformedURLException;
31 import java.net.URL;
32 import java.util.Arrays;
33 import java.util.Collections;
34 import java.util.List;
35
36 import org.json.simple.JSONObject;
37 import org.json.simple.parser.JSONParser;
38 import org.json.simple.parser.ParseException;
39
40 /**
41  * A client for the Ensembl /lookup REST endpoint, used to find the gene
42  * identifier given a gene, transcript or protein identifier, or to extract the
43  * species or chromosomal coordinates from the same service response
44  * 
45  * @author gmcarstairs
46  */
47 public class EnsemblLookup extends EnsemblRestClient
48 {
49   private static final String SPECIES = "species";
50
51   /**
52    * Default constructor (to use rest.ensembl.org)
53    */
54   public EnsemblLookup()
55   {
56     super();
57   }
58
59   /**
60    * Constructor given the target domain to fetch data from
61    * 
62    * @param
63    */
64   public EnsemblLookup(String d)
65   {
66     super(d);
67   }
68
69   @Override
70   public String getDbName()
71   {
72     return "ENSEMBL";
73   }
74
75   @Override
76   public AlignmentI getSequenceRecords(String queries) throws Exception
77   {
78     return null;
79   }
80
81   @Override
82   protected URL getUrl(List<String> ids) throws MalformedURLException
83   {
84     String identifier = ids.get(0);
85     return getUrl(identifier, null);
86   }
87
88   /**
89    * Gets the url for lookup of the given identifier, optionally with objectType
90    * also specified in the request
91    * 
92    * @param identifier
93    * @param objectType
94    * @return
95    */
96   protected URL getUrl(String identifier, String objectType)
97   {
98     String url = getDomain() + "/lookup/id/" + identifier
99             + CONTENT_TYPE_JSON;
100     if (objectType != null)
101     {
102       url += "&" + OBJECT_TYPE + "=" + objectType;
103     }
104
105     try
106     {
107       return new URL(url);
108     } catch (MalformedURLException e)
109     {
110       return null;
111     }
112   }
113
114   @Override
115   protected boolean useGetRequest()
116   {
117     return true;
118   }
119
120   @Override
121   protected String getRequestMimeType(boolean multipleIds)
122   {
123     return "application/json";
124   }
125
126   @Override
127   protected String getResponseMimeType()
128   {
129     return "application/json";
130   }
131
132   /**
133    * Returns the gene id related to the given identifier (which may be for a
134    * gene, transcript or protein)
135    * 
136    * @param identifier
137    * @return
138    */
139   public String getGeneId(String identifier)
140   {
141     return getGeneId(identifier, null);
142   }
143
144   /**
145    * Returns the gene id related to the given identifier (which may be for a
146    * gene, transcript or protein)
147    * 
148    * @param identifier
149    * @param objectType
150    * @return
151    */
152   public String getGeneId(String identifier, String objectType)
153   {
154     return parseGeneId(getResult(identifier, objectType));
155   }
156
157   /**
158    * Parses the JSON response and returns the gene identifier, or null if not
159    * found. If the returned object_type is Gene, returns the id, if Transcript
160    * returns the Parent. If it is Translation (peptide identifier), then the
161    * Parent is the transcript identifier, so we redo the search with this value.
162    * 
163    * @param br
164    * @return
165    */
166   protected String parseGeneId(JSONObject val)
167   {
168     String geneId = null;
169     String type = val.get(OBJECT_TYPE).toString();
170     if (OBJECT_TYPE_GENE.equalsIgnoreCase(type))
171     {
172       // got the gene - just returns its id
173       geneId = val.get(JSON_ID).toString();
174     }
175     else if (OBJECT_TYPE_TRANSCRIPT.equalsIgnoreCase(type))
176     {
177       // got the transcript - return its (Gene) Parent
178       geneId = val.get(PARENT).toString();
179     }
180     else if (OBJECT_TYPE_TRANSLATION.equalsIgnoreCase(type))
181     {
182       // got the protein - get its Parent, restricted to type Transcript
183       String transcriptId = val.get(PARENT).toString();
184       geneId = getGeneId(transcriptId, OBJECT_TYPE_TRANSCRIPT);
185     }
186
187     return geneId;
188   }
189
190   /**
191    * Calls the Ensembl lookup REST endpoint and retrieves the 'species' for the
192    * given identifier, or null if not found
193    * 
194    * @param identifier
195    * @return
196    */
197   public String getSpecies(String identifier)
198   {
199     String species = null;
200     JSONObject json = getResult(identifier, null);
201     if (json != null)
202     {
203       Object o = json.get(SPECIES);
204       if (o != null)
205       {
206         species = o.toString();
207       }
208     }
209     return species;
210   }
211
212   /**
213    * Calls the /lookup/id rest service and returns the response as a JSONObject,
214    * or null if any error
215    * 
216    * @param identifier
217    * @param objectType
218    *          (optional)
219    * @return
220    */
221   protected JSONObject getResult(String identifier, String objectType)
222   {
223     List<String> ids = Arrays.asList(new String[] { identifier });
224
225     BufferedReader br = null;
226     try
227     {
228       URL url = getUrl(identifier, objectType);
229
230       if (url != null)
231       {
232         br = getHttpResponse(url, ids);
233       }
234       return br == null ? null : (JSONObject) (new JSONParser().parse(br));
235     } catch (IOException | ParseException e)
236     {
237       System.err.println("Error parsing " + identifier + " lookup response "
238               + e.getMessage());
239       return null;
240     } finally
241     {
242       if (br != null)
243       {
244         try
245         {
246           br.close();
247         } catch (IOException e)
248         {
249           // ignore
250         }
251       }
252     }
253   }
254
255   /**
256    * Calls the /lookup/id rest service for the given id, and if successful,
257    * parses and returns the gene's chromosomal coordinates
258    * 
259    * @param geneId
260    * @return
261    */
262   public GeneLociI getGeneLoci(String geneId)
263   {
264     return parseGeneLoci(getResult(geneId, OBJECT_TYPE_GENE));
265   }
266
267   /**
268    * Parses the /lookup/id response for species, asssembly_name,
269    * seq_region_name, start, end and returns an object that wraps them, or null
270    * if unsuccessful
271    * 
272    * @param json
273    * @return
274    */
275   GeneLociI parseGeneLoci(JSONObject json)
276   {
277     if (json == null)
278     {
279       return null;
280     }
281
282     try
283     {
284       final String species = json.get("species").toString();
285       final String assembly = json.get("assembly_name").toString();
286       final String chromosome = json.get("seq_region_name").toString();
287       String strand = json.get("strand").toString();
288       int start = Integer.parseInt(json.get("start").toString());
289       int end = Integer.parseInt(json.get("end").toString());
290       int fromEnd = end - start + 1;
291       boolean reverseStrand = "-1".equals(strand);
292       int toStart = reverseStrand ? end : start;
293       int toEnd = reverseStrand ? start : end;
294       List<int[]> fromRange = Collections.singletonList(new int[] { 1,
295           fromEnd });
296       List<int[]> toRange = Collections.singletonList(new int[] { toStart,
297           toEnd });
298       final MapList map = new MapList(fromRange, toRange, 1, 1);
299       return new GeneLociI()
300       {
301
302         @Override
303         public String getSpeciesId()
304         {
305           return species == null ? "" : species;
306         }
307
308         @Override
309         public String getAssemblyId()
310         {
311           return assembly;
312         }
313
314         @Override
315         public String getChromosomeId()
316         {
317           return chromosome;
318         }
319
320         @Override
321         public MapList getMap()
322         {
323           return map;
324         }
325       };
326     } catch (NullPointerException | NumberFormatException e)
327     {
328       Cache.log.error("Error looking up gene loci: " + e.getMessage());
329       e.printStackTrace();
330     }
331     return null;
332   }
333
334 }