View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math3.analysis.function;
19  
20  import org.apache.commons.math3.analysis.FunctionUtils;
21  import org.apache.commons.math3.analysis.UnivariateFunction;
22  import org.apache.commons.math3.analysis.DifferentiableUnivariateFunction;
23  import org.apache.commons.math3.analysis.ParametricUnivariateFunction;
24  import org.apache.commons.math3.analysis.differentiation.DerivativeStructure;
25  import org.apache.commons.math3.analysis.differentiation.UnivariateDifferentiableFunction;
26  import org.apache.commons.math3.exception.NotStrictlyPositiveException;
27  import org.apache.commons.math3.exception.NullArgumentException;
28  import org.apache.commons.math3.exception.DimensionMismatchException;
29  import org.apache.commons.math3.util.FastMath;
30  
31  /**
32   * <a href="http://en.wikipedia.org/wiki/Generalised_logistic_function">
33   *  Generalised logistic</a> function.
34   *
35   * @since 3.0
36   * @version $Id: Logistic.java 1513430 2013-08-13 10:46:48Z erans $
37   */
38  public class Logistic implements UnivariateDifferentiableFunction, DifferentiableUnivariateFunction {
39      /** Lower asymptote. */
40      private final double a;
41      /** Upper asymptote. */
42      private final double k;
43      /** Growth rate. */
44      private final double b;
45      /** Parameter that affects near which asymptote maximum growth occurs. */
46      private final double oneOverN;
47      /** Parameter that affects the position of the curve along the ordinate axis. */
48      private final double q;
49      /** Abscissa of maximum growth. */
50      private final double m;
51  
52      /**
53       * @param k If {@code b > 0}, value of the function for x going towards +&infin;.
54       * If {@code b < 0}, value of the function for x going towards -&infin;.
55       * @param m Abscissa of maximum growth.
56       * @param b Growth rate.
57       * @param q Parameter that affects the position of the curve along the
58       * ordinate axis.
59       * @param a If {@code b > 0}, value of the function for x going towards -&infin;.
60       * If {@code b < 0}, value of the function for x going towards +&infin;.
61       * @param n Parameter that affects near which asymptote the maximum
62       * growth occurs.
63       * @throws NotStrictlyPositiveException if {@code n <= 0}.
64       */
65      public Logistic(double k,
66                      double m,
67                      double b,
68                      double q,
69                      double a,
70                      double n)
71          throws NotStrictlyPositiveException {
72          if (n <= 0) {
73              throw new NotStrictlyPositiveException(n);
74          }
75  
76          this.k = k;
77          this.m = m;
78          this.b = b;
79          this.q = q;
80          this.a = a;
81          oneOverN = 1 / n;
82      }
83  
84      /** {@inheritDoc} */
85      public double value(double x) {
86          return value(m - x, k, b, q, a, oneOverN);
87      }
88  
89      /** {@inheritDoc}
90       * @deprecated as of 3.1, replaced by {@link #value(DerivativeStructure)}
91       */
92      @Deprecated
93      public UnivariateFunction derivative() {
94          return FunctionUtils.toDifferentiableUnivariateFunction(this).derivative();
95      }
96  
97      /**
98       * Parametric function where the input array contains the parameters of
99       * the {@link Logistic#Logistic(double,double,double,double,double,double)
100      * logistic function}, ordered as follows:
101      * <ul>
102      *  <li>k</li>
103      *  <li>m</li>
104      *  <li>b</li>
105      *  <li>q</li>
106      *  <li>a</li>
107      *  <li>n</li>
108      * </ul>
109      */
110     public static class Parametric implements ParametricUnivariateFunction {
111         /**
112          * Computes the value of the sigmoid at {@code x}.
113          *
114          * @param x Value for which the function must be computed.
115          * @param param Values for {@code k}, {@code m}, {@code b}, {@code q},
116          * {@code a} and  {@code n}.
117          * @return the value of the function.
118          * @throws NullArgumentException if {@code param} is {@code null}.
119          * @throws DimensionMismatchException if the size of {@code param} is
120          * not 6.
121          * @throws NotStrictlyPositiveException if {@code param[5] <= 0}.
122          */
123         public double value(double x, double ... param)
124             throws NullArgumentException,
125                    DimensionMismatchException,
126                    NotStrictlyPositiveException {
127             validateParameters(param);
128             return Logistic.value(param[1] - x, param[0],
129                                   param[2], param[3],
130                                   param[4], 1 / param[5]);
131         }
132 
133         /**
134          * Computes the value of the gradient at {@code x}.
135          * The components of the gradient vector are the partial
136          * derivatives of the function with respect to each of the
137          * <em>parameters</em>.
138          *
139          * @param x Value at which the gradient must be computed.
140          * @param param Values for {@code k}, {@code m}, {@code b}, {@code q},
141          * {@code a} and  {@code n}.
142          * @return the gradient vector at {@code x}.
143          * @throws NullArgumentException if {@code param} is {@code null}.
144          * @throws DimensionMismatchException if the size of {@code param} is
145          * not 6.
146          * @throws NotStrictlyPositiveException if {@code param[5] <= 0}.
147          */
148         public double[] gradient(double x, double ... param)
149             throws NullArgumentException,
150                    DimensionMismatchException,
151                    NotStrictlyPositiveException {
152             validateParameters(param);
153 
154             final double b = param[2];
155             final double q = param[3];
156 
157             final double mMinusX = param[1] - x;
158             final double oneOverN = 1 / param[5];
159             final double exp = FastMath.exp(b * mMinusX);
160             final double qExp = q * exp;
161             final double qExp1 = qExp + 1;
162             final double factor1 = (param[0] - param[4]) * oneOverN / FastMath.pow(qExp1, oneOverN);
163             final double factor2 = -factor1 / qExp1;
164 
165             // Components of the gradient.
166             final double gk = Logistic.value(mMinusX, 1, b, q, 0, oneOverN);
167             final double gm = factor2 * b * qExp;
168             final double gb = factor2 * mMinusX * qExp;
169             final double gq = factor2 * exp;
170             final double ga = Logistic.value(mMinusX, 0, b, q, 1, oneOverN);
171             final double gn = factor1 * Math.log(qExp1) * oneOverN;
172 
173             return new double[] { gk, gm, gb, gq, ga, gn };
174         }
175 
176         /**
177          * Validates parameters to ensure they are appropriate for the evaluation of
178          * the {@link #value(double,double[])} and {@link #gradient(double,double[])}
179          * methods.
180          *
181          * @param param Values for {@code k}, {@code m}, {@code b}, {@code q},
182          * {@code a} and {@code n}.
183          * @throws NullArgumentException if {@code param} is {@code null}.
184          * @throws DimensionMismatchException if the size of {@code param} is
185          * not 6.
186          * @throws NotStrictlyPositiveException if {@code param[5] <= 0}.
187          */
188         private void validateParameters(double[] param)
189             throws NullArgumentException,
190                    DimensionMismatchException,
191                    NotStrictlyPositiveException {
192             if (param == null) {
193                 throw new NullArgumentException();
194             }
195             if (param.length != 6) {
196                 throw new DimensionMismatchException(param.length, 6);
197             }
198             if (param[5] <= 0) {
199                 throw new NotStrictlyPositiveException(param[5]);
200             }
201         }
202     }
203 
204     /**
205      * @param mMinusX {@code m - x}.
206      * @param k {@code k}.
207      * @param b {@code b}.
208      * @param q {@code q}.
209      * @param a {@code a}.
210      * @param oneOverN {@code 1 / n}.
211      * @return the value of the function.
212      */
213     private static double value(double mMinusX,
214                                 double k,
215                                 double b,
216                                 double q,
217                                 double a,
218                                 double oneOverN) {
219         return a + (k - a) / FastMath.pow(1 + q * FastMath.exp(b * mMinusX), oneOverN);
220     }
221 
222     /** {@inheritDoc}
223      * @since 3.1
224      */
225     public DerivativeStructure value(final DerivativeStructure t) {
226         return t.negate().add(m).multiply(b).exp().multiply(q).add(1).pow(oneOverN).reciprocal().multiply(k - a).add(a);
227     }
228 
229 }