3
// Author: Julien Dutheil
5
// Last modification : Friday August 8 2003
9
Copyright or © or Copr. CNRS, (November 17, 2004)
11
This software is a computer program whose purpose is to provide classes
12
for sequences analysis.
14
This software is governed by the CeCILL license under French law and
15
abiding by the rules of distribution of free software. You can use,
16
modify and/ or redistribute the software under the terms of the CeCILL
17
license as circulated by CEA, CNRS and INRIA at the following URL
18
"http://www.cecill.info".
20
As a counterpart to the access to the source code and rights to copy,
21
modify and redistribute granted by the license, users are provided only
22
with a limited warranty and the software's author, the holder of the
23
economic rights, and the successive licensors have only limited
26
In this respect, the user's attention is drawn to the risks associated
27
with loading, using, modifying and/or developing or reproducing the
28
software by the user in light of its specific status of free software,
29
that may mean that it is complicated to manipulate, and that also
30
therefore means that it is reserved for developers and experienced
31
professionals having in-depth computer knowledge. Users are therefore
32
encouraged to load and test the software's suitability as regards their
33
requirements in conditions enabling the security of their systems and/or
34
data to be ensured and, more generally, to use and operate it in the
35
same conditions as regards security.
37
The fact that you are presently reading this means that you have had
38
knowledge of the CeCILL license and that you accept its terms.
44
#include "SymbolListTools.h"
46
#include <Bpp/Exceptions.h>
54
* @brief Utilitary methods dealing with sites.
58
public SymbolListTools
62
virtual ~SiteTools() {}
67
* @return True if the site contains one or several gap(s).
69
static bool hasGap(const Site& site);
73
* @return True if the site contains only gaps.
75
static bool isGapOnly(const Site& site);
79
* @return True if the site contains only gaps.
81
static bool isGapOrUnresolvedOnly(const Site& site);
85
* @return True if the site contains one or several unknwn characters.
87
static bool hasUnknown(const Site& site);
91
* @return True if the site contains a Stop Codon, when the alphabet is a CodonAlphabet.
93
static bool hasStopCodon(const Site& site);
96
* @return True if the site contains no gap and no unknown characters.
98
static bool isComplete(const Site& site);
101
* @brief Tell if a site is constant, that is displaying the same state in all sequences that do not present a gap.
103
* @param site A site.
104
* @param ignoreUnknown If true, positions with unknown positions will be ignored.
105
* Otherwise, a site with one single state + any uncertain state will not be considered as constant.
106
* @return True if the site is made of only one state.
107
* @throw EmptySiteException If the site has size 0.
109
static bool isConstant(const Site& site, bool ignoreUnknown = false) throw (EmptySiteException);
112
* @param site1 The first site.
113
* @param site2 The second site.
114
* @return True if the two states have the same content (and, of course, alphabet).
116
static bool areSitesIdentical(const Site& site1, const Site& site2);
119
* @brief Compute the Shannon entropy index of a site.
122
* I = - \sum_x f_x\cdot \ln(f_x)
124
* where \f$f_x\f$ is the frequency of state \f$x\f$.
127
* @param site A site.
128
* @param resolveUnknowns Tell is unknown characters must be resolved.
129
* @return The Shannon entropy index of this site.
130
* @throw EmptySiteException If the site has size 0.
132
static double variabilityShannon(const Site& site, bool resolveUnknowns) throw (EmptySiteException);
135
* @brief Compute the factorial diversity index of a site.
138
* F = \frac{log\left(\left(\sum_x p_x\right)!\right)}{\sum_x \log(p_x)!}
140
* where \f$p_x\f$ is the number of times state \f$x\f$ is observed in the site.
143
* @param site A site.
144
* @return The factorial diversity index of this site.
145
* @throw EmptySiteException If the site has size 0.
147
static double variabilityFactorial(const Site& site) throw (EmptySiteException);
150
* @brief Compute the mutual information between two sites.
153
* MI = \sum_x \sum_y p_{x,y}\ln\left(\frac{p_{x,y}}{p_x \cdot p_y}\right)
155
* where \f$p_x\f$ and \f$p_y\f$ are the frequencies of states \f$x\f$ and \f$y\f$, and
156
* \f$p_{x,y}\f$ is the frequency of the pair \f$(x,y)\f$.
159
* @param site1 First site
160
* @param site2 Second site
161
* @param resolveUnknowns Tell is unknown characters must be resolved.
162
* @return The mutual information for the pair of sites.
163
* @throw DimensionException If the sites do not have the same length.
164
* @throw EmptySiteException If the sites have size 0.
166
static double mutualInformation(const Site& site1, const Site& site2, bool resolveUnknowns) throw (DimensionException,EmptySiteException);
169
* @brief Compute the entropy of a site. This is an alias of method variabilityShannon.
172
* I = - \sum_x f_x\cdot \ln(f_x)
174
* where \f$f_x\f$ is the frequency of state \f$x\f$.
177
* @param site A site.
178
* @param resolveUnknowns Tell is unknown characters must be resolved.
179
* @return The Shannon entropy index of this site.
180
* @throw EmptySiteException If the site has size 0.
182
static double entropy(const Site& site, bool resolveUnknowns) throw (EmptySiteException) {
183
return variabilityShannon(site, resolveUnknowns);
188
* @brief Compute the joint entropy between two sites.
191
* H_{i,j} = - \sum_x \sum_y p_{x,y}\ln\left(p_{x,y}\right)
193
* where \f$p_{x,y}\f$ is the frequency of the pair \f$(x,y)\f$.
196
* @param site1 First site
197
* @param site2 Second site
198
* @param resolveUnknowns Tell is unknown characters must be resolved.
199
* @return The mutual information for the pair of sites.
200
* @throw DimensionException If the sites do not have the same length.
201
* @throw EmptySiteException If the sites have size 0.
203
static double jointEntropy(const Site& site1, const Site& site2, bool resolveUnknowns) throw (DimensionException,EmptySiteException);
206
* @brief Compute the heterozygosity index of a site.
209
* H = 1 - \sum_x f_x^2
211
* where \f$f_x\f$ is the frequency of state \f$x\f$.
213
* @param site A site.
214
* @return The heterozygosity index of this site.
215
* @throw EmptySiteException If the site has size 0.
217
static double heterozygosity(const Site& site) throw (EmptySiteException);
220
* @brief Give the number of distinct characters at a site.
223
* @return The number of distinct characters in the given site.
225
static unsigned int getNumberOfDistinctCharacters(const Site& site) throw (EmptySiteException);
228
* @brief Tell if a site has singletons
231
* @param site a Site.
232
* @return True if the site has singletons.
234
static bool hasSingleton(const Site& site) throw (EmptySiteException);
237
* @brief Tell if a site is a parsimony informative site.
239
* At least two distinct characters must be present.
241
* @param site a Site.
242
* @return True if the site is parsimony informative.
244
static bool isParsimonyInformativeSite(const Site& site) throw (EmptySiteException);
248
* @brief Tell if a site has more than 2 distinct characters
250
* @param site a Site.
251
* @return True if the site has more than 2 distinct characters
253
static bool isTriplet(const Site& site) throw (EmptySiteException);
255
} // end of namespace bpp.
257
#endif // _SITETOOLS_H_
added
removed
src/Bpp/Seq/SiteTools.h
