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 package org.apache.commons.math3.stat.descriptive.summary;
18
19 import java.io.Serializable;
20
21 import org.apache.commons.math3.exception.MathIllegalArgumentException;
22 import org.apache.commons.math3.exception.NullArgumentException;
23 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
24 import org.apache.commons.math3.util.MathUtils;
25
26 /**
27 * Returns the sum of the squares of the available values.
28 * <p>
29 * If there are no values in the dataset, then 0 is returned.
30 * If any of the values are
31 * <code>NaN</code>, then <code>NaN</code> is returned.</p>
32 * <p>
33 * <strong>Note that this implementation is not synchronized.</strong> If
34 * multiple threads access an instance of this class concurrently, and at least
35 * one of the threads invokes the <code>increment()</code> or
36 * <code>clear()</code> method, it must be synchronized externally.</p>
37 *
38 * @version $Id: SumOfSquares.java 1416643 2012-12-03 19:37:14Z tn $
39 */
40 public class SumOfSquares extends AbstractStorelessUnivariateStatistic implements Serializable {
41
42 /** Serializable version identifier */
43 private static final long serialVersionUID = 1460986908574398008L;
44
45 /** */
46 private long n;
47
48 /**
49 * The currently running sumSq
50 */
51 private double value;
52
53 /**
54 * Create a SumOfSquares instance
55 */
56 public SumOfSquares() {
57 n = 0;
58 value = 0;
59 }
60
61 /**
62 * Copy constructor, creates a new {@code SumOfSquares} identical
63 * to the {@code original}
64 *
65 * @param original the {@code SumOfSquares} instance to copy
66 * @throws NullArgumentException if original is null
67 */
68 public SumOfSquares(SumOfSquares original) throws NullArgumentException {
69 copy(original, this);
70 }
71
72 /**
73 * {@inheritDoc}
74 */
75 @Override
76 public void increment(final double d) {
77 value += d * d;
78 n++;
79 }
80
81 /**
82 * {@inheritDoc}
83 */
84 @Override
85 public double getResult() {
86 return value;
87 }
88
89 /**
90 * {@inheritDoc}
91 */
92 public long getN() {
93 return n;
94 }
95
96 /**
97 * {@inheritDoc}
98 */
99 @Override
100 public void clear() {
101 value = 0;
102 n = 0;
103 }
104
105 /**
106 * Returns the sum of the squares of the entries in the specified portion of
107 * the input array, or <code>Double.NaN</code> if the designated subarray
108 * is empty.
109 * <p>
110 * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
111 *
112 * @param values the input array
113 * @param begin index of the first array element to include
114 * @param length the number of elements to include
115 * @return the sum of the squares of the values or 0 if length = 0
116 * @throws MathIllegalArgumentException if the array is null or the array index
117 * parameters are not valid
118 */
119 @Override
120 public double evaluate(final double[] values,final int begin, final int length)
121 throws MathIllegalArgumentException {
122 double sumSq = Double.NaN;
123 if (test(values, begin, length, true)) {
124 sumSq = 0.0;
125 for (int i = begin; i < begin + length; i++) {
126 sumSq += values[i] * values[i];
127 }
128 }
129 return sumSq;
130 }
131
132 /**
133 * {@inheritDoc}
134 */
135 @Override
136 public SumOfSquares copy() {
137 SumOfSquares result = new SumOfSquares();
138 // no try-catch or advertised exception here because args are valid
139 copy(this, result);
140 return result;
141 }
142
143 /**
144 * Copies source to dest.
145 * <p>Neither source nor dest can be null.</p>
146 *
147 * @param source SumOfSquares to copy
148 * @param dest SumOfSquares to copy to
149 * @throws NullArgumentException if either source or dest is null
150 */
151 public static void copy(SumOfSquares source, SumOfSquares dest)
152 throws NullArgumentException {
153 MathUtils.checkNotNull(source);
154 MathUtils.checkNotNull(dest);
155 dest.setData(source.getDataRef());
156 dest.n = source.n;
157 dest.value = source.value;
158 }
159
160 }