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}