JAL-1479 improved SiftsClient test coverage and implemented previously unimplemented...
[jalview.git] / src / jalview / ws / sifts / SiftsClient.java
index 00da2fc..13e52cd 100644 (file)
@@ -26,6 +26,7 @@ import jalview.api.SiftsClientI;
 import jalview.datamodel.DBRefEntry;
 import jalview.datamodel.DBRefSource;
 import jalview.datamodel.SequenceI;
+import jalview.io.StructureFile;
 import jalview.schemes.ResidueProperties;
 import jalview.structure.StructureMapping;
 import jalview.util.Format;
@@ -36,49 +37,50 @@ import jalview.xml.binding.sifts.Entry.Entity.Segment.ListMapRegion.MapRegion;
 import jalview.xml.binding.sifts.Entry.Entity.Segment.ListResidue.Residue;
 import jalview.xml.binding.sifts.Entry.Entity.Segment.ListResidue.Residue.CrossRefDb;
 import jalview.xml.binding.sifts.Entry.Entity.Segment.ListResidue.Residue.ResidueDetail;
-import jalview.xml.binding.sifts.Entry.ListDB.Db;
 
 import java.io.File;
 import java.io.FileInputStream;
-import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.PrintStream;
 import java.net.URL;
 import java.net.URLConnection;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.BasicFileAttributes;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
 import java.util.TreeMap;
 import java.util.zip.GZIPInputStream;
 
 import javax.xml.bind.JAXBContext;
-import javax.xml.bind.JAXBException;
 import javax.xml.bind.Unmarshaller;
-import javax.xml.stream.FactoryConfigurationError;
 import javax.xml.stream.XMLInputFactory;
-import javax.xml.stream.XMLStreamException;
 import javax.xml.stream.XMLStreamReader;
 
 import MCview.Atom;
 import MCview.PDBChain;
