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