JAL-1705 refactoring etc for fetching Ensembl --> Uniprot
[jalview.git] / src / jalview / analysis / CrossRef.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.analysis;
22
23 import jalview.datamodel.AlignedCodonFrame;
24 import jalview.datamodel.Alignment;
25 import jalview.datamodel.AlignmentI;
26 import jalview.datamodel.DBRefEntry;
27 import jalview.datamodel.DBRefSource;
28 import jalview.datamodel.Mapping;
29 import jalview.datamodel.Sequence;
30 import jalview.datamodel.SequenceFeature;
31 import jalview.datamodel.SequenceI;
32 import jalview.util.DBRefUtils;
33 import jalview.util.MapList;
34 import jalview.ws.SequenceFetcher;
35 import jalview.ws.seqfetcher.ASequenceFetcher;
36
37 import java.util.ArrayList;
38 import java.util.List;
39 import java.util.Vector;
40
41 /**
42  * Functions for cross-referencing sequence databases. user must first specify
43  * if cross-referencing from protein or dna (set dna==true)
44  * 
45  * @author JimP
46  * 
47  */
48 public class CrossRef
49 {
50   /*
51    * A sub-class that ignores Parent attribute when comparing sequence 
52    * features. This avoids 'duplicate' CDS features that only
53    * differ in their parent Transcript ids.
54    */
55   class MySequenceFeature extends SequenceFeature
56   {
57     private SequenceFeature feat;
58
59     MySequenceFeature(SequenceFeature sf)
60     {
61       this.feat = sf;
62     }
63
64     @Override
65     public boolean equals(Object o)
66     {
67       return feat.equals(o, true);
68     }
69   }
70
71   /**
72    * Select just the DNA or protein references for a protein or dna sequence
73    * 
74    * @param fromDna
75    *          if true, select references from DNA (i.e. Protein databases), else
76    *          DNA database references
77    * @param refs
78    *          a set of references to select from
79    * @return
80    */
81   public static DBRefEntry[] findXDbRefs(boolean fromDna, DBRefEntry[] refs)
82   {
83     return DBRefUtils.selectRefs(refs, fromDna ? DBRefSource.PROTEINDBS
84             : DBRefSource.DNACODINGDBS);
85     // could attempt to find other cross
86     // refs here - ie PDB xrefs
87     // (not dna, not protein seq)
88   }
89
90   /**
91    * @param dna
92    *          true if seqs are DNA seqs
93    * @param seqs
94    * @return a list of sequence database cross reference source types
95    */
96   public static String[] findSequenceXrefTypes(boolean dna, SequenceI[] seqs)
97   {
98     return findSequenceXrefTypes(dna, seqs, null);
99   }
100
101   /**
102    * Indirect references are references from other sequences from the dataset to
103    * any of the direct DBRefEntrys on the given sequences.
104    * 
105    * @param dna
106    *          true if seqs are DNA seqs
107    * @param seqs
108    * @return a list of sequence database cross reference source types
109    */
110   public static String[] findSequenceXrefTypes(boolean dna,
111           SequenceI[] seqs, AlignmentI dataset)
112   {
113     String[] dbrefs = null;
114     List<String> refs = new ArrayList<String>();
115     for (SequenceI seq : seqs)
116     {
117       if (seq != null)
118       {
119         SequenceI dss = seq;
120         while (dss.getDatasetSequence() != null)
121         {
122           dss = dss.getDatasetSequence();
123         }
124         DBRefEntry[] rfs = findXDbRefs(dna, dss.getDBRefs());
125         if (rfs != null)
126         {
127           for (DBRefEntry ref : rfs)
128           {
129             if (!refs.contains(ref.getSource()))
130             {
131               refs.add(ref.getSource());
132             }
133           }
134         }
135         if (dataset != null)
136         {
137           // search for references to this sequence's direct references.
138           DBRefEntry[] lrfs = CrossRef.findXDbRefs(!dna, seq.getDBRefs());
139           List<SequenceI> rseqs = new ArrayList<SequenceI>();
140           CrossRef.searchDatasetXrefs(seq, !dna, lrfs, dataset, rseqs,
141                   null); // don't need to specify codon frame for mapping here
142           for (SequenceI rs : rseqs)
143           {
144             DBRefEntry[] xrs = findXDbRefs(dna, rs.getDBRefs());
145             if (xrs != null)
146             {
147               for (DBRefEntry ref : xrs)
148               {
149                 if (!refs.contains(ref.getSource()))
150                 {
151                   refs.add(ref.getSource());
152                 }
153               }
154             }
155             // looks like copy and paste - change rfs to xrs?
156             // for (int r = 0; rfs != null && r < rfs.length; r++)
157             // {
158             // if (!refs.contains(rfs[r].getSource()))
159             // {
160             // refs.add(rfs[r].getSource());
161             // }
162             // }
163           }
164         }
165       }
166     }
167     if (refs.size() > 0)
168     {
169       dbrefs = new String[refs.size()];
170       refs.toArray(dbrefs);
171     }
172     return dbrefs;
173   }
174
175   public static boolean hasCdnaMap(SequenceI[] seqs)
176   {
177     // TODO unused - remove?
178     String[] reftypes = findSequenceXrefTypes(false, seqs);
179     for (int s = 0; s < reftypes.length; s++)
180     {
181       if (reftypes.equals(DBRefSource.EMBLCDS))
182       {
183         return true;
184         // no map
185       }
186     }
187     return false;
188   }
189
190   public static SequenceI[] getCdnaMap(SequenceI[] seqs)
191   {
192     // TODO unused - remove?
193     Vector cseqs = new Vector();
194     for (int s = 0; s < seqs.length; s++)
195     {
196       DBRefEntry[] cdna = findXDbRefs(true, seqs[s].getDBRefs());
197       for (int c = 0; c < cdna.length; c++)
198       {
199         if (cdna[c].getSource().equals(DBRefSource.EMBLCDS))
200         {
201           System.err
202                   .println("TODO: unimplemented sequence retrieval for coding region sequence.");
203           // TODO: retrieve CDS dataset sequences
204           // need global dataset sequence retriever/resolver to reuse refs
205           // and construct Mapping entry.
206           // insert gaps in CDS according to peptide gaps.
207           // add gapped sequence to cseqs
208         }
209       }
210     }
211     if (cseqs.size() > 0)
212     {
213       SequenceI[] rsqs = new SequenceI[cseqs.size()];
214       cseqs.copyInto(rsqs);
215       return rsqs;
216     }
217     return null;
218
219   }
220
221   /**
222    * 
223    * @param seqs
224    *          sequences whose xrefs are being retrieved
225    * @param dna
226    *          true if sequences are nucleotide
227    * @param source
228    * @param al
229    *          alignment to search for cross-referenced sequences (and possibly
230    *          add to)
231    * @param addedPeers
232    *          a list of sequences to add to if 'peers' to the original sequences
233    *          are found e.g. alternative protein products for a protein's gene
234    * @return products (as dataset sequences)
235    */
236   public static Alignment findXrefSequences(SequenceI[] seqs,
237           final boolean dna, final String source, AlignmentI al,
238           List<SequenceI> addedPeers)
239   {
240     AlignmentI dataset = al.getDataset() == null ? al : al.getDataset();
241     List<SequenceI> rseqs = new ArrayList<SequenceI>();
242     AlignedCodonFrame cf = new AlignedCodonFrame();
243     for (SequenceI seq : seqs)
244     {
245       SequenceI dss = seq;
246       while (dss.getDatasetSequence() != null)
247       {
248         dss = dss.getDatasetSequence();
249       }
250       boolean found = false;
251       DBRefEntry[] xrfs = CrossRef.findXDbRefs(dna, dss.getDBRefs());
252       if ((xrfs == null || xrfs.length == 0) && dataset != null)
253       {
254         System.out.println("Attempting to find ds Xrefs refs.");
255         // FIXME should be dss not seq here?
256         DBRefEntry[] lrfs = CrossRef.findXDbRefs(!dna, seq.getDBRefs());
257         // less ambiguous would be a 'find primary dbRefEntry' method.
258         // filter for desired source xref here
259         found = CrossRef.searchDatasetXrefs(dss, !dna, lrfs, dataset,
260                 rseqs, cf);
261       }
262       for (int r = 0; xrfs != null && r < xrfs.length; r++)
263       {
264         DBRefEntry xref = xrfs[r];
265         if (source != null && !source.equals(xref.getSource()))
266         {
267           continue;
268         }
269         if (xref.hasMap())
270         {
271           if (xref.getMap().getTo() != null)
272           {
273             SequenceI rsq = new Sequence(xref.getMap().getTo());
274             rseqs.add(rsq);
275             if (xref.getMap().getMap().getFromRatio() != xref
276                     .getMap().getMap().getToRatio())
277             {
278               // get sense of map correct for adding to product alignment.
279               if (dna)
280               {
281                 // map is from dna seq to a protein product
282                 cf.addMap(dss, rsq, xref.getMap().getMap());
283               }
284               else
285               {
286                 // map should be from protein seq to its coding dna
287                 cf.addMap(rsq, dss, xref.getMap().getMap().getInverse());
288               }
289             }
290             found = true;
291           }
292         }
293         if (!found)
294         {
295           // do a bit more work - search for sequences with references matching
296           // xrefs on this sequence.
297           if (dataset != null)
298           {
299             found |= searchDataset(dss, xref, dataset, rseqs, cf, false,
300                     !dna);
301             // ,false,!dna);
302             if (found)
303             {
304               xrfs[r] = null; // we've recovered seqs for this one.
305             }
306           }
307         }
308       }
309       if (!found)
310       {
311         if (xrfs != null && xrfs.length > 0)
312         {
313           // Try and get the sequence reference...
314           /*
315            * Ideal world - we ask for a sequence fetcher implementation here if
316            * (jalview.io.RunTimeEnvironment.getSequenceFetcher()) (
317            */
318           ASequenceFetcher sftch = new SequenceFetcher();
319           SequenceI[] retrieved = null;
320           int l = xrfs.length;
321           for (int r = 0; r < xrfs.length; r++)
322           {
323             // filter out any irrelevant or irretrievable references
324             if (xrfs[r] == null
325                     || ((source != null && !source.equals(xrfs[r]
326                             .getSource())) || !sftch.isFetchable(xrfs[r]
327                             .getSource())))
328             {
329               l--;
330               xrfs[r] = null;
331             }
332           }
333           if (l > 0)
334           {
335             System.out
336                     .println("Attempting to retrieve cross referenced sequences.");
337             DBRefEntry[] t = new DBRefEntry[l];
338             l = 0;
339             for (int r = 0; r < xrfs.length; r++)
340             {
341               if (xrfs[r] != null)
342               {
343                 t[l++] = xrfs[r];
344               }
345             }
346             xrfs = t;
347             try
348             {
349               retrieved = sftch.getSequences(xrfs, !dna);
350               // problem here is we don't know which of xrfs resulted in which
351               // retrieved element
352             } catch (Exception e)
353             {
354               System.err
355                       .println("Problem whilst retrieving cross references for Sequence : "
356                               + seq.getName());
357               e.printStackTrace();
358             }
359
360             if (retrieved != null)
361             {
362               updateDbrefMappings(dna, seq, xrfs, retrieved, cf);
363
364               List<SequenceFeature> copiedFeatures = new ArrayList<SequenceFeature>();
365               CrossRef me = new CrossRef();
366               for (int rs = 0; rs < retrieved.length; rs++)
367               {
368                 // TODO: examine each sequence for 'redundancy'
369                 DBRefEntry[] dbr = retrieved[rs].getDBRefs();
370                 if (dbr != null && dbr.length > 0)
371                 {
372                   for (int di = 0; di < dbr.length; di++)
373                   {
374                     // find any entry where we should put in the sequence being
375                     // cross-referenced into the map
376                     Mapping map = dbr[di].getMap();
377                     if (map != null)
378                     {
379                       if (map.getTo() != null && map.getMap() != null)
380                       {
381                         // should search the local dataset to find any existing
382                         // candidates for To !
383                         try
384                         {
385                           // compare ms with dss and replace with dss in mapping
386                           // if map is congruent
387                           SequenceI ms = map.getTo();
388                           int sf = map.getMap().getToLowest();
389                           int st = map.getMap().getToHighest();
390                           SequenceI mappedrg = ms.getSubSequence(sf, st);
391                           // SequenceI loc = dss.getSubSequence(sf, st);
392                           if (mappedrg.getLength() > 0
393                                   && ms.getSequenceAsString().equals(
394                                           dss.getSequenceAsString()))
395                           // && mappedrg.getSequenceAsString().equals(
396                           // loc.getSequenceAsString()))
397                           {
398                             String msg = "Mapping updated from "
399                                     + ms.getName()
400                                     + " to retrieved crossreference "
401                                     + dss.getName();
402                             System.out.println(msg);
403                             // method to update all refs of existing To on
404                             // retrieved sequence with dss and merge any props
405                             // on To onto dss.
406                             map.setTo(dss);
407                             /*
408                              * copy sequence features as well, avoiding
409                              * duplication (e.g. from 2 transcripts)
410                              */
411                             SequenceFeature[] sfs = ms
412                                     .getSequenceFeatures();
413                             if (sfs != null)
414                             {
415                               for (SequenceFeature feat : sfs)
416                               {
417                                 /* 
418                                  * we override SequenceFeature.equals here (but
419                                  * not elsewhere) to ignore Parent attribute
420                                  * TODO not quite working yet!
421                                  */
422                                 if (!copiedFeatures
423                                         .contains(me.new MySequenceFeature(
424                                                 feat)))
425                                 {
426                                   dss.addSequenceFeature(feat);
427                                   copiedFeatures.add(feat);
428                                 }
429                               }
430                             }
431                             cf.addMap(retrieved[rs].getDatasetSequence(),
432                                     dss, map.getMap());
433                           }
434                           else
435                           {
436                             addedPeers.add(map.getTo());
437                             cf.addMap(retrieved[rs].getDatasetSequence(),
438                                     map.getTo(), map.getMap());
439                           }
440                         } catch (Exception e)
441                         {
442                           System.err
443                                   .println("Exception when consolidating Mapped sequence set...");
444                           e.printStackTrace(System.err);
445                         }
446                       }
447                     }
448                   }
449                 }
450                 retrieved[rs].updatePDBIds();
451                 rseqs.add(retrieved[rs]);
452               }
453             }
454           }
455         }
456       }
457     }
458
459     Alignment ral = null;
460     if (rseqs.size() > 0)
461     {
462       ral = new Alignment(rseqs.toArray(new SequenceI[rseqs.size()]));
463       if (cf != null && !cf.isEmpty())
464       {
465         ral.addCodonFrame(cf);
466       }
467     }
468     return ral;
469   }
470
471   /**
472    * Updates any empty mappings in the cross-references with one to a compatible
473    * retrieved sequence if found, and adds any new mappings to the
474    * AlignedCodonFrame
475    * 
476    * @param dna
477    * @param mapFrom
478    * @param xrefs
479    * @param retrieved
480    * @param acf
481    */
482   static void updateDbrefMappings(boolean dna, SequenceI mapFrom,
483           DBRefEntry[] xrefs, SequenceI[] retrieved, AlignedCodonFrame acf)
484   {
485     SequenceIdMatcher matcher = new SequenceIdMatcher(retrieved);
486     for (DBRefEntry xref : xrefs)
487     {
488       if (!xref.hasMap())
489       {
490         String targetSeqName = xref.getSource() + "|"
491                 + xref.getAccessionId();
492         SequenceI[] matches = matcher.findAllIdMatches(targetSeqName);
493         if (matches == null)
494         {
495           return;
496         }
497         for (SequenceI seq : matches)
498         {
499           MapList mapping = null;
500           if (dna)
501           {
502             mapping = AlignmentUtils.mapCdnaToProtein(seq, mapFrom);
503           }
504           else
505           {
506             mapping = AlignmentUtils.mapCdnaToProtein(mapFrom, seq);
507             if (mapping != null)
508             {
509               mapping = mapping.getInverse();
510             }
511           }
512           if (mapping != null)
513           {
514             xref.setMap(new Mapping(seq, mapping));
515             if (dna)
516             {
517               AlignmentUtils.computeProteinFeatures(mapFrom, seq, mapping);
518             }
519             if (dna)
520             {
521               acf.addMap(mapFrom, seq, mapping);
522             }
523             else
524             {
525               acf.addMap(seq, mapFrom, mapping.getInverse());
526             }
527             continue;
528           }
529         }
530       }
531     }
532   }
533
534   /**
535    * find references to lrfs in the cross-reference set of each sequence in
536    * dataset (that is not equal to sequenceI) Identifies matching DBRefEntry
537    * based on source and accession string only - Map and Version are nulled.
538    * 
539    * @param sequenceI
540    * @param lrfs
541    * @param dataset
542    * @param rseqs
543    * @return true if matches were found.
544    */
545   private static boolean searchDatasetXrefs(SequenceI sequenceI,
546           boolean dna, DBRefEntry[] lrfs, AlignmentI dataset,
547           List<SequenceI> rseqs, AlignedCodonFrame cf)
548   {
549     boolean found = false;
550     if (lrfs == null)
551     {
552       return false;
553     }
554     for (int i = 0; i < lrfs.length; i++)
555     {
556       DBRefEntry xref = new DBRefEntry(lrfs[i]);
557       // add in wildcards
558       xref.setVersion(null);
559       xref.setMap(null);
560       found = searchDataset(sequenceI, xref, dataset, rseqs, cf, false, dna);
561     }
562     return found;
563   }
564
565   /**
566    * search a given sequence dataset for references matching cross-references to
567    * the given sequence
568    * 
569    * @param sequenceI
570    * @param xrf
571    * @param dataset
572    * @param rseqs
573    *          set of unique sequences
574    * @param cf
575    * @return true if one or more unique sequences were found and added
576    */
577   public static boolean searchDataset(SequenceI sequenceI, DBRefEntry xrf,
578           AlignmentI dataset, List<SequenceI> rseqs, AlignedCodonFrame cf)
579   {
580     return searchDataset(sequenceI, xrf, dataset, rseqs, cf, true, false);
581   }
582
583   /**
584    * TODO: generalise to different protein classifications Search dataset for
585    * DBRefEntrys matching the given one (xrf) and add the associated sequence to
586    * rseq.
587    * 
588    * @param sequenceI
589    * @param xrf
590    * @param dataset
591    * @param rseqs
592    * @param direct
593    *          - search all references or only subset
594    * @param dna
595    *          search dna or protein xrefs (if direct=false)
596    * @return true if relationship found and sequence added.
597    */
598   public static boolean searchDataset(SequenceI sequenceI, DBRefEntry xrf,
599           AlignmentI dataset, List<SequenceI> rseqs, AlignedCodonFrame cf,
600           boolean direct, boolean dna)
601   {
602     boolean found = false;
603     SequenceI[] typer = new SequenceI[1];
604     if (dataset == null)
605     {
606       return false;
607     }
608     if (dataset.getSequences() == null)
609     {
610       System.err.println("Empty dataset sequence set - NO VECTOR");
611       return false;
612     }
613     List<SequenceI> ds;
614     synchronized (ds = dataset.getSequences())
615     {
616       for (SequenceI nxt : ds)
617       {
618         if (nxt != null)
619         {
620           if (nxt.getDatasetSequence() != null)
621           {
622             System.err
623                     .println("Implementation warning: getProducts passed a dataset alignment without dataset sequences in it!");
624           }
625           if (nxt != sequenceI && nxt != sequenceI.getDatasetSequence())
626           {
627             // check if this is the correct sequence type
628             {
629               typer[0] = nxt;
630               boolean isDna = jalview.util.Comparison.isNucleotide(typer);
631               if ((direct && isDna == dna) || (!direct && isDna != dna))
632               {
633                 // skip this sequence because it is same molecule type
634                 continue;
635               }
636             }
637
638             // look for direct or indirect references in common
639             DBRefEntry[] poss = nxt.getDBRefs(), cands = null;
640             if (direct)
641             {
642               cands = jalview.util.DBRefUtils.searchRefs(poss, xrf);
643             }
644             else
645             {
646               poss = CrossRef.findXDbRefs(dna, poss); //
647               cands = jalview.util.DBRefUtils.searchRefs(poss, xrf);
648             }
649             if (cands != null)
650             {
651               if (!rseqs.contains(nxt))
652               {
653                 rseqs.add(nxt);
654                 boolean foundmap = cf != null;
655                 // don't search if we aren't given a codon map object
656                 for (int r = 0; foundmap && r < cands.length; r++)
657                 {
658                   if (cands[r].hasMap())
659                   {
660                     if (cands[r].getMap().getTo() != null
661                             && cands[r].getMap().getMap().getFromRatio() != cands[r]
662                                     .getMap().getMap().getToRatio())
663                     {
664                       foundmap = true;
665                       // get sense of map correct for adding to product
666                       // alignment.
667                       if (dna)
668                       {
669                         // map is from dna seq to a protein product
670                         cf.addMap(sequenceI, nxt, cands[r].getMap()
671                                 .getMap());
672                       }
673                       else
674                       {
675                         // map should be from protein seq to its coding dna
676                         cf.addMap(nxt, sequenceI, cands[r].getMap()
677                                 .getMap().getInverse());
678                       }
679                     }
680                   }
681                 }
682                 // TODO: add mapping between sequences if necessary
683                 found = true;
684               }
685             }
686
687           }
688         }
689       }
690     }
691     return found;
692   }
693
694   /**
695    * precalculate different products that can be found for seqs in dataset and
696    * return them.
697    * 
698    * @param dna
699    * @param seqs
700    * @param dataset
701    * @param fake
702    *          - don't actually build lists - just get types
703    * @return public static Object[] buildXProductsList(boolean dna, SequenceI[]
704    *         seqs, AlignmentI dataset, boolean fake) { String types[] =
705    *         jalview.analysis.CrossRef.findSequenceXrefTypes( dna, seqs,
706    *         dataset); if (types != null) { System.out.println("Xref Types for:
707    *         "+(dna ? "dna" : "prot")); for (int t = 0; t < types.length; t++) {
708    *         System.out.println("Type: " + types[t]); SequenceI[] prod =
709    *         jalview.analysis.CrossRef.findXrefSequences(seqs, dna, types[t]);
710    *         System.out.println("Found " + ((prod == null) ? "no" : "" +
711    *         prod.length) + " products"); if (prod!=null) { for (int p=0;
712    *         p<prod.length; p++) { System.out.println("Prod "+p+":
713    *         "+prod[p].getDisplayId(true)); } } } } else {
714    *         System.out.println("Trying getProducts for
715    *         "+al.getSequenceAt(0).getDisplayId(true));
716    *         System.out.println("Search DS Xref for: "+(dna ? "dna" : "prot"));
717    *         // have a bash at finding the products amongst all the retrieved
718    *         sequences. SequenceI[] prod =
719    *         jalview.analysis.CrossRef.findXrefSequences(al
720    *         .getSequencesArray(), dna, null, ds); System.out.println("Found " +
721    *         ((prod == null) ? "no" : "" + prod.length) + " products"); if
722    *         (prod!=null) { // select non-equivalent sequences from dataset list
723    *         for (int p=0; p<prod.length; p++) { System.out.println("Prod "+p+":
724    *         "+prod[p].getDisplayId(true)); } } } }
725    */
726 }