-import MCview.PDBfile;
 
 public class SiftsClient implements SiftsClientI
 {
   private Entry siftsEntry;
 
-  private PDBfile pdb;
+  private StructureFile pdb;
 
   private String pdbId;
 
   private String structId;
 
-  private String segStartEnd;
+  // private String segStartEnd;
 
   private CoordinateSys seqCoordSys = CoordinateSys.UNIPROT;
 
@@ -90,11 +92,9 @@ public class SiftsClient implements SiftsClientI
 
   private static final int PDB_ATOM_POS = 1;
 
-  private static final String NOT_FOUND = "Not_Found";
-
   private static final String NOT_OBSERVED = "Not_Observed";
 
-  private static final String SIFTS_FTP_BASE_URL = "ftp://ftp.ebi.ac.uk/pub/databases/msd/sifts/xml/";
+  private static final String SIFTS_FTP_BASE_URL = "http://ftp.ebi.ac.uk/pub/databases/msd/sifts/xml/";
 
   private final static String NEWLINE = System.lineSeparator();
 
@@ -142,29 +142,14 @@ public class SiftsClient implements SiftsClientI
    * @param pdbId
    * @throws SiftsException
    */
-  public SiftsClient(PDBfile pdb) throws SiftsException
+  public SiftsClient(StructureFile pdb) throws SiftsException
   {
     this.pdb = pdb;
-    this.pdbId = pdb.id;
+    this.pdbId = pdb.getId();
     File siftsFile = getSiftsFile(pdbId);
     siftsEntry = parseSIFTs(siftsFile);
   }
 
-  /**
-   * Construct an instance of SiftsClient using the supplied SIFTs file. Note:
-   * The SIFTs file should correspond to the PDB Id in PDBfile instance
-   * 
-   * @param pdbId
-   * @param siftsFile
-   * @throws SiftsException
-   * @throws Exception
-   */
-  public SiftsClient(PDBfile pdb, File siftsFile) throws SiftsException
-  {
-    this.pdb = pdb;
-    this.pdbId = pdb.id;
-    siftsEntry = parseSIFTs(siftsFile);
-  }
 
   /**
    * Parse the given SIFTs File and return a JAXB POJO of parsed data
@@ -180,29 +165,13 @@ public class SiftsClient implements SiftsClientI
     try (InputStream in = new FileInputStream(siftFile);
             GZIPInputStream gzis = new GZIPInputStream(in);)
     {
-      System.out.println("File : " + siftFile.getAbsolutePath());
+      // System.out.println("File : " + siftFile.getAbsolutePath());
       JAXBContext jc = JAXBContext.newInstance("jalview.xml.binding.sifts");
       XMLStreamReader streamReader = XMLInputFactory.newInstance()
               .createXMLStreamReader(gzis);
       Unmarshaller um = jc.createUnmarshaller();
       return (Entry) um.unmarshal(streamReader);
-    } catch (JAXBException e)
-    {
-      e.printStackTrace();
-      throw new SiftsException(e.getMessage());
-    } catch (FileNotFoundException e)
-    {
-      e.printStackTrace();
-      throw new SiftsException(e.getMessage());
-    } catch (XMLStreamException e)
-    {
-      e.printStackTrace();
-      throw new SiftsException(e.getMessage());
-    } catch (FactoryConfigurationError e)
-    {
-      e.printStackTrace();
-      throw new SiftsException(e.getMessage());
-    } catch (IOException e)
+    } catch (Exception e)
     {
       e.printStackTrace();
       throw new SiftsException(e.getMessage());
@@ -219,30 +188,85 @@ public class SiftsClient implements SiftsClientI
    */
   public static File getSiftsFile(String pdbId) throws SiftsException
   {
-    File siftsFile = new File(SiftsSettings.getSiftDownloadDirectory()
-            + pdbId.toLowerCase()
-            + ".xml.gz");
+    String siftsFileName = SiftsSettings.getSiftDownloadDirectory()
+            + pdbId.toLowerCase() + ".xml.gz";
+    File siftsFile = new File(siftsFileName);
     if (siftsFile.exists())
     {
-      // TODO it may be worth performing an age check to determine if a
-      // new SIFTs file should be re-downloaded as SIFTs entries are usually
-      // updated weekly
+      // The line below is required for unit testing... don't comment it out!!!
       System.out.println(">>> SIFTS File already downloaded for " + pdbId);
-      return siftsFile;
+
+      if (isFileOlderThanThreshold(siftsFile,
+              SiftsSettings.getCacheThresholdInDays()))
+      {
+        File oldSiftsFile = new File(siftsFileName + "_old");
+        siftsFile.renameTo(oldSiftsFile);
+        try
+        {
+          siftsFile = downloadSiftsFile(pdbId.toLowerCase());
+          oldSiftsFile.delete();
+          return siftsFile;
+        } catch (IOException e)
+        {
+          e.printStackTrace();
+          oldSiftsFile.renameTo(siftsFile);
+          return new File(siftsFileName);
+        }
+      }
+    }
+    try
+    {
+      siftsFile = downloadSiftsFile(pdbId.toLowerCase());
+    } catch (IOException e)
+    {
+      throw new SiftsException(e.getMessage());
     }
-    siftsFile = downloadSiftsFile(pdbId.toLowerCase());
     return siftsFile;
   }
 
   /**
+   * This method enables checking if a cached file has exceeded a certain
+   * threshold(in days)
+   * 
+   * @param file
+   *          the cached file
+   * @param noOfDays
+   *          the threshold in days
+   * @return
+   */
+  public static boolean isFileOlderThanThreshold(File file, int noOfDays)
+  {
+    Path filePath = file.toPath();
+    BasicFileAttributes attr;
+    int diffInDays = 0;
+    try
+    {
+      attr = Files.readAttributes(filePath, BasicFileAttributes.class);
+      diffInDays = (int) ((new Date().getTime() - attr.lastModifiedTime()
+              .toMillis()) / (1000 * 60 * 60 * 24));
+      // System.out.println("Diff in days : " + diffInDays);
+    } catch (IOException e)
+    {
+      e.printStackTrace();
+    }
+    return noOfDays <= diffInDays;
+  }
+
+  /**
    * Download a SIFTs XML file for a given PDB Id from an FTP repository
    * 
    * @param pdbId
    * @return downloaded SIFTs XML file
    * @throws SiftsException
+   * @throws IOException
    */
-  public static File downloadSiftsFile(String pdbId) throws SiftsException
+  public static File downloadSiftsFile(String pdbId) throws SiftsException,
+          IOException
   {
+    if (pdbId.contains(".cif"))
+    {
+      pdbId = pdbId.replace(".cif", "");
+    }
     String siftFile = pdbId + ".xml.gz";
     String siftsFileFTPURL = SIFTS_FTP_BASE_URL + siftFile;
     String downloadedSiftsFile = SiftsSettings.getSiftDownloadDirectory()
@@ -253,9 +277,7 @@ public class SiftsClient implements SiftsClientI
     {
       siftsDownloadDir.mkdirs();
     }
-    try
-    {
-      System.out.println(">> Download ftp url : " + siftsFileFTPURL);
+      // System.out.println(">> Download ftp url : " + siftsFileFTPURL);
       URL url = new URL(siftsFileFTPURL);
       URLConnection conn = url.openConnection();
       InputStream inputStream = conn.getInputStream();
@@ -269,11 +291,7 @@ public class SiftsClient implements SiftsClientI
       }
       outputStream.close();
       inputStream.close();
-      System.out.println(">>> File downloaded : " + downloadedSiftsFile);
-    } catch (IOException ex)
-    {
-      throw new SiftsException(ex.getMessage());
-    }
+      // System.out.println(">>> File downloaded : " + downloadedSiftsFile);
     return new File(downloadedSiftsFile);
   }
 
