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;
027import org.biojava.nbio.structure.jama.Matrix;
028
029/**
030 * A MultipleAlignmentEnsemble is a collection of {@link MultipleAlignment}s
031 * that share the same structures (Atoms) and creation properties (algorithm,
032 * version, creation time, etc.).
033 * <p>
034 * This class is the top level of the hierarchy and allows the storage of a set
035 * of alignment alternatives created by a multiple structure alignment
036 * algorithm, so that only one object is returned with more than one alignment
037 * option.
038 *
039 * @author Aleix Lafita
040 * @author Spencer Bliven
041 * @since 4.1.0
042 *
043 */
044public interface MultipleAlignmentEnsemble extends ScoresCache {
045
046        /**
047         * Creates and returns an identical copy of this ensemble, including a deep
048         * clone of all constituent alignments.
049         *
050         * @return MultipleAlignmentEnsemble identical copy of this object.
051         */
052        public MultipleAlignmentEnsemble clone();
053
054        /**
055         * Returns the name of the multiple structure alignment algorithm that
056         * created the MultipleAlignment objects.
057         *
058         * @return String name of the algorithm.
059         * @see #setAlgorithmName(String)
060         */
061        public String getAlgorithmName();
062
063        /**
064         * Set the name of the multiple structure alignment algorithm that created
065         * the MultipleAlignment objects.
066         *
067         * @param algorithmName name of the algorithm.
068         * @see #getAlgorithmName()
069         */
070        public void setAlgorithmName(String algorithmName);
071
072        /**
073         * Returns the version of the algorithm used to generate the
074         * MultipleAlignment objects.
075         *
076         * @return String version of the algorithm.
077         * @see #setVersion(String)
078         */
079        public String getVersion();
080
081        /**
082         * Sets the version of the algorithm used to generate the MultipleAlignment
083         * objects.
084         *
085         * @param version the version of the algorithm.
086         * @see #getVersion()
087         */
088        public void setVersion(String version);
089
090        /**
091         * Returns a List containing the names of the structures aligned
092         * (i.e.: PDB code, SCOP domain, etc.).<p>
093         * The names are structure identifiers of the structures.
094         * They are in the same order as in the alignment Blocks (same index number
095         * for same structure).
096         *
097         * @return List of String names of the structures
098         * @see #setStructureIdentifiers(List)
099         * @see #getAtomArrays()
100         */
101        public List<StructureIdentifier> getStructureIdentifiers();
102
103        /**
104         * Set the List containing the names of the structures aligned
105         * (i.e.: PDB code, SCOP domain, etc.).<p>
106         * The names are structure identifiers of the structures.
107         *
108         * @param structureIdentifiers names of the structures, structure identifiers
109         * @see #getStructureIdentifiers()
110         * @see #setAtomArrays(List)
111         */
112        public void setStructureIdentifiers(List<StructureIdentifier> structureIdentifiers);
113
114        /**
115         * Get an array of representative atoms for each structure (CA atoms for
116         * proteins).<p>
117         * Atoms should be unrotated. Thus, to obtain a superimposed set of
118         * structures, each atom array should be cloned and then rotated according
119         * to the transformation matrix.<p>
120         * If atoms have not previously been set using
121         * {@link #setAtomArrays(List)}, attempts to load representative atoms
122         * based on {@link #getStructureIdentifiers()}.
123         * If it fails to load the Atoms it gives a NullPointerException before
124         * returning null.
125         *
126         * @return List of Atom[].
127         * @see #setAtomArrays(List)
128         */
129        public List<Atom[]> getAtomArrays();
130
131        /**
132         * Sets the List of Atom arrays. Every structure has an Atom array
133         * associated. Note that this should be called in conjunction with
134         * {@link #setStructureIdentifiers(List)}.<p>
135         * Setting the atom arrays to null will cause them to be automatically
136         * regenerated based on {@link #getStructureIdentifiers()} during the next call
137         * to {@link #getAtomArrays()}.
138         *
139         * @param atomArrays the List of representative (C-alpha) atom arrays
140         * @see #getAtomArrays()
141         * @see #setStructureIdentifiers(List)
142         */
143        public void setAtomArrays(List<Atom[]> atomArrays);
144
145        /**
146         * Returns the List containing the interatomic distance Matrix of each
147         * structure.
148         *
149         * @return List of Matrix interatomic distance matrices.
150         * @see #updateDistanceMatrix()
151         */
152        public List<Matrix> getDistanceMatrix();
153
154        /**
155         * Returns the List of MultipleAlignments in the ensemble.
156         *
157         * @return List of MultipleAlignment in the ensemble.
158         * @see #setMultipleAlignments()
159         */
160        public List<MultipleAlignment> getMultipleAlignments();
161
162        /**
163         * Returns the MultipleAlignments at the specified index
164         * in the ensemble. Throws an exception equivalently to
165         * accessing an index of a List
166         *
167         * @return MultipleAlignment at the index in the ensemble.
168         * @see #setMultipleAlignments()
169         */
170        public MultipleAlignment getMultipleAlignment(int index);
171
172        /**
173         * Set the List of MultipleAlignments in the ensemble.
174         *
175         * @param alignments List of MultipleAlignments that are part of the
176         * ensemble.
177         * @see #addMultipleAlignment(MultipleAlignment)
178         */
179        public void setMultipleAlignments(List<MultipleAlignment> alignments);
180
181        /**
182         * Add a new MultipleAlignment to the end of the ensemble and set its
183         * parent ensemble to this.
184         *
185         * @param alignment
186         */
187        public void addMultipleAlignment(MultipleAlignment alignment);
188
189        /**
190         * Returns the number of aligned structures in the MultipleAlignments.
191         *
192         * @return int number of aligned structures.
193         * @see #getStructureIdentifiers()
194         * @see #getAtomArrays()
195         */
196        public int size();
197
198        /**
199         * Returns the io time for this object, in milliseconds.
200         * @return long creation time, or null if unset
201         */
202        public Long getIoTime();
203
204        /**
205         * Set the IO time to load this object
206         * @param millis
207         */
208        public void setIoTime(Long millis);
209
210        /**
211         * Returns the running time of the structure alignment calculation, in
212         * milliseconds.
213         *
214         * @return long running time of the calculation, or null if unset
215         * @see #getIoTime()
216         */
217        public Long getCalculationTime();
218
219        /**
220         * Set the running time spent to calculate this alignment.
221         *
222         * @param millis
223         */
224        public void setCalculationTime(Long millis);
225
226        /**
227         * Clear scores and other properties which depend on the specific
228         * alignment. This frees memory and ensures consistency of the cached
229         * variables.<p>
230         * Recursively clears the member MultipleAlignments.
231         */
232        public void clear();
233}