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 }