@@ -287,8 +305,7 @@ public class SiftsClient implements SiftsClientI
   public static boolean deleteSiftsFileByPDBId(String pdbId)
   {
     File siftsFile = new File(SiftsSettings.getSiftDownloadDirectory()
-            + pdbId.toLowerCase()
-            + ".xml.gz");
+            + pdbId.toLowerCase() + ".xml.gz");
     if (siftsFile.exists())
     {
       return siftsFile.delete();
@@ -296,7 +313,6 @@ public class SiftsClient implements SiftsClientI
     return true;
   }
 
-
   /**
    * Get a valid SIFTs DBRef for the given sequence current SIFTs entry
    * 
@@ -320,7 +336,8 @@ public class SiftsClient implements SiftsClientI
       DBRefEntry[] dbRefs = seq.getDBRefs();
       if (dbRefs == null || dbRefs.length < 1)
       {
-        throw new SiftsException("Could not get source DB Ref");
+        throw new SiftsException(
+                "Source DBRef could not be determined. DBRefs might not have been retrieved.");
       }
 
       for (DBRefEntryI dbRef : dbRefs)
@@ -334,6 +351,7 @@ public class SiftsClient implements SiftsClientI
                 && (dbRef.getSource().equalsIgnoreCase(DBRefSource.UNIPROT) || dbRef
                         .getSource().equalsIgnoreCase(DBRefSource.PDB)))
         {
+          seq.setSourceDBRef(dbRef);
           return dbRef;
         }
       }
@@ -345,7 +363,6 @@ public class SiftsClient implements SiftsClientI
     throw new SiftsException("Could not get source DB Ref");
   }
 
-
   /**
    * Check that the DBRef Entry is properly populated and is available in this
    * SiftClient instance
@@ -354,7 +371,7 @@ public class SiftsClient implements SiftsClientI
    *          - DBRefEntry to validate
    * @return true validation is successful otherwise false is returned.
    */
-  private boolean isValidDBRefEntry(DBRefEntryI entry)
+  boolean isValidDBRefEntry(DBRefEntryI entry)
   {
     return entry != null && entry.getAccessionId() != null
             && isFoundInSiftsEntry(entry.getAccessionId());
@@ -374,7 +391,8 @@ public class SiftsClient implements SiftsClientI
                 .getMapRegion();
         for (MapRegion mapRegion : mapRegions)
         {
-          accessions.add(mapRegion.getDb().getDbAccessionId());
+          accessions
+                  .add(mapRegion.getDb().getDbAccessionId().toLowerCase());
         }
       }
     }
@@ -408,32 +426,26 @@ public class SiftsClient implements SiftsClientI
 
     String mappingOutput = mappingDetails.toString();
     StructureMapping siftsMapping = new StructureMapping(seq, pdbFile,
-            pdbId, chain, mapping,
-            mappingOutput);
+            pdbId, chain, mapping, mappingOutput);
     return siftsMapping;
   }
 
   @Override
