001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math.distribution;
019
020 import java.io.Serializable;
021
022 import org.apache.commons.math.MathRuntimeException;
023
024 /**
025 * Implementation for the {@link ZipfDistribution}.
026 *
027 * @version $Revision: 920852 $ $Date: 2010-03-09 07:53:44 -0500 (Tue, 09 Mar 2010) $
028 */
029 public class ZipfDistributionImpl extends AbstractIntegerDistribution
030 implements ZipfDistribution, Serializable {
031
032 /** Serializable version identifier. */
033 private static final long serialVersionUID = -140627372283420404L;
034
035 /** Number of elements. */
036 private int numberOfElements;
037
038 /** Exponent parameter of the distribution. */
039 private double exponent;
040
041 /**
042 * Create a new Zipf distribution with the given number of elements and
043 * exponent. Both values must be positive; otherwise an
044 * <code>IllegalArgumentException</code> is thrown.
045 *
046 * @param numberOfElements the number of elements
047 * @param exponent the exponent
048 * @exception IllegalArgumentException if n ≤ 0 or s ≤ 0.0
049 */
050 public ZipfDistributionImpl(final int numberOfElements, final double exponent)
051 throws IllegalArgumentException {
052 setNumberOfElementsInternal(numberOfElements);
053 setExponentInternal(exponent);
054 }
055
056 /**
057 * Get the number of elements (e.g. corpus size) for the distribution.
058 *
059 * @return the number of elements
060 */
061 public int getNumberOfElements() {
062 return numberOfElements;
063 }
064
065 /**
066 * Set the number of elements (e.g. corpus size) for the distribution.
067 * The parameter value must be positive; otherwise an
068 * <code>IllegalArgumentException</code> is thrown.
069 *
070 * @param n the number of elements
071 * @exception IllegalArgumentException if n ≤ 0
072 * @deprecated as of 2.1 (class will become immutable in 3.0)
073 */
074 @Deprecated
075 public void setNumberOfElements(final int n) {
076 setNumberOfElementsInternal(n);
077 }
078 /**
079 * Set the number of elements (e.g. corpus size) for the distribution.
080 * The parameter value must be positive; otherwise an
081 * <code>IllegalArgumentException</code> is thrown.
082 *
083 * @param n the number of elements
084 * @exception IllegalArgumentException if n ≤ 0
085 */
086 private void setNumberOfElementsInternal(final int n)
087 throws IllegalArgumentException {
088 if (n <= 0) {
089 throw MathRuntimeException.createIllegalArgumentException(
090 "invalid number of elements {0} (must be positive)",
091 n);
092 }
093 this.numberOfElements = n;
094 }
095
096 /**
097 * Get the exponent characterising the distribution.
098 *
099 * @return the exponent
100 */
101 public double getExponent() {
102 return exponent;
103 }
104
105 /**
106 * Set the exponent characterising the distribution.
107 * The parameter value must be positive; otherwise an
108 * <code>IllegalArgumentException</code> is thrown.
109 *
110 * @param s the exponent
111 * @exception IllegalArgumentException if s ≤ 0.0
112 * @deprecated as of 2.1 (class will become immutable in 3.0)
113 */
114 @Deprecated
115 public void setExponent(final double s) {
116 setExponentInternal(s);
117 }
118 /**
119 * Set the exponent characterising the distribution.
120 * The parameter value must be positive; otherwise an
121 * <code>IllegalArgumentException</code> is thrown.
122 *
123 * @param s the exponent
124 * @exception IllegalArgumentException if s ≤ 0.0
125 */
126 private void setExponentInternal(final double s)
127 throws IllegalArgumentException {
128 if (s <= 0.0) {
129 throw MathRuntimeException.createIllegalArgumentException(
130 "invalid exponent {0} (must be positive)",
131 s);
132 }
133 this.exponent = s;
134 }
135
136 /**
137 * The probability mass function P(X = x) for a Zipf distribution.
138 *
139 * @param x the value at which the probability density function is evaluated.
140 * @return the value of the probability mass function at x
141 */
142 public double probability(final int x) {
143 if (x <= 0 || x > numberOfElements) {
144 return 0.0;
145 }
146
147 return (1.0 / Math.pow(x, exponent)) / generalizedHarmonic(numberOfElements, exponent);
148
149 }
150
151 /**
152 * The probability distribution function P(X <= x) for a Zipf distribution.
153 *
154 * @param x the value at which the PDF is evaluated.
155 * @return Zipf distribution function evaluated at x
156 */
157 @Override
158 public double cumulativeProbability(final int x) {
159 if (x <= 0) {
160 return 0.0;
161 } else if (x >= numberOfElements) {
162 return 1.0;
163 }
164
165 return generalizedHarmonic(x, exponent) / generalizedHarmonic(numberOfElements, exponent);
166
167 }
168
169 /**
170 * Access the domain value lower bound, based on <code>p</code>, used to
171 * bracket a PDF root.
172 *
173 * @param p the desired probability for the critical value
174 * @return domain value lower bound, i.e.
175 * P(X < <i>lower bound</i>) < <code>p</code>
176 */
177 @Override
178 protected int getDomainLowerBound(final double p) {
179 return 0;
180 }
181
182 /**
183 * Access the domain value upper bound, based on <code>p</code>, used to
184 * bracket a PDF root.
185 *
186 * @param p the desired probability for the critical value
187 * @return domain value upper bound, i.e.
188 * P(X < <i>upper bound</i>) > <code>p</code>
189 */
190 @Override
191 protected int getDomainUpperBound(final double p) {
192 return numberOfElements;
193 }
194
195
196 /**
197 * Calculates the Nth generalized harmonic number. See
198 * <a href="http://mathworld.wolfram.com/HarmonicSeries.html">Harmonic
199 * Series</a>.
200 *
201 * @param n the term in the series to calculate (must be ≥ 1)
202 * @param m the exponent; special case m == 1.0 is the harmonic series
203 * @return the nth generalized harmonic number
204 */
205 private double generalizedHarmonic(final int n, final double m) {
206 double value = 0;
207 for (int k = n; k > 0; --k) {
208 value += 1.0 / Math.pow(k, m);
209 }
210 return value;
211 }
212
213 }