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         */
151        public List<Matrix> getDistanceMatrix();
152
153        /**
154         * Returns the List of MultipleAlignments in the ensemble.
155         *
156         * @return List of MultipleAlignment in the ensemble.
157         */
158        public List<MultipleAlignment> getMultipleAlignments();
159
160        /**
161         * Returns the MultipleAlignments at the specified index
162         * in the ensemble. Throws an exception equivalently to
163         * accessing an index of a List
164         *
165         * @return MultipleAlignment at the index in the ensemble.
166         */
167        public MultipleAlignment getMultipleAlignment(int index);
168
169        /**
170         * Set the List of MultipleAlignments in the ensemble.
171         *
172         * @param alignments List of MultipleAlignments that are part of the
173         * ensemble.
174         * @see #addMultipleAlignment(MultipleAlignment)
175         */
176        public void setMultipleAlignments(List<MultipleAlignment> alignments);
177
178        /**
179         * Add a new MultipleAlignment to the end of the ensemble and set its
180         * parent ensemble to this.
181         *
182         * @param alignment
183         */
184        public void addMultipleAlignment(MultipleAlignment alignment);
185
186        /**
187         * Returns the number of aligned structures in the MultipleAlignments.
188         *
189         * @return int number of aligned structures.
190         * @see #getStructureIdentifiers()
191         * @see #getAtomArrays()
192         */
193        public int size();
194
195        /**
196         * Returns the io time for this object, in milliseconds.
197         * @return long creation time, or null if unset
198         */
199        public Long getIoTime();
200
201        /**
202         * Set the IO time to load this object
203         * @param millis
204         */
205        public void setIoTime(Long millis);
206
207        /**
208         * Returns the running time of the structure alignment calculation, in
209         * milliseconds.
210         *
211         * @return long running time of the calculation, or null if unset
212         * @see #getIoTime()
213         */
214        public Long getCalculationTime();
215
216        /**
217         * Set the running time spent to calculate this alignment.
218         *
219         * @param millis
220         */
221        public void setCalculationTime(Long millis);
222
223        /**
224         * Clear scores and other properties which depend on the specific
225         * alignment. This frees memory and ensures consistency of the cached
226         * variables.<p>
227         * Recursively clears the member MultipleAlignments.
228         */
229        public void clear();
230}