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 org.biojava.nbio.structure.Atom;
026import org.biojava.nbio.structure.StructureIdentifier;
027
028/**
029 * A MultipleAlignment is a Data Structure to store the core information of a
030 * multiple structure alignment, as a return type.
031 * <p>
032 * Each alignment is described as a collection of:
033 * <ul>
034 * <li>{@link BlockSet}s that define the aligned positions and 3D superposition,
035 * <li>Structure identifiers (i,e. Atom arrays, structure names),
036 * <li>Creation properties (algorithm, version, etc).
037 * </ul>
038 * A collection of MultipleAlignments that share the same structures and
039 * creation properties are part of the same {@link MultipleAlignmentEnsemble}.
040 * Every MultipleAlignment has a {@link MultipleAlignmentEnsemble} as its
041 * parent, which contains the shared meta-information.
042 *
043 * @author Aleix Lafita
044 * @author Spencer Bliven
045 * @since 4.1.0
046 *
047 */
048public interface MultipleAlignment extends ScoresCache {
049
050        /**
051         * Creates and returns an identical copy of this alignment, including a deep
052         * copy of all constituent BlockSets.
053         *
054         * @return MultipleAlignment identical copy of this object.
055         */
056        public MultipleAlignment clone();
057
058        /**
059         * Returns the parent Ensemble of the MultipleAlignment. Returns null if
060         * there is no referenced object.
061         *
062         * @return MultipleAlignmentEnsemble the parent MultipleAlignment of the
063         *         BlockSet, or null.
064         * @see #setEnsemble(MultipleAlignmentEnsemble)
065         */
066        public MultipleAlignmentEnsemble getEnsemble();
067
068        /**
069         * Set the back-reference to its parent Ensemble.
070         * <p>
071         * Neither removes this alignment from its previous ensemble, if any, nor
072         * adds it to the new parent. Calling code should assure that links to and
073         * from the ensemble are consistent and free of memory leaks.
074         *
075         * @param parent
076         *            the parent MultipleAlignmentEnsemble.
077         * @see #getEnsemble()
078         */
079        public void setEnsemble(MultipleAlignmentEnsemble parent);
080
081        /**
082         * Returns the BlockSet List of the multiple structure alignment.
083         * Initializes the variable if it is null.
084         *
085         * @return List of BlockSets that describe the aligned residues of all the
086         *         structures.
087         * @see #getBlocks()
088         * @see #setBlockSets(List)
089         */
090        public List<BlockSet> getBlockSets();
091
092        /**
093         * Returns the BlockSet with the specified index of the MultipleAlignment.
094         * Throws an Exception if the index is out of bounds, like accessing a
095         * normal List.
096         *
097         * @param index
098         *            of the BlockSet
099         * @return BlockSets at the specified index
100         * @see #getBlocks()
101         * @see #getBlockSets()
102         */
103        public BlockSet getBlockSet(int index);
104
105        /**
106         * Sets the List of BlockSet List of the specified alignment.
107         *
108         * @param blockSets
109         *            the List of BlockSets that describe the aligned residues.
110         * @see #getBlockSets()
111         */
112        public void setBlockSets(List<BlockSet> blockSets);
113
114        /**
115         * Convenience method to get a List of all Blocks from all BlockSets.
116         * Modifications of this List will not alter the MultipleAlignment, but
117         * modifications to the Blocks will.
118         *
119         * @return List of Blocks
120         * @see #getBlockSets()
121         */
122        public List<Block> getBlocks();
123
124        /**
125         * Returns the Block with the specified index of the MultipleAlignment.
126         * Throws an Exception if the index is out of bounds, like accessing a
127         * normal List.
128         *
129         * @param index
130         *            of the BlockSet
131         * @return Block at the specified index
132         * @see #getBlocks()
133         * @see #getBlockSets()
134         */
135        public Block getBlock(int index);
136
137        /**
138         * Returns the array of Atoms for each structure from its parent Ensemble.
139         * Throws an Exception if the parent ensemble is null or the Atom variables
140         * are not previously set.
141         *
142         * @return List of Atom arrays
143         * @see #getEnsemble()
144         */
145        public List<Atom[]> getAtomArrays();
146
147        /**
148         * Returns the StructureIdentifier associated with the structure index from
149         * its parent Ensemble. Throws an Exception if the parent ensemble is null
150         * or the StructureIdentifiers are not previously set.
151         *
152         * @return StructureIdentifier
153         * @see #getEnsemble()
154         */
155        public StructureIdentifier getStructureIdentifier(int index);
156
157        /**
158         * Returns the number of aligned structures in the MultipleAlignment.
159         *
160         * @return int number of aligned structures
161         * @see #length()
162         * @see #getCoreLength()
163         */
164        public int size();
165
166        /**
167         * Returns the total number of aligned residues (columns) in the multiple
168         * alignment: the sum of all BlockSet lengths.
169         *
170         * @return int the total number of aligned residues in the alignment.
171         * @see #getCoreLength()
172         * @see #size()
173         */
174        public int length();
175
176        /**
177         * Returns the number of aligned residues (columns) without gaps in the
178         * alignment: the sum of all BlockSet core lengths.
179         *
180         * @return int the total number of aligned residues.
181         * @see #length()
182         * @see #size()
183         */
184        public int getCoreLength();
185
186        /**
187         * Returns the number of non null positions (residues) of each structure in
188         * the alignment. The values can be used to compute the coverages.
189         *
190         * @return List of residue counts for each structure
191         */
192        public List<Integer> getAlignResCounts();
193
194        /**
195         * Returns the coverage of the alignment for each structure in the
196         * alignment as a fraction between 0.0 and 1.0.
197         *
198         * @return List coverage for each structure
199         */
200        public List<Double> getCoverages();
201
202        /**
203         * Clear scores and other properties which depend on the specific alignment.
204         * This frees memory and ensures consistency of the cached variables.
205         * <p>
206         * Recursively clears member BlockSets.
207         */
208        public void clear();
209
210        /**
211         * Return a summary of the MultipleAlignment, containing the structures, the
212         * lengths and the cached scores. Can be used as a header for the differnt
213         * display options.
214         *
215         * @return String header summary of the MultipleAlignment
216         */
217        @Override
218        public String toString();
219
220}