opr-calc 0.1.2 → 1.0.0

data/README.md

@@ -0,0 +1,25 @@
+# opr-calc
+
+[![Gem Version](https://badge.fury.io/rb/opr-calc.png)](http://badge.fury.io/rb/opr-calc)
+
+A rubygem for calculating the OPR, DPR, and CCWM of FRC teams.
+
+## Usage
+
+Define a new ScoreSet with `OPRCalc::ScoreSet.new`. This takes four matrices as arguments: `ared`, `ablue`, `scorered`, and `scoreblue`.
+The `a` matrices define what teams are in what matches.
+The `score` matrices define what the final match scores are.
+For example, consider the following match.
+The first, third, and fifth team are on the red alliance, which scores 26.
+The zeroth, second, and fourth team are on the blue alliance, which scores 56.
+This would result in the following rows the various matrices.
+
+`ared`: `[0, 1, 0, 1, 0, 1]`
+
+`scorered`: `[26]`
+
+`ablue`: `[1, 0, 1, 0, 1, 0]`
+
+`scoreblue`: `[56]`
+
+For other examples, read the tests, which are in the `test/` directory.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new :spec
+
+task default: :spec

data/lib/opr-calc.rb

@@ -16,5 +16,5 @@
 	along with this program.  If not, see <http://www.gnu.org/licenses/>.
 =end
 
-require "opr-calc/matrix.rb"
-require "opr-calc/score_set.rb"
+require 'opr-calc/matrix.rb'
+require 'opr-calc/score_set.rb'

data/lib/opr-calc/matrix.rb

@@ -16,7 +16,7 @@
 	along with this program.  If not, see <http://www.gnu.org/licenses/>.
 =end
 
-require "matrix"
+require 'matrix'
 
 # Props to http://rosettacode.org/wiki/Cholesky_decomposition#Ruby :L
 class Matrix
@@ -27,7 +27,9 @@ class Matrix
 
 		(0...row_size).each do |i|
 			(0..i).each do |j|
+
 				return false if self[i,j] != self[j,i]
+
 			end
 		end
 
@@ -38,21 +40,26 @@ class Matrix
 	# To obtain [L]*, just transpose the matrix, it should work.
 	def cholesky_factor
 		# We need a symmetric matrix for Cholesky decomposition.
-		raise ArgumentError, "must provide a symmetric matrix" unless symmetric?
+		raise ArgumentError, 'must provide a symmetric matrix' unless symmetric?
 
 		# Make a new matrix to return.
 		l = Array.new(row_size) { Array.new(row_size, 0) }
 
 		(0...row_size).each do |k|
 			(0...row_size).each do |i|
+
 				if i == k
+
 					sum = (0..k-1).inject(0.0) { |sum, j| sum + l[k][j] ** 2 }
 					val = Math.sqrt(self[k,k] - sum)
 					l[k][k] = val
+
 				elsif i > k
+
 					sum = (0..k-1).inject(0.0) { |sum, j| sum + l[i][j] * l[k][j] }
 					val = (self[k,i] - sum) / l[k][k]
 					l[i][k] = val
+
 				end
 			end
 		end
@@ -64,10 +71,12 @@ class Matrix
 	def output
 		(0..self.row_size - 1).each do |row_number|
 			(0..self.column_size - 1).each do |column_number|
-				printf("%8.4f ", self[row_number, column_number])
+
+				printf('%8.4f ', self[row_number, column_number])
+
 			end
 
-			printf("\n")
+			printf('\n')
 		end
 
 		self

data/lib/opr-calc/score_set.rb

@@ -24,28 +24,28 @@ module OPRCalc
 			@ared = value
 			@opr_recalc = @dpr_recalc = @ccwm_recalc = true
 		end
-		
+
 		def ablue=(value)
 			@ablue = value
 			@opr_recalc = @dpr_recalc = @ccwm_recalc = true
 		end
-		
+
 		def scorered=(value)
 			@scorered = value
 			@opr_recalc = @dpr_recalc = @ccwm_recalc = true
 		end
-		
+
 		def scoreblue=(value)
 			@scoreblue = value
 			@opr_recalc = @dpr_recalc = @ccwm_recalc = true
 		end
 
 		def initialize(ared, ablue, scorered, scoreblue)
-			raise TypeError, "ared must be a Matrix" unless ared.is_a? Matrix
-			raise TypeError, "ablue must be a Matrix" unless ablue.is_a? Matrix
-			raise TypeError, "scorered must be a Matrix" unless scorered.is_a? Matrix
-			raise TypeError, "scoreblue must be a Matrix" unless scoreblue.is_a? Matrix
-			
+			raise TypeError, 'ared must be a Matrix' unless ared.is_a? Matrix
+			raise TypeError, 'ablue must be a Matrix' unless ablue.is_a? Matrix
+			raise TypeError, 'scorered must be a Matrix' unless scorered.is_a? Matrix
+			raise TypeError, 'scoreblue must be a Matrix' unless scoreblue.is_a? Matrix
+
 			@ared = ared
 			@ablue = ablue
 			@scorered = scorered
@@ -55,9 +55,12 @@ module OPRCalc
 		# A generic function for smooshing two matrices (one red, one blue).
 		# Each should have the same dimensions.
 		def alliance_smooshey(redmatrix, bluematrix)
-			throw ArgumentError "Matrices must have same dimensions" unless (redmatrix.row_size == bluematrix.row_size) && (redmatrix.column_size == bluematrix.column_size)
+			throw ArgumentError 'Matrices must have same dimensions' unless
+				(redmatrix.row_size == bluematrix.row_size) &&
+				(redmatrix.column_size == bluematrix.column_size)
 
-			# Then we just pull the column and row size from the red matrix because we can.
+			# Then we just pull the column and row size
+			# from the red matrix because we can.
 			column_count = redmatrix.column_size
 			row_count = redmatrix.row_size
 
@@ -72,9 +75,8 @@ module OPRCalc
 					bluematrix[row - row_count, column]
 				end
 			end
-			
-			# This will end up looking like as follows:
 
+			# This will end up looking like as follows:
 			# [[red[0]],
 			#  [red[1]],
 			#  [red[2]],
@@ -92,19 +94,20 @@ module OPRCalc
 
 		# Solve equation of form [l][x] = [s] for [x]
 		# l must be a lower triangular matrix.
-		# Based off of algorithm given at `http://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution`.
+		# Based off of algorithm given at
+		# `http://en.wikipedia.org/wiki/Triangular_matrix#Forward_and_back_substitution`.
 		def forward_substitute(l, s)
-			raise "l must be a lower triangular matrix" unless l.lower_triangular?
+			raise 'l must be a lower triangular matrix' unless l.lower_triangular?
 
 			x = Array.new s.row_size
 
 			x.size.times do |i|
 				x[i] = s[i, 0]
-				
+
 				i.times do |j|
 					x[i] -= l[i, j] * x[j]
 				end
-				
+
 				x[i] /= l[i, i]
 			end
 
@@ -114,17 +117,17 @@ module OPRCalc
 		# Solve equation of form [u][x] = [s] for [x]
 		# u must be a upper triangular matrix.
 		def back_substitute(u, s)
-			raise "u must be an upper triangular matrix" unless u.upper_triangular?
+			raise 'u must be an upper triangular matrix' unless u.upper_triangular?
 
 			x = Array.new s.row_size
 
 			(x.size - 1).downto 0 do |i|
 				x[i] = s[i, 0]
-				
+
 				(i + 1).upto(x.size - 1) do |j|
 					x[i] -= u[i, j] * x[j]
 				end
-				
+
 				x[i] /= u[i, i]
 			end
 
@@ -132,19 +135,6 @@ module OPRCalc
 		end
 
 		private :forward_substitute, :back_substitute
-		
-		# base matrix equation: [A][OPR] = [SCORE]
-		# define [A]^t to be [A] transpose
-		# define [P] to be [A]^t[A]
-		# define [S] to be [A]^t[SCORE]
-		# equation is now [P][OPR] = [S]
-		# refactor [P] as [L][L]^t using cholesky
-		# [L] is a lower triangular matrix and [L]^t an upper
-		# Therefore [L][L]^t[OPR] = [S]
-		# define [Y] = [L]^t[OPR]
-		# equation is now [L][Y] = [S]
-		# find [Y] through forward substitution
-		# find [OPR] through back substitution
 
 		def opr_calculate(a, score)
 			p = a.t * a
@@ -159,44 +149,53 @@ module OPRCalc
 			back_substitute l.t, y
 		end
 
-		# Offensive power rating: the average amount of points that a team contributes to their alliance's score.
+		# Offensive power rating: the average amount of points that a team
+		# contributes to their alliance's score.
+		#
 		# This is high for a good team.
 		def opr(recalc = false)
 			if !@opr || recalc || @opr_recalc
 				a = alliance_smooshey @ared, @ablue
 				score = alliance_smooshey @scorered, @scoreblue
-				
+
 				@opr = opr_calculate a, score
 				@opr_recalc = false
 			end
-			
+
 			@opr
 		end
 
-		# Defensive power rating: the average amount of points that a team lets the other alliance score.
+		# Defensive power rating: the average amount of points that a team lets
+		# the other alliance score.
+		#
 		# This is low for a good team.
 		def dpr(recalc = false)
 			if !@dpr || recalc || @dpr_recalc
 				a = alliance_smooshey @ared, @ablue
-				score = alliance_smooshey @scoreblue, @scorered # intentionally swapped, that's how dpr works.
-				
+
+				# scoreblue and scorered are intentionally
+				# swapped; that's how dpr works.
+				score = alliance_smooshey @scoreblue, @scorered
+
 				@dpr = opr_calculate a, score
 				@dpr_recalc = false
 			end
-			
+
 			@dpr
 		end
 
-		# Calculated contribution to winning margin: the average amount of points that a team contributes to their alliance's winning margin.
-		# This is high for a good team.
+		# Calculated contribution to winning margin: the average amount of
+		# points that a team contributes to their alliance's winning margin.
+		#
+		# This value is high for a good team.
 		def ccwm(recalc = false)
 			if !@ccwm || recalc || @ccwm_recalc
 				a = alliance_smooshey @ared, @ablue
-				
+
 				red_wm = Matrix.build(@scorered.row_size, @scorered.column_size) do |row, column|
 					@scorered[row, column] - @scoreblue[row, column]
 				end
-				
+
 				blue_wm = Matrix.build(@scoreblue.row_size, @scoreblue.column_size) do |row, column|
 					@scoreblue[row, column] - @scorered[row, column]
 				end
@@ -206,7 +205,7 @@ module OPRCalc
 				@ccwm = opr_calculate a, score
 				@ccwm_recalc = false
 			end
-			
+
 			@ccwm
 		end
 	end

data/opr-calc.gemspec

@@ -0,0 +1,26 @@
+Gem::Specification.new do |s|
+	s.name        = 'opr-calc'
+	s.email       = 'kristofer.rye@gmail.com'
+	s.version     = '1.0.0'
+
+	s.summary     = 'A tool for calculating OPR and other scouting stats for FRC teams.'
+	s.description = "A tool for calculating the OPR, DPR, and CCWM of FRC teams, allowing for more detailed analysis of a team's projected performance.  Uses the internal Ruby Matrix library for basic Matrix operations."
+
+	s.authors     = ['Kristofer Rye',
+	                 'Christopher Cooper',
+	                 'Sam Craig']
+
+	s.homepage    = 'https://github.com/frc461/opr-calc'
+	s.files       = Dir['lib/**/*.rb'] + %W[Gemfile opr-calc.gemspec LICENSE README.md Rakefile]
+	s.test_files  = Dir['spec/**/*.rb'] + %W[.rspec Guardfile]
+	s.required_ruby_version = '>= 1.9.3'
+	s.license     = 'GPL-3.0'
+
+	s.add_development_dependency 'rake', '~> 11'
+	s.add_development_dependency 'rspec', '~> 3.4'
+	s.add_development_dependency 'guard', '~> 2.14'
+	s.add_development_dependency 'guard-rspec', '~> 4.7'
+
+	s.add_development_dependency 'pry', '~> 0'
+	s.add_development_dependency 'pry-doc', '~> 0.9'
+end

data/spec/lib/opr-calc/matrix_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+describe 'opr-calc/matrix' do
+	it 'can be required without error' do
+		expect { require subject }.not_to raise_error
+	end
+end
+
+require 'opr-calc/matrix'
+
+describe Matrix do
+	context 'when symmetric' do
+		subject :symmetric_matrix do
+			Matrix[[   4,  12, -16 ],
+			       [  12,  37, -43 ],
+			       [ -16, -43,  98 ]]
+		end
+
+		describe '#symmetric?' do
+			it 'returns true' do
+				expect(symmetric_matrix.symmetric?).to be(true)
+			end
+		end
+
+		describe '#cholesky_factor' do
+			let :expected_cholesky_factorization do
+				Matrix[[ 2, 0, 0],
+				       [ 6, 1, 0],
+				       [-8, 5, 3]]
+			end
+
+			it 'returns a Matrix' do
+				expect(symmetric_matrix.cholesky_factor).to be_a(Matrix)
+			end
+
+			it 'properly calculates the Cholesky factorization' do
+				expect(symmetric_matrix.cholesky_factor).to eq(expected_cholesky_factorization)
+			end
+		end
+	end
+
+	context 'when asymmetric' do
+		subject :asymmetric_matrix do
+			Matrix[[3, 5, 3],
+			       [2, 4, 2],
+			       [5, 2, 1]]
+		end
+
+		describe '#symmetric?' do
+			it 'returns false' do
+				expect(asymmetric_matrix.symmetric?).to be(false)
+			end
+		end
+
+		describe '#cholesky_factor' do
+			it 'raises an error' do
+				expect { asymmetric_matrix.cholesky_factor }.to raise_error(ArgumentError, 'must provide a symmetric matrix')
+			end
+		end
+	end
+end

data/spec/lib/opr-calc/score_set_spec.rb

@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+describe 'opr-calc/score_set' do
+	it 'can be required without error' do
+		expect { require subject }.not_to raise_error
+	end
+end
+
+require 'opr-calc/score_set'
+require 'opr-calc/matrix'
+
+describe OPRCalc::ScoreSet do
+	context 'taking 4 valid arguments' do
+		let :ared do
+			Matrix[[1, 0, 1, 0, 1, 0, 0, 0, 0, 0],
+			       [0, 1, 0, 1, 0, 1, 0, 0, 0, 0],
+			       [0, 0, 0, 0, 1, 1, 1, 0, 0, 0],
+			       [0, 0, 0, 0, 0, 0, 0, 1, 1, 1],
+			       [0, 1, 0, 0, 0, 1, 1, 0, 0, 0],
+			       [1, 0, 0, 1, 0, 0, 1, 0, 0, 0]]
+		end
+
+		let :ablue do
+			Matrix[[0, 0, 1, 0, 0, 0, 0, 1, 0, 1],
+			       [1, 0, 0, 0, 1, 0, 0, 0, 1, 0],
+			       [1, 1, 1, 0, 0, 0, 0, 0, 0, 0],
+			       [0, 0, 1, 0, 0, 1, 1, 0, 0, 0],
+			       [0, 0, 0, 1, 0, 0, 0, 0, 1, 1],
+			       [0, 1, 0, 0, 1, 0, 0, 1, 0, 0]]
+		end
+
+		let :scorered do
+			Matrix[[6],
+			       [9],
+			       [15],
+			       [24],
+			       [12],
+			       [9]]
+		end
+
+		let :scoreblue do
+			Matrix[[18],
+			       [12],
+			       [3],
+			       [13],
+			       [20],
+			       [12]]
+		end
+
+		subject do
+			OPRCalc::ScoreSet.new ared, ablue, scorered, scoreblue
+		end
+
+		describe '#opr' do
+			let :expected do
+				Matrix[[0],
+				       [1],
+				       [2],
+				       [3],
+				       [4],
+				       [5],
+				       [6],
+				       [7],
+				       [8],
+				       [9]]
+			end
+
+			it 'produces a fully Numeric OPR vector that is finite' do
+				subject.opr.each do |cell|
+					expect(cell).to be_a(Numeric)
+					expect(cell).to be_finite
+				end
+			end
+
+			it 'produces the expected OPR' do
+				expect(subject.opr.round).to eq(expected)
+			end
+		end
+
+		describe '#dpr' do
+			it 'produces a fully Numeric DPR vector that is finite' do
+				subject.dpr.each do |cell|
+					expect(cell).to be_a(Numeric)
+					expect(cell).to be_finite
+				end
+			end
+		end
+
+		describe '#ccwm' do
+			it 'produces a fully Numeric CCWM vector that is finite' do
+				subject.ccwm.each do |cell|
+					expect(cell).to be_a(Numeric)
+					expect(cell).to be_finite
+				end
+			end
+
+			it 'produces the correct OPR-DPR values' do
+				expect(subject.ccwm.round(2)).to eq((subject.opr - subject.dpr).round(2))
+			end
+		end
+	end
+end