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