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;
025import java.util.List;
026
027import org.biojava.bio.Annotatable;
028import org.biojava.bio.seq.StrandedFeature.Strand;
029
030/**
031 * Objects of this type represent one particular hit (sequence and
032 * associated information) from a sequence similarity search.
033 *
034 * @author Gerald Loeffler
035 * @author Keith James
036 */
037public interface SeqSimilaritySearchHit extends Annotatable
038{
039    /**
040     * Return the overall score of this hit in the units defined by the
041     * search algorithm.
042     *
043     * @return the overall score of this hit. This is a mandatory piece
044     * of information and hence may not be NaN.
045     */
046    public double getScore();
047
048    /**
049     * Return the overall P-value of this hit.
050     *
051     * @return the overall P-value of this hit. This is an optional
052     * (but desired) piece of information and implementations of this
053     * interface may return NaN if a P-value is not available for this
054     * hit.
055     */
056    public double getPValue();
057  
058    /**
059     * Return the overall E-value of this hit.
060     *
061     * @return the overall E-value of this hit. This is an optional
062     * (but desired) piece of information and implementations of this
063     * interface may return NaN if an E-value is not available for
064     * this hit.
065     */
066    public double getEValue();
067
068    /**
069     * Return the start position of the first sub-hit in the query
070     * sequence.
071     *
072     * @return an <code>int</code>.
073     */
074    public int getQueryStart();
075
076    /**
077     * Return the end position of the last sub-hit in the query
078     * sequence.
079     *
080     * @return an <code>int</code>.
081     */
082    public int getQueryEnd();
083
084    /**
085     * Return the strand of the hit with respect to the query
086     * sequence. If the sub-hits are not all on the same strand this
087     * should return the unknown strand. This may be null for protein
088     * sequences.
089     *
090     * @return a <code>Strand</code>.
091     */
092    public Strand getQueryStrand();
093
094    /**
095     * Return the start position of the first sub-hit in the subject
096     * sequence.
097     *
098     * @return an <code>int</code>.
099     */
100    public int getSubjectStart();
101
102    /**
103     * Return the end position of the last sub-hit in the subject
104     * sequence.
105     *
106     * @return an <code>int</code>.
107     */
108    public int getSubjectEnd();
109
110    /**
111     * Return the strand of the sub-hit with respect to the subject
112     * sequence. If the sub-hits are not all on the same strand this
113     * should return the unknown strand. This may be null for protein
114     * sequences.
115     *
116     * @return a <code>Strand</code>.
117     */
118    public Strand getSubjectStrand();
119
120    /**
121     * The sequence identifier of this hit within the sequence
122     * database against which the search was performed.
123     *
124     * @return the (unique) sequence identifier for this hit, valid
125     * within the sequence database against which this search was
126     * performed. Never returns null.
127     */
128    public String getSubjectID();
129
130    /**
131     * Return all sub-hits for this sequence similarity search
132     * hit. The sub-hits contain concrete alignments (and scores) for
133     * sequence stretches from the sequence of this hit. The sub-hits
134     * in the list returned by this method are sorted from best to
135     * worst.
136     * @return a List of SeqSimilaritySearchSubHit objects containing
137     * all sub-hits for this hit.  Never returns null and the List is
138     * guaranteed to contain at least one entry.
139     */
140    public List getSubHits();
141
142    /**
143     * <code>byScore</code> contains a
144     * <code>SeqSimilaritySearchHit</code> comparator which
145     * compares by their score.
146     */
147    public static final ByScoreComparator byScore = new ByScoreComparator();
148
149    /**
150     * <code>bySubHitCount</code> contains a
151     * <code>SeqSimilaritySearchHit</code> comparator which
152     * compares by their number of sub-hits.
153     */
154    public static final BySubHitCountComparator bySubHitCount =
155        new BySubHitCountComparator();
156
157    /**
158     * <code>ByScoreComparator</code> compares
159     * <code>SeqSimilaritySearchHit</code>s by their score.
160     */
161    public static final class ByScoreComparator implements Comparator
162    {
163        public int compare(Object o1, Object o2)
164        {
165            SeqSimilaritySearchHit h1 = (SeqSimilaritySearchHit) o1;
166            SeqSimilaritySearchHit h2 = (SeqSimilaritySearchHit) o2;
167
168            if (h1.getScore() > h2.getScore())
169                return 1;
170            else if (h1.getScore() < h2.getScore())
171                return -1;
172            else
173                return 0;
174        }
175    }
176
177    /**
178     * <code>BySubHitCountComparator</code> compares
179     * <code>SeqSimilaritySearchHit</code>s by their number of
180     * sub-hits.
181     */
182    public static final class BySubHitCountComparator implements Comparator
183    {
184        public int compare(Object o1, Object o2)
185        {
186            SeqSimilaritySearchHit h1 = (SeqSimilaritySearchHit) o1;
187            SeqSimilaritySearchHit h2 = (SeqSimilaritySearchHit) o2;
188
189            if (h1.getSubHits().size() > h2.getSubHits().size())
190                return 1;
191            else if (h1.getSubHits().size() < h2.getSubHits().size())
192                return -1;
193            else
194                return 0;
195        }
196    }
197}