From 828c863a006a063c47e39f104643c66552d12571 Mon Sep 17 00:00:00 2001
From: Phil Steitz <psteitz@apache.org>
Date: Sun, 21 Jun 2009 00:58:14 +0000
Subject: [PATCH] Added ranking subsection.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@786935 13f79535-47bb-0310-9956-ffa450edef68
---
 src/site/xdoc/userguide/index.xml |  5 ++-
 src/site/xdoc/userguide/stat.xml  | 53 ++++++++++++++++++++++++++++---
 2 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml
index 475b054c2..4c5088c10 100644
--- a/src/site/xdoc/userguide/index.xml
+++ b/src/site/xdoc/userguide/index.xml
@@ -43,7 +43,10 @@
                 <li><a href="stat.html#a1.2_Descriptive_statistics">1.2 Descriptive statistics</a></li>
                 <li><a href="stat.html#a1.3_Frequency_distributions">1.3 Frequency distributions</a></li>
                 <li><a href="stat.html#a1.4_Simple_regression">1.4 Simple regression</a></li>
-                <li><a href="stat.html#a1.5_Statistical_tests">1.5 Statistical tests</a></li>
+                <li><a href="stat.html#a1.5_Multiple_linear_regression">1.5 Multiple Regression</a></li>
+                <li><a href="stat.html#a1.6_Rank_transformations">1.6 Rank transformations</a></li>
+                <li><a href="stat.html#a1.7_Covariance_and_correlation">1.7 Covariance and correlation</a></li>
+                <li><a href="stat.html#a1.8_Statistical_tests">1.8 Statistical Tests</a></li>
                 </ul></li>
             <li><a href="random.html">2. Data Generation</a>
                 <ul>
diff --git a/src/site/xdoc/userguide/stat.xml b/src/site/xdoc/userguide/stat.xml
index e85a449c3..4abbdc499 100644
--- a/src/site/xdoc/userguide/stat.xml
+++ b/src/site/xdoc/userguide/stat.xml
@@ -36,8 +36,9 @@
          <a href="#a1.3_Frequency_distributions">Frequency distributions</a><br></br>
          <a href="#a1.4_Simple_regression">Simple Regression</a><br></br>
          <a href="#a1.5_Multiple_linear_regression">Multiple Regression</a><br></br>
-         <a href="#a1.6_Covariance_and_correlation">Covariance and correlation</a><br></br>
-         <a href="#a1.7_Statistical_tests">Statistical Tests</a><br></br>
+         <a href="#a1.6_Rank_transformations">Rank transformations</a><br></br>
+         <a href="#a1.7_Covariance_and_correlation">Covariance and correlation</a><br></br>
+         <a href="#a1.8_Statistical_tests">Statistical Tests</a><br></br>
         </p>
       </subsection>
       <subsection name="1.2 Descriptive statistics">
@@ -493,8 +494,50 @@ regression.addData(y, x, omega); // we do need covariance
          </dd>
          </dl>
         </p>
-      </subsection>      
-      <subsection name="1.6 Covariance and correlation">
+      </subsection>    
+      <subsection name="1.6 Rank transformations">
+      <p>
+         Some statistical algorithms require that input data be replaced by ranks.
+         The <a href="../apidocs/org/apache/commons/math/stat/ranking/package-summary.html">
+         org.apache.commons.math.stat.ranking</a> package provides rank transformation.
+         <a href="../apidocs/org/apache/commons/math/stat/ranking/RankingAlgorithm.html">
+         RankingAlgorithm</a> defines the interface for ranking.  
+         <a href="../apidocs/org/apache/commons/math/stat/ranking/NaturalRanking.html">
+         NaturalRanking</a> provides an implementation that has two configuration options.
+         <ul>
+         <li><a href="../apidocs/org/apache/commons/math/stat/ranking/TiesStrategy.html">
+         Ties strategy</a> deterimines how ties in the source data are handled by the ranking</li>
+         <li><a href="../apidocs/org/apache/commons/math/stat/ranking/NaNStrategy.html">
+         NaN strategy</a> determines how NaN values in the source data are handled.</li>
+         </ul>
+      </p>
+      <p>
+         Examples:
+         <source>
+NaturalRanking ranking = new NaturalRanking(NaNStrategy.MINIMAL,
+TiesStrategy.MAXIMUM);
+double[] data = { 20, 17, 30, 42.3, 17, 50,
+                  Double.NaN, Double.NEGATIVE_INFINITY, 17 };
+double[] ranks = ranking.rank(exampleData);
+         </source>
+         results in <code>ranks</code> containing <code>{6, 5, 7, 8, 5, 9, 2, 2, 5}.</code>
+         <source>
+new NaturalRanking(NaNStrategy.REMOVED,TiesStrategy.SEQUENTIAL).rank(exampleData);   
+         </source>
+         returns <code>{5, 2, 6, 7, 3, 8, 1, 4}.</code>
+      </p>
+      <p>
+        The default <code>NaNStrategy</code> is NaNStrategy.MAXIMAL.  This makes <code>NaN</code>
+        values larger than any other value (including <code>Double.POSITIVE_INFINITY</code>). The
+        default <code>TiesStrategy</code> is <code>TiesStrategy.AVERAGE,</code> which assigns tied
+        values the average of the ranks applicable to the sequence of ties.  See the 
+        <a href="../apidocs/org/apache/commons/math/stat/ranking/NaturalRanking.html">
+        NaturalRanking</a> for more examples and <a href="../apidocs/org/apache/commons/math/stat/ranking/TiesStrategy.html">
+        TiesStrategy</a> and <a href="../apidocs/org/apache/commons/math/stat/ranking/NaNStrategy.html">NaNStrategy</a>
+        for details on these configuration options.
+       </p>
+      </subsection>  
+      <subsection name="1.7 Covariance and correlation">
         <p>
           The <a href="../apidocs/org/apache/commons/math/stat/correlation/package-summary.html">
           org.apache.commons.math.stat.correlation</a> package computes covariances
@@ -617,7 +660,7 @@ new PearsonsCorrelation(data).getCorrelationPValues().getEntry(0,1)
         </dl>
         </p>
       </subsection>
-            <subsection name="1.7 Statistical tests">
+            <subsection name="1.8 Statistical tests">
         <p>
           The interfaces and implementations in the
           <a href="../apidocs/org/apache/commons/math/stat/inference/">