Javadoc, test improvements, user guide update. JIRA: MATH-649.

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

src/main/java/org/apache/commons/math/stat/regression/SimpleRegression.java

@@ -48,11 +48,16 @@ import org.apache.commons.math.util.Precision;
  * different x coordinates are required to estimate a bivariate regression
  * model.
  * </li>
- * <li> getters for the statistics always compute values based on the current
+ * <li> Getters for the statistics always compute values based on the current
  * set of observations -- i.e., you can get statistics, then add more data
  * and get updated statistics without using a new instance.  There is no
  * "compute" method that updates all statistics.  Each of the getters performs
- * the necessary computations to return the requested statistic.</li>
+ * the necessary computations to return the requested statistic.
+ * </li>
+ * <li> The intercept term may be suppressed by passing {@code false} to
+ * the {@link #SimpleRegression(boolean)} constructor.  When the
+ * {@code hasIntercept} property is false, the model is estimated without a
+ * constant term and {@link #getIntercept()} returns {@code 0}.</li>
  * </ul></p>
  *
  * @version $Id$
@@ -97,8 +102,15 @@ public class SimpleRegression implements Serializable, UpdatingMultipleLinearReg
         this(true);
     }
     /**
-    * Secondary constructor which allows the user the ability to include/exclude const
+    * Create a SimpleRegression instance, specifying whether or not to estimate
-    * @param includeIntercept boolean flag, true includes an intercept
+    * an intercept.
+    *
+    * <p>Use {@code false} to estimate a model with no intercept.  When the
+    * {@code hasIntercept} property is false, the model is estimated without a
+    * constant term and {@link #getIntercept()} returns {@code 0}.</p>
+    *
+    * @param includeIntercept whether or not to include an intercept term in
+    * the regression model
     */
     public SimpleRegression(boolean includeIntercept) {
         super();
@@ -332,7 +344,8 @@ public class SimpleRegression implements Serializable, UpdatingMultipleLinearReg
     }
 
     /**
-     * Returns the intercept of the estimated regression line.
+     * Returns the intercept of the estimated regression line, if
+     * {@link #hasIntercept()} is true; otherwise 0.
      * <p>
      * The least squares estimate of the intercept is computed using the
      * <a href="http://www.xycoon.com/estimation4.htm">normal equations</a>.
@@ -345,16 +358,19 @@ public class SimpleRegression implements Serializable, UpdatingMultipleLinearReg
      * returned.
      * </li></ul></p>
      *
-     * @return the intercept of the regression line
+     * @return the intercept of the regression line if the model includes an
+     * intercept; 0 otherwise
+     * @see #SimpleRegression(boolean)
      */
     public double getIntercept() {
         return hasIntercept ? getIntercept(getSlope()) : 0.0;
     }
 
     /**
-     * Returns true if a constant has been included false otherwise.
+     * Returns true if the model includes an intercept term.
      *
-     * @return true if constant exists, false otherwise
+     * @return true if the regression includes an intercept; false otherwise
+     * @see #SimpleRegression(boolean)
      */
     public boolean hasIntercept() {
         return hasIntercept;

src/site/xdoc/userguide/stat.xml

@@ -365,10 +365,12 @@ System.out.println(f.getCumPct("z"));  // displays 1
            <code> y = intercept + slope * x  </code>
          </p>
          <p>
-         or
+           or
-         <p>
-           <code> y = slope * x  </code>
          </p>
+         <p>
+           <code> y = slope * x </code>
+         </p>
+         <p>
            Standard errors for <code>intercept</code> and <code>slope</code> are
            available as well as ANOVA, r-square and Pearson's r statistics.
          </p>
@@ -390,6 +392,11 @@ System.out.println(f.getCumPct("z"));  // displays 1
            and get updated statistics without using a new instance.  There is no
            "compute" method that updates all statistics.  Each of the getters performs
            the necessary computations to return the requested statistic.</li>
+           <li> The intercept term may be suppressed by passing <code>false</code> to the
+           <a href="../apidocs/org/apache/commons/math/stat/regression/SimpleRegression.html#SimpleRegression(boolean)">
+           SimpleRegression(boolean)</a> constructor.  When the <code>hasIntercept</code>
+           property is false, the model is estimated without a constant term and
+           <code>getIntercept()</code> returns <code>0</code>.</li>
           </ul>
         </p>
         <p>

src/test/java/org/apache/commons/math/stat/regression/SimpleRegressionTest.java

@@ -162,6 +162,7 @@ public final class SimpleRegressionTest {
          regression.addData(noint2[0][1], noint2[0][0]);
          regression.addData(noint2[1][1], noint2[1][0]);
          regression.addData(noint2[2][1], noint2[2][0]);
+         Assert.assertEquals("intercept", 0, regression.getIntercept(), 0);
          Assert.assertEquals("slope", 0.727272727272727,
                  regression.getSlope(), 10E-12);
          Assert.assertEquals("slope std err", 0.420827318078432E-01,
@@ -183,6 +184,7 @@ public final class SimpleRegressionTest {
         for (int i = 0; i < noint1.length; i++) {
             regression.addData(noint1[i][1], noint1[i][0]);
         }
+        Assert.assertEquals("intercept", 0, regression.getIntercept(), 0);
         Assert.assertEquals("slope", 2.07438016528926, regression.getSlope(), 10E-12);
         Assert.assertEquals("slope std err", 0.165289256198347E-01,
                 regression.getSlopeStdErr(),10E-12);