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()
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 #updateCoreLength()
112         * @see #length()
113         * @see #size()
114         */
115        public int getCoreLength();
116
117        /**
118         * Returns the number of non null positions (residues) of each structure in
119         * the alignment Block. The values can be used to compute the coverages.
120         *
121         * @return List of residue counts for each structure
122         */
123        public List<Integer> getAlignResCounts();
124
125        /**
126         * Calculates and returns the first position of the specified structure in
127         * the alignment that is not null. This will return the aligment index, not
128         * the reisude aligned in that position.
129         *
130         * @param str
131         *            structure index
132         *
133         * @return the first non null aligned position of the structure
134         */
135        public int getStartIndex(int str);
136
137        /**
138         * Calculates and returns the first residue of the specified structure in
139         * the alignment that is not null. This will return the aligned residue, not
140         * the alignment index.
141         *
142         * @param str
143         *            structure index
144         *
145         * @return the first non null aligned residue of the structure
146         */
147        public int getStartResidue(int str);
148
149        /**
150         * Calculates and returns the last position of the specified structure in
151         * the alignment that is not null. This will return the aligment index, not
152         * the reisude aligned in that position.
153         *
154         * @param str
155         *            structure index
156         *
157         * @return the last non null aligned position of the structure
158         */
159        public int getFinalIndex(int str);
160
161        /**
162         * Calculates and returns the last residue of the specified structure in the
163         * alignment that is not null. This will return the aligned residue, not the
164         * alignment index.
165         *
166         * @param str
167         *            structure index
168         *
169         * @return the last non null aligned residue of the structure
170         */
171        public int getFinalResidue(int str);
172
173        /**
174         * Clear scores and other properties which depend on the specific alignment.
175         * This frees memory and ensures consistency of the cached variables.
176         */
177        public void clear();
178
179}