JAL-1926 JAL-2106 source DB refs come from SequenceI.getPrimaryDBRefs()
[jalview.git] / src / jalview / ws / sifts / SiftsClient.java
index 7d5ae2e..e08b8cb 100644 (file)
@@ -26,8 +26,10 @@ 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.DBRefUtils;
 import jalview.util.Format;
 import jalview.xml.binding.sifts.Entry;
 import jalview.xml.binding.sifts.Entry.Entity;
@@ -36,11 +38,9 @@ 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;
@@ -58,33 +58,29 @@ 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 CoordinateSys seqCoordSys = CoordinateSys.UNIPROT;
 
   private static final int BUFFER_SIZE = 4096;
@@ -95,21 +91,17 @@ 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();
 
-  private final static int THRESHOLD_IN_DAYS = 2;
-
   private String curSourceDBRef;
 
   private HashSet<String> curDBRefAccessionIdsString;
 
-  public enum CoordinateSys
+  private enum CoordinateSys
   {
     UNIPROT("UniProt"), PDB("PDBresnum"), PDBe("PDBe");
     private String name;
@@ -125,7 +117,7 @@ public class SiftsClient implements SiftsClientI
     }
   };
 
-  public enum ResidueDetailType
+  private enum ResidueDetailType
   {
     NAME_SEC_STRUCTURE("nameSecondaryStructure"), CODE_SEC_STRUCTURE(
             "codeSecondaryStructure"), ANNOTATION("Annotation");
@@ -149,29 +141,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
@@ -193,23 +170,7 @@ public class SiftsClient implements SiftsClientI
               .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());
@@ -226,21 +187,39 @@ 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())
     {
       // The line below is required for unit testing... don't comment it out!!!
       System.out.println(">>> SIFTS File already downloaded for " + pdbId);
 
-      if (isFileOlderThanThreshold(siftsFile, THRESHOLD_IN_DAYS))
+      if (isFileOlderThanThreshold(siftsFile,
+              SiftsSettings.getCacheThresholdInDays()))
       {
-        // System.out.println("Downloaded file is out of date, hence re-downloading...");
-        siftsFile = downloadSiftsFile(pdbId.toLowerCase());
+        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);
+        }
       }
-      return siftsFile;
     }
-    siftsFile = downloadSiftsFile(pdbId.toLowerCase());
+    try
+    {
+      siftsFile = downloadSiftsFile(pdbId.toLowerCase());
+    } catch (IOException e)
+    {
+      throw new SiftsException(e.getMessage());
+    }
     return siftsFile;
   }
 
@@ -278,9 +257,15 @@ public class SiftsClient implements SiftsClientI
    * @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()
@@ -291,8 +276,6 @@ public class SiftsClient implements SiftsClientI
     {
       siftsDownloadDir.mkdirs();
     }
-    try
-    {
       // System.out.println(">> Download ftp url : " + siftsFileFTPURL);
       URL url = new URL(siftsFileFTPURL);
       URLConnection conn = url.openConnection();
@@ -308,10 +291,6 @@ public class SiftsClient implements SiftsClientI
       outputStream.close();
       inputStream.close();
       // System.out.println(">>> File downloaded : " + downloadedSiftsFile);
-    } catch (IOException ex)
-    {
-      throw new SiftsException(ex.getMessage());
-    }
     return new File(downloadedSiftsFile);
   }
 
@@ -345,39 +324,30 @@ public class SiftsClient implements SiftsClientI
   public DBRefEntryI getValidSourceDBRef(SequenceI seq)
           throws SiftsException
   {
-    DBRefEntryI sourceDBRef = null;
-    sourceDBRef = seq.getSourceDBRef();
-    if (sourceDBRef != null && isValidDBRefEntry(sourceDBRef))
+    List<DBRefEntry> dbRefs = seq.getPrimaryDBRefs();
+    if (dbRefs == null || dbRefs.size() < 1)
     {
-      return sourceDBRef;
+      throw new SiftsException(
+              "Source DBRef could not be determined. DBRefs might not have been retrieved.");
     }
-    else
+
+    for (DBRefEntry dbRef : dbRefs)
     {
-      DBRefEntry[] dbRefs = seq.getDBRefs();
-      if (dbRefs == null || dbRefs.length < 1)
+      if (dbRef == null || dbRef.getAccessionId() == null
+              || dbRef.getSource() == null)
       {
-        throw new SiftsException("Could not get source DB Ref");
+        continue;
       }
-
-      for (DBRefEntryI dbRef : dbRefs)
+      if (isValidDBRefEntry(dbRef)
+              && dbRef.isPrimary()
+              && (DBRefUtils.getCanonicalName(dbRef.getSource())
+                      .equalsIgnoreCase(DBRefSource.UNIPROT) || DBRefUtils
+                      .getCanonicalName(dbRef.getSource())
+                      .equalsIgnoreCase(DBRefSource.PDB)))
       {
-        if (dbRef == null || dbRef.getAccessionId() == null
-                || dbRef.getSource() == null)
-        {
-          continue;
-        }
-        if (isFoundInSiftsEntry(dbRef.getAccessionId())
-                && (dbRef.getSource().equalsIgnoreCase(DBRefSource.UNIPROT) || dbRef
-                        .getSource().equalsIgnoreCase(DBRefSource.PDB)))
-        {
-          return dbRef;
-        }
+        return dbRef;
       }
     }
-    if (sourceDBRef != null && isValidDBRefEntry(sourceDBRef))
-    {
-      return sourceDBRef;
-    }
     throw new SiftsException("Could not get source DB Ref");
   }
 
