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.datamodel.Sequence;
  26 import jalview.datamodel.SequenceFeature;
  27 import jalview.datamodel.SequenceI;
  28 import jalview.io.gff.SequenceOntologyI;
  29 import jalview.util.JSONUtils;
  30
  31 import java.io.BufferedReader;
  32 import java.io.IOException;
  33 import java.net.MalformedURLException;
  34 import java.net.URL;
  35 import java.util.ArrayList;
  36 import java.util.Iterator;
  37 import java.util.List;
  38
  39 import org.json.simple.JSONArray;
  40 import org.json.simple.JSONObject;
  41 import org.json.simple.parser.JSONParser;
  42 import org.json.simple.parser.ParseException;
  43
  44 /**
  45  * A client for fetching and processing Ensembl feature data in GFF format by
  46  * calling the overlap REST service
  47  *
  48  * @author gmcarstairs
  49  * @see http://rest.ensembl.org/documentation/info/overlap_id
  50  */
  51 class EnsemblFeatures extends EnsemblRestClient
  52 {
  53   /*
  54    * The default features to retrieve from Ensembl
  55    * can override in getSequenceRecords parameter
  56    */
  57   private EnsemblFeatureType[] featuresWanted = { EnsemblFeatureType.cds,
  58       EnsemblFeatureType.exon, EnsemblFeatureType.variation };
  59
  60   /**
  61    * Default constructor (to use rest.ensembl.org)
  62    */
  63   public EnsemblFeatures()
  64   {
  65     super();
  66   }
  67
  68   /**
  69    * Constructor given the target domain to fetch data from
  70    *
  71    * @param d
  72    */
  73   public EnsemblFeatures(String d)
  74   {
  75     super(d);
  76   }
  77
  78   @Override
  79   public String getDbName()
  80   {
  81     return "ENSEMBL (features)";
  82   }
  83
  84   /**
  85    * Makes a query to the REST overlap endpoint for the given sequence
  86    * identifier. This returns an 'alignment' consisting of one 'dummy sequence'
  87    * (the genomic sequence for which overlap features are returned by the
  88    * service). This sequence will have on it sequence features which are the
  89    * real information of interest, such as CDS regions or sequence variations.
  90    */
  91   @Override
  92   public AlignmentI getSequenceRecords(String query) throws IOException
  93   {
  94     // TODO: use a vararg String... for getSequenceRecords instead?
  95     List<String> queries = new ArrayList<>();
  96     queries.add(query);
  97     BufferedReader fp = getSequenceReader(queries);
  98     if (fp == null)
  99     {
 100       return null;
 101     }
 102
 103     SequenceI seq = parseFeaturesJson(fp);
 104     return new Alignment(new SequenceI[] { seq });
 105   }
 106
 107   /**
 108    * Parses the JSON response into Jalview sequence features and attaches them
 109    * to a dummy sequence
 110    *
 111    * @param br
 112    * @return
 113    */
 114   private SequenceI parseFeaturesJson(BufferedReader br)
 115   {
 116     SequenceI seq = new Sequence("Dummy", "");
 117
 118     JSONParser jp = new JSONParser();
 119     try
 120     {
 121       JSONArray responses = (JSONArray) jp.parse(br);
 122       Iterator rvals = responses.iterator();
 123       while (rvals.hasNext())
 124       {
 125         try
 126         {
 127           JSONObject obj = (JSONObject) rvals.next();
 128           String type = obj.get("feature_type").toString();
 129           int start = Integer.parseInt(obj.get("start").toString());
 130           int end = Integer.parseInt(obj.get("end").toString());
 131           String source = obj.get("source").toString();
 132           String strand = obj.get("strand").toString();
 133           Object phase = obj.get("phase");
 134           String alleles = JSONUtils
 135                   .arrayToList((JSONArray) obj.get("alleles"));
 136           String clinSig = JSONUtils
 137                   .arrayToList(
 138                           (JSONArray) obj.get("clinical_significance"));
 139
 140           /*
 141            * convert 'variation' to 'sequence_variant', and 'cds' to 'CDS'
 142            * so as to have a valid SO term for the feature type
 143            * ('gene', 'exon', 'transcript' don't need any conversion)
 144            */
 145           if ("variation".equals(type))
 146           {
 147             type = SequenceOntologyI.SEQUENCE_VARIANT;
 148           }
 149           else if (SequenceOntologyI.CDS.equalsIgnoreCase((type)))
 150           {
 151             type = SequenceOntologyI.CDS;
 152           }
 153
 154           String desc = getFirstNotNull(obj, "alleles", "external_name",
 155                   JSON_ID);
 156           SequenceFeature sf = new SequenceFeature(type, desc, start, end,
 157                   source);
 158           sf.setStrand("1".equals(strand) ? "+" : "-");
 159           if (phase != null)
 160           {
 161             sf.setPhase(phase.toString());
 162           }
 163           setFeatureAttribute(sf, obj, "id");
 164           setFeatureAttribute(sf, obj, "Parent");
 165           setFeatureAttribute(sf, obj, "consequence_type");
 166           sf.setValue("alleles", alleles);
 167           sf.setValue("clinical_significance", clinSig);
 168
 169           seq.addSequenceFeature(sf);
 170         } catch (Throwable t)
 171         {
 172           // ignore - keep trying other features
 173         }
 174       }
 175     } catch (ParseException | IOException e)
 176     {
 177       // ignore
 178     }
 179
 180     return seq;
 181   }
 182
 183   /**
 184    * Returns the first non-null attribute found (if any) as a string, formatted
 185    * suitably for display as feature description or tooltip. Answers null if
 186    * none of the attribute keys is present.
 187    *
 188    * @param obj
 189    * @param keys
 190    * @return
 191    */
 192   protected String getFirstNotNull(JSONObject obj, String... keys)
 193   {
 194     String desc = null;
 195
 196     for (String key : keys)
 197     {
 198       Object val = obj.get(key);
 199       if (val != null)
 200       {
 201         String s = val instanceof JSONArray
 202                 ? JSONUtils.arrayToList((JSONArray) val)
 203                 : val.toString();
 204         if (!s.isEmpty())
 205         {
 206           return s;
 207         }
 208       }
 209     }
 210     return desc;
 211   }
 212
 213   /**
 214    * A helper method that reads the 'key' entry in the JSON object, and if not
 215    * null, sets its string value as an attribute on the sequence feature
 216    *
 217    * @param sf
 218    * @param obj
 219    * @param key
 220    */
 221   protected void setFeatureAttribute(SequenceFeature sf, JSONObject obj,
 222           String key)
 223   {
 224     Object object = obj.get(key);
 225     if (object != null)
 226     {
 227       sf.setValue(key, object.toString());
 228     }
 229   }
 230
 231   /**
 232    * Returns a URL for the REST overlap endpoint
 233    *
 234    * @param ids
 235    * @return
 236    */
 237   @Override
 238   protected URL getUrl(List<String> ids) throws MalformedURLException
 239   {
 240     StringBuffer urlstring = new StringBuffer(128);
 241     urlstring.append(getDomain()).append("/overlap/id/").append(ids.get(0));
 242
 243     // @see https://github.com/Ensembl/ensembl-rest/wiki/Output-formats
 244     urlstring.append("?content-type=" + getResponseMimeType());
 245
 246     /*
 247      * specify object_type=gene in case is shared by transcript and/or protein;
 248      * currently only fetching features for gene sequences;
 249      * refactor in future if needed to fetch for transcripts
 250      */
 251     urlstring.append("&").append(OBJECT_TYPE).append("=")
 252             .append(OBJECT_TYPE_GENE);
 253
 254     /*
 255      * specify  features to retrieve
 256      * @see http://rest.ensembl.org/documentation/info/overlap_id
 257      * could make the list a configurable entry in .jalview_properties
 258      */
 259     for (EnsemblFeatureType feature : featuresWanted)
 260     {
 261       urlstring.append("&feature=").append(feature.name());
 262     }
 263
 264     return new URL(urlstring.toString());
 265   }
 266
 267   @Override
 268   protected boolean useGetRequest()
 269   {
 270     return true;
 271   }
 272
 273   /**
 274    * Returns the MIME type for GFF3. For GET requests the Content-type header
 275    * describes the required encoding of the response.
 276    */
 277   @Override
 278   protected String getRequestMimeType()
 279   {
 280     return "application/json";
 281   }
 282
 283   /**
 284    * Returns the MIME type wanted for the response
 285    */
 286   @Override
 287   protected String getResponseMimeType()
 288   {
 289     return "application/json";
 290   }
 291
 292   /**
 293    * Overloaded method that allows a list of features to retrieve to be
 294    * specified
 295    *
 296    * @param accId
 297    * @param features
 298    * @return
 299    * @throws IOException
 300    */
 301   protected AlignmentI getSequenceRecords(String accId,
 302           EnsemblFeatureType[] features) throws IOException
 303   {
 304     featuresWanted = features;
 305     return getSequenceRecords(accId);
 306   }
 307 }