JAL-3019 correctly form toRange of 'traversed' MapList
[jalview.git] / src / jalview / ext / ensembl / EnsemblFeatures.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.Alignment;
24 import jalview.datamodel.AlignmentI;
25 import jalview.io.FeaturesFile;
26 import jalview.io.FileParse;
27
28 import java.io.IOException;
29 import java.net.MalformedURLException;
30 import java.net.URL;
31 import java.util.ArrayList;
32 import java.util.List;
33
34 /**
35  * A client for fetching and processing Ensembl feature data in GFF format by
36  * calling the overlap REST service
37  * 
38  * @author gmcarstairs
39  * @see http://rest.ensembl.org/documentation/info/overlap_id
40  */
41 class EnsemblFeatures extends EnsemblRestClient
42 {
43   /*
44    * The default features to retrieve from Ensembl
45    * can override in getSequenceRecords parameter
46    */
47   private EnsemblFeatureType[] featuresWanted = { EnsemblFeatureType.cds,
48       EnsemblFeatureType.exon, EnsemblFeatureType.variation };
49
50   /**
51    * Default constructor (to use rest.ensembl.org)
52    */
53   public EnsemblFeatures()
54   {
55     super();
56   }
57
58   /**
59    * Constructor given the target domain to fetch data from
60    * 
61    * @param d
62    */
63   public EnsemblFeatures(String d)
64   {
65     super(d);
66   }
67
68   @Override
69   public String getDbName()
70   {
71     return "ENSEMBL (features)";
72   }
73
74   /**
75    * Makes a query to the REST overlap endpoint for the given sequence
76    * identifier. This returns an 'alignment' consisting of one 'dummy sequence'
77    * (the genomic sequence for which overlap features are returned by the
78    * service). This sequence will have on it sequence features which are the
79    * real information of interest, such as CDS regions or sequence variations.
80    */
81   @Override
82   public AlignmentI getSequenceRecords(String query) throws IOException
83   {
84     // TODO: use a vararg String... for getSequenceRecords instead?
85     List<String> queries = new ArrayList<>();
86     queries.add(query);
87     FileParse fp = getSequenceReader(queries);
88     if (fp == null || !fp.isValid())
89     {
90       return null;
91     }
92     FeaturesFile fr = new FeaturesFile(fp);
93     return new Alignment(fr.getSeqsAsArray());
94   }
95
96   /**
97    * Returns a URL for the REST overlap endpoint
98    * 
99    * @param ids
100    * @return
101    */
102   @Override
103   protected URL getUrl(List<String> ids) throws MalformedURLException
104   {
105     StringBuffer urlstring = new StringBuffer(128);
106     urlstring.append(getDomain()).append("/overlap/id/").append(ids.get(0));
107
108     // @see https://github.com/Ensembl/ensembl-rest/wiki/Output-formats
109     urlstring.append("?content-type=text/x-gff3");
110
111     /*
112      * specify object_type=gene in case is shared by transcript and/or protein;
113      * currently only fetching features for gene sequences;
114      * refactor in future if needed to fetch for transcripts
115      */
116     urlstring.append("&").append(OBJECT_TYPE).append("=")
117             .append(OBJECT_TYPE_GENE);
118
119     /*
120      * specify  features to retrieve
121      * @see http://rest.ensembl.org/documentation/info/overlap_id
122      * could make the list a configurable entry in .jalview_properties
123      */
124     for (EnsemblFeatureType feature : featuresWanted)
125     {
126       urlstring.append("&feature=").append(feature.name());
127     }
128
129     return new URL(urlstring.toString());
130   }
131
132   @Override
133   protected boolean useGetRequest()
134   {
135     return true;
136   }
137
138   /**
139    * Returns the MIME type for GFF3. For GET requests the Content-type header
140    * describes the required encoding of the response.
141    */
142   @Override
143   protected String getRequestMimeType(boolean multipleIds)
144   {
145     return "text/x-gff3";
146   }
147
148   /**
149    * Returns the MIME type for GFF3.
150    */
151   @Override
152   protected String getResponseMimeType()
153   {
154     return "text/x-gff3";
155   }
156
157   /**
158    * Overloaded method that allows a list of features to retrieve to be
159    * specified
160    * 
161    * @param accId
162    * @param features
163    * @return
164    * @throws IOException
165    */
166   protected AlignmentI getSequenceRecords(String accId,
167           EnsemblFeatureType[] features) throws IOException
168   {
169     featuresWanted = features;
170     return getSequenceRecords(accId);
171   }
172 }