Mercurial > hg > de.mpg.mpiwg.itgroup.digilib.plugin

comparison libs/commons-math-2.1/docs/apidocs/src-html/org/apache/commons/math/stat/correlation/SpearmansCorrelation.html @ 13:cbf34dd4d7e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commons-math-2.1 added
author dwinter
date Tue, 04 Jan 2011 10:02:07 +0100
parents
children
comparison
equal deleted inserted replaced
12:970d26a94fb7 13:cbf34dd4d7e6
1 <HTML>
2 <BODY BGCOLOR="white">
3 <PRE>
4 <FONT color="green">001</FONT> /*<a name="line.1"></a>
5 <FONT color="green">002</FONT> * Licensed to the Apache Software Foundation (ASF) under one or more<a name="line.2"></a>
6 <FONT color="green">003</FONT> * contributor license agreements. See the NOTICE file distributed with<a name="line.3"></a>
7 <FONT color="green">004</FONT> * this work for additional information regarding copyright ownership.<a name="line.4"></a>
8 <FONT color="green">005</FONT> * The ASF licenses this file to You under the Apache License, Version 2.0<a name="line.5"></a>
9 <FONT color="green">006</FONT> * (the "License"); you may not use this file except in compliance with<a name="line.6"></a>
10 <FONT color="green">007</FONT> * the License. You may obtain a copy of the License at<a name="line.7"></a>
11 <FONT color="green">008</FONT> *<a name="line.8"></a>
12 <FONT color="green">009</FONT> * http://www.apache.org/licenses/LICENSE-2.0<a name="line.9"></a>
13 <FONT color="green">010</FONT> *<a name="line.10"></a>
14 <FONT color="green">011</FONT> * Unless required by applicable law or agreed to in writing, software<a name="line.11"></a>
15 <FONT color="green">012</FONT> * distributed under the License is distributed on an "AS IS" BASIS,<a name="line.12"></a>
16 <FONT color="green">013</FONT> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<a name="line.13"></a>
17 <FONT color="green">014</FONT> * See the License for the specific language governing permissions and<a name="line.14"></a>
18 <FONT color="green">015</FONT> * limitations under the License.<a name="line.15"></a>
19 <FONT color="green">016</FONT> */<a name="line.16"></a>
20 <FONT color="green">017</FONT> <a name="line.17"></a>
21 <FONT color="green">018</FONT> package org.apache.commons.math.stat.correlation;<a name="line.18"></a>
22 <FONT color="green">019</FONT> <a name="line.19"></a>
23 <FONT color="green">020</FONT> import org.apache.commons.math.MathRuntimeException;<a name="line.20"></a>
24 <FONT color="green">021</FONT> import org.apache.commons.math.linear.BlockRealMatrix;<a name="line.21"></a>
25 <FONT color="green">022</FONT> import org.apache.commons.math.linear.RealMatrix;<a name="line.22"></a>
26 <FONT color="green">023</FONT> import org.apache.commons.math.stat.ranking.NaturalRanking;<a name="line.23"></a>
27 <FONT color="green">024</FONT> import org.apache.commons.math.stat.ranking.RankingAlgorithm;<a name="line.24"></a>
28 <FONT color="green">025</FONT> <a name="line.25"></a>
29 <FONT color="green">026</FONT> /**<a name="line.26"></a>
30 <FONT color="green">027</FONT> * &lt;p&gt;Spearman's rank correlation. This implementation performs a rank<a name="line.27"></a>
31 <FONT color="green">028</FONT> * transformation on the input data and then computes {@link PearsonsCorrelation}<a name="line.28"></a>
32 <FONT color="green">029</FONT> * on the ranked data.&lt;/p&gt;<a name="line.29"></a>
33 <FONT color="green">030</FONT> *<a name="line.30"></a>
34 <FONT color="green">031</FONT> * &lt;p&gt;By default, ranks are computed using {@link NaturalRanking} with default<a name="line.31"></a>
35 <FONT color="green">032</FONT> * strategies for handling NaNs and ties in the data (NaNs maximal, ties averaged).<a name="line.32"></a>
36 <FONT color="green">033</FONT> * The ranking algorithm can be set using a constructor argument.&lt;/p&gt;<a name="line.33"></a>
37 <FONT color="green">034</FONT> *<a name="line.34"></a>
38 <FONT color="green">035</FONT> * @since 2.0<a name="line.35"></a>
39 <FONT color="green">036</FONT> * @version $Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $<a name="line.36"></a>
40 <FONT color="green">037</FONT> */<a name="line.37"></a>
41 <FONT color="green">038</FONT> <a name="line.38"></a>
42 <FONT color="green">039</FONT> public class SpearmansCorrelation {<a name="line.39"></a>
43 <FONT color="green">040</FONT> <a name="line.40"></a>
44 <FONT color="green">041</FONT> /** Input data */<a name="line.41"></a>
45 <FONT color="green">042</FONT> private final RealMatrix data;<a name="line.42"></a>
46 <FONT color="green">043</FONT> <a name="line.43"></a>
47 <FONT color="green">044</FONT> /** Ranking algorithm */<a name="line.44"></a>
48 <FONT color="green">045</FONT> private final RankingAlgorithm rankingAlgorithm;<a name="line.45"></a>
49 <FONT color="green">046</FONT> <a name="line.46"></a>
50 <FONT color="green">047</FONT> /** Rank correlation */<a name="line.47"></a>
51 <FONT color="green">048</FONT> private final PearsonsCorrelation rankCorrelation;<a name="line.48"></a>
52 <FONT color="green">049</FONT> <a name="line.49"></a>
53 <FONT color="green">050</FONT> /**<a name="line.50"></a>
54 <FONT color="green">051</FONT> * Create a SpearmansCorrelation with the given input data matrix<a name="line.51"></a>
55 <FONT color="green">052</FONT> * and ranking algorithm.<a name="line.52"></a>
56 <FONT color="green">053</FONT> *<a name="line.53"></a>
57 <FONT color="green">054</FONT> * @param dataMatrix matrix of data with columns representing<a name="line.54"></a>
58 <FONT color="green">055</FONT> * variables to correlate<a name="line.55"></a>
59 <FONT color="green">056</FONT> * @param rankingAlgorithm ranking algorithm<a name="line.56"></a>
60 <FONT color="green">057</FONT> */<a name="line.57"></a>
61 <FONT color="green">058</FONT> public SpearmansCorrelation(final RealMatrix dataMatrix, final RankingAlgorithm rankingAlgorithm) {<a name="line.58"></a>
62 <FONT color="green">059</FONT> this.data = dataMatrix.copy();<a name="line.59"></a>
63 <FONT color="green">060</FONT> this.rankingAlgorithm = rankingAlgorithm;<a name="line.60"></a>
64 <FONT color="green">061</FONT> rankTransform(data);<a name="line.61"></a>
65 <FONT color="green">062</FONT> rankCorrelation = new PearsonsCorrelation(data);<a name="line.62"></a>
66 <FONT color="green">063</FONT> }<a name="line.63"></a>
67 <FONT color="green">064</FONT> <a name="line.64"></a>
68 <FONT color="green">065</FONT> /**<a name="line.65"></a>
69 <FONT color="green">066</FONT> * Create a SpearmansCorrelation from the given data matrix.<a name="line.66"></a>
70 <FONT color="green">067</FONT> *<a name="line.67"></a>
71 <FONT color="green">068</FONT> * @param dataMatrix matrix of data with columns representing<a name="line.68"></a>
72 <FONT color="green">069</FONT> * variables to correlate<a name="line.69"></a>
73 <FONT color="green">070</FONT> */<a name="line.70"></a>
74 <FONT color="green">071</FONT> public SpearmansCorrelation(final RealMatrix dataMatrix) {<a name="line.71"></a>
75 <FONT color="green">072</FONT> this(dataMatrix, new NaturalRanking());<a name="line.72"></a>
76 <FONT color="green">073</FONT> }<a name="line.73"></a>
77 <FONT color="green">074</FONT> <a name="line.74"></a>
78 <FONT color="green">075</FONT> /**<a name="line.75"></a>
79 <FONT color="green">076</FONT> * Create a SpearmansCorrelation without data.<a name="line.76"></a>
80 <FONT color="green">077</FONT> */<a name="line.77"></a>
81 <FONT color="green">078</FONT> public SpearmansCorrelation() {<a name="line.78"></a>
82 <FONT color="green">079</FONT> data = null;<a name="line.79"></a>
83 <FONT color="green">080</FONT> this.rankingAlgorithm = new NaturalRanking();<a name="line.80"></a>
84 <FONT color="green">081</FONT> rankCorrelation = null;<a name="line.81"></a>
85 <FONT color="green">082</FONT> }<a name="line.82"></a>
86 <FONT color="green">083</FONT> <a name="line.83"></a>
87 <FONT color="green">084</FONT> /**<a name="line.84"></a>
88 <FONT color="green">085</FONT> * Calculate the Spearman Rank Correlation Matrix.<a name="line.85"></a>
89 <FONT color="green">086</FONT> *<a name="line.86"></a>
90 <FONT color="green">087</FONT> * @return Spearman Rank Correlation Matrix<a name="line.87"></a>
91 <FONT color="green">088</FONT> */<a name="line.88"></a>
92 <FONT color="green">089</FONT> public RealMatrix getCorrelationMatrix() {<a name="line.89"></a>
93 <FONT color="green">090</FONT> return rankCorrelation.getCorrelationMatrix();<a name="line.90"></a>
94 <FONT color="green">091</FONT> }<a name="line.91"></a>
95 <FONT color="green">092</FONT> <a name="line.92"></a>
96 <FONT color="green">093</FONT> /**<a name="line.93"></a>
97 <FONT color="green">094</FONT> * Returns a {@link PearsonsCorrelation} instance constructed from the<a name="line.94"></a>
98 <FONT color="green">095</FONT> * ranked input data. That is,<a name="line.95"></a>
99 <FONT color="green">096</FONT> * &lt;code&gt;new SpearmansCorrelation(matrix).getRankCorrelation()&lt;/code&gt;<a name="line.96"></a>
100 <FONT color="green">097</FONT> * is equivalent to<a name="line.97"></a>
101 <FONT color="green">098</FONT> * &lt;code&gt;new PearsonsCorrelation(rankTransform(matrix))&lt;/code&gt; where<a name="line.98"></a>
102 <FONT color="green">099</FONT> * &lt;code&gt;rankTransform(matrix)&lt;/code&gt; is the result of applying the<a name="line.99"></a>
103 <FONT color="green">100</FONT> * configured &lt;code&gt;RankingAlgorithm&lt;/code&gt; to each of the columns of<a name="line.100"></a>
104 <FONT color="green">101</FONT> * &lt;code&gt;matrix.&lt;/code&gt;<a name="line.101"></a>
105 <FONT color="green">102</FONT> *<a name="line.102"></a>
106 <FONT color="green">103</FONT> * @return PearsonsCorrelation among ranked column data<a name="line.103"></a>
107 <FONT color="green">104</FONT> */<a name="line.104"></a>
108 <FONT color="green">105</FONT> public PearsonsCorrelation getRankCorrelation() {<a name="line.105"></a>
109 <FONT color="green">106</FONT> return rankCorrelation;<a name="line.106"></a>
110 <FONT color="green">107</FONT> }<a name="line.107"></a>
111 <FONT color="green">108</FONT> <a name="line.108"></a>
112 <FONT color="green">109</FONT> /**<a name="line.109"></a>
113 <FONT color="green">110</FONT> * Computes the Spearman's rank correlation matrix for the columns of the<a name="line.110"></a>
114 <FONT color="green">111</FONT> * input matrix.<a name="line.111"></a>
115 <FONT color="green">112</FONT> *<a name="line.112"></a>
116 <FONT color="green">113</FONT> * @param matrix matrix with columns representing variables to correlate<a name="line.113"></a>
117 <FONT color="green">114</FONT> * @return correlation matrix<a name="line.114"></a>
118 <FONT color="green">115</FONT> */<a name="line.115"></a>
119 <FONT color="green">116</FONT> public RealMatrix computeCorrelationMatrix(RealMatrix matrix) {<a name="line.116"></a>
120 <FONT color="green">117</FONT> RealMatrix matrixCopy = matrix.copy();<a name="line.117"></a>
121 <FONT color="green">118</FONT> rankTransform(matrixCopy);<a name="line.118"></a>
122 <FONT color="green">119</FONT> return new PearsonsCorrelation().computeCorrelationMatrix(matrixCopy);<a name="line.119"></a>
123 <FONT color="green">120</FONT> }<a name="line.120"></a>
124 <FONT color="green">121</FONT> <a name="line.121"></a>
125 <FONT color="green">122</FONT> /**<a name="line.122"></a>
126 <FONT color="green">123</FONT> * Computes the Spearman's rank correlation matrix for the columns of the<a name="line.123"></a>
127 <FONT color="green">124</FONT> * input rectangular array. The columns of the array represent values<a name="line.124"></a>
128 <FONT color="green">125</FONT> * of variables to be correlated.<a name="line.125"></a>
129 <FONT color="green">126</FONT> *<a name="line.126"></a>
130 <FONT color="green">127</FONT> * @param matrix matrix with columns representing variables to correlate<a name="line.127"></a>
131 <FONT color="green">128</FONT> * @return correlation matrix<a name="line.128"></a>
132 <FONT color="green">129</FONT> */<a name="line.129"></a>
133 <FONT color="green">130</FONT> public RealMatrix computeCorrelationMatrix(double[][] matrix) {<a name="line.130"></a>
134 <FONT color="green">131</FONT> return computeCorrelationMatrix(new BlockRealMatrix(matrix));<a name="line.131"></a>
135 <FONT color="green">132</FONT> }<a name="line.132"></a>
136 <FONT color="green">133</FONT> <a name="line.133"></a>
137 <FONT color="green">134</FONT> /**<a name="line.134"></a>
138 <FONT color="green">135</FONT> * Computes the Spearman's rank correlation coefficient between the two arrays.<a name="line.135"></a>
139 <FONT color="green">136</FONT> *<a name="line.136"></a>
140 <FONT color="green">137</FONT> * &lt;/p&gt;Throws IllegalArgumentException if the arrays do not have the same length<a name="line.137"></a>
141 <FONT color="green">138</FONT> * or their common length is less than 2&lt;/p&gt;<a name="line.138"></a>
142 <FONT color="green">139</FONT> *<a name="line.139"></a>
143 <FONT color="green">140</FONT> * @param xArray first data array<a name="line.140"></a>
144 <FONT color="green">141</FONT> * @param yArray second data array<a name="line.141"></a>
145 <FONT color="green">142</FONT> * @return Returns Spearman's rank correlation coefficient for the two arrays<a name="line.142"></a>
146 <FONT color="green">143</FONT> * @throws IllegalArgumentException if the arrays lengths do not match or<a name="line.143"></a>
147 <FONT color="green">144</FONT> * there is insufficient data<a name="line.144"></a>
148 <FONT color="green">145</FONT> */<a name="line.145"></a>
149 <FONT color="green">146</FONT> public double correlation(final double[] xArray, final double[] yArray)<a name="line.146"></a>
150 <FONT color="green">147</FONT> throws IllegalArgumentException {<a name="line.147"></a>
151 <FONT color="green">148</FONT> if (xArray.length == yArray.length &amp;&amp; xArray.length &gt; 1) {<a name="line.148"></a>
152 <FONT color="green">149</FONT> return new PearsonsCorrelation().correlation(rankingAlgorithm.rank(xArray),<a name="line.149"></a>
153 <FONT color="green">150</FONT> rankingAlgorithm.rank(yArray));<a name="line.150"></a>
154 <FONT color="green">151</FONT> }<a name="line.151"></a>
155 <FONT color="green">152</FONT> else {<a name="line.152"></a>
156 <FONT color="green">153</FONT> throw MathRuntimeException.createIllegalArgumentException(<a name="line.153"></a>
157 <FONT color="green">154</FONT> "invalid array dimensions. xArray has size {0}; yArray has {1} elements",<a name="line.154"></a>
158 <FONT color="green">155</FONT> xArray.length, yArray.length);<a name="line.155"></a>
159 <FONT color="green">156</FONT> }<a name="line.156"></a>
160 <FONT color="green">157</FONT> }<a name="line.157"></a>
161 <FONT color="green">158</FONT> <a name="line.158"></a>
162 <FONT color="green">159</FONT> /**<a name="line.159"></a>
163 <FONT color="green">160</FONT> * Applies rank transform to each of the columns of &lt;code&gt;matrix&lt;/code&gt;<a name="line.160"></a>
164 <FONT color="green">161</FONT> * using the current &lt;code&gt;rankingAlgorithm&lt;/code&gt;<a name="line.161"></a>
165 <FONT color="green">162</FONT> *<a name="line.162"></a>
166 <FONT color="green">163</FONT> * @param matrix matrix to transform<a name="line.163"></a>
167 <FONT color="green">164</FONT> */<a name="line.164"></a>
168 <FONT color="green">165</FONT> private void rankTransform(RealMatrix matrix) {<a name="line.165"></a>
169 <FONT color="green">166</FONT> for (int i = 0; i &lt; matrix.getColumnDimension(); i++) {<a name="line.166"></a>
170 <FONT color="green">167</FONT> matrix.setColumn(i, rankingAlgorithm.rank(matrix.getColumn(i)));<a name="line.167"></a>
171 <FONT color="green">168</FONT> }<a name="line.168"></a>
172 <FONT color="green">169</FONT> }<a name="line.169"></a>
173 <FONT color="green">170</FONT> }<a name="line.170"></a>
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234 </PRE>
235 </BODY>
236 </HTML>