@@ -389,7 +359,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());
@@ -409,7 +379,8 @@ public class SiftsClient implements SiftsClientI
                 .getMapRegion();
         for (MapRegion mapRegion : mapRegions)
         {
-          accessions.add(mapRegion.getDb().getDbAccessionId());
+          accessions
+                  .add(mapRegion.getDb().getDbAccessionId().toLowerCase());
         }
       }
     }
@@ -451,21 +422,18 @@ public class SiftsClient implements SiftsClientI
   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());
     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
-    }
+    DBRefEntryI 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))
@@ -485,11 +453,92 @@ public class SiftsClient implements SiftsClientI
 
     TreeMap<Integer, String> resNumMap = new TreeMap<Integer, String>();
     List<Segment> segments = entity.getSegment();
+    SegmentHelperPojo shp = new SegmentHelperPojo(seq, mapping, resNumMap,
+            omitNonObserved, nonObservedShiftIndex);
+    processSegments(segments, shp);
+    try
+    {
+      populateAtomPositions(entityId, mapping);
+    } catch (Exception e)
+    {
+      e.printStackTrace();
+    }
+    if (seqCoordSys == CoordinateSys.UNIPROT)
+    {
+      padWithGaps(resNumMap, omitNonObserved);
+    }
+    int seqStart = UNASSIGNED;
+    int seqEnd = UNASSIGNED;
+    int pdbStart = UNASSIGNED;
+    int pdbEnd = UNASSIGNED;
+
+    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];
+
+    String matchedSeq = originalSeq;
+    if (seqStart != UNASSIGNED)
+    {
+      pdbStart = mapping.get(seqStart)[PDB_RES_POS];
+      pdbEnd = mapping.get(seqEnd)[PDB_RES_POS];
+      int orignalSeqStart = seq.getStart();
+      if (orignalSeqStart >= 1)
+      {
+        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();
+    for (String res : resNumMap.values())
+    {
+      targetStrucSeqs.append(res);
+    }
+
+    if (os != null)
+    {
+      MappingOutputPojo mop = new MappingOutputPojo();
+      mop.setSeqStart(pdbStart);
+      mop.setSeqEnd(pdbEnd);
+      mop.setSeqName(seq.getName());
+      mop.setSeqResidue(matchedSeq);
+
+      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;
+  }
+
+  void processSegments(List<Segment> segments, SegmentHelperPojo shp)
+  {
+    SequenceI seq = shp.getSeq();
+    HashMap<Integer, int[]> mapping = shp.getMapping();
+    TreeMap<Integer, String> resNumMap = shp.getResNumMap();
+    List<Integer> omitNonObserved = shp.getOmitNonObserved();
+    int nonObservedShiftIndex = shp.getNonObservedShiftIndex();
     for (Segment segment : segments)
     {
-      segStartEnd = segment.getStart() + " - " + segment.getEnd();
-      System.out.println("Mappging segments : " + segment.getSegId() + "\\"
-              + segStartEnd);
+      // System.out.println("Mapping segments : " + segment.getSegId() + "\\"s
+      // + segStartEnd);
       List<Residue> residues = segment.getListResidue().getResidue();
       for (Residue residue : residues)
       {
@@ -516,6 +565,7 @@ public class SiftsClient implements SiftsClientI
             {
               currSeqIndex = Integer.valueOf(resNumIndexString
                       .split("[a-zA-Z]")[0]);
+              continue;
             }
             if (pdbRefDb != null)
             {
@@ -527,7 +577,7 @@ public class SiftsClient implements SiftsClientI
         {
           continue;
         }
-        if (currSeqIndex > seq.getStart() && currSeqIndex <= seq.getEnd())
+        if (currSeqIndex >= seq.getStart() && currSeqIndex <= seq.getEnd())
         {
           int resNum;
           try
@@ -540,13 +590,15 @@ public class SiftsClient implements SiftsClientI
             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
@@ -559,66 +611,68 @@ 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
+   * @throws SiftsException
+   */
+  void populateAtomPositions(String chainId, Map<Integer, int[]> mapping)
+          throws IllegalArgumentException, SiftsException
+  {
     try
     {
-      populateAtomPositions(entityId, mapping);
-    } catch (Exception e)
-    {
-      e.printStackTrace();
-    }
-    if (seqCoordSys == CoordinateSys.UNIPROT)
-    {
-      padWithGaps(resNumMap, omitNonObserved);
-    }
-    int seqStart = UNASSIGNED;
-    int seqEnd = UNASSIGNED;
-    int pdbStart = UNASSIGNED;
-    int pdbEnd = UNASSIGNED;
-
-    Integer[] keys = mapping.keySet().toArray(new Integer[0]);
-    Arrays.sort(keys);
-    seqStart = keys[0];
-    seqEnd = keys[keys.length - 1];
+      PDBChain chain = pdb.findChain(chainId);
 
-    String matchedSeq = originalSeq;
-    if (seqStart != UNASSIGNED)
-    {
-      pdbStart = mapping.get(seqStart)[PDB_RES_POS];
-      pdbEnd = mapping.get(seqEnd)[PDB_RES_POS];
-      int orignalSeqStart = seq.getStart();
-      if (orignalSeqStart >= 1)
+      if (chain == null || mapping == null)
       {
-        int subSeqStart = seqStart - orignalSeqStart;
-        int subSeqEnd = seqEnd - (orignalSeqStart - 1);
-        subSeqEnd = originalSeq.length() < subSeqEnd ? originalSeq.length()
-                : subSeqEnd;
-        matchedSeq = originalSeq.substring(subSeqStart, subSeqEnd);
+        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());
     }
+  }
 
-    StringBuilder targetStrucSeqs = new StringBuilder();
-    for (String res : resNumMap.values())
+  /**
+   * 
+   * @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)
     {
-      targetStrucSeqs.append(res);
+      throw new IllegalArgumentException(
+              "atoms collection must not be null!");
     }
-
-    if (os != null)
+    for (Atom atom : atoms)
     {
-      MappingOutputPojo mop = new MappingOutputPojo();
-      mop.setSeqStart(seqStart);
-      mop.setSeqEnd(seqEnd);
-      mop.setSeqName(seq.getName());
-      mop.setSeqResidue(matchedSeq);
-
-      mop.setStrStart(pdbStart);
-      mop.setStrEnd(pdbEnd);
-      mop.setStrName(structId);
-      mop.setStrResidue(targetStrucSeqs.toString());
-
-      mop.setType("pep");
-      os.print(getMappingOutput(mop).toString());
+      if (atom.resNumber == residueIndex)
+      {
+        return atom.atomIndex;
+      }
     }
-    return mapping;
+    return UNASSIGNED;
   }
 
   /**
@@ -629,16 +683,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;
   }
@@ -650,18 +706,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
@@ -674,8 +731,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());
   }
 
   /**
@@ -683,19 +741,19 @@ 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())
     {
       return;
     }
     Integer[] keys = resNumMap.keySet().toArray(new Integer[0]);
-    Arrays.sort(keys);
+    // 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))
@@ -705,70 +763,13 @@ 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
-  {
-    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);
-      }
-    }
-  }
 
-  /**
-   * 
-   * @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;
-  }
 
   @Override
   public Entity getEntityById(String id) throws SiftsException
   {
-    List<Entity> entities = siftsEntry.getEntity();
-    for (Entity entity : entities)
-    {
-      if (!entity.getEntityId().equalsIgnoreCase(id))
-      {
-        continue;
-      }
-      return entity;
-    }
+    // Determines an entity to process by performing a heuristic matching of all
+    // Entities with the given chainId and choosing the best matching Entity
     Entity entity = getEntityByMostOptimalMatchedId(id);
     if (entity != null)
     {
@@ -787,8 +788,7 @@ public class SiftsClient implements SiftsClientI
    */
   public Entity getEntityByMostOptimalMatchedId(String chainId)
   {
-    System.out
-            .println("--------------> advanced greedy entityId matching block entered..");
+    // System.out.println("---> advanced greedy entityId matching block entered..");
     List<Entity> entities = siftsEntry.getEntity();
     SiftsEntitySortPojo[] sPojo = new SiftsEntitySortPojo[entities.size()];
     int count = 0;
@@ -818,12 +818,13 @@ public class SiftsClient implements SiftsClientI
           }
         }
       }
-      sPojo[count].pid = 100 * (sPojo[count].chainIdFreq / sPojo[count].resCount);
+      sPojo[count].pid = (100 * sPojo[count].chainIdFreq)
+              / sPojo[count].resCount;
       ++count;
     }
     Arrays.sort(sPojo, Collections.reverseOrder());
-    System.out.println("highest matched entity : " + sPojo[0].entityId);
-    System.out.println("highest matched pid : " + sPojo[0].pid);
+    // System.out.println("highest matched entity : " + sPojo[0].entityId);
+    // System.out.println("highest matched pid : " + sPojo[0].pid);
 
     if (sPojo[0].entityId != null)
     {
@@ -839,7 +840,7 @@ public class SiftsClient implements SiftsClientI
     return null;
   }
 
-  public class SiftsEntitySortPojo implements
+  private class SiftsEntitySortPojo implements
           Comparable<SiftsEntitySortPojo>
   {
     public String entityId;
@@ -857,18 +858,79 @@ public class SiftsClient implements SiftsClientI
     }
   }
 
-  @Override
-  public String[] getEntryDBs()
+  private class SegmentHelperPojo
   {
-    System.out.println("\nListing DB entries...");
-    List<String> availDbs = new ArrayList<String>();
-    List<Db> dbs = siftsEntry.getListDB().getDb();
-    for (Db db : dbs)
+    private SequenceI seq;
+
+    private HashMap<Integer, int[]> mapping;
+
+    private TreeMap<Integer, String> resNumMap;
+
+    private List<Integer> omitNonObserved;
+
+    private int nonObservedShiftIndex;
+
+    public SegmentHelperPojo(SequenceI seq,
+            HashMap<Integer, int[]> mapping,
+            TreeMap<Integer, String> resNumMap,
+            List<Integer> omitNonObserved, int nonObservedShiftIndex)
+    {
+      setSeq(seq);
+      setMapping(mapping);
+      setResNumMap(resNumMap);
+      setOmitNonObserved(omitNonObserved);
+      setNonObservedShiftIndex(nonObservedShiftIndex);
+    }
+
+    public SequenceI getSeq()
+    {
+      return seq;
+    }
+
+    public void setSeq(SequenceI seq)
+    {
+      this.seq = seq;
+    }
+
+    public HashMap<Integer, int[]> getMapping()
+    {
+      return mapping;
+    }
+
+    public void setMapping(HashMap<Integer, int[]> mapping)
+    {
+      this.mapping = mapping;
+    }
+
+    public TreeMap<Integer, String> getResNumMap()
+    {
+      return resNumMap;
+    }
+
+    public void setResNumMap(TreeMap<Integer, String> resNumMap)
     {
-      availDbs.add(db.getDbSource());
-      System.out.println(db.getDbSource() + " | " + db.getDbCoordSys());
+      this.resNumMap = resNumMap;
+    }
+
+    public List<Integer> getOmitNonObserved()
+    {
+      return omitNonObserved;
+    }
+
+    public void setOmitNonObserved(List<Integer> omitNonObserved)
+    {
+      this.omitNonObserved = omitNonObserved;
+    }
+
+    public int getNonObservedShiftIndex()
+    {
+      return nonObservedShiftIndex;
+    }
+
+    public void setNonObservedShiftIndex(int nonObservedShiftIndex)
+    {
+      this.nonObservedShiftIndex = nonObservedShiftIndex;
     }
-    return availDbs.toArray(new String[0]);
   }
 
   @Override
@@ -896,7 +958,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);
 
@@ -983,14 +1046,13 @@ 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(new Format("Percentage ID = %2.2f").form(pid));
-    output.append(NEWLINE);
     return output;
   }
 
@@ -1013,12 +1075,6 @@ public class SiftsClient implements SiftsClientI
   }
 
   @Override
-  public String getDbEvidence()
-  {
-    return siftsEntry.getDbEvidence();
-  }
-
-  @Override
   public String getDbSource()
   {
     return siftsEntry.getDbSource();