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}