Create Math-Statistics package and add harmonic and geometric mean, and mode (#186)

* Create Math-Statistics package and add  harmonic mean geometric mean and mode.

* Refactor harmonicMean to use a guard clause.

Also add in a test to make sure that passing in a negative number causes an error.

* change the implementation  of geometricMean.

* Add in guard clause to prevent use with negative numbers as the behaviour is not well defined.
* Prevent a potential float under/overflow by summing the logarithms as suggested by Nicolas Cellier.

* Convert extension methods into new class: PMStatisticalSample

Author: ctSkennerton

src/Math-Statistics/PMStatisticalSample.class.st

@@ -0,0 +1,135 @@
+"
+I am a collection of data that statistical measures can be applied to. 
+ 
+My input collection can be anything but most measures need numerical data to work properly.
+
+Create me by calling new and then calling my `data:` message
+
+    sample := PMStatisticalSample new
+	 sample data: #(1 2 3 4 5)
+
+or using my `newFrom:` class message 
+
+	sample := PMStatisticalSample newFrom: #(1 2 3 4 5)
+
+Now you can get statistical measures of the data using any of the following messages 
+
+    sample mode
+	 sample geometricMean
+	 sample harmonicMean
+
+If you only want one statistical measure for a collection you can use my class methods
+
+	 gMean := PMStatisticalSample geometricMean: #(1 2 3 4 5)
+    hMean := PMStatisticalSample harmonicMean: #(1 2 3 4 5)
+    mode := PMStatisticalSample mode: #(1 2 3 4 5)
+
+
+"
+Class {
+	#name : #PMStatisticalSample,
+	#superclass : #Object,
+	#instVars : [
+		'data'
+	],
+	#category : #'Math-Statistics'
+}
+
+{ #category : #information }
+PMStatisticalSample class >> geometricMean: aCollection [
+	"Calculate the geometric mean of a collection. This shortcut method will create a new instance of PMStatisticalSample and return the desired metric."
+
+	^ (self newFrom: aCollection) geometricMean
+]
+
+{ #category : #information }
+PMStatisticalSample class >> harmonicMean: aCollection [
+	"Calculate the harmonic mean of a collection. This shortcut method will create a new instance of PMStatisticalSample and return the desired metric."
+
+	^ (self newFrom: aCollection) harmonicMean
+]
+
+{ #category : #information }
+PMStatisticalSample class >> mode: aCollection [
+	"Calculate the mode of a collection. This shortcut method will create a new instance of PMStatisticalSample and return the desired metric."
+
+	^ (self newFrom: aCollection) mode
+]
+
+{ #category : #'instance creation' }
+PMStatisticalSample class >> newFrom: aCollection [
+	"Create a new PMStatisticalSample with aCollection as the data"
+
+	| ss |
+	ss := self new.
+	ss data: aCollection.
+	^ ss
+]
+
+{ #category : #accessing }
+PMStatisticalSample >> data [
+	"Get the collection that this StatisticalSample is calculated against"
+
+	^data 
+]
+
+{ #category : #accessing }
+PMStatisticalSample >> data: aCollection [
+	"Set the collection of data points that statistical samples will be made against"
+
+	data := aCollection
+]
+
+{ #category : #information }
+PMStatisticalSample >> geometricMean [
+	"Answer with the geometric mean of the collection"
+
+	"(StatisticalSample new data: #(1 1 2 3 4 5 5 6 6 7 8 9)) geometricMean  >>> 3.8583980015011217"
+
+	"(StatisticalSample new data: { 4. 1.  1 / 32}) geometricMean >>> 0.49999999999999994"
+
+	"(StatisticalSample new data: #(3.14 1 4.56 0.333)) geometricMean >>> 1.4776945822943937"
+
+	"(StatisticalSample new data: {1/3. 2/3. 8/3. 16/3}) geometricMean >>> 1.3333333333333335"
+
+	data
+		detect: [ :i | i <= 0 ]
+		ifFound: [ Error new
+				signal: 'The geometric mean should only be calculated on positive numbers' ].
+
+	"For large collections there is a chance of Float overflow/underflow when raising to a fraction. 
+	 Instead sum the logarithms with the side effect that the returned value will be a Float and subject 
+	 to floating point arethmetic imprecision"
+	"^(self reduce: [ :a :b | a * b ] ) raisedToFraction:  1 / self size."
+	^ ((data collect: #ln) sum / data size) exp
+]
+
+{ #category : #information }
+PMStatisticalSample >> harmonicMean [
+	"Answer with the harmonic mean of the data."
+
+	"(StatisticalSample new data: #(2.5 3 10)) harmonicMean >>> 3.6"
+
+	| sum |
+	data
+		detect: [ :i | i <= 0 ]
+		ifFound: [ Error new
+				signal: 'The harmonic mean should only be calculated on positive numbers' ].
+	sum := 0.
+	data do: [ :i | sum := sum + (1 / i) ].
+	^ data size / sum
+]
+
+{ #category : #information }
+PMStatisticalSample >> mode [
+	"answers with the most common value in a collection.
+	
+	If there are values that are equally common then the one that is 
+	smallest is returned."
+
+	"(StatisticalSample new data: #(1 2 2 2 3 4 5)) mode  >>> 2"
+
+	"(StatisticalSample new data: #(5 5 1 1 2 3 4)) mode  >>> 1"
+
+	^ (data asBag sortedCounts at: 1) value
+]

src/Math-Statistics/package.st

@@ -0,0 +1 @@
+Package { #name : #'Math-Statistics' }

src/Math-Tests-Statistics/PMStatisticsTests.class.st

@@ -0,0 +1,66 @@
+Class {
+	#name : #PMStatisticsTests,
+	#superclass : #TestCase,
+	#category : #'Math-Tests-Statistics'
+}
+
+{ #category : #tests }
+PMStatisticsTests >> testGeometricMean [
+	self
+		assert:
+			((PMStatisticalSample new data: #(1 1 2 3 4 5 5 6 6 7 8 9))
+				geometricMean round: 4)
+		equals: 3.8584.
+	self
+		assert:
+			((PMStatisticalSample new
+				data:
+					{4.
+					1.
+					(1 / 32)}) geometricMean round: 4)
+		equals: 0.5.
+	self
+		assert:
+			((PMStatisticalSample new data: #(3.14 1 4.56 0.333)) geometricMean
+				round: 4)
+		equals: 1.4777.
+	self
+		should: [ (PMStatisticalSample new data: #(-1 5 6.78)) geometricMean ]
+		raise: Error.
+	self
+		assert:
+			((PMStatisticalSample geometricMean: 
+					{4.
+					1.
+					(1 / 32)}) round: 4)
+		equals: 0.5.
+]
+
+{ #category : #tests }
+PMStatisticsTests >> testHarmonicMean [
+	self
+		assert: ((PMStatisticalSample new data: #(2.5 3 10)) harmonicMean round: 1)
+		equals: 3.6.
+	self
+		assert: ((PMStatisticalSample harmonicMean: #(2.5 3 10)) round: 1)
+		equals: 3.6.
+	self
+		should: [ (PMStatisticalSample new data: #(3 1.1 -1)) harmonicMean ]
+		raise: Error
+]
+
+{ #category : #tests }
+PMStatisticsTests >> testMode [
+	| c |
+	c := PMStatisticalSample new data: #(1 2 3 4 5 5).
+	self assert: c mode equals: 5.
+	c := PMStatisticalSample mode: #(1 2 3 4 5 5).
+	self assert: c equals: 5.
+	c := PMStatisticalSample new data: #(5 6 8 3 3 3 2 2 2).
+	self assert: c mode equals: 2.
+	c := PMStatisticalSample new data: #(1.1 1.2 1.1 3.4).
+	self assert: c mode equals: 1.1.
+	c := PMStatisticalSample new
+		data: #(dat1 dat2 dat4 dat1 dat4 dat4 dat2 dat9 dat8).
+	self assert: c mode equals: 'dat4'
+]

src/Math-Tests-Statistics/package.st

@@ -0,0 +1 @@
+Package { #name : #'Math-Tests-Statistics' }