Indicator value override (#15)

* tighten indicator identification
* add testing workflow
* allow the user to hardcode calculated indicator values

Author: Tom Pearson

npm-publish.yml renamed to .github/workflows/npm-publish.yml

@@ -39,7 +39,7 @@ There will often be ancillary imformation associated with each entity, things li
 ---
 ## API
 
-### indexCore(_indicators:Array_, _entities:Array_, [_indexMax:Number_])
+### indexCore(_indicators:Array_, _entities:Array_, [_indexMax:Number=100_],[_allowOverwrite:Boolean=true_])
 
 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. 
 
@@ -68,7 +68,10 @@ __entities__ is an array of enetity objects
 
 Take a look at the data source descriptions for a fuller description of the properties these objects might take: [indicators](#data-indicators) [entities](#data-entities)
 
-__indexMax__, optional. is the maximum value for the index score (minimum is always 0) by thefault this is 100, other typical values are 1 and 10.
+__indexMax__, optional. is the maximum value for the index score (minimum is always 0) by default this is 100, other typical values are 1 and 10.
+
+__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.
+
 
 ### indexCore.__adjustValue(_entityName:String_, _indicatorID:String_, _value:Number_)__
 A function that allows the user to adjust an entity's indicator score within the index the index is recalculated using the new value. The index is recalculated after calling this function.

README.md

@@ -1,8 +1,8 @@
-name,1.1,1.2,1.3,1.4,1.5,1.6,2.1,2.2,2.3.1,2.3.2,3.1,3.2
-Catan,5,5,5,8,1.5,7,6,4,1,0,35,70
-Monopoly,4,4,9,6,2,2,4,4,1,0,19,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
+name,1,1.1,1.2,1.3,1.4,1.5,1.6,2.1,2.2,2.3.1,2.3.2,3.1,3.2
+Catan,10,5,5,5,8,1.5,7,6,4,1,0,35,70
+Monopoly,,4,4,9,6,2,2,4,4,1,0,19,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

data/simple-index-set/entities.csv

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

package.json

@@ -2,7 +2,7 @@ import { calculateWeightedMean, clone, normalise } from './utils.js';
 
 const indicatorIdTest = /^([\w]\.)*\w{1}$/;
 
-function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100) {
+function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100, allowOverwrite = true) {
   if (indicatorsData.length === 0 || entitiesData.length === 0) return {};
   const indicatorLookup = Object.fromEntries(
     indicatorsData
@@ -92,24 +92,30 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100) {
     };
   }
 
-  function indexEntity(entity, calculationList) {
+  function indexEntity(entity, calculationList, overwrite = allowOverwrite) {
     const newEntity = clone(entity);
     calculationList.forEach((indicatorID) => {
-      if (newEntity[indicatorID]) { console.log('overwriting', 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))
-        .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);
+      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))
+          .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);
+      }else{
+        console.log(`retaining existing value for ${newEntity.name} - ${indicatorID} : ${Number(entity[indicatorID])}`)
+        newEntity[indicatorID] = Number(entity[indicatorID]);
+      }
     });
 
     const pillarIndicators = indicatorsData
-      .filter((indicator) => indicator.id.match(indicatorIdTest) && indicator.id.split('.').length === 1)
+      .filter((indicator) => String(indicator.id).match(indicatorIdTest) && indicator.id.split('.').length === 1)
       .map((indicator) => formatIndicator(indicator, newEntity, indexMax));
 
     newEntity.value = calculateWeightedMean(pillarIndicators, indexMax);
@@ -156,10 +162,10 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100) {
     return tree;
   }
 
-  function calculateIndex() {
+  function calculateIndex(overwrite = allowOverwrite) {
     const onlyIdIndicators = indicatorsData
       .filter((i) =>{
-        const isIndicator = i.id.match(indicatorIdTest)
+        const isIndicator = String(i.id).match(indicatorIdTest)
         const isExcluded = excludeIndicator(i);
         return isIndicator && !isExcluded;
       });
@@ -173,7 +179,7 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100) {
     indexStructure = createStructure(onlyIdIndicators.map((i) => i.id));
 
     entitiesData.forEach((entity) => {
-      const indexedEntity = indexEntity(entity, calculationList);
+      const indexedEntity = indexEntity(entity, calculationList, overwrite);
       indexedEntity.data = entity;
       indexedData[entity.name] = indexedEntity;
     });
@@ -186,12 +192,12 @@ function indexCore(indicatorsData = [], entitiesData = [], indexMax = 100) {
     calculateIndex();
   }
 
-  function filterIndicators(exclude = ()=>false){
+  function filterIndicators(exclude = ()=>false, overwrite=allowOverwrite){
     excludeIndicator = exclude;
-    calculateIndex();  
+    calculateIndex(overwrite);  
   }
 
-  calculateIndex();
+  calculateIndex(allowOverwrite);
 
   return {
     adjustValue,

src/index-core.js

@@ -47,4 +47,14 @@ test('diverging indicator index-core', ()=>{
   const simpleIndex = indexCore(simpleIndicators, simpleEntities);
   expect(simpleIndex.indexedData['Tigris and Eurphrates']['2.3']).toBe(70);
   expect(simpleIndex.indexedData['Twilight Imperium']['2.3']).toBe(70);
+})
+
+test('indicator overide index-core', ()=>{
+  const simpleIndexOverwrite = indexCore(simpleIndicators, simpleEntities, undefined, true);
+  expect(simpleIndexOverwrite.indexedData['Catan']['1']).toBe(46.66666666666667);
+  expect(simpleIndexOverwrite.indexedData['Twilight Imperium']['2.3']).toBe(70);
+
+  const simpleIndex = indexCore(simpleIndicators, simpleEntities, undefined, false);
+  expect(simpleIndex.indexedData['Catan']['1']).toBe(10);
+  expect(simpleIndex.indexedData['Twilight Imperium']['2.3']).toBe(70);
 })