Add clamping (#21)

* add new test data
* add clamping and tests to index-core
* add clamping and tests to the utils
* docs

Author: Tom Pearson

README.md

@@ -39,7 +39,7 @@ There will often be ancillary imformation associated with each entity, things li
 ---
 ## API
 
-### indexCore(_indicators:Array_, _entities:Array_, [_indexMax:Number=100_],[_allowOverwrite:Boolean=true_])
+### indexCore(_indicators:Array_, _entities:Array_, [_indexMax:Number=100_],[_allowOverwrite:Boolean=true_],[_clamp=false_])
 
 indexCore constructs and calculates an index it returns an `index` object allowing access to results of the calculation for all the entities at a give indicator level, the structure of the index as a whole and methods for adjusting indicator values and weightings. 
 
@@ -72,6 +72,7 @@ __indexMax__, optional. is the maximum value for the index score (minimum is alw
 
 __allowOverwrite__, optional. By default this is set to true ensuring that all calculated values _will_ be calculated by the module. If set to false, calculated values that are supplied in the `entities` sheet will take precedence. Most of the time you don't want to do this but it might be a handy escape hatch.
 
+__clamp__, optional. By default this is set to false. Indicator values above the max or below the min values for that indicator will not be constrained therefor normalised values may lie outside the expected range. Set to true if you want you values constrained.
 
 ### indexCore.__adjustValue(_entityName:String_, _indicatorID:String_, _value:Number_)__
 A function that allows the user to adjust an entity's (_entityName_) indicator (_indicatorID_) score to a specified _value_. Calculated values for that entity are re-calculated using the new value. If the function is called without _value_ the indicator is reset to it's inital value. If the function is called without _indicatorId_ or _value_ all indicators on the entity are reset to their initial values. As a convenience the function returns an object with all the recalculated values.

data/simple-index-set/entities.csv

@@ -5,4 +5,5 @@ Brass: Birmingham,,8,8,3,7,3,6,7,7,4,10,50,100
 Treasure Island,,7,5,3,7,1.5,8,8,8,6,10,40,20
 Tigris and Eurphrates,,8,5,4,6,1,7,3,6,1,5,35,100
 The Crew,,8,4,7,6,.5,7,3,6,0,0,13,30
-Twilight Imperium,,6,7,4,4,7,8,8,6,1,-5,90,10
+Twilight Imperium,,6,7,4,4,7,8,8,6,1,-5,90,10
+Chinatown,,7,5,7,20,1,8,8,7,4,0,45,90

data/simple-index-set/indicators.csv

@@ -5,7 +5,7 @@ id,indicatorName,min,max,invert,diverging,weighting,type,
 1.1,thinkyness,0,10,,,1,,
 1.2,rules complexity,0,10,,,1,,
 1.3,mechanical familiarity,0,10,,,1,,
-1.4 ,rule book quality,0,10,,,1,,
+1.4,rule book quality,0,10,,,1,,
 1.5,play length,0.5,8,,,1,,
 1.6,fun,0,10,,,1,,
 2.1,theme integration,0,10,,,1,,

index.js

@@ -1,46 +1,17 @@
-import { clone } from './src/utils.js';
 import {csvParse} from 'd3';
 import fs from 'fs';
 import indexCore from './src/index-core.js';
 
-const waterRootDir = 'data/wateroptimisation';
+const simpleRootDir = 'data/simple-index-set';
 
-const waterIndicators = csvParse(fs.readFileSync(`${waterRootDir}/indicators.csv`, 'utf-8'));
-const waterEntities = csvParse(fs.readFileSync(`${waterRootDir}/entities.csv`, 'utf-8'));
+const simpleIndicators = csvParse(fs.readFileSync(`${simpleRootDir}/indicators.csv`, 'utf-8'));
+const simpleEntities = csvParse(fs.readFileSync(`${simpleRootDir}/entities.csv`, 'utf-8'));
 
-// const waterOptimisationIndex = indexCore(waterIndicators, waterEntities);
+const simpleIndex = indexCore(simpleIndicators, simpleEntities, 100 ,true, true);
+const simpleIndexUnrestricted = indexCore(simpleIndicators, simpleEntities);
 
-const inclusiveIternetRootDir = 'data/inclusiveinternet/2021';
+//console.log( simpleIndex.getEntity('Chinatown') )
+console.log( simpleIndex.getEntity('Chinatown').value, 'vs', simpleIndexUnrestricted.getEntity('Chinatown').value );
+console.log( simpleIndex.getEntity('Chinatown')['1'], 'vs', simpleIndexUnrestricted.getEntity('Chinatown')['1'] )
+console.log( simpleIndex.getEntity('Chinatown')['1.4'], 'vs', simpleIndexUnrestricted.getEntity('Chinatown')['1.4'] )
 
-const inclusiveInternetIndicators = csvParse(fs.readFileSync(`${inclusiveIternetRootDir}/indicators.csv`, 'utf-8'));
-const inclusiveInternetEntities = csvParse(fs.readFileSync(`${inclusiveIternetRootDir}/entities.csv`, 'utf-8'));
-const inclusiveInternetIndex = indexCore(inclusiveInternetIndicators, inclusiveInternetEntities);
-
-
-// console.log('value', inclusiveInternetIndex.indexedData['Singapore']['value'])
-// console.log('1', inclusiveInternetIndex.indexedData['Singapore']['1'])
-// console.log('1.2', inclusiveInternetIndex.indexedData['Singapore']['1.2'])
-// console.log('1.2.1', inclusiveInternetIndex.getEntityIndicator('Singapore','1.2.1'))
-
-console.log(inclusiveInternetIndex.adjustValue('Singapore','1.2.1',50));
-
-// console.log('adjusted')
-// console.log('value', inclusiveInternetIndex.indexedData['Singapore']['value'])
-// console.log('1', inclusiveInternetIndex.indexedData['Singapore']['1'])
-// console.log('1.2', inclusiveInternetIndex.indexedData['Singapore']['1.2'])
-// console.log('1.2.1', inclusiveInternetIndex.getEntityIndicator('Singapore','1.2.1'))
-
-// const simpleRootDir = 'data/simple-index-set';
-
-// const simpleIndicators = csvParse(fs.readFileSync(`${simpleRootDir}/indicators.csv`, 'utf-8'));
-// const simpleEntities = csvParse(fs.readFileSync(`${simpleRootDir}/entities.csv`, 'utf-8'));
-
-// const simpleIndex = indexCore(simpleIndicators, simpleEntities);
-// console.log(simpleIndex.indexedData['Monopoly'].value)
-// console.log(simpleIndex.indexedData['Monopoly']['1'])
-// console.log(simpleIndex.indexedData['Monopoly']['1.1'])
-// simpleIndex.adjustValue('Monopoly','1.1',10);
-// console.log('---');
-// console.log(simpleIndex.indexedData['Monopoly'].value)
-// console.log(simpleIndex.indexedData['Monopoly']['1'])
-// console.log(simpleIndex.indexedData['Monopoly']['1.1'])

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economist/index-core",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "",
   "main": "src/index-core.js",
   "type": "module",

src/index-core.js

@@ -2,7 +2,14 @@ import { calculateWeightedMean, clone, normalise } from './utils.js';
 
 const indicatorIdTest = /^([\w]\.)*\w{1}$/;
 
-function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100, allowOverwrite = true) {
+// TODO: the last 3 args, (indexMax, allowOverwrite, clamp) should proabbly be an options object
+function indexCore(
+  indicatorsData = [],
+  entitiesData = [],
+  indexMax = 100,
+  allowOverwrite = true,
+  clamp = false,
+) {
   if (indicatorsData.length === 0 || entitiesData.length === 0) return {};
   const indicatorLookup = Object.fromEntries(
     indicatorsData
@@ -56,7 +63,7 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100, allow
       if (!normalised) {
         return acc + Number(v[indicatorID]);
       }
-      return acc + normalise(Number(v[indicatorID]), indicatorRange, indexMax);
+      return acc + normalise(Number(v[indicatorID]), indicatorRange, indexMax, clamp);
     }, 0);
     return sum / length;
   }
@@ -102,18 +109,18 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100, allow
   function indexEntity(entity, calculationList, overwrite = allowOverwrite) {
     const newEntity = clone(entity);
     calculationList.forEach((indicatorID) => {
-      if ((newEntity[indicatorID] && overwrite === true)
-        || !newEntity[indicatorID]) {
+      if ((newEntity[indicatorID] && overwrite === true) || !newEntity[indicatorID]) {
         // get the required component indicators to calculate the parent value
         // this is a bit brittle maybe?
+
         const componentIndicators = indicatorsData
           .filter((indicator) => (indicator.id.indexOf(indicatorID) === 0
             && indicator.id.length === indicatorID.length + 2))
-          .filter((indicator) => !excludeIndicator(indicator))
+          .filter((indicator) => excludeIndicator(indicator) === false)
           .map((indicator) => formatIndicator(indicator, newEntity, indexMax));
         // calculate the weighted mean of the component indicators on the newEntity
         // assign that value to the newEntity
-        newEntity[indicatorID] = calculateWeightedMean(componentIndicators, indexMax);
+        newEntity[indicatorID] = calculateWeightedMean(componentIndicators, indexMax, clamp);
       } else {
         console.warn(`retaining existing value for ${newEntity.name} - ${indicatorID} : ${Number(entity[indicatorID])}`);
         newEntity[indicatorID] = Number(entity[indicatorID]);
@@ -124,7 +131,7 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100, allow
       .filter((indicator) => String(indicator.id).match(indicatorIdTest) && indicator.id.split('.').length === 1)
       .map((indicator) => formatIndicator(indicator, newEntity, indexMax));
 
-    newEntity.value = calculateWeightedMean(pillarIndicators, indexMax);
+    newEntity.value = calculateWeightedMean(pillarIndicators, indexMax, clamp);
     if (!newEntity.user) {
       newEntity.user = {};
     }

src/utils.js

@@ -2,16 +2,24 @@ export function clone(o) {
   return JSON.parse(JSON.stringify(o));
 }
 
-export function normalise(value, range = [0, 100], normaliseTo = 100) {
-  return ((value - range[0]) / (range[1] - range[0])) * normaliseTo;
+export function clamper(range, value) { // restrict a value to between the vales of a tuple
+  return Math.min(Math.max(value, range[0]), range[1]);
 }
 
-export function calculateWeightedMean(weightedValues, normaliseTo = 100) {
+export function normalise(value, range = [0, 100], normaliseTo = 100, clamp = false) {
+  let x = value;
+  if (clamp) {
+    x = clamper(range, value);
+  }
+  return ((x - range[0]) / (range[1] - range[0])) * normaliseTo;
+}
+
+export function calculateWeightedMean(weightedValues, normaliseTo = 100, clamp = false) {
   let weightedSum = 0;
   let cumulativeWeight = 0;
   for (let i = 0; i < weightedValues.length; i += 1) {
     const indicator = weightedValues[i];
-    const normalisedValue = normalise(indicator.value, indicator.range, normaliseTo);
+    const normalisedValue = normalise(indicator.value, indicator.range, normaliseTo, clamp);
     const weightedValue = indicator.invert
       ? ((normaliseTo - normalisedValue) * indicator.weight)
       : (normalisedValue * indicator.weight);

test/index-core.test.js

@@ -26,8 +26,8 @@ test('adjust indicator', ()=>{
   const adjustedValue = simpleIndex.indexedData['Monopoly'].value;
   simpleIndex.adjustValue('Monopoly');
   const resetValue = simpleIndex.indexedData['Monopoly'].value;
-  expect(originalValue.toFixed(3)).toBe('49.118')
-  expect(adjustedValue.toFixed(3)).toBe('53.118')
+  expect(originalValue.toFixed(3)).toBe('50.118')
+  expect(adjustedValue.toFixed(3)).toBe('53.451')
   expect(originalValue).toBe(resetValue);
 })
 
@@ -37,7 +37,7 @@ test('reset individual indicator', ()=>{
   simpleIndex.adjustValue('Monopoly','1.2',1);
   simpleIndex.adjustValue('Monopoly','1.2');
   const resetValue = simpleIndex.indexedData['Monopoly'].value;
-  expect(resetValue.toFixed(3)).toBe('53.118')
+  expect(resetValue.toFixed(3)).toBe('53.451')
 })
 
 test('getIndicatorMean index-core', ()=>{
@@ -72,7 +72,7 @@ test('diverging indicator index-core', ()=>{
 
 test('indicator overide index-core', ()=>{
   const simpleIndexOverwrite = indexCore(simpleIndicators, simpleEntities, undefined, true);
-  expect(simpleIndexOverwrite.indexedData['Catan']['1']).toBe(46.66666666666667);
+  expect(simpleIndexOverwrite.indexedData['Catan']['1'].toFixed(3)).toBe('52.222');
   expect(simpleIndexOverwrite.indexedData['Twilight Imperium']['2.3']).toBe(70);
 
   const simpleIndex = indexCore(simpleIndicators, simpleEntities, undefined, false);
@@ -92,4 +92,12 @@ test('check the return value from adjustValue', ()=>{
   expect(adjustedObject['1.2']).toBe(3.142);
   expect(adjustedObject['user']).toBe(undefined);
   expect(adjustedObject['data']).toBe(undefined);
+})
+
+test('test for clamped values', ()=>{
+  const clampedIndex = indexCore(simpleIndicators, simpleEntities, 100, true, true);
+  const unrestrictedIndex = indexCore(simpleIndicators, simpleEntities);
+  expect(clampedIndex.getEntity('Chinatown')['1'].toFixed(3)).toBe('62.778');
+  expect(unrestrictedIndex.getEntity('Chinatown')['1'].toFixed(3)).toBe('79.444');
+  
 })

test/utils.test.js

@@ -1,5 +1,6 @@
 import {
   calculateWeightedMean,
+  clamper,
   normalise
 } from '../src/utils';
 
@@ -59,6 +60,16 @@ test('simple weighted mean', ()=>{
 
 test('normalise', ()=>{
   const normA = normalise(32,[0,64],100);
+  const normB = normalise(100,[0,64],100, true);
+  const normC = normalise(96,[0,64],100);
   expect(normA).toBe(50);
+  expect(normB).toBe(100);
+  expect(normC).toBe(150);
 });
 
+test('clamper',()=>{
+  expect(clamper([0,100],300)).toBe(100);
+  expect(clamper([0,100],-50)).toBe(0);
+  expect(clamper([0,100],50)).toBe(50);
+})
+