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
025/**
026 * A Block is a Data Structure that stores aligned positions of a
027 * {@link MultipleAlignment} with the condition that residues are in a
028 * sequential order.
029 * <p>
030 * A collection of Blocks, named {@link BlockSet}, allows the description of
031 * circular permutations (CP) and non-topological alignments.
032 * <p>
033 * Every Block object is part of a {@link BlockSet} instance, its parent, which
034 * has in turn a {@link MultipleAlignment} instance as parent.
035 *
036 * @author Aleix Lafita
037 * @author Spencer Bliven
038 * @since 4.1.0
039 *
040 */
041public interface Block extends ScoresCache {
042
043        /**
044         * Creates and returns an identical copy of this block.
045         *
046         * @return Block identical copy of this object.
047         */
048        public Block clone();
049
050        /**
051         * Set the back-reference to its parent BlockSet.
052         *
053         * @param parent
054         *            the parent BlockSet.
055         * @see #getBlockSet()
056         */
057        public void setBlockSet(BlockSet parent);
058
059        /**
060         * Returns the parent BlockSet of the Block. Returns null if there is no
061         * referenced object.
062         *
063         * @return BlockSet the parent BlockSet of the Block, or null.
064         * @see #setBlockSet(BlockSet)
065         */
066        public BlockSet getBlockSet();
067
068        /**
069         * Returns the double List containing the aligned residues for each
070         * structure.
071         * <p>
072         * alignRes.get(structure).get(residue) = alignRes.get(size).get(length).
073         *
074         * @return List a double List of aligned residues for each structure.
075         * @see #setAlignRes(List)
076         */
077        public List<List<Integer>> getAlignRes();
078
079        /**
080         * Set the double List containing the aligned residues for each structure.
081         *
082         * @param alignRes
083         *            a double List of Integers with the aligned residues.
084         * @see #getAlignRes()
085         */
086        public void setAlignRes(List<List<Integer>> alignRes);
087
088        /**
089         * Returns the total number of aligned positions (columns) in the Block.
090         *
091         * @return int number of aligned residues.
092         * @see #getCoreLength()
093         * @see #size()
094         */
095        public int length();
096
097        /**
098         * Returns the number of aligned structures (rows) in the Block.
099         *
100         * @return int number of aligned structures.
101         * @see #length()
102         * @see #getCoreLength()
103         */
104        public int size();
105
106        /**
107         * Returns the number of aligned positions (columns) without gaps in the
108         * Block.
109         *
110         * @return int number of aligned residues.
111         * @see #length()
112         * @see #size()
113         */
114        public int getCoreLength();
115
116        /**
117         * Returns the number of non null positions (residues) of each structure in
118         * the alignment Block. The values can be used to compute the coverages.
119         *
120         * @return List of residue counts for each structure
121         */
122        public List<Integer> getAlignResCounts();
123
124        /**
125         * Calculates and returns the first position of the specified structure in
126         * the alignment that is not null. This will return the alignment index, not
127         * the residue aligned in that position.
128         *
129         * @param str
130         *            structure index
131         *
132         * @return the first non null aligned position of the structure
133         */
134        public int getStartIndex(int str);
135
136        /**
137         * Calculates and returns the first residue of the specified structure in
138         * the alignment that is not null. This will return the aligned residue, not
139         * the alignment index.
140         *
141         * @param str
142         *            structure index
143         *
144         * @return the first non null aligned residue of the structure
145         */
146        public int getStartResidue(int str);
147
148        /**
149         * Calculates and returns the last position of the specified structure in
150         * the alignment that is not null. This will return the alignment index, not
151         * the residue aligned in that position.
152         *
153         * @param str
154         *            structure index
155         *
156         * @return the last non null aligned position of the structure
157         */
158        public int getFinalIndex(int str);
159
160        /**
161         * Calculates and returns the last residue of the specified structure in the
162         * alignment that is not null. This will return the aligned residue, not the
163         * alignment index.
164         *
165         * @param str
166         *            structure index
167         *
168         * @return the last non null aligned residue of the structure
169         */
170        public int getFinalResidue(int str);
171
172        /**
173         * Clear scores and other properties which depend on the specific alignment.
174         * This frees memory and ensures consistency of the cached variables.
175         */
176        public void clear();
177
178}