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 * Created on June 7, 2010
021 * Author: Mark Chapman
022 */
023
024package org.biojava.nbio.alignment.template;
025
026import org.biojava.nbio.core.alignment.template.ProfilePair;
027import org.biojava.nbio.core.alignment.template.Profile;
028import org.biojava.nbio.core.sequence.template.Compound;
029import org.biojava.nbio.core.sequence.template.Sequence;
030
031import javax.swing.tree.TreeNode;
032import java.util.concurrent.Future;
033
034/**
035 * Defines a data structure for the node in a guide tree used during progressive multiple sequence alignment.
036 *
037 * @author Mark Chapman
038 * @param <S> each {@link Sequence} in the tree is of type S
039 * @param <C> each element of a {@link Sequence} is a {@link Compound} of type C
040 */
041public interface GuideTreeNode<S extends Sequence<C>, C extends Compound> extends TreeNode {
042
043        /**
044         * Returns the first child node of this node.  For leaf nodes (sequences), this will be null.
045         *
046         * @return the first child node of this node
047         */
048        GuideTreeNode<S, C> getChild1();
049
050        /**
051         * Returns the second child node of this node.  For leaf nodes (sequences), this will be null.
052         *
053         * @return the second child node of this node
054         */
055        GuideTreeNode<S, C> getChild2();
056
057        /**
058         * Returns the difference in height of this node and it's parent node.  A likely meaning of this distance is half
059         * the percent difference between this node and it's sibling node.
060         *
061         * @return the difference in height of this node to it's parent node
062         */
063        double getDistanceToParent();
064
065        /**
066         * Returns the name of this node.  For leaf nodes (sequences), this will likely be the accession ID.
067         *
068         * @return the name of this node
069         */
070        String getName();
071
072        /**
073         * Returns the profile stored at this node.  If the node is a leaf, the profile is that of a single sequence.  If
074         * not, this returns null until {@link #setProfile(Profile)} has been called.
075         *
076         * @return the profile stored at this node
077         */
078        Profile<S, C> getProfile();
079
080        /**
081         * Returns the profile future stored at this node, but does not force the calculation, yet.  This allows alignment
082         * tasks for the entire tree to be queued in a post-order traversal before concurrent execution.
083         *
084         * @return the profile future stored at this node
085         */
086        Future<ProfilePair<S, C>> getProfileFuture();
087
088        /**
089         * Stores the given profile.
090         *
091         * @param profile new profile stored at this node
092         */
093        void setProfile(Profile<S, C> profile);
094
095        /**
096         * Stores the given profile future.  This allows concurrent execution of alignment tasks.
097         *
098         * @param profileFuture new profile to be calculated and then stored at this node
099         */
100        void setProfileFuture(Future<ProfilePair<S, C>> profileFuture);
101
102}