MATH-503

Added sigmoid and generalized logistic functions.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1065146 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math/analysis/function/Logistic.java

@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.math.analysis.function;
+
+import org.apache.commons.math.analysis.UnivariateRealFunction;
+import org.apache.commons.math.exception.NotStrictlyPositiveException;
+import org.apache.commons.math.util.FastMath;
+
+/**
+ * <a href="http://en.wikipedia.org/wiki/Generalised_logistic_function">
+ *  Generalised logistic</a> function.
+ *
+ * @version $Revision$ $Date$
+ * @since 3.0
+ */
+public class Logistic implements UnivariateRealFunction {
+    /** Lower asymptote. */
+    private final double a;
+    /** Upper asymptote. */
+    private final double k;
+    /** Growth rate. */
+    private final double b;
+    /** Parameter that affects near which asymptote maximum growth occurs. */
+    private final double n;
+    /** Parameter that affects the position of the curve along the ordinate axis. */
+    private final double q;
+    /** Abscissa of maximum growth. */
+    private final double m;
+
+    /**
+     * @param k Upper asymptote.
+     * @param m Abscissa of maximum growth.
+     * @param b Growth rate.
+     * @param q Parameter that affects the position of the curve along the
+     * ordinate axis.
+     * @param a Lower asymptote.
+     * @param n Parameter that affects near which asymptote the maximum
+     * growth occurs.
+     * @throws NotStrictlyPositiveException if {@code n <= 0}.
+     */
+    public Logistic(double k,
+                    double m,
+                    double b,
+                    double q,
+                    double a,
+                    double n) {
+        if (n <= 0) {
+            throw new NotStrictlyPositiveException(n);
+        }
+
+        this.k = k;
+        this.m = m;
+        this.b = b;
+        this.q = q;
+        this.a = a;
+        this.n = n;
+    }
+
+    /** {@inheritDoc} */
+    public double value(double x) {
+        return a + (k - a) / FastMath.pow((1 + q * FastMath.exp(b * (m - x))), 1 / n);
+    }
+}

src/main/java/org/apache/commons/math/analysis/function/Sigmoid.java

@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.math.analysis.function;
+
+import org.apache.commons.math.analysis.UnivariateRealFunction;
+import org.apache.commons.math.exception.NotStrictlyPositiveException;
+import org.apache.commons.math.util.FastMath;
+
+/**
+ * <a href="http://en.wikipedia.org/wiki/Sigmoid_function">
+ *  Sigmoid</a> function.
+ * A more flexible version, the generalised logistic, is implemented
+ * by the {@link Logistic} class.
+ *
+ * @version $Revision$ $Date$
+ * @since 3.0
+ */
+public class Sigmoid implements UnivariateRealFunction {
+    /** {@inheritDoc} */
+    public double value(double x) {
+        return 1 / (1 + FastMath.exp(-x));
+    }
+}

src/test/java/org/apache/commons/math/analysis/function/LogisticTest.java

@@ -0,0 +1,84 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.math.analysis.function;
+
+import org.apache.commons.math.analysis.UnivariateRealFunction;
+import org.apache.commons.math.exception.NotStrictlyPositiveException;
+import org.apache.commons.math.util.FastMath;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+/**
+ * Test for class {@link Logistic}.
+ */
+public class LogisticTest {
+    private final double EPS = Math.ulp(1d);
+
+    @Test
+    public void testPreconditions() {
+        try {
+            final UnivariateRealFunction f = new Logistic(1, 0, 1, 1, 0, -1);
+        } catch (NotStrictlyPositiveException e) {
+            // Expected.
+        }
+
+        try {
+            final UnivariateRealFunction f = new Logistic(1, 0, 1, 1, 0, 0);
+        } catch (NotStrictlyPositiveException e) {
+            // Expected.
+        }
+    }
+
+    @Test
+    public void testCompareSigmoid() {
+        final UnivariateRealFunction sig = new Sigmoid();
+        final UnivariateRealFunction sigL = new Logistic(1, 0, 1, 1, 0, 1);
+
+        final double min = -2;
+        final double max = 2;
+        final int n = 100;
+        final double delta = (max - min) / n;
+        for (int i = 0; i < n; i++) {
+            final double x = min + i * delta;
+            Assert.assertEquals("x=" + x, sig.value(x), sigL.value(x), EPS);
+        }
+    }
+
+    @Test
+    public void testSomeValues() {
+        final double k = 4;
+        final double m = 5;
+        final double b = 2;
+        final double q = 3;
+        final double a = -1;
+        final double n = 2;
+
+        final UnivariateRealFunction f = new Logistic(k, m, b, q, a, n);
+
+        double x;
+        x = m;
+        Assert.assertEquals("x=" + x, a + (k - a) / FastMath.sqrt(1 + q), f.value(x), EPS);
+
+        x = Double.NEGATIVE_INFINITY;
+        Assert.assertEquals("x=" + x, a, f.value(x), EPS);
+
+        x = Double.POSITIVE_INFINITY;
+        Assert.assertEquals("x=" + x, k, f.value(x), EPS);
+    }
+}

src/test/java/org/apache/commons/math/analysis/function/SigmoidTest.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.math.analysis.function;
+
+import org.apache.commons.math.analysis.UnivariateRealFunction;
+import org.apache.commons.math.exception.NotStrictlyPositiveException;
+import org.apache.commons.math.util.FastMath;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+/**
+ * Test for class {@link Sigmoid}.
+ */
+public class SigmoidTest {
+    private final double EPS = Math.ulp(1d);
+
+    @Test
+    public void testSomeValues() {
+        final UnivariateRealFunction f = new Sigmoid();
+
+        double x;
+        x = 0;
+        Assert.assertEquals("x=" + x, 0.5, f.value(x), EPS);
+
+        x = Double.NEGATIVE_INFINITY;
+        Assert.assertEquals("x=" + x, 0, f.value(x), EPS);
+
+        x = Double.POSITIVE_INFINITY;
+        Assert.assertEquals("x=" + x, 1, f.value(x), EPS);
+    }
+}