src/jalview/io/AlignFile.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.io;
  22
  23 import jalview.datamodel.AlignmentAnnotation;
  24 import jalview.datamodel.AlignmentI;
  25 import jalview.datamodel.Sequence;
  26 import jalview.datamodel.SequenceGroup;
  27 import jalview.datamodel.SequenceI;
  28 import jalview.util.MessageManager;
  29
  30 import java.io.IOException;
  31 import java.util.ArrayList;
  32 import java.util.Enumeration;
  33 import java.util.Hashtable;
  34 import java.util.List;
  35 import java.util.Vector;
  36
  37 /**
  38  * DOCUMENT ME!
  39  *
  40  * @author $author$
  41  * @version $Revision$
  42  */
  43 public abstract class AlignFile extends FileParse
  44         implements AlignmentFileReaderI, AlignmentFileWriterI
  45 {
  46   int noSeqs = 0;
  47
  48   int maxLength = 0;
  49
  50   /**
  51    * Sequences to be added to form a new alignment. TODO: remove vector in this
  52    * class
  53    */
  54   protected Vector<SequenceI> seqs;
  55
  56   /**
  57    * annotation to be added to generated alignment object
  58    */
  59   protected Vector<AlignmentAnnotation> annotations;
  60
  61   /**
  62    * SequenceGroups to be added to the alignment object
  63    */
  64   protected List<SequenceGroup> seqGroups;
  65
  66   /**
  67    * Properties to be added to generated alignment object
  68    */
  69   private Hashtable properties;
  70
  71   long start;
  72
  73   long end;
  74
  75   /**
  76    * true if parse() has been called
  77    */
  78   private boolean parseCalled = false;
  79
  80   private boolean parseImmediately = true;
  81
  82   /**
  83    * @return if doParse() was called at construction time
  84    */
  85   protected boolean isParseImmediately()
  86   {
  87     return parseImmediately;
  88   }
  89
  90   /**
  91    * Creates a new AlignFile object.
  92    */
  93   public AlignFile()
  94   {
  95     // Shouldn't we init data structures (JBPNote: not sure - initData is for
  96     // initialising the structures used for reading from a datasource, and the
  97     // bare constructor hasn't got any datasource)
  98     initData();
  99   }
 100
 101   public AlignFile(SequenceI[] seqs)
 102   {
 103     this();
 104     setSeqs(seqs);
 105   }
 106
 107   /**
 108    * Constructor which parses the data from a file of some specified type.
 109    *
 110    * @param dataObject
 111    *          Filename, URL or Pasted String to read from.
 112    * @param sourceType
 113    *          What type of file to read from (File, URL, Pasted String)
 114    */
 115   public AlignFile(String dataObject, DataSourceType sourceType)
 116           throws IOException
 117   {
 118     this(true, dataObject, sourceType);
 119   }
 120
 121   /**
 122    * Constructor which (optionally delays) parsing of data from a file of some
 123    * specified type.
 124    *
 125    * @param parseImmediately
 126    *          if false, need to call 'doParse()' to begin parsing data
 127    * @param dataObject
 128    *          Filename, URL or Pasted String to read from.
 129    * @param sourceType
 130    *          What type of file to read from (File, URL)
 131    * @throws IOException
 132    */
 133   public AlignFile(boolean parseImmediately, String dataObject,
 134           DataSourceType sourceType) throws IOException
 135   {
 136     super(dataObject, sourceType);
 137     initData();
 138     if (parseImmediately)
 139     {
 140       doParse();
 141     }
 142   }
 143
 144   /**
 145    * Attempt to read from the position where some other parsing process left
 146    * off.
 147    *
 148    * @param source
 149    * @throws IOException
 150    */
 151   public AlignFile(FileParse source) throws IOException
 152   {
 153     this(true, source);
 154   }
 155
 156   /**
 157    * Construct a new parser to read from the position where some other parsing
 158    * process left
 159    *
 160    * @param parseImmediately
 161    *          if false, need to call 'doParse()' to begin parsing data
 162    * @param source
 163    */
 164   public AlignFile(boolean parseImmediately, FileParse source)
 165           throws IOException
 166   {
 167     super(source);
 168     initData();
 169
 170     // stash flag in case parse needs to know if it has to autoconfigure or was
 171     // configured after construction
 172     this.parseImmediately = parseImmediately;
 173
 174     if (parseImmediately)
 175     {
 176       doParse();
 177     }
 178   }
 179
 180   /**
 181    * called if parsing was delayed till after parser was constructed
 182    *
 183    * @throws IOException
 184    */
 185   public void doParse() throws IOException
 186   {
 187     if (parseCalled)
 188     {
 189       throw new IOException(
 190               "Implementation error: Parser called twice for same data.\n"
 191                       + "Need to call initData() again before parsing can be reattempted.");
 192     }
 193     parseCalled = true;
 194     parse();
 195   }
 196
 197   /**
 198    * Return the seqs Vector
 199    */
 200   public Vector<SequenceI> getSeqs()
 201   {
 202     return seqs;
 203   }
 204
 205   public List<SequenceGroup> getSeqGroups()
 206   {
 207     return seqGroups;
 208   }
 209
 210   /**
 211    * Return the Sequences in the seqs Vector as an array of Sequences
 212    */
 213   @Override
 214   public SequenceI[] getSeqsAsArray()
 215   {
 216     SequenceI[] s = new SequenceI[seqs.size()];
 217
 218     for (int i = 0; i < seqs.size(); i++)
 219     {
 220       s[i] = seqs.elementAt(i);
 221     }
 222
 223     return s;
 224   }
 225
 226   /**
 227    * called by AppletFormatAdapter to generate an annotated alignment, rather
 228    * than bare sequences.
 229    *
 230    * @param al
 231    */
 232   @Override
 233   public void addAnnotations(AlignmentI al)
 234   {
 235     addProperties(al);
 236     for (int i = 0; i < annotations.size(); i++)
 237     {
 238       // detect if annotations.elementAt(i) rna secondary structure
 239       // if so then do:
 240       /*
 241        * SequenceFeature[] pairArray =
 242        * Rna.GetBasePairsFromAlignmentAnnotation(annotations.elementAt(i));
 243        * Rna.HelixMap(pairArray);
 244        */
 245       AlignmentAnnotation an = annotations.elementAt(i);
 246       an.validateRangeAndDisplay();
 247       al.addAnnotation(an);
 248     }
 249
 250   }
 251
 252   /**
 253    * register sequence groups on the alignment for **output**
 254    *
 255    * @param al
 256    */
 257   public void addSeqGroups(AlignmentI al)
 258   {
 259     this.seqGroups = al.getGroups();
 260
 261   }
 262
 263   /**
 264    * Add any additional information extracted from the file to the alignment
 265    * properties.
 266    *
 267    * @note implicitly called by addAnnotations()
 268    * @param al
 269    */
 270   public void addProperties(AlignmentI al)
 271   {
 272     if (properties != null && properties.size() > 0)
 273     {
 274       Enumeration keys = properties.keys();
 275       Enumeration vals = properties.elements();
 276       while (keys.hasMoreElements())
 277       {
 278         al.setProperty(keys.nextElement(), vals.nextElement());
 279       }
 280     }
 281   }
 282
 283   /**
 284    * Store a non-null key-value pair in a hashtable used to set alignment
 285    * properties note: null keys will raise an error, null values will result in
 286    * the key/value pair being silently ignored.
 287    *
 288    * @param key
 289    *          - non-null key object
 290    * @param value
 291    *          - non-null value
 292    */
 293   protected void setAlignmentProperty(Object key, Object value)
 294   {
 295     if (key == null)
 296     {
 297       throw new Error(MessageManager.getString(
 298               "error.implementation_error_cannot_have_null_alignment"));
 299     }
 300     if (value == null)
 301     {
 302       return; // null properties are ignored.
 303     }
 304     if (properties == null)
 305     {
 306       properties = new Hashtable();
 307     }
 308     properties.put(key, value);
 309   }
 310
 311   protected Object getAlignmentProperty(Object key)
 312   {
 313     if (properties != null && key != null)
 314     {
 315       return properties.get(key);
 316     }
 317     return null;
 318   }
 319
 320   /**
 321    * Initialise objects to store sequence data in.
 322    */
 323   protected void initData()
 324   {
 325     seqs = new Vector<>();
 326     annotations = new Vector<>();
 327     seqGroups = new ArrayList<>();
 328     parseCalled = false;
 329   }
 330
 331   /**
 332    * DOCUMENT ME!
 333    *
 334    * @param s
 335    *          DOCUMENT ME!
 336    */
 337   @Override
 338   public void setSeqs(SequenceI[] s)
 339   {
 340     seqs = new Vector<>();
 341
 342     for (int i = 0; i < s.length; i++)
 343     {
 344       seqs.addElement(s[i]);
 345     }
 346   }
 347
 348   /**
 349    * This method must be implemented to parse the contents of the file.
 350    */
 351   public abstract void parse() throws IOException;
 352
 353   /**
 354    * A general parser for ids.
 355    *
 356    * @String id Id to be parsed
 357    */
 358   Sequence parseId(String id)
 359   {
 360     Sequence seq = null;
 361     id = id.trim();
 362     int space = id.indexOf(" ");
 363     if (space > -1)
 364     {
 365       seq = new Sequence(id.substring(0, space), "");
 366       String desc = id.substring(space + 1);
 367       seq.setDescription(desc);
 368
 369       /*
 370        * it is tempting to parse Ensembl style gene description e.g.
 371        * chromosome:GRCh38:7:140696688:140721955:1 and set the
 372        * start position of the sequence, but this causes much confusion
 373        * for reverse strand feature locations
 374        */
 375     }
 376     else
 377     {
 378       seq = new Sequence(id, "");
 379     }
 380
 381     return seq;
 382   }
 383
 384   /**
 385    * Creates the output id. Adds prefix Uniprot format source|id and optionally
 386    * suffix Jalview /start-end
 387    *
 388    * @param jvsuffix
 389    *
 390    * @String id Id to be parsed
 391    */
 392   String printId(SequenceI seq, boolean jvsuffix)
 393   {
 394     return seq.getDisplayId(jvsuffix);
 395   }
 396
 397   String printId(SequenceI seq)
 398   {
 399     return printId(seq, true);
 400   }
 401
 402   /**
 403    * vector of String[] treeName, newickString pairs
 404    */
 405   Vector<String[]> newickStrings = null;
 406
 407   protected void addNewickTree(String treeName, String newickString)
 408   {
 409     if (newickStrings == null)
 410     {
 411       newickStrings = new Vector<>();
 412     }
 413     newickStrings.addElement(new String[] { treeName, newickString });
 414   }
 415
 416   protected int getTreeCount()
 417   {
 418     return newickStrings == null ? 0 : newickStrings.size();
 419   }
 420
 421   @Override
 422   public void addGroups(AlignmentI al)
 423   {
 424
 425     for (SequenceGroup sg : getSeqGroups())
 426     {
 427       al.addGroup(sg);
 428     }
 429   }
 430
 431   protected void addSequence(SequenceI seq)
 432   {
 433     seqs.add(seq);
 434   }
 435
 436   /**
 437    * Used only for hmmer statistics, so should probably be removed at some
 438    * point. TODO remove this
 439    *
 440    * @return
 441    */
 442   public Vector<AlignmentAnnotation> getAnnotations()
 443   {
 444     return annotations;
 445   }
 446
 447 }