Merge branch 'patch/JAL-4298_synchronize_consoledoc' into bug/JAL-4298_java_console_c...
[jalview.git] / src / jalview / ext / ensembl / EnsemblMap.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.datamodel.AlignmentI;
24 import jalview.datamodel.DBRefSource;
25 import jalview.datamodel.GeneLociI;
26 import jalview.datamodel.GeneLocus;
27 import jalview.datamodel.Mapping;
28 import jalview.util.MapList;
29
30 import java.io.IOException;
31 import java.net.MalformedURLException;
32 import java.net.URL;
33 import java.util.ArrayList;
34 import java.util.Collections;
35 import java.util.Iterator;
36 import java.util.List;
37 import java.util.Map;
38
39 import org.json.simple.parser.ParseException;
40
41 /**
42  * A client for the Ensembl REST service /map endpoint, to convert from
43  * coordinates of one genome assembly to another.
44  * <p>
45  * Note that species and assembly identifiers passed to this class must be valid
46  * in Ensembl. They are not case sensitive.
47  * 
48  * @author gmcarstairs
49  * @see https://rest.ensembl.org/documentation/info/assembly_map
50  * @see https://rest.ensembl.org/info/assembly/human?content-type=text/xml
51  * @see https://rest.ensembl.org/info/species?content-type=text/xml
52  */
53 public class EnsemblMap extends EnsemblRestClient
54 {
55   private static final String MAPPED = "mapped";
56
57   private static final String MAPPINGS = "mappings";
58
59   private static final String CDS = "cds";
60
61   private static final String CDNA = "cdna";
62
63   /**
64    * Default constructor (to use rest.ensembl.org)
65    */
66   public EnsemblMap()
67   {
68     super();
69   }
70
71   /**
72    * Constructor given the target domain to fetch data from
73    * 
74    * @param
75    */
76   public EnsemblMap(String domain)
77   {
78     super(domain);
79   }
80
81   @Override
82   public String getDbName()
83   {
84     return DBRefSource.ENSEMBL;
85   }
86
87   @Override
88   public AlignmentI getSequenceRecords(String queries) throws Exception
89   {
90     return null; // not used
91   }
92
93   /**
94    * Constructs a URL of the format <code>
95    * http://rest.ensembl.org/map/human/GRCh38/17:45051610..45109016:1/GRCh37?content-type=application/json
96    * </code>
97    * 
98    * @param species
99    * @param chromosome
100    * @param fromRef
101    * @param toRef
102    * @param startPos
103    * @param endPos
104    * @return
105    * @throws MalformedURLException
106    */
107   protected URL getAssemblyMapUrl(String species, String chromosome,
108           String fromRef, String toRef, int startPos, int endPos)
109           throws MalformedURLException
110   {
111     /*
112      * start-end might be reverse strand - present forwards to the service
113      */
114     boolean forward = startPos <= endPos;
115     int start = forward ? startPos : endPos;
116     int end = forward ? endPos : startPos;
117     String strand = forward ? "1" : "-1";
118     String url = String.format(
119             "%s/map/%s/%s/%s:%d..%d:%s/%s?content-type=application/json",
120             getDomain(), species, fromRef, chromosome, start, end, strand,
121             toRef);
122     return new URL(url);
123   }
124
125   @Override
126   protected boolean useGetRequest()
127   {
128     return true;
129   }
130
131   @Override
132   protected URL getUrl(List<String> ids) throws MalformedURLException
133   {
134     return null; // not used
135   }
136
137   /**
138    * Calls the REST /map service to get the chromosomal coordinates (start/end)
139    * in 'toRef' that corresponding to the (start/end) queryRange in 'fromRef'
140    * 
141    * @param species
142    * @param chromosome
143    * @param fromRef
144    * @param toRef
145    * @param queryRange
146    * @return
147    * @see http://rest.ensemblgenomes.org/documentation/info/assembly_map
148    */
149   public int[] getAssemblyMapping(String species, String chromosome,
150           String fromRef, String toRef, int[] queryRange)
151   {
152     URL url = null;
153     try
154     {
155       url = getAssemblyMapUrl(species, chromosome, fromRef, toRef,
156               queryRange[0], queryRange[1]);
157       return (parseAssemblyMappingResponse(url));
158     } catch (Throwable t)
159     {
160       jalview.bin.Console.outPrintln("Error calling " + url + ": " + t.getMessage());
161       return null;
162     }
163   }
164
165   /**
166    * Parses the JSON response from the /map/&lt;species&gt;/ REST service. The
167    * format is (with some fields omitted)
168    * 
169    * <pre>
170    *  {"mappings": 
171    *    [{
172    *       "original": {"end":45109016,"start":45051610},
173    *       "mapped"  : {"end":43186384,"start":43128978} 
174    *  }] }
175    * </pre>
176    * 
177    * @param br
178    * @return
179    */
180   @SuppressWarnings("unchecked")
181   protected int[] parseAssemblyMappingResponse(URL url)
182   {
183     int[] result = null;
184
185     try
186     {
187       Iterator<Object> rvals = (Iterator<Object>) getJSON(url, null, -1,
188               MODE_ITERATOR, MAPPINGS);
189       if (rvals == null)
190       {
191         return null;
192       }
193       while (rvals.hasNext())
194       {
195         // todo check for "mapped"
196         Map<String, Object> val = (Map<String, Object>) rvals.next();
197         Map<String, Object> mapped = (Map<String, Object>) val.get(MAPPED);
198         int start = Integer.parseInt(mapped.get("start").toString());
199         int end = Integer.parseInt(mapped.get("end").toString());
200         String strand = mapped.get("strand").toString();
201         if ("1".equals(strand))
202         {
203           result = new int[] { start, end };
204         }
205         else
206         {
207           result = new int[] { end, start };
208         }
209       }
210     } catch (IOException | ParseException | NumberFormatException e)
211     {
212       // ignore
213     }
214     return result;
215   }
216
217   /**
218    * Calls the REST /map/cds/id service, and returns a DBRefEntry holding the
219    * returned chromosomal coordinates, or returns null if the call fails
220    * 
221    * @param division
222    *          e.g. Ensembl, EnsemblMetazoa
223    * @param accession
224    *          e.g. ENST00000592782, Y55B1AR.1.1
225    * @param start
226    * @param end
227    * @return
228    */
229   public GeneLociI getCdsMapping(String division, String accession,
230           int start, int end)
231   {
232     return getIdMapping(division, accession, start, end, CDS);
233   }
234
235   /**
236    * Calls the REST /map/cdna/id service, and returns a DBRefEntry holding the
237    * returned chromosomal coordinates, or returns null if the call fails
238    * 
239    * @param division
240    *          e.g. Ensembl, EnsemblMetazoa
241    * @param accession
242    *          e.g. ENST00000592782, Y55B1AR.1.1
243    * @param start
244    * @param end
245    * @return
246    */
247   public GeneLociI getCdnaMapping(String division, String accession,
248           int start, int end)
249   {
250     return getIdMapping(division, accession, start, end, CDNA);
251   }
252
253   GeneLociI getIdMapping(String division, String accession, int start,
254           int end, String cdsOrCdna)
255   {
256     URL url = null;
257     try
258     {
259       String domain = new EnsemblInfo().getDomain(division);
260       if (domain != null)
261       {
262         url = getIdMapUrl(domain, accession, start, end, cdsOrCdna);
263         return (parseIdMappingResponse(url, accession, domain));
264       }
265       return null;
266     } catch (Throwable t)
267     {
268       jalview.bin.Console.outPrintln("Error calling " + url + ": " + t.getMessage());
269       return null;
270     }
271   }
272
273   /**
274    * Constructs a URL to the /map/cds/<id> or /map/cdna/<id> REST service. The
275    * REST call is to either ensembl or ensemblgenomes, as determined from the
276    * division, e.g. Ensembl or EnsemblProtists.
277    * 
278    * @param domain
279    * @param accession
280    * @param start
281    * @param end
282    * @param cdsOrCdna
283    * @return
284    * @throws MalformedURLException
285    */
286   URL getIdMapUrl(String domain, String accession, int start, int end,
287           String cdsOrCdna) throws MalformedURLException
288   {
289     String url = String.format(
290             "%s/map/%s/%s/%d..%d?include_original_region=1&content-type=application/json",
291             domain, cdsOrCdna, accession, start, end);
292     return new URL(url);
293   }
294
295   /**
296    * Parses the JSON response from the /map/cds/ or /map/cdna REST service. The
297    * format is
298    * 
299    * <pre>
300    * {"mappings":
301    *   [
302    *    {"assembly_name":"TAIR10","end":2501311,"seq_region_name":"1","gap":0,
303    *     "strand":-1,"coord_system":"chromosome","rank":0,"start":2501114},
304    *    {"assembly_name":"TAIR10","end":2500815,"seq_region_name":"1","gap":0,
305    *     "strand":-1,"coord_system":"chromosome","rank":0,"start":2500714}
306    *   ]
307    * }
308    * </pre>
309    * 
310    * @param br
311    * @param accession
312    * @param domain
313    * @return
314    */
315   @SuppressWarnings("unchecked")
316   GeneLociI parseIdMappingResponse(URL url, String accession, String domain)
317   {
318
319     try
320     {
321       Iterator<Object> rvals = (Iterator<Object>) getJSON(url, null, -1,
322               MODE_ITERATOR, MAPPINGS);
323       if (rvals == null)
324       {
325         return null;
326       }
327       String assembly = null;
328       String chromosome = null;
329       int fromEnd = 0;
330       List<int[]> regions = new ArrayList<>();
331
332       while (rvals.hasNext())
333       {
334         Map<String, Object> val = (Map<String, Object>) rvals.next();
335         Map<String, Object> original = (Map<String, Object>) val
336                 .get("original");
337         fromEnd = Integer.parseInt(original.get("end").toString());
338
339         Map<String, Object> mapped = (Map<String, Object>) val.get(MAPPED);
340         int start = Integer.parseInt(mapped.get("start").toString());
341         int end = Integer.parseInt(mapped.get("end").toString());
342         String ass = mapped.get("assembly_name").toString();
343         if (assembly != null && !assembly.equals(ass))
344         {
345           jalview.bin.Console.errPrintln(
346                   "EnsemblMap found multiple assemblies - can't resolve");
347           return null;
348         }
349         assembly = ass;
350         String chr = mapped.get("seq_region_name").toString();
351         if (chromosome != null && !chromosome.equals(chr))
352         {
353           jalview.bin.Console.errPrintln(
354                   "EnsemblMap found multiple chromosomes - can't resolve");
355           return null;
356         }
357         chromosome = chr;
358         String strand = mapped.get("strand").toString();
359         if ("-1".equals(strand))
360         {
361           regions.add(new int[] { end, start });
362         }
363         else
364         {
365           regions.add(new int[] { start, end });
366         }
367       }
368
369       /*
370        * processed all mapped regions on chromosome, assemble the result,
371        * having first fetched the species id for the accession
372        */
373       final String species = new EnsemblLookup(domain)
374               .getSpecies(accession);
375       final String as = assembly;
376       final String chr = chromosome;
377       List<int[]> fromRange = Collections
378               .singletonList(new int[]
379               { 1, fromEnd });
380       Mapping mapping = new Mapping(new MapList(fromRange, regions, 1, 1));
381       return new GeneLocus(species == null ? "" : species, as, chr,
382               mapping);
383     } catch (IOException | ParseException | NumberFormatException e)
384     {
385       // ignore
386     }
387
388     return null;
389   }
390
391 }