-  public HashMap<Integer, int[]> getGreedyMapping(String entityId, SequenceI seq,
-          java.io.PrintStream os)
- throws SiftsException
+  public HashMap<Integer, int[]> getGreedyMapping(String entityId,
+          SequenceI seq, java.io.PrintStream os) throws SiftsException
   {
-    ArrayList<Integer> omitNonObserved = new ArrayList<Integer>();
+    List<Integer> omitNonObserved = new ArrayList<Integer>();
     int nonObservedShiftIndex = 0;
-    System.out.println("Generating mappings for : " + entityId);
+    // System.out.println("Generating mappings for : " + entityId);
     Entity entity = null;
     entity = getEntityById(entityId);
     String originalSeq = AlignSeq.extractGaps(
-            jalview.util.Comparison.GapChars,
-            seq.getSequenceAsString());
+            jalview.util.Comparison.GapChars, seq.getSequenceAsString());
     HashMap<Integer, int[]> mapping = new HashMap<Integer, int[]>();
     DBRefEntryI sourceDBRef = seq.getSourceDBRef();
-    if (sourceDBRef == null)
-    {
-      sourceDBRef = getValidSourceDBRef(seq);
-      // TODO ensure sequence start/end is in the same coordinate system and
-      // consistent with the choosen sourceDBRef
-    }
+    sourceDBRef = getValidSourceDBRef(seq);
+    // TODO ensure sequence start/end is in the same coordinate system and
+    // consistent with the choosen sourceDBRef
 
     // set sequence coordinate system - default value is UniProt
     if (sourceDBRef.getSource().equalsIgnoreCase(DBRefSource.PDB))
