001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 * Created on 12.03.2004
021 * @author Andreas Prlic
022 *
023 */
024package org.biojava.nbio.structure;
025
026
027import org.biojava.nbio.structure.io.FileConvert;
028import org.biojava.nbio.structure.io.mmcif.ChemCompGroupFactory;
029import org.biojava.nbio.structure.io.mmcif.chem.PolymerType;
030import org.biojava.nbio.structure.io.mmcif.model.ChemComp;
031import org.biojava.nbio.core.exceptions.CompoundNotFoundException;
032import org.biojava.nbio.core.sequence.ProteinSequence;
033import org.biojava.nbio.core.sequence.compound.AminoAcidCompound;
034import org.biojava.nbio.core.sequence.template.Sequence;
035import org.slf4j.Logger;
036import org.slf4j.LoggerFactory;
037
038import java.util.*;
039
040
041/**
042 * A Chain in a PDB file. It contains several groups which can be of
043 * one of the types defined in the {@link GroupType} constants.
044 *
045 * @author Andreas Prlic
046 * @author Jules Jacobsen
047 * @since 1.4
048 */
049public class ChainImpl implements Chain {
050
051        private final static Logger logger = LoggerFactory.getLogger(ChainImpl.class);
052
053        private static final long serialVersionUID = 1990171805277911840L;
054
055        /**
056         * The default chain identifier used to be an empty space
057         */
058        private static final String DEFAULT_CHAIN_ID = "A";
059
060        private String swissprot_id ;
061        private String authId; // the 'public' chain identifier as assigned by authors in PDB files
062
063        private List <Group> groups;
064        private List<Group> seqResGroups;
065
066        private EntityInfo entity;
067        private Structure parent;
068
069        private Map<String, Integer> pdbResnumMap;
070        private String asymId; // the 'internal' chain identifier as used in mmCIF files
071
072
073        private List<SeqMisMatch> seqMisMatches = null;
074        /**
075         *  Constructs a ChainImpl object.
076         */
077        public ChainImpl() {
078                super();
079
080                authId = DEFAULT_CHAIN_ID;
081                groups = new ArrayList<>() ;
082
083                seqResGroups = new ArrayList<>();
084                pdbResnumMap = new HashMap<>();
085                asymId = null;
086
087        }
088
089        /** {@inheritDoc}
090         *
091         */
092        @Override
093        public String getId() {
094                return asymId;
095        }
096
097        /** {@inheritDoc}
098         *
099         */
100        @Override
101        public void setId(String asymId) {
102                this.asymId = asymId;
103        }
104
105        /** {@inheritDoc}
106         *
107         */
108        @Override
109        public String getName() { return authId; }
110
111        /** {@inheritDoc}
112         *
113         */
114        @Override
115        public void setName(String authId) { this.authId = authId; }
116
117        /** {@inheritDoc}
118         *
119         */
120        @Override
121        @Deprecated
122        public void setParent(Structure parent) {
123                setStructure(parent);
124        }
125
126        /** {@inheritDoc}
127         *
128         */
129        @Override
130        public void setStructure(Structure parent){
131                this.parent = parent;
132        }
133
134        /** Returns the parent Structure of this chain.
135         *
136         * @return the parent Structure object
137         */
138        @Override
139        public Structure getStructure() {
140
141                return parent;
142        }
143
144
145        /** Returns the parent Structure of this chain.
146         *
147         * @return the parent Structure object
148         * @deprecated  use getStructure instead.
149         */
150        @Override
151        @Deprecated
152        public Structure getParent() {
153
154                return getStructure();
155        }
156
157        /** Returns an identical copy of this Chain .
158         * @return an identical copy of this Chain
159         */
160        @Override
161        public Object clone() {
162                // go through all groups and add to new Chain.
163                ChainImpl n = new ChainImpl();
164                // copy chain data:
165
166                n.setId(getId());
167                n.setName(getName());
168                n.setSwissprotId ( getSwissprotId());
169
170                // NOTE the EntityInfo will be reset at the parent level (Structure) if cloning is happening from parent level
171                // here we don't deep-copy it and just keep the same reference, in case the cloning is happening at the Chain level only
172                n.setEntityInfo(this.entity);
173
174
175                for (Group group : groups) {
176                        Group g = (Group) group.clone();
177                        n.addGroup(g);
178                        g.setChain(n);
179                }
180
181                if (seqResGroups!=null){
182
183                        List<Group> tmpSeqRes = new ArrayList<>();
184
185                        // cloning seqres and atom groups is ugly, due to their
186                        // nested relationship (some of the atoms can be in the seqres, but not all)
187
188                        for (Group seqResGroup : seqResGroups) {
189
190                                if (seqResGroup==null) {
191                                        tmpSeqRes.add(null);
192                                        continue;
193                                }
194
195                                int i = groups.indexOf(seqResGroup);
196
197                                Group g ;
198
199                                if (i!=-1) {
200                                        // group found in atom groups, we get the equivalent reference from the newly cloned atom groups
201                                        g = n.getAtomGroup(i);
202                                } else {
203                                        // group not found in atom groups, we clone the seqres group
204                                        g = (Group) seqResGroup.clone();
205                                }
206                                g.setChain(n);
207                                tmpSeqRes.add(g);
208                        }
209
210                        n.setSeqResGroups(tmpSeqRes);
211                }
212
213                return n ;
214        }
215
216        /** {@inheritDoc}
217         *
218         */
219        @Override
220        public void setEntityInfo(EntityInfo mol) {
221                this.entity = mol;
222        }
223
224        /** {@inheritDoc}
225         *
226         */
227        @Override
228        public EntityInfo getEntityInfo() {
229                return this.entity;
230        }
231
232        /** set the Swissprot id of this chains .
233         * @param sp_id  a String specifying the swissprot id value
234         * @see #getSwissprotId
235         */
236        @Override
237        public void setSwissprotId(String sp_id){
238                swissprot_id = sp_id ;
239        }
240
241        /** get the Swissprot id of this chains .
242         * @return a String representing the swissprot id value
243         * @see #setSwissprotId
244         */
245        @Override
246        public String getSwissprotId() {
247                return swissprot_id ;
248        }
249
250        /** {@inheritDoc}
251         *
252         */
253        @Override
254        public void addGroup(Group group) {
255
256                group.setChain(this);
257
258                // Set the altlocs chain as well
259                for(Group g : group.getAltLocs()) {
260                        g.setChain(this);
261                }
262
263                groups.add(group);
264
265                // store the position internally for quick access of this group
266
267                String pdbResnum = null ;
268                ResidueNumber resNum = group.getResidueNumber();
269                if ( resNum != null)
270                        pdbResnum = resNum.toString();
271                if ( pdbResnum != null) {
272                        Integer pos = groups.size() - 1;
273                        // ARGH sometimes numbering in PDB files is confusing.
274                        // e.g. PDB: 1sfe
275                        /*
276                         * ATOM    620  N   GLY    93     -24.320  -6.591   4.210  1.00 46.82           N
277                         * ATOM    621  CA  GLY    93     -24.960  -6.849   5.497  1.00 47.35           C
278                         * ATOM    622  C   GLY    93     -26.076  -5.873   5.804  1.00 47.24           C
279                         * ATOM    623  O   GLY    93     -26.382  -4.986   5.006  1.00 47.56           O
280                         *    and ...
281                         * HETATM 1348  O   HOH    92     -21.853 -16.886  19.138  1.00 66.92           O
282                         * HETATM 1349  O   HOH    93     -26.126   1.226  29.069  1.00 71.69           O
283                         * HETATM 1350  O   HOH    94     -22.250 -18.060  -6.401  1.00 61.97           O
284                         */
285
286                        // this check is to give in this case the entry priority that is an AminoAcid / comes first...
287                        // a good example of same residue number for 2 residues is 3th3, chain T, residue 201 (a LYS and a sugar BGC covalently attached to it) - JD 2016-03-09
288                        if (  pdbResnumMap.containsKey(pdbResnum)) {
289
290                                logger.warn("Adding residue {}({}) to chain {} but a residue with same residue number is already present: {}({}). Will add only the aminoacid residue (if any) to the lookup, lookups for that residue number won't work properly.",
291                                                pdbResnum, group.getPDBName(), getChainID(), groups.get(pdbResnumMap.get(pdbResnum)).getResidueNumber(), groups.get(pdbResnumMap.get(pdbResnum)).getPDBName());
292                                if ( group instanceof AminoAcid)
293                                        pdbResnumMap.put(pdbResnum,pos);
294                        } else
295                                pdbResnumMap.put(pdbResnum,pos);
296                }
297
298        }
299
300
301        /**
302         * {@inheritDoc}
303         */
304        @Override
305        public Group getAtomGroup(int position) {
306
307                return groups.get(position);
308        }
309
310        /**
311         * {@inheritDoc}
312         */
313        @Override
314        public List<Group> getAtomGroups(GroupType type){
315
316                List<Group> tmp = new ArrayList<>() ;
317                for (Group g : groups) {
318                        if (g.getType().equals(type)) {
319                                tmp.add(g);
320                        }
321                }
322
323                return tmp ;
324        }
325
326
327        /** {@inheritDoc}
328         *
329         */
330        @Override
331        public List<Group> getAtomGroups(){
332                return groups ;
333        }
334
335        /** {@inheritDoc}
336         *
337         */
338        @Override
339        public void setAtomGroups(List<Group> groups){
340                for (Group g:groups){
341                        g.setChain(this);
342                }
343                this.groups = groups;
344        }
345
346        @Override
347        public Group[] getGroupsByPDB(ResidueNumber start, ResidueNumber end, boolean ignoreMissing)
348                        throws StructureException {
349                // Short-circut for include all groups
350                if(start == null && end == null) {
351                        return groups.toArray(new Group[groups.size()]);
352                }
353
354
355                List<Group> retlst = new ArrayList<>();
356
357                boolean adding, foundStart;
358                if( start == null ) {
359                        // start with first group
360                        adding = true;
361                        foundStart = true;
362                } else {
363                        adding = false;
364                        foundStart = false;
365                }
366
367
368                for (Group g: groups){
369
370                        // Check for start
371                        if (!adding && start.equalsPositional(g.getResidueNumber())) {
372                                adding = true;
373                                foundStart = true;
374                        }
375
376                        // Check if past start
377                        if ( ignoreMissing && ! (foundStart && adding) ) {
378                                ResidueNumber pos = g.getResidueNumber();
379
380                                if ( start != null && start.compareToPositional(pos) <= 0) {
381                                        foundStart = true;
382                                        adding = true;
383                                }
384                        }
385
386                        if ( adding)
387                                retlst.add(g);
388
389                        // check for end
390                        if ( end != null && end.equalsPositional(g.getResidueNumber())) {
391                                if ( ! adding)
392                                        throw new StructureException("did not find start PDB residue number " + start + " in chain " + authId);
393                                adding = false;
394                                break;
395                        }
396                        // check if past end
397                        if ( ignoreMissing && adding && end != null){
398
399                                ResidueNumber pos = g.getResidueNumber();
400                                if ( end.compareToPositional(pos) <= 0) {
401                                        adding = false;
402                                        break;
403                                }
404
405                        }
406                }
407
408                if ( ! foundStart){
409                        throw new StructureException("did not find start PDB residue number " + start + " in chain " + authId);
410                }
411                if ( end != null && adding && !ignoreMissing) {
412                        throw new StructureException("did not find end PDB residue number " + end + " in chain " + authId);
413                }
414
415
416                //not checking if the end has been found in this case...
417
418                return retlst.toArray(new Group[retlst.size()] );
419        }
420
421
422        /**
423         * {@inheritDoc}
424         *
425         */
426        @Override
427        public Group getGroupByPDB(ResidueNumber resNum) throws StructureException {
428                String pdbresnum = resNum.toString();
429                if ( pdbResnumMap.containsKey(pdbresnum)) {
430                        Integer pos = pdbResnumMap.get(pdbresnum);
431                        return groups.get(pos);
432                } else {
433                        throw new StructureException("unknown PDB residue number " + pdbresnum + " in chain " + authId);
434                }
435        }
436
437        /**
438         * {@inheritDoc}
439         *
440         */
441        @Override
442        public Group[] getGroupsByPDB(ResidueNumber start, ResidueNumber end)
443                        throws StructureException {
444                return getGroupsByPDB(start, end, false);
445        }
446
447
448
449        /**
450         * {@inheritDoc}
451         */
452        @Override
453        public int getSeqResLength() {
454                //new method returns the length of the sequence defined in the SEQRES records
455                return seqResGroups.size();
456        }
457
458        /**
459         * {@inheritDoc}
460         */
461        @Override
462        public void   setChainID(String asymId) { this.asymId = asymId;   }
463
464
465        /**
466         * {@inheritDoc}
467         */
468        @Override
469        public String getChainID()           {  return this.asymId;  }
470
471
472
473        /** String representation.
474         * @return String representation of the Chain
475         */
476        @Override
477        public String toString(){
478                String newline = System.getProperty("line.separator");
479                StringBuilder str = new StringBuilder();
480                str.append("Chain asymId:").append(getChainID()).append(" authId:").append(getName()).append(newline);
481                if ( entity != null ){
482                        if ( entity.getDescription() != null){
483                                str.append(entity.getDescription()).append(newline);
484                        }
485                }
486                str.append("total SEQRES length: ").append(getSeqResGroups().size()).append(" total ATOM length:")
487                .append(getAtomLength()).append(" residues ").append(newline);
488
489                return str.toString() ;
490
491        }
492
493        /**
494         * {@inheritDoc}
495         */
496        @Override
497        public Sequence<?> getBJSequence()  {
498
499                String seq = getSeqResSequence();
500
501                Sequence<AminoAcidCompound> s = null;
502
503                try {
504                        s = new ProteinSequence(seq);
505                } catch (CompoundNotFoundException e) {
506                        logger.error("Could not create sequence object from seqres sequence. Some unknown compound: {}",e.getMessage());
507                }
508
509                //TODO: return a DNA sequence if the content is DNA...
510                return s;
511
512        }
513
514        /**
515         * {@inheritDoc}
516         */
517        @Override
518        public String getAtomSequence(){
519
520
521                List<Group> groups = getAtomGroups();
522                StringBuilder sequence = new StringBuilder() ;
523
524                for ( Group g: groups){
525                        ChemComp cc = g.getChemComp();
526
527                        if ( PolymerType.PROTEIN_ONLY.contains(cc.getPolymerType()) ||
528                                        PolymerType.POLYNUCLEOTIDE_ONLY.contains(cc.getPolymerType())){
529                                // an amino acid residue.. use for alignment
530                                String oneLetter= ChemCompGroupFactory.getOneLetterCode(cc);
531                                if ( oneLetter == null)
532                                        oneLetter = Character.toString(StructureTools.UNKNOWN_GROUP_LABEL);
533                                sequence.append(oneLetter);
534                        }
535
536                }
537                return sequence.toString();
538
539
540        }
541
542        /**
543         * {@inheritDoc}
544         */
545        @Override
546        public String getSeqResSequence(){
547
548                StringBuilder str = new StringBuilder();
549                for (Group g : seqResGroups) {
550                        ChemComp cc = g.getChemComp();
551                        if ( cc == null) {
552                                logger.warn("Could not load ChemComp for group: ", g);
553                                str.append(StructureTools.UNKNOWN_GROUP_LABEL);
554                        } else if ( PolymerType.PROTEIN_ONLY.contains(cc.getPolymerType()) ||
555                                        PolymerType.POLYNUCLEOTIDE_ONLY.contains(cc.getPolymerType())){
556                                // an amino acid residue.. use for alignment
557                                String oneLetter= ChemCompGroupFactory.getOneLetterCode(cc);
558                                // AB oneLetter.length() should be one. e.g. in 1EMA it is 3 and this makes mapping residue to sequence impossible.
559                                if ( oneLetter == null || oneLetter.isEmpty() || oneLetter.equals("?")) {
560                                        oneLetter = Character.toString(StructureTools.UNKNOWN_GROUP_LABEL);
561                                }
562                                str.append(oneLetter);
563                        } else {
564                                str.append(StructureTools.UNKNOWN_GROUP_LABEL);
565                        }
566                }
567                return str.toString();
568        }
569
570        /**
571         * Get the one letter sequence so that Sequence is guaranteed to
572         * be the same length as seqResGroups.
573         * Method related to https://github.com/biojava/biojava/issues/457
574         * @return a string of the sequence guaranteed to be the same length
575         * as seqResGroups.
576         */
577        public String getSeqResOneLetterSeq(){
578
579                StringBuilder str = new StringBuilder();
580                for (Group g : seqResGroups) {
581                        ChemComp cc = g.getChemComp();
582                        if ( cc == null) {
583                                logger.warn("Could not load ChemComp for group: ", g);
584                                str.append(StructureTools.UNKNOWN_GROUP_LABEL);
585                        } else if ( PolymerType.PROTEIN_ONLY.contains(cc.getPolymerType()) ||
586                                        PolymerType.POLYNUCLEOTIDE_ONLY.contains(cc.getPolymerType())){
587                                // an amino acid residue.. use for alignment
588                                String oneLetter= ChemCompGroupFactory.getOneLetterCode(cc);
589                                // AB oneLetter.length() should be one. e.g. in 1EMA it is 3 and this makes mapping residue to sequence impossible.
590                                if ( oneLetter == null || oneLetter.isEmpty() || oneLetter.equals("?") || oneLetter.length()!=1) {
591                                        oneLetter = Character.toString(StructureTools.UNKNOWN_GROUP_LABEL);
592                                }
593                                str.append(oneLetter);
594                        } else {
595                                str.append(StructureTools.UNKNOWN_GROUP_LABEL);
596                        }
597                }
598                return str.toString();
599        }
600
601
602        /**
603         * {@inheritDoc}
604         */
605        @Override
606        public Group getSeqResGroup(int position) {
607
608                return seqResGroups.get(position);
609        }
610
611        /**
612         * {@inheritDoc}
613         */
614        @Override
615        public List<Group> getSeqResGroups(GroupType type) {
616                List<Group> tmp = new ArrayList<>() ;
617                for (Group g : seqResGroups) {
618                        if (g.getType().equals(type)) {
619                                tmp.add(g);
620                        }
621                }
622
623                return tmp ;
624        }
625
626        /** {@inheritDoc}
627         *
628         */
629        @Override
630        public List<Group> getSeqResGroups() {
631                return seqResGroups;
632        }
633
634        /** {@inheritDoc}
635         *
636         */
637        @Override
638        public void setSeqResGroups(List<Group> groups){
639                for (Group g: groups){
640                        if (g != null) {
641                                g.setChain(this);
642                        }
643                }
644                this.seqResGroups = groups;
645        }
646
647
648        /** {@inheritDoc}
649         *
650         */
651        @Override
652        public int getAtomLength() {
653
654                return groups.size();
655        }
656
657        /** {@inheritDoc}
658         *
659         */
660        @Override
661        public List<Group> getAtomLigands(){
662                List<Group> ligands = new ArrayList<>();
663
664                for (Group g : groups)
665                        if (!seqResGroups.contains(g) && !g.isWater())
666                                ligands.add(g);
667
668                return ligands;
669        }
670
671        @Override
672        public String getInternalChainID() {
673                return asymId;
674        }
675
676        @Override
677        public void setInternalChainID(String internalChainID) {
678                this.asymId = internalChainID;
679
680        }
681
682        @Override
683        public String toPDB() {
684                return FileConvert.toPDB(this);
685        }
686
687        @Override
688        public String toMMCIF() {
689                return FileConvert.toMMCIF(this, true);
690        }
691
692        @Override
693        public void setSeqMisMatches(List<SeqMisMatch> seqMisMatches) {
694                this.seqMisMatches = seqMisMatches;
695        }
696
697        @Override
698        public List<SeqMisMatch> getSeqMisMatches() {
699                return seqMisMatches;
700        }
701
702        @Override
703        public EntityType getEntityType() {
704                if (getEntityInfo()==null) return null;
705                return getEntityInfo().getType();
706        }
707
708        @Override
709        public boolean isWaterOnly() {
710                for (Group g : getAtomGroups()) {
711                        if (!g.isWater())
712                                return false;
713                }
714                return true;
715        }
716
717        @Override
718        public boolean isPureNonPolymer() {
719                for (Group g : getAtomGroups()) {
720
721                        //ChemComp cc = g.getChemComp();
722
723                        if (    g.isPolymeric() &&
724                                        !g.isHetAtomInFile() ) {
725
726                                // important: the aminoacid or nucleotide residue can be in Atom records
727
728                                return false;
729                        }
730
731                }
732                return true;
733        }
734
735        @Override
736        public GroupType getPredominantGroupType(){
737
738                double ratioResiduesToTotal = StructureTools.RATIO_RESIDUES_TO_TOTAL;
739
740                int sizeAminos = getAtomGroups(GroupType.AMINOACID).size();
741                int sizeNucleotides = getAtomGroups(GroupType.NUCLEOTIDE).size();
742                List<Group> hetAtoms = getAtomGroups(GroupType.HETATM);
743                int sizeHetatoms = hetAtoms.size();
744                int sizeWaters = 0;
745                for (Group g : hetAtoms) {
746                        if (g.isWater())
747                                sizeWaters++;
748                }
749                int sizeHetatomsWithoutWater = sizeHetatoms - sizeWaters;
750
751                int fullSize = sizeAminos + sizeNucleotides + sizeHetatomsWithoutWater;
752
753                if ((double) sizeAminos / (double) fullSize > ratioResiduesToTotal)
754                        return GroupType.AMINOACID;
755
756                if ((double) sizeNucleotides / (double) fullSize > ratioResiduesToTotal)
757                        return GroupType.NUCLEOTIDE;
758
759                if ((double) (sizeHetatomsWithoutWater) / (double) fullSize > ratioResiduesToTotal)
760                        return GroupType.HETATM;
761
762                // finally if neither condition works, we try based on majority, but log
763                // it
764                GroupType max;
765                if (sizeNucleotides > sizeAminos) {
766                        if (sizeNucleotides > sizeHetatomsWithoutWater) {
767                                max = GroupType.NUCLEOTIDE;
768                        } else {
769                                max = GroupType.HETATM;
770                        }
771                } else {
772                        if (sizeAminos > sizeHetatomsWithoutWater) {
773                                max = GroupType.AMINOACID;
774                        } else {
775                                max = GroupType.HETATM;
776                        }
777                }
778                logger.debug(
779                                "Ratio of residues to total for chain with asym_id {} is below {}. Assuming it is a {} chain. "
780                                                + "Counts: # aa residues: {}, # nuc residues: {}, # non-water het residues: {}, # waters: {}, "
781                                                + "ratio aa/total: {}, ratio nuc/total: {}",
782                                getId(), ratioResiduesToTotal, max, sizeAminos,
783                                sizeNucleotides, sizeHetatomsWithoutWater, sizeWaters,
784                                (double) sizeAminos / (double) fullSize,
785                                (double) sizeNucleotides / (double) fullSize);
786
787                return max;
788        }
789
790        @Override
791        public  boolean isProtein() {
792                return getPredominantGroupType() == GroupType.AMINOACID;
793        }
794
795        @Override
796        public  boolean isNucleicAcid() {
797                return getPredominantGroupType() == GroupType.NUCLEOTIDE;
798        }
799
800
801}
802