@quenty/elo 7.2.0 → 7.3.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [7.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/elo@7.2.0...@quenty/elo@7.3.0) (2024-04-28)
+
+
+### Features
+
+* Add EloUtils percentile helper logic ([d2b4910](https://github.com/Quenty/NevermoreEngine/commit/d2b4910b93570f30c1060f78992286b1bf6a7698))
+
+
+
+
+
 # [7.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/elo@7.1.1...@quenty/elo@7.2.0) (2024-04-27)
 
 **Note:** Version bump only for package @quenty/elo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/elo",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Elo rating utility library.",
   "keywords": [
     "Roblox",
@@ -33,5 +33,8 @@
     "@quenty/loader": "^10.2.0",
     "@quenty/maid": "^3.1.0"
   },
-  "gitHead": "5c9eab1eac73f0d54953cca5017b7be968182f72"
+  "dependencies": {
+    "@quenty/probability": "^2.2.0"
+  },
+  "gitHead": "1f65df4adb6f3c04fb25d70bfa93f0f7c332c143"
 }

package/src/Shared/EloUtils.lua

@@ -26,6 +26,7 @@ local require = require(script.Parent.loader).load(script)
 
 local EloMatchResult = require("EloMatchResult")
 local EloMatchResultUtils = require("EloMatchResultUtils")
+local Probability = require("Probability")
 
 local EloUtils = {}
 
@@ -64,6 +65,57 @@ end
 ]=]
 function EloUtils.isEloConfig(config)
 	return type(config) == "table"
+		and type(config.factor) == "number"
+		and (type(config.kfactor) == "number" or type(config.kfactor) == "function")
+		and type(config.initial) == "number"
+		and type(config.ratingFloor) == "number"
+		and type(config.groupMultipleResultAsOne) == "boolean"
+end
+
+--[=[
+	Gets the standard deviation of the elo curve
+
+	@param eloConfig EloConfig
+	@return number
+]=]
+function EloUtils.getStandardDeviation(eloConfig)
+	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
+
+	return 0.5*eloConfig.factor*math.sqrt(2)
+end
+
+--[=[
+	Gets the standard deviation of the elo curve from 0 to 1
+
+	@param eloConfig EloConfig
+	@param elo number
+	@return number
+]=]
+function EloUtils.getPercentile(eloConfig, elo)
+	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
+
+	local standardDeviation = EloUtils.getStandardDeviation(eloConfig)
+	local mean = eloConfig.initial
+
+	local zScore = (elo - mean)/standardDeviation
+	return Probability.cdf(zScore)
+end
+
+--[=[
+	Gets the standard deviation of the elo curve from 0 to 1
+
+	@param eloConfig EloConfig
+	@param percentile number
+	@return number
+]=]
+function EloUtils.percentileToElo(eloConfig, percentile)
+	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
+
+	local standardDeviation = EloUtils.getStandardDeviation(eloConfig)
+	local mean = eloConfig.initial
+
+	local zScore = Probability.percentileToZScore(percentile)
+	return mean + zScore*standardDeviation
 end
 
 --[=[

package/src/Shared/EloUtils.spec.lua

@@ -64,5 +64,11 @@ return function()
 			expect(winChange > drawChange ).to.equal(true)
 			expect(drawChange > lossChange).to.equal(true)
 		end)
+
+		it("should compute percentile as 0.5", function()
+			local percentile = EloUtils.getPercentile(config, 1400)
+
+			expect(percentile).to.equal(0.5)
+		end)
 	end)
 end