@@ -455,9 +467,9 @@ public class SiftsClient implements SiftsClientI
     List<Segment> segments = entity.getSegment();
     for (Segment segment : segments)
     {
-      segStartEnd = segment.getStart() + " - " + segment.getEnd();
-      System.out.println("Mappging segments : " + segment.getSegId() + "\\"
-              + segStartEnd);
+      // segStartEnd = segment.getStart() + " - " + segment.getEnd();
+      // System.out.println("Mapping segments : " + segment.getSegId() + "\\"
+      // + segStartEnd);
       List<Residue> residues = segment.getListResidue().getResidue();
       for (Residue residue : residues)
       {
@@ -477,7 +489,15 @@ public class SiftsClient implements SiftsClientI
             String resNumIndexString = cRefDb.getDbResNum()
                     .equalsIgnoreCase("None") ? String.valueOf(UNASSIGNED)
                     : cRefDb.getDbResNum();
-            currSeqIndex = Integer.valueOf(resNumIndexString);
+            try
+            {
+              currSeqIndex = Integer.valueOf(resNumIndexString);
+            } catch (NumberFormatException nfe)
+            {
+              currSeqIndex = Integer.valueOf(resNumIndexString
+                      .split("[a-zA-Z]")[0]);
+              continue;
+            }
             if (pdbRefDb != null)
             {
               break;// exit loop if pdb and uniprot are already found
@@ -488,25 +508,28 @@ public class SiftsClient implements SiftsClientI
         {
           continue;
         }
-        if (currSeqIndex > seq.getStart() && currSeqIndex <= seq.getEnd())
+        if (currSeqIndex >= seq.getStart() && currSeqIndex <= seq.getEnd())
         {
           int resNum;
           try
           {
             resNum = (pdbRefDb == null) ? Integer.valueOf(residue
-                  .getDbResNum()) : Integer.valueOf(pdbRefDb.getDbResNum());
+                    .getDbResNum()) : Integer.valueOf(pdbRefDb
+                    .getDbResNum());
           } catch (NumberFormatException nfe)
           {
             resNum = (pdbRefDb == null) ? Integer.valueOf(residue
                     .getDbResNum()) : Integer.valueOf(pdbRefDb
                     .getDbResNum().split("[a-zA-Z]")[0]);
+            continue;
           }
 
           if (isResidueObserved(residue)
                   || seqCoordSys == CoordinateSys.UNIPROT)
           {
             char resCharCode = ResidueProperties
-                    .getSingleCharacterCode(residue.getDbResName());
+                    .getSingleCharacterCode(ResidueProperties
+                            .getCanonicalAminoAcid(residue.getDbResName()));
             resNumMap.put(currSeqIndex, String.valueOf(resCharCode));
           }
           else
@@ -526,7 +549,10 @@ public class SiftsClient implements SiftsClientI
     {
       e.printStackTrace();
     }
-    padWithGaps(resNumMap, omitNonObserved);
+    if (seqCoordSys == CoordinateSys.UNIPROT)
+    {
+      padWithGaps(resNumMap, omitNonObserved);
+    }
     int seqStart = UNASSIGNED;
     int seqEnd = UNASSIGNED;
     int pdbStart = UNASSIGNED;
@@ -534,6 +560,10 @@ public class SiftsClient implements SiftsClientI
 
     Integer[] keys = mapping.keySet().toArray(new Integer[0]);
     Arrays.sort(keys);
+    if (keys.length < 1)
+    {
+      throw new SiftsException(">>> Empty SIFTS mapping generated!!");
+    }
     seqStart = keys[0];
     seqEnd = keys[keys.length - 1];
 
@@ -545,12 +575,17 @@ public class SiftsClient implements SiftsClientI
       int orignalSeqStart = seq.getStart();
       if (orignalSeqStart >= 1)
       {
-        int subSeqStart = seqStart - orignalSeqStart;
+        int subSeqStart = (seqStart >= orignalSeqStart) ? seqStart
+                - orignalSeqStart : 0;
         int subSeqEnd = seqEnd - (orignalSeqStart - 1);
         subSeqEnd = originalSeq.length() < subSeqEnd ? originalSeq.length()
                 : subSeqEnd;
         matchedSeq = originalSeq.substring(subSeqStart, subSeqEnd);
       }
+      else
+      {
+        matchedSeq = originalSeq.substring(1, originalSeq.length());
+      }
     }
 
     StringBuilder targetStrucSeqs = new StringBuilder();
@@ -562,23 +597,87 @@ public class SiftsClient implements SiftsClientI
     if (os != null)
     {
       MappingOutputPojo mop = new MappingOutputPojo();
-      mop.setSeqStart(seqStart);
-      mop.setSeqEnd(seqEnd);
+      mop.setSeqStart(pdbStart);
+      mop.setSeqEnd(pdbEnd);
       mop.setSeqName(seq.getName());
       mop.setSeqResidue(matchedSeq);
 
-      mop.setStrStart(pdbStart);
-      mop.setStrEnd(pdbEnd);
+      mop.setStrStart(seqStart);
+      mop.setStrEnd(seqEnd);
       mop.setStrName(structId);
       mop.setStrResidue(targetStrucSeqs.toString());
 
       mop.setType("pep");
       os.print(getMappingOutput(mop).toString());
+      os.println();
     }
     return mapping;
   }
 
   /**
+   * 
+   * @param chainId
+   *          Target chain to populate mapping of its atom positions.
+   * @param mapping
+   *          Two dimension array of residue index versus atom position
+   * @throws IllegalArgumentException
+   *           Thrown if chainId or mapping is null
+   * @throws SiftsException
+   */
+  void populateAtomPositions(String chainId, Map<Integer, int[]> mapping)
+          throws IllegalArgumentException, SiftsException
+  {
+    try
+    {
+      PDBChain chain = pdb.findChain(chainId);
+
+      if (chain == null || mapping == null)
+      {
+        throw new IllegalArgumentException(
+                "Chain id or mapping must not be null.");
+      }
+      for (int[] map : mapping.values())
+      {
+        if (map[PDB_RES_POS] != UNASSIGNED)
+        {
+          map[PDB_ATOM_POS] = getAtomIndex(map[PDB_RES_POS], chain.atoms);
+        }
+      }
+    } catch (NullPointerException e)
+    {
+      throw new SiftsException(e.getMessage());
+    } catch (Exception e)
+    {
+      throw new SiftsException(e.getMessage());
+    }
+  }
+
+  /**
+   * 
+   * @param residueIndex
+   *          The residue index used for the search
+   * @param atoms
+   *          A collection of Atom to search
+   * @return atom position for the given residue index
+   */
+  int getAtomIndex(int residueIndex, Collection<Atom> atoms)
+  {
+    if (atoms == null)
+    {
+      throw new IllegalArgumentException(
+              "atoms collection must not be null!");
+    }
+    for (Atom atom : atoms)
+    {
+      if (atom.resNumber == residueIndex)
+      {
+        return atom.atomIndex;
+      }
+    }
+    return UNASSIGNED;
+  }
+
+  /**
    * Checks if the residue instance is marked 'Not_observed' or not
    * 
    * @param residue
@@ -586,16 +685,18 @@ public class SiftsClient implements SiftsClientI
    */
   private boolean isResidueObserved(Residue residue)
   {
-    String annotation = getResidueAnnotaiton(residue,
+    Set<String> annotations = getResidueAnnotaitons(residue,
             ResidueDetailType.ANNOTATION);
-    if (annotation == null)
+    if (annotations == null || annotations.isEmpty())
     {
       return true;
     }
-    if (!annotation.equalsIgnoreCase(NOT_FOUND)
-            && annotation.equalsIgnoreCase(NOT_OBSERVED))
+    for (String annotation : annotations)
     {
-      return false;
+      if (annotation.equalsIgnoreCase(NOT_OBSERVED))
+      {
+        return false;
+      }
     }
     return true;
   }
@@ -607,18 +708,19 @@ public class SiftsClient implements SiftsClientI
    * @param type
    * @return
    */
-  private String getResidueAnnotaiton(Residue residue,
+  private Set<String> getResidueAnnotaitons(Residue residue,
           ResidueDetailType type)
   {
+    HashSet<String> foundAnnotations = new HashSet<String>();
     List<ResidueDetail> resDetails = residue.getResidueDetail();
     for (ResidueDetail resDetail : resDetails)
     {
       if (resDetail.getProperty().equalsIgnoreCase(type.getCode()))
       {
-        return resDetail.getContent();
+        foundAnnotations.add(resDetail.getContent());
       }
     }
-    return NOT_FOUND;
+    return foundAnnotations;
   }
 
   @Override
@@ -631,8 +733,9 @@ public class SiftsClient implements SiftsClientI
 
   private boolean isFoundInSiftsEntry(String accessionId)
   {
+    Set<String> siftsDBRefs = getAllMappingAccession();
     return accessionId != null
-            && getAllMappingAccession().contains(accessionId);
+            && siftsDBRefs.contains(accessionId.toLowerCase());
   }
 
   /**
@@ -640,8 +743,8 @@ public class SiftsClient implements SiftsClientI
    * 
    * @param resNumMap
    */
-  void padWithGaps(TreeMap<Integer, String> resNumMap,
-          ArrayList<Integer> omitNonObserved)
+  void padWithGaps(Map<Integer, String> resNumMap,
+          List<Integer> omitNonObserved)
   {
     if (resNumMap == null || resNumMap.isEmpty())
     {
@@ -651,8 +754,8 @@ public class SiftsClient implements SiftsClientI
     Arrays.sort(keys);
     int firstIndex = keys[0];
     int lastIndex = keys[keys.length - 1];
-    System.out.println("Min value " + firstIndex);
-    System.out.println("Max value " + lastIndex);
+    // System.out.println("Min value " + firstIndex);
+    // System.out.println("Max value " + lastIndex);
     for (int x = firstIndex; x <= lastIndex; x++)
     {
       if (!resNumMap.containsKey(x) && !omitNonObserved.contains(x))
@@ -663,87 +766,120 @@ public class SiftsClient implements SiftsClientI
   }
 
 
-  /**
-   * 
-   * @param chainId
-   *          Target chain to populate mapping of its atom positions.
-   * @param mapping
-   *          Two dimension array of residue index versus atom position
-   * @throws IllegalArgumentException
-   *           Thrown if chainId or mapping is null
-   */
-  void populateAtomPositions(String chainId, HashMap<Integer, int[]> mapping)
-          throws IllegalArgumentException
+
+  @Override
+  public Entity getEntityById(String id) throws SiftsException
   {
-    PDBChain chain = pdb.findChain(chainId);
-    if (chain == null || mapping == null)
+    // Sometimes SIFTS mappings are wrongly swapped between different chains of
+    // a PDB entry. This results to wrong mappings being generated. The boolean
+    // flag 'isGetEntityIdDirectly, determines whether an entity to process is
+    // determined by a greedy heuristic search or by just matching the Chain Id
+    // directly against the entity Id tag. Setting the default value to 'false'
+    // utilise the heuristic search which always produces correct mappings but
+    // less optimised processing, where as changing the value to 'true'
+    // optimises performance but might result to incorrect mapping in some cases
+    // where SIFTS mappings are wrongly swapped between different chains.
+    // boolean isGetEntityIdDirectly = false;
+    // if (isGetEntityIdDirectly)
+    // {
+    // List<Entity> entities = siftsEntry.getEntity();
+    // for (Entity entity : entities)
+    // {
+    // if (!entity.getEntityId().equalsIgnoreCase(id))
+    // {
+    // continue;
+    // }
+    // return entity;
+    // }
+    // }
+    Entity entity = getEntityByMostOptimalMatchedId(id);
+    if (entity != null)
     {
-      throw new IllegalArgumentException(
-              "Chain id or mapping must not be null.");
-    }
-    for (int[] map : mapping.values())
-    {
-      if (map[PDB_RES_POS] != UNASSIGNED)
-      {
-        map[PDB_ATOM_POS] = getAtomIndex(map[PDB_RES_POS], chain.atoms);
-      }
+      return entity;
     }
+    throw new SiftsException("Entity " + id + " not found");
   }
 
   /**
+   * This method was added because EntityId is NOT always equal to ChainId.
+   * Hence, it provides the logic to greedily detect the "true" Entity for a
+   * given chainId where discrepancies exist.
    * 
-   * @param residueIndex
-   *          The residue index used for the search
-   * @param atoms
-   *          A collection of Atom to search
-   * @return atom position for the given residue index
+   * @param chainId
+   * @return
    */
-  int getAtomIndex(int residueIndex, Collection<Atom> atoms)
+  public Entity getEntityByMostOptimalMatchedId(String chainId)
   {
-    if (atoms == null)
-    {
-      throw new IllegalArgumentException(
-              "atoms collection must not be null!");
-    }
-    for (Atom atom : atoms)
+    // System.out.println("---> advanced greedy entityId matching block entered..");
+    List<Entity> entities = siftsEntry.getEntity();
+    SiftsEntitySortPojo[] sPojo = new SiftsEntitySortPojo[entities.size()];
+    int count = 0;
+    for (Entity entity : entities)
     {
-      if (atom.resNumber == residueIndex)
+      sPojo[count] = new SiftsEntitySortPojo();
+      sPojo[count].entityId = entity.getEntityId();
+
+      List<Segment> segments = entity.getSegment();
+      for (Segment segment : segments)
       {
-        return atom.atomIndex;
+        List<Residue> residues = segment.getListResidue().getResidue();
+        for (Residue residue : residues)
+        {
+          List<CrossRefDb> cRefDbs = residue.getCrossRefDb();
+          for (CrossRefDb cRefDb : cRefDbs)
+          {
+            if (!cRefDb.getDbSource().equalsIgnoreCase("PDB"))
+            {
+              continue;
+            }
+            ++sPojo[count].resCount;
+            if (cRefDb.getDbChainId().equalsIgnoreCase(chainId))
+            {
+              ++sPojo[count].chainIdFreq;
+            }
+          }
+        }
       }
+      sPojo[count].pid = 100 * (sPojo[count].chainIdFreq / sPojo[count].resCount);
+      ++count;
     }
-    return UNASSIGNED;
-  }
+    Arrays.sort(sPojo, Collections.reverseOrder());
+    // System.out.println("highest matched entity : " + sPojo[0].entityId);
+    // System.out.println("highest matched pid : " + sPojo[0].pid);
 
-  @Override
-  public Entity getEntityById(String id) throws SiftsException
-  {
-    List<Entity> entities = siftsEntry.getEntity();
-    for (Entity entity : entities)
+    if (sPojo[0].entityId != null)
     {
-      if (!entity.getEntityId().equalsIgnoreCase(id))
+      for (Entity entity : entities)
       {
-        continue;
+        if (!entity.getEntityId().equalsIgnoreCase(sPojo[0].entityId))
+        {
+          continue;
+        }
+        return entity;
       }
-      return entity;
     }
-    throw new SiftsException("Entity " + id + " not found");
+    return null;
   }
 
-  @Override
-  public String[] getEntryDBs()
+  public class SiftsEntitySortPojo implements
+          Comparable<SiftsEntitySortPojo>
   {
-    System.out.println("\nListing DB entries...");
-    List<String> availDbs = new ArrayList<String>();
-    List<Db> dbs = siftsEntry.getListDB().getDb();
-    for (Db db : dbs)
+    public String entityId;
+
+    public int chainIdFreq;
+
+    public int pid;
+
+    public int resCount;
+
+    @Override
+    public int compareTo(SiftsEntitySortPojo o)
     {
-      availDbs.add(db.getDbSource());
-      System.out.println(db.getDbSource() + " | " + db.getDbCoordSys());
+      return this.pid - o.pid;
     }
-    return availDbs.toArray(new String[0]);
   }
 
+
   @Override
   public StringBuffer getMappingOutput(MappingOutputPojo mp)
           throws SiftsException
@@ -757,9 +893,9 @@ public class SiftsClient implements SiftsClientI
     String strName = mp.getStrName();
     int pdbStart = mp.getStrStart();
     int pdbEnd = mp.getStrEnd();
-    
+
     String type = mp.getType();
-    
+
     int maxid = (seqName.length() >= strName.length()) ? seqName.length()
             : strName.length();
     int len = 72 - maxid - 1;
@@ -769,7 +905,8 @@ public class SiftsClient implements SiftsClientI
     // output mappings
     StringBuffer output = new StringBuffer();
     output.append(NEWLINE);
-    output.append("Sequence ⟷ Structure mapping details").append(NEWLINE);
+    output.append("Sequence \u27f7 Structure mapping details").append(
+            NEWLINE);
     output.append("Method: SIFTS");
     output.append(NEWLINE).append(NEWLINE);
 
@@ -786,7 +923,7 @@ public class SiftsClient implements SiftsClientI
     output.append(" - ");
     output.append(String.valueOf(pdbEnd));
     output.append(NEWLINE).append(NEWLINE);
-    
+
     int matchedSeqCount = 0;
     for (int j = 0; j < nochunks; j++)
     {
@@ -810,32 +947,33 @@ public class SiftsClient implements SiftsClientI
       {
         try
         {
-        if ((i + (j * len)) < seqRes.length())
-        {
-          if (seqRes.charAt(i + (j * len)) == strRes.charAt(i + (j * len))
-                  && !jalview.util.Comparison.isGap(seqRes.charAt(i
-                          + (j * len))))
+          if ((i + (j * len)) < seqRes.length())
           {
+            if (seqRes.charAt(i + (j * len)) == strRes
+                    .charAt(i + (j * len))
+                    && !jalview.util.Comparison.isGap(seqRes.charAt(i
+                            + (j * len))))
+            {
               matchedSeqCount++;
-            output.append("|");
-          }
-          else if (type.equals("pep"))
-          {
-            if (ResidueProperties.getPAM250(seqRes.charAt(i + (j * len)),
-                    strRes.charAt(i + (j * len))) > 0)
+              output.append("|");
+            }
+            else if (type.equals("pep"))
             {
-              output.append(".");
+              if (ResidueProperties.getPAM250(seqRes.charAt(i + (j * len)),
+                      strRes.charAt(i + (j * len))) > 0)
+              {
+                output.append(".");
+              }
+              else
+              {
+                output.append(" ");
+              }
             }
             else
             {
               output.append(" ");
             }
           }
-          else
-          {
-            output.append(" ");
-          }
-        }
         } catch (IndexOutOfBoundsException e)
         {
           continue;
@@ -855,17 +993,16 @@ public class SiftsClient implements SiftsClientI
       output.append(NEWLINE).append(NEWLINE);
     }
     float pid = (float) matchedSeqCount / seqRes.length() * 100;
-    if (pid < 2)
+    if (pid < SiftsSettings.getFailSafePIDThreshold())
     {
-      throw new SiftsException("Low PID detected for SIFTs mapping...");
+      throw new SiftsException(">>> Low PID detected for SIFTs mapping...");
     }
-    output.append("Length of alignment = " + seqRes.length())
-            .append(NEWLINE);
+    output.append("Length of alignment = " + seqRes.length()).append(
+            NEWLINE);
     output.append(new Format("Percentage ID = %2.2f").form(pid));
-    output.append(NEWLINE);
     return output;
   }
-  
+
   @Override
   public int getEntityCount()
   {
@@ -885,12 +1022,6 @@ public class SiftsClient implements SiftsClientI
   }
 
   @Override
-  public String getDbEvidence()
-  {
-    return siftsEntry.getDbEvidence();
-  }
-
-  @Override
   public String getDbSource()
   {
     return siftsEntry.getDbSource();
@@ -901,4 +1032,5 @@ public class SiftsClient implements SiftsClientI
   {
     return siftsEntry.getDbVersion();
   }
+
 }