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 */
021package org.biojava.nbio.structure.align.multiple;
022
023import java.util.List;
024
025import javax.vecmath.Matrix4d;
026
027/**
028 * A BlockSet is a Data Structure to store a flexible alignment part of a
029 * multiple alignment. It is described by a collection of {@link Block}s and
030 * a transformation matrix for every structure.
031 * <p>
032 * It allows the description of non-topological and circularly permutated
033 * flexible parts, thus being as general as possible, thanks to the multiple
034 * {@link Block} format.
035 * <p>
036 * Every BlockSet has a unique transformation 4D matrix for every structure,
037 * which describes the 3D superimposition of the structures in this particular
038 * part of the alignment.
039 * <p>
040 * A collection of BlockSets, in a {@link MultipleAlignment}, allows the
041 * description of alignments with several flexible parts.
042 * Every BlockSet object is part of a {@link MultipleAlignment} instance,
043 * its parent.
044 *
045 * @author Aleix Lafita
046 * @author Spencer Bliven
047 * @since 4.1.0
048 *
049 */
050public interface BlockSet extends ScoresCache {
051
052        /**
053         * Creates and returns an identical copy of this blockset,
054         * including a deep copy of all constituent {@link Block}s.
055         *
056         * @return BlockSet identical copy of this object.
057         */
058        public BlockSet clone();
059
060        /**
061         * Returns the parent MultipleAlignment of the BlockSet.
062         * Returns null if there is no referenced object.
063         *
064         * @return MultipleAlignment the parent MultipleAlignment of the BlockSet,
065         * or null.
066         * @see #setMultipleAlignment(MultipleAlignment)
067         */
068        public MultipleAlignment getMultipleAlignment();
069
070        /**
071         * Set the back-reference to its parent MultipleAlignment.
072         * <p>
073         * Neither removes this BlockSet from its previous alignment, if any, nor
074         * adds it to the new parent. Calling code should assure that links to
075         * and from the ensemble are consistent and free of memory leaks.
076         *
077         * @param parent the parent MultipleAlignment.
078         * @see #getMultipleAlignment()
079         */
080        public void setMultipleAlignment(MultipleAlignment parent);
081
082        /**
083         * Returns the List of alignment Blocks of the BlockSet.
084         * It initializes a new List of Blocks if it is null.
085         * @return List of alignment Blocks.
086         *
087         * @see #setBlocks(List)
088         */
089        public List<Block> getBlocks();
090
091        /**
092         * Set the List of alignment Blocks of the BlockSet.
093         * <p>
094         * Also calls {@link Block#setBlockSet(BlockSet)} for each argument
095         *
096         * @param blocks List of alignment Blocks.
097         * @see #getBlocks()
098         */
099        public void setBlocks(List<Block> blocks);
100
101        /**
102         * Returns a transformation matrix for each structure giving the
103         * 3D superimposition information of the multiple structure alignment.
104         *
105         * @return the 3D superimposition information of the alignment
106         */
107        public List<Matrix4d> getTransformations();
108
109        /**
110         * Set a new superposition for the structures.
111         * This may trigger other properties to update which depend on the
112         * superposition.
113         *
114         * @param matrices
115         */
116        public void setTransformations(List<Matrix4d> transformations);
117
118        /**
119         * Returns the total number of aligned residues (columns) in the alignment:
120         * the sum of all Block lengths.
121         *
122         * @return int the total number of aligned residues.
123         * @see #getCoreLength()
124         * @see #size()
125         */
126        public int length();
127
128        /**
129         * Returns the number of aligned residues (columns) without gaps in the
130         * alignment: the sum of all Block core lengths.
131         *
132         * @return int the total number of aligned residues.
133         * @see #length()
134         * @see #size()
135         */
136        public int getCoreLength();
137
138        /**
139         * Returns the number of non null positions (residues) of each structure in
140         * the alignment Block Set. The values can be used to compute the coverages.
141         *
142         * @return List of residue counts for each structure
143         */
144        public List<Integer> getAlignResCounts();
145
146        /**
147         * Returns the number of aligned structures in the BlockSet.
148         *
149         * @return int number of aligned structures
150         * @see #length()
151         * @see #getCoreLength()
152         */
153        public int size();
154
155        /**
156         * Clear scores and other properties which depend on the specific
157         * alignment. This frees memory and ensures consistency of the cached
158         * variables.<p>
159         * Recursively clears the memeber Blocks.
160         */
161        public void clear();
162}