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 */
021
022package org.biojava.bio.search;
023
024import java.util.Comparator;
025
026import org.biojava.bio.Annotatable;
027import org.biojava.bio.alignment.Alignment;
028import org.biojava.bio.seq.StrandedFeature.Strand;
029
030/**
031 * Objects of this type represent one particular sub-hit (one concrete
032 * sequence stretch within a sequence and associated information) from
033 * a sequence similarity search hit.
034 *
035 * @author Gerald Loeffler
036 * @author Keith James
037 */
038public interface SeqSimilaritySearchSubHit extends Annotatable
039{
040    /**
041     * This object is used as the label for the query sequence in the
042     * alignment of the query sequence with this sub-hit sequence.
043     */
044    public static final String QUERY_LABEL = "Query";
045  
046    /**
047     * Return the score of this sub-hit in the units defined by the
048     * search algorithm.
049     *
050     * @return the score of this sub-hit. This is a mandatory piece of
051     * information and hence may not be NaN.
052     */
053    public double getScore();
054
055    /**
056     * Return the P-value of this sub-hit.
057     *
058     * @return the P-value of this sub-hit. This is an optional (but
059     * desired) piece of information and implementations of this
060     * interface may return NaN if a P-value is not available for this
061     * hit.
062     */
063    public double getPValue();
064  
065    /**
066     * Return the E-value of this sub-hit.
067     *
068     * @return the E-value of this sub-hit. This is an optional (but
069     * desired) piece of information and implementations of this
070     * interface may return NaN if an E-value is not available for
071     * this hit.
072     */
073    public double getEValue();
074  
075    /**
076     * Return the start position of the sub-hit in the query sequence.
077     *
078     * @return an <code>int</code>.
079     */
080    public int getQueryStart();
081
082    /**
083     * Return the end position of the sub-hit in the query sequence.
084     *
085     * @return an <code>int</code>.
086     */
087    public int getQueryEnd();
088
089    /**
090     * Return the strand of the sub-hit with respect to the query
091     * sequence. This may be null for protein sequences.
092     *
093     * @return a <code>Strand</code>.
094     */
095    public Strand getQueryStrand();
096
097    /**
098     * Return the start position of the sub-hit in the subject
099     * sequence.
100     *
101     * @return an <code>int</code>.
102     */
103    public int getSubjectStart();
104
105    /**
106     * Return the start position of the sub-hit in the subject
107     * sequence.
108     *
109     * @return an <code>int</code>.
110     */
111    public int getSubjectEnd();
112
113    /**
114     * Return the strand of the sub-hit with respect to the subject
115     * sequence. This may be null for protein sequences.
116     *
117     * @return a <code>Strand</code>.
118     */
119    public Strand getSubjectStrand();
120
121    /**
122     * Return an alignment of (possibly part of) the query sequence
123     * against (possibly part of) this hit sequence. In this
124     * alignment, the query is identified by the label given by the
125     * static field QUERY_LABEL.
126     *
127     * @return the alignment of the query sequence against this hit
128     * sequence.
129     */
130    public Alignment getAlignment();
131
132    /**
133     * <code>byScore</code> contains a
134     * <code>SeqSimilaritySearchSubHit</code> comparator which
135     * compares by the score of the sub-hit.
136     */
137    public static final ByScoreComparator byScore = new ByScoreComparator();
138
139    /**
140     * <code>bySubjectStart</code> contains a
141     * <code>SeqSimilaritySearchSubHit</code> comparator which
142     * compares by the start position of the sub-hit on the subject
143     * sequence.
144     */
145    public static final BySubjectStartComparator bySubjectStart
146        = new BySubjectStartComparator();
147
148    /**
149     * <code>ByScoreComparator</code> compares
150     * <code>SeqSimilaritySearchSubHit</code>s by their score.
151     */
152    public static final class ByScoreComparator implements Comparator
153    {
154        public int compare(Object o1, Object o2)
155        {
156            SeqSimilaritySearchSubHit h1 = (SeqSimilaritySearchSubHit) o1;
157            SeqSimilaritySearchSubHit h2 = (SeqSimilaritySearchSubHit) o2;
158
159            if (h1.getScore() > h2.getScore())
160                return 1;
161            else if (h1.getScore() < h2.getScore())
162                return -1;
163            else
164                return 0;
165        }
166    }
167
168    /**
169     * <code>BySubjectStartComparator</code> compares
170     * <code>SeqSimilaritySearchSubHit</code>s by their start position
171     * on the subject sequence.
172     */
173    public static final class BySubjectStartComparator implements Comparator
174    {
175        public int compare(Object o1, Object o2)
176        {
177            SeqSimilaritySearchSubHit h1 = (SeqSimilaritySearchSubHit) o1;
178            SeqSimilaritySearchSubHit h2 = (SeqSimilaritySearchSubHit) o2;
179
180            if (h1.getSubjectStart() > h2.getSubjectStart())
181                return 1;
182            else if (h1.getSubjectStart() < h2.getSubjectStart())
183                return -1;
184            else
185                return 0;
186        }
187    }
188}