src/jalview/ws/dbsources/EBIAlfaFold.java

   1
   2 /*
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  */
  22 package jalview.ws.dbsources;
  23
  24 import java.io.File;
  25 import java.io.FileInputStream;
  26 import java.io.FileNotFoundException;
  27 import java.io.IOException;
  28 import java.io.InputStream;
  29 import java.util.ArrayList;
  30 import java.util.Date;
  31 import java.util.HashMap;
  32 import java.util.List;
  33 import java.util.Map;
  34
  35 import org.json.simple.JSONArray;
  36 import org.json.simple.JSONObject;
  37 import org.json.simple.parser.ParseException;
  38
  39 import com.stevesoft.pat.Regex;
  40
  41 import jalview.api.FeatureSettingsModelI;
  42 import jalview.bin.Console;
  43 import jalview.datamodel.AlignmentAnnotation;
  44 import jalview.datamodel.AlignmentI;
  45 import jalview.datamodel.ContactMatrixI;
  46 import jalview.datamodel.DBRefEntry;
  47 import jalview.datamodel.GroupSet;
  48 import jalview.datamodel.PDBEntry;
  49 import jalview.datamodel.SequenceFeature;
  50 import jalview.datamodel.SequenceI;
  51 import jalview.gui.Desktop;
  52 import jalview.io.DataSourceType;
  53 import jalview.io.FileFormat;
  54 import jalview.io.FileFormatI;
  55 import jalview.io.FormatAdapter;
  56 import jalview.io.PDBFeatureSettings;
  57 import jalview.structure.StructureImportSettings.TFType;
  58 import jalview.structure.StructureMapping;
  59 import jalview.structure.StructureSelectionManager;
  60 import jalview.util.MessageManager;
  61 import jalview.util.Platform;
  62 import jalview.ws.datamodel.alphafold.PAEContactMatrix;
  63 import jalview.ws.utils.UrlDownloadClient;
  64
  65 /**
  66  * @author JimP
  67  *
  68  */
  69 public class EBIAlfaFold extends EbiFileRetrievedProxy
  70 {
  71   private static final String SEPARATOR = "|";
  72
  73   private static final String COLON = ":";
  74
  75   private static final int PDB_ID_LENGTH = 4;
  76
  77   private static String AF_VERSION = "3";
  78
  79   public EBIAlfaFold()
  80   {
  81     super();
  82   }
  83
  84   /*
  85    * (non-Javadoc)
  86    *
  87    * @see jalview.ws.DbSourceProxy#getAccessionSeparator()
  88    */
  89   @Override
  90   public String getAccessionSeparator()
  91   {
  92     return null;
  93   }
  94
  95   /*
  96    * (non-Javadoc)
  97    *
  98    * @see jalview.ws.DbSourceProxy#getAccessionValidator()
  99    */
 100   @Override
 101   public Regex getAccessionValidator()
 102   {
 103     Regex validator = new Regex("(AF-[A-Z]+[0-9]+[A-Z0-9]+-F1)");
 104     validator.setIgnoreCase(true);
 105     return validator;
 106   }
 107
 108   /*
 109    * (non-Javadoc)
 110    *
 111    * @see jalview.ws.DbSourceProxy#getDbSource()
 112    */
 113   @Override
 114   public String getDbSource()
 115   {
 116     return "ALPHAFOLD";
 117   }
 118
 119   /*
 120    * (non-Javadoc)
 121    *
 122    * @see jalview.ws.DbSourceProxy#getDbVersion()
 123    */
 124   @Override
 125   public String getDbVersion()
 126   {
 127     return "1";
 128   }
 129
 130   public static String getAlphaFoldCifDownloadUrl(String id, String vnum)
 131   {
 132     if (vnum == null || vnum.length() == 0)
 133     {
 134       vnum = AF_VERSION;
 135     }
 136     return "https://alphafold.ebi.ac.uk/files/" + id + "-model_v" + vnum
 137             + ".cif";
 138   }
 139
 140   public static String getAlphaFoldPaeDownloadUrl(String id, String vnum)
 141   {
 142     if (vnum == null || vnum.length() == 0)
 143     {
 144       vnum = AF_VERSION;
 145     }
 146     return "https://alphafold.ebi.ac.uk/files/" + id
 147             + "-predicted_aligned_error_v" + vnum + ".json";
 148   }
 149
 150   /*
 151    * (non-Javadoc)
 152    *
 153    * @see jalview.ws.DbSourceProxy#getSequenceRecords(java.lang.String[])
 154    */
 155   @Override
 156   public AlignmentI getSequenceRecords(String queries) throws Exception
 157   {
 158     return getSequenceRecords(queries, null);
 159   }
 160
 161   public AlignmentI getSequenceRecords(String queries, String retrievalUrl)
 162           throws Exception
 163   {
 164     AlignmentI pdbAlignment = null;
 165     String chain = null;
 166     String id = null;
 167     if (queries.indexOf(COLON) > -1)
 168     {
 169       chain = queries.substring(queries.indexOf(COLON) + 1);
 170       id = queries.substring(0, queries.indexOf(COLON));
 171     }
 172     else
 173     {
 174       id = queries;
 175     }
 176
 177     if (!isValidReference(id))
 178     {
 179       System.err.println(
 180               "(AFClient) Ignoring invalid alphafold query: '" + id + "'");
 181       stopQuery();
 182       return null;
 183     }
 184     String alphaFoldCif = getAlphaFoldCifDownloadUrl(id, AF_VERSION);
 185     if (retrievalUrl != null)
 186     {
 187       alphaFoldCif = retrievalUrl;
 188     }
 189
 190     try
 191     {
 192       File tmpFile = File.createTempFile(id, ".cif");
 193       Console.debug("Retrieving structure file for " + id + " from "
 194               + alphaFoldCif);
 195       UrlDownloadClient.download(alphaFoldCif, tmpFile);
 196
 197       // may not need this check ?
 198       file = tmpFile.getAbsolutePath();
 199       if (file == null)
 200       {
 201         return null;
 202       }
 203       // TODO Get the PAE file somewhere around here and remove from JmolParser
 204
 205       pdbAlignment = importDownloadedStructureFromUrl(alphaFoldCif, tmpFile,
 206               id, chain, getDbSource(), getDbVersion());
 207
 208       if (pdbAlignment == null || pdbAlignment.getHeight() < 1)
 209       {
 210         throw new Exception(MessageManager.formatMessage(
 211                 "exception.no_pdb_records_for_chain", new String[]
 212                 { id, ((chain == null) ? "' '" : chain) }));
 213       }
 214       // done during structure retrieval
 215       // retrieve_AlphaFold_pAE(id, pdbAlignment, retrievalUrl);
 216
 217     } catch (Exception ex) // Problem parsing PDB file
 218     {
 219       stopQuery();
 220       throw (ex);
 221     }
 222     return pdbAlignment;
 223   }
 224
 225   /**
 226    * get an alphafold pAE for the given id and return the File object of the
 227    * downloaded (temp) file
 228    *
 229    * @param id
 230    * @param pdbAlignment
 231    * @param retrievalUrl
 232    *          - URL of .mmcif from EBI-AlphaFold - will be used to generate the
 233    *          pAE URL automatically
 234    * @throws IOException
 235    * @throws Exception
 236    */
 237   public static File fetchAlphaFoldPAE(String id, String retrievalUrl)
 238           throws IOException
 239   {
 240     // import PAE as contact matrix - assume this will work if there was a
 241     // model
 242     String paeURL = getAlphaFoldPaeDownloadUrl(id, AF_VERSION);
 243
 244     if (retrievalUrl != null)
 245     {
 246       // manufacture the PAE url from a url like ...-model-vN.cif
 247       paeURL = retrievalUrl.replace("model", "predicted_aligned_error")
 248               .replace(".cif", ".json");
 249     }
 250
 251     // check the cache
 252     File pae = paeDownloadCache.get(paeURL);
 253     if (pae != null && pae.exists() && (new Date().getTime()
 254             - pae.lastModified()) < PAE_CACHE_STALE_TIME)
 255     {
 256       Console.debug(
 257               "Using existing file in PAE cache for '" + paeURL + "'");
 258       return pae;
 259     }
 260
 261     try
 262     {
 263       pae = File.createTempFile(id == null ? "af_pae" : id, "pae_json");
 264     } catch (IOException e)
 265     {
 266       e.printStackTrace();
 267     }
 268     Console.debug("Downloading pae from " + paeURL + " to " + pae.toString()
 269             + "");
 270     try
 271     {
 272       UrlDownloadClient.download(paeURL, pae);
 273     } catch (IOException e)
 274     {
 275       throw e;
 276     }
 277     // cache and it if successful
 278     paeDownloadCache.put(paeURL, pae);
 279     return pae;
 280   }
 281
 282   /**
 283    * get an alphafold pAE for the given id, and add it to sequence 0 in
 284    * pdbAlignment (assuming it came from structurefile parser).
 285    *
 286    * @param id
 287    * @param pdbAlignment
 288    * @param retrievalUrl
 289    *          - URL of .mmcif from EBI-AlphaFold - will be used to generate the
 290    *          pAE URL automatically
 291    * @throws IOException
 292    * @throws Exception
 293    */
 294   public static void retrieve_AlphaFold_pAE(String id,
 295           AlignmentI pdbAlignment, String retrievalUrl) throws IOException
 296   {
 297     File pae = fetchAlphaFoldPAE(id, retrievalUrl);
 298     addAlphaFoldPAE(pdbAlignment, pae, 0, null, false, false, null);
 299   }
 300
 301   public static void addAlphaFoldPAE(AlignmentI pdbAlignment, File pae,
 302           int index, String id, boolean isStruct, boolean isStructId,
 303           String label)
 304   {
 305     FileInputStream paeInput = null;
 306     try
 307     {
 308       paeInput = new FileInputStream(pae);
 309     } catch (FileNotFoundException e)
 310     {
 311       Console.error(
 312               "Could not find pAE file '" + pae.getAbsolutePath() + "'", e);
 313       return;
 314     }
 315
 316     if (isStruct)
 317     {
 318       // ###### WRITE A TEST for this bit of the logic addAlphaFoldPAE with
 319       // different params.
 320       StructureSelectionManager ssm = StructureSelectionManager
 321               .getStructureSelectionManager(Desktop.instance);
 322       if (ssm != null)
 323       {
 324         String structFilename = isStructId ? ssm.findFileForPDBId(id) : id;
 325         addPAEToStructure(ssm, structFilename, pae, label);
 326       }
 327
 328     }
 329     else
 330     {
 331       // attach to sequence?!
 332       try
 333       {
 334         if (!importPaeJSONAsContactMatrixToSequence(pdbAlignment, paeInput,
 335                 index, id, label))
 336         {
 337           Console.warn("Could not import contact matrix from '"
 338                   + pae.getAbsolutePath() + "' to sequence.");
 339         }
 340       } catch (IOException e1)
 341       {
 342         Console.error("Error when importing pAE file '"
 343                 + pae.getAbsolutePath() + "'", e1);
 344       } catch (ParseException e2)
 345       {
 346         Console.error("Error when parsing pAE file '"
 347                 + pae.getAbsolutePath() + "'", e2);
 348       }
 349     }
 350
 351   }
 352
 353   public static void addPAEToStructure(StructureSelectionManager ssm,
 354           String structFilename, File pae, String label)
 355   {
 356     FileInputStream paeInput = null;
 357     try
 358     {
 359       paeInput = new FileInputStream(pae);
 360     } catch (FileNotFoundException e)
 361     {
 362       Console.error(
 363               "Could not find pAE file '" + pae.getAbsolutePath() + "'", e);
 364       return;
 365     }
 366     if (ssm == null)
 367     {
 368       ssm = StructureSelectionManager
 369               .getStructureSelectionManager(Desktop.instance);
 370     }
 371     if (ssm != null)
 372     {
 373       StructureMapping[] smArray = ssm.getMapping(structFilename);
 374
 375       try
 376       {
 377         if (!importPaeJSONAsContactMatrixToStructure(smArray, paeInput,
 378                 label))
 379         {
 380           Console.warn("Could not import contact matrix from '"
 381                   + pae.getAbsolutePath() + "' to structure.");
 382         }
 383       } catch (IOException e1)
 384       {
 385         Console.error("Error when importing pAE file '"
 386                 + pae.getAbsolutePath() + "'", e1);
 387       } catch (ParseException e2)
 388       {
 389         Console.error("Error when parsing pAE file '"
 390                 + pae.getAbsolutePath() + "'", e2);
 391       }
 392     }
 393   }
 394
 395   /**
 396    * parses the given pAE matrix and adds it to sequence 0 in the given
 397    * alignment
 398    *
 399    * @param pdbAlignment
 400    * @param pae_input
 401    * @return true if there was a pAE matrix added
 402    * @throws ParseException
 403    * @throws IOException
 404    * @throws Exception
 405    */
 406   public static boolean importPaeJSONAsContactMatrixToSequence(
 407           AlignmentI pdbAlignment, InputStream pae_input, int index,
 408           String seqId, String label) throws IOException, ParseException
 409   {
 410     SequenceI sequence = null;
 411     if (seqId == null)
 412     {
 413       int seqToGet = index > 0 ? index : 0;
 414       sequence = pdbAlignment.getSequenceAt(seqToGet);
 415     }
 416     if (sequence == null)
 417     {
 418       SequenceI[] sequences = pdbAlignment.findSequenceMatch(seqId);
 419       if (sequences == null || sequences.length < 1)
 420       {
 421         Console.warn("Could not find sequence with id '" + seqId
 422                 + "' to attach pAE matrix to. Ignoring matrix.");
 423         return false;
 424       }
 425       else
 426       {
 427         sequence = sequences[0]; // just use the first sequence with this seqId
 428       }
 429     }
 430     if (sequence == null)
 431     {
 432       return false;
 433     }
 434     return importPaeJSONAsContactMatrixToSequence(pdbAlignment, pae_input,
 435             sequence, label);
 436   }
 437
 438   public static boolean importPaeJSONAsContactMatrixToSequence(
 439           AlignmentI pdbAlignment, InputStream pae_input,
 440           SequenceI sequence, String label)
 441           throws IOException, ParseException
 442   {
 443     JSONObject paeDict = parseJSONtoPAEContactMatrix(pae_input);
 444     if (paeDict == null)
 445     {
 446       Console.debug("JSON file did not parse properly.");
 447       return false;
 448     }
 449     ContactMatrixI matrix = new PAEContactMatrix(sequence,
 450             (Map<String, Object>) paeDict);
 451     matrix.setGroupSet(GroupSet.makeGroups(matrix, 5f, true));
 452
 453     AlignmentAnnotation cmannot = sequence.addContactList(matrix);
 454     if (label != null)
 455       cmannot.label = label;
 456     pdbAlignment.addAnnotation(cmannot);
 457
 458     return true;
 459   }
 460
 461   public static JSONObject parseJSONtoPAEContactMatrix(
 462           InputStream pae_input) throws IOException, ParseException
 463   {
 464     Object paeJson = Platform.parseJSON(pae_input);
 465     JSONObject paeDict = null;
 466     if (paeJson instanceof JSONObject)
 467     {
 468       paeDict = (JSONObject) paeJson;
 469     }
 470     else if (paeJson instanceof JSONArray)
 471     {
 472       JSONArray jsonArray = (JSONArray) paeJson;
 473       if (jsonArray.size() > 0)
 474         paeDict = (JSONObject) jsonArray.get(0);
 475     }
 476
 477     return paeDict;
 478   }
 479
 480   // ###### TEST THIS
 481   public static boolean importPaeJSONAsContactMatrixToStructure(
 482           StructureMapping[] smArray, InputStream paeInput, String label)
 483           throws IOException, ParseException
 484   {
 485     boolean someDone = false;
 486     for (StructureMapping sm : smArray)
 487     {
 488       boolean thisDone = importPaeJSONAsContactMatrixToStructure(sm,
 489               paeInput, label);
 490       someDone |= thisDone;
 491     }
 492     return someDone;
 493   }
 494
 495   public static boolean importPaeJSONAsContactMatrixToStructure(
 496           StructureMapping sm, InputStream paeInput, String label)
 497           throws IOException, ParseException
 498   {
 499     JSONObject pae_obj = parseJSONtoPAEContactMatrix(paeInput);
 500     if (pae_obj == null)
 501     {
 502       Console.debug("JSON file did not parse properly.");
 503       return false;
 504     }
 505
 506     SequenceI seq = sm.getSequence();
 507     ContactMatrixI matrix = new PAEContactMatrix(seq,
 508             (Map<String, Object>) pae_obj);
 509     matrix.setGroupSet(GroupSet.makeGroups(matrix, 5f, true));
 510     AlignmentAnnotation cmannot = sm.getSequence().addContactList(matrix);
 511     /* this already happens in Sequence.addContactList()
 512      seq.addAlignmentAnnotation(cmannot);
 513      */
 514     return true;
 515   }
 516
 517   /**
 518    * general purpose structure importer - designed to yield alignment useful for
 519    * transfer of annotation to associated sequences
 520    *
 521    * @param alphaFoldCif
 522    * @param tmpFile
 523    * @param id
 524    * @param chain
 525    * @param dbSource
 526    * @param dbVersion
 527    * @return
 528    * @throws Exception
 529    */
 530   public static AlignmentI importDownloadedStructureFromUrl(
 531           String alphaFoldCif, File tmpFile, String id, String chain,
 532           String dbSource, String dbVersion) throws Exception
 533   {
 534     String file = tmpFile.getAbsolutePath();
 535     // todo get rid of Type and use FileFormatI instead?
 536     FileFormatI fileFormat = FileFormat.MMCif;
 537     TFType tempfacType = TFType.PLDDT;
 538     AlignmentI pdbAlignment = new FormatAdapter().readFile(tmpFile, file,
 539             DataSourceType.FILE, fileFormat, tempfacType);
 540
 541     if (pdbAlignment != null)
 542     {
 543       List<SequenceI> toremove = new ArrayList<SequenceI>();
 544       for (SequenceI pdbcs : pdbAlignment.getSequences())
 545       {
 546         String chid = null;
 547         // Mapping map=null;
 548         for (PDBEntry pid : pdbcs.getAllPDBEntries())
 549         {
 550           if (pid.getFile() == file)
 551           {
 552             chid = pid.getChainCode();
 553           }
 554         }
 555         if (chain == null || (chid != null && (chid.equals(chain)
 556                 || chid.trim().equals(chain.trim())
 557                 || (chain.trim().length() == 0 && chid.equals("_")))))
 558         {
 559           // FIXME seems to result in 'PDB|1QIP|1qip|A' - 1QIP is redundant.
 560           // TODO: suggest simplify naming to 1qip|A as default name defined
 561           pdbcs.setName(id + SEPARATOR + pdbcs.getName());
 562           // Might need to add more metadata to the PDBEntry object
 563           // like below
 564           /*
 565            * PDBEntry entry = new PDBEntry(); // Construct the PDBEntry
 566            * entry.setId(id); if (entry.getProperty() == null)
 567            * entry.setProperty(new Hashtable());
 568            * entry.getProperty().put("chains", pdbchain.id + "=" +
 569            * sq.getStart() + "-" + sq.getEnd());
 570            * sq.getDatasetSequence().addPDBId(entry);
 571            */
 572           // Add PDB DB Refs
 573           // We make a DBRefEtntry because we have obtained the PDB file from
 574           // a
 575           // verifiable source
 576           // JBPNote - PDB DBRefEntry should also carry the chain and mapping
 577           // information
 578           if (dbSource != null)
 579           {
 580             DBRefEntry dbentry = new DBRefEntry(dbSource,
 581
 582                     dbVersion, (chid == null ? id : id + chid));
 583             // dbentry.setMap()
 584             pdbcs.addDBRef(dbentry);
 585             // update any feature groups
 586             List<SequenceFeature> allsf = pdbcs.getFeatures()
 587                     .getAllFeatures();
 588             List<SequenceFeature> newsf = new ArrayList<SequenceFeature>();
 589             if (allsf != null && allsf.size() > 0)
 590             {
 591               for (SequenceFeature f : allsf)
 592               {
 593                 if (file.equals(f.getFeatureGroup()))
 594                 {
 595                   f = new SequenceFeature(f, f.type, f.begin, f.end, id,
 596                           f.score);
 597                 }
 598                 newsf.add(f);
 599               }
 600               pdbcs.setSequenceFeatures(newsf);
 601             }
 602           }
 603         }
 604         else
 605         {
 606           // mark this sequence to be removed from the alignment
 607           // - since it's not from the right chain
 608           toremove.add(pdbcs);
 609         }
 610       }
 611       // now remove marked sequences
 612       for (SequenceI pdbcs : toremove)
 613       {
 614         pdbAlignment.deleteSequence(pdbcs);
 615         if (pdbcs.getAnnotation() != null)
 616         {
 617           for (AlignmentAnnotation aa : pdbcs.getAnnotation())
 618           {
 619             pdbAlignment.deleteAnnotation(aa);
 620           }
 621         }
 622       }
 623     }
 624     return pdbAlignment;
 625   }
 626
 627   /*
 628    * (non-Javadoc)
 629    *
 630    * @see jalview.ws.DbSourceProxy#isValidReference(java.lang.String)
 631    */
 632   @Override
 633   public boolean isValidReference(String accession)
 634   {
 635     Regex r = getAccessionValidator();
 636     return r.search(accession.trim());
 637   }
 638
 639   /**
 640    * human glyoxalase
 641    */
 642   @Override
 643   public String getTestQuery()
 644   {
 645     return "AF-O15552-F1";
 646   }
 647
 648   @Override
 649   public String getDbName()
 650   {
 651     return "ALPHAFOLD"; // getDbSource();
 652   }
 653
 654   @Override
 655   public int getTier()
 656   {
 657     return 0;
 658   }
 659
 660   /**
 661    * Returns a descriptor for suitable feature display settings with
 662    * <ul>
 663    * <li>ResNums or insertions features visible</li>
 664    * <li>insertions features coloured red</li>
 665    * <li>ResNum features coloured by label</li>
 666    * <li>Insertions displayed above (on top of) ResNums</li>
 667    * </ul>
 668    */
 669   @Override
 670   public FeatureSettingsModelI getFeatureColourScheme()
 671   {
 672     return new PDBFeatureSettings();
 673   }
 674
 675   // days * 86400000
 676   private static final long PAE_CACHE_STALE_TIME = 1 * 86400000;
 677
 678   private static Map<String, File> paeDownloadCache = new HashMap<>();
 679
 680 }