@dra2020/district-analytics 1.0.3 → 1.0.6

package/src/report.ts

@@ -0,0 +1,997 @@
+//
+// GENERATE REPORTS
+// - A test log: a simple enumeration of all analytics & validations w/ raw results
+// - A scorecard: a structured subset of analytics & validations w/ normalized
+//   results, cateories, and an overall score
+// 
+
+import * as T from './types'
+import * as U from './utils';
+import * as S from './settings';
+
+import * as D from './_data'
+import { AnalyticsSession } from './_api';
+import { doDeriveSecondaryTests } from './analyze';
+
+
+// TEST META-DATA
+
+enum TestType {
+  PassFail,
+  Percentage,
+  Number
+}
+
+const completeDefn: T.Dict = {
+  ID: T.Test.Complete,
+  name: "Complete",
+  normalize: false,
+  externalType: TestType.PassFail,
+  detailsFn: doPrepareCompleteDetails,
+  suites: [T.Suite.Legal]
+};
+
+const contiguousDefn: T.Dict = {
+  ID: T.Test.Contiguous,
+  name: "Contiguous",
+  normalize: false,
+  externalType: TestType.PassFail,
+  detailsFn: doPrepareContiguousDetails,
+  suites: [T.Suite.Legal]
+};
+
+const freeOfHolesDefn: T.Dict = {
+  ID: T.Test.FreeOfHoles,
+  name: "Free of Holes",
+  normalize: false,
+  externalType: TestType.PassFail,
+  detailsFn: doPrepareFreeOfHolesDetails,
+  suites: [T.Suite.Legal]
+};
+
+const equalPopulationDefn: T.Dict = {
+  ID: T.Test.EqualPopulation,
+  name: "Equal Population",
+  normalize: false,
+  externalType: TestType.PassFail,
+  detailsFn: doPrepareEqualPopulationDetails,
+  suites: [T.Suite.Legal]
+};
+
+const populationDeviationDefn: T.Dict = {
+  ID: T.Test.PopulationDeviation,
+  name: "Population Deviation",
+  normalize: true,
+  externalType: TestType.Percentage,
+  detailsFn: doPreparePopulationDeviationDetails,
+  suites: [T.Suite.Legal, T.Suite.Best]  // Both so EqualPopulation can be assessed
+};
+
+const reockDefn: T.Dict = {
+  ID: T.Test.Reock,
+  name: "Reock",
+  normalize: true,
+  externalType: TestType.Number,
+  detailsFn: doPrepareReockDetails,
+  suites: [T.Suite.Best]
+};
+
+const polsbyPopperDefn: T.Dict = {
+  ID: T.Test.PolsbyPopper,
+  name: "Polsby-Popper",
+  normalize: true,
+  externalType: TestType.Number,
+  detailsFn: doPreparePolsbyPopperDetails,
+  suites: [T.Suite.Best]
+};
+
+const countySplitsDefn: T.Dict = {
+  ID: T.Test.CountySplits,
+  name: "County splits",
+  trailer: "of the population had their county split unexpectedly.",
+  normalize: true,                          // TODO - Normalize this for real
+  externalType: TestType.Percentage,
+  detailsFn: doPrepareCountySplitDetails,
+  suites: [T.Suite.Best]
+};
+
+const efficiencyGapDefn: T.Dict = {
+  ID: T.Test.EfficiencyGap,
+  name: "Efficiency Gap",
+  normalize: false,                         // TODO - Normalize this!
+  externalType: TestType.Percentage,
+  detailsFn: doPrepareEfficiencyGapDetails,
+  suites: [T.Suite.Fair]
+};
+
+// A structure to hold test definitions
+type TestDefns = {
+  [category: number]: any;
+}
+
+// All the tests that have been defined (can be reported on)
+const testDefns = {
+  [T.Test.Complete]: completeDefn,
+  [T.Test.Contiguous]: contiguousDefn,
+  [T.Test.FreeOfHoles]: freeOfHolesDefn,
+  [T.Test.EqualPopulation]: equalPopulationDefn,
+  [T.Test.PopulationDeviation]: populationDeviationDefn,
+  [T.Test.Reock]: reockDefn,
+  [T.Test.PolsbyPopper]: polsbyPopperDefn,
+  [T.Test.CountySplits]: countySplitsDefn,
+  [T.Test.EfficiencyGap]: efficiencyGapDefn
+
+  /* TODO - More tests ... */
+} as TestDefns;
+
+
+// SCORECARD
+
+// The notion of a scorecard is:
+// - A subset of analytics & validations
+// - Normalized, if numeric
+// - Organized into several dimensions/categories
+// - With combined category scores, and
+// - Those combined into an overall score
+
+// A scorecard
+export type Scorecard = {
+  [category: number]: ScorecardCategoryEntry;
+}
+
+type ScorecardCategoryEntry = {
+  catName: string;
+  catScore?: number | boolean;
+  catTests: T.TestEntries;
+}
+
+// A scorecard definition
+type ScorecardDefn = {
+  [category: number]: any;
+}
+
+// Scorecard category definitions
+
+const validCategory = {
+  catName: "Valid",
+  catTests: [
+    { testID: T.Test.Complete },
+    { testID: T.Test.Contiguous },
+    { testID: T.Test.FreeOfHoles },
+    { testID: T.Test.EqualPopulation }
+  ],
+  catNumeric: false,
+  catWeight: undefined,
+  catPrepareFn: doPrepareValidSection
+};
+
+const fairCategory = {
+  catName: "Fair",
+  catTests: [
+    {
+      testID: T.Test.EfficiencyGap,
+      testWeight: 100
+    }
+  ],
+  catNumeric: true,
+  catWeight: undefined,
+  catPrepareFn: doPrepareFairSection
+};
+
+// TODO - Decide on the relative weights of these tests!
+// NOTE: 'testWeights' are simply relative, i.e., each normalized score is
+//   multiplied by the associated 'testWeight', and the sum of those is divided
+//   by the total weight. Weights don't have to add to 100.
+const bestCategory = {
+  catName: "Best",
+  catTests: [
+    {
+      testID: T.Test.PopulationDeviation,
+      testWeight: 10
+    },
+    {
+      testID: T.Test.Reock,
+      testWeight: 25
+    },
+    {
+      testID: T.Test.PolsbyPopper,
+      testWeight: 25
+    },
+    {
+      testID: T.Test.CountySplits,
+      testWeight: 50
+    }
+  ],
+  catNumeric: true,
+  catWeight: undefined,
+  catPrepareFn: doPrepareBestSection
+};
+
+
+// The overall scorecard definition
+
+const scorecardDefn = {
+  [T.Suite.Legal]: validCategory,
+  // TODO - NIY
+  // [T.Suite.Fair]: fairCategory,
+  [T.Suite.Best]: bestCategory
+} as ScorecardDefn;
+
+
+// NORMALIZE RAW ANALYTICS
+//   Raw numeric analytics, such as population deviation, compactness, etc. are
+//   normalized as part of creating a scorecard, so the code to normalize results
+//   is encapsulated here.
+
+// Configure scale parameters for normalizing each raw test result
+//   This needs to be separate from the scorecard configuration info above,
+//   because some scales need access to the analytics session object.
+export function doConfigureScales(s: AnalyticsSession): void {
+  // Scale defn for PopulationDeviation
+  const CDLimit = 0.75 / 100;                 // Deviation threshold for CD's
+  const LDLimit = 10.00 / 100;                // Deviation threshold for LD's
+
+  const CDGoodEnough = 0.20 / 100;
+  const LDGoodEnough = (CDGoodEnough / CDLimit) * LDLimit;
+  const scale = (s.legislativeDistricts) ? [1.0 - LDLimit, 1.0 - LDGoodEnough] : [1.0 - CDLimit, 1.0 - CDGoodEnough];
+  // const scale = [1.0 - CDLimit, 1.0 - CDGoodEnough];
+
+  s.testScales[T.Test.PopulationDeviation] = { testScale: scale, testInvertp: true };
+
+  s.testScales[T.Test.Reock] = { testScale: [0.25, 0.50], testInvertp: false };
+  s.testScales[T.Test.PolsbyPopper] = { testScale: [0.10, 0.50], testInvertp: false };
+
+  const SPLITLimit = 0.1;  // TODO - Just a placeholder default maximum (10%)
+  s.testScales[T.Test.CountySplits] = { testScale: [1.0 - SPLITLimit, 1.0], testInvertp: true };
+
+  // TODO - More analytics ...
+}
+
+// Postprocess analytics - Normalize numeric results and derive secondary tests.
+// Do this after analytics have been run and before preparing a test log or scorecard. 
+export function doAnalyzePostProcessing(s: AnalyticsSession): void {
+  // Normalize the raw scores for all the numerics tests
+  let testResults = U.getNumericObjectKeys(testDefns);
+
+  for (let testID of testResults) {
+    if (testDefns[testID]['normalize']) {
+      let testResult = s.getTest(testID) as T.TestEntry;
+
+      let rawScore = testResult['score'] as number;
+      let normalizedScore: number;
+      let { testScale, testInvertp } = s.testScales[testID];
+
+      normalizedScore = U.normalize(rawScore, testScale, testInvertp);
+      testResult['normalizedScore'] = normalizedScore;
+
+      // Add the scale used to normalize the raw score to the details
+      testResult['details']['scale'] = testScale;
+    }
+  }
+
+  // Derive secondary tests
+  doDeriveSecondaryTests(s);
+
+  // Toggle the semaphore, so postprocessing isn't for both the testlog & scorecard
+  s.bPostProcessingDone = true;
+}
+
+// Prepare a structured but unformatted scorecard, from the test results
+function doGenerateScorecard(s: AnalyticsSession): Scorecard {
+  if (!(s.bPostProcessingDone)) {
+    doAnalyzePostProcessing(s);
+  }
+
+  // Create a new scorecard
+  let scorecard = {} as Scorecard;
+
+  // Filter the defined scorecard categories by the requested test suites
+  let categories = U.getNumericObjectKeys(scorecardDefn);
+  let suitesRequested = s.config['suites'];
+  categories = categories.filter(x => suitesRequested.includes(x));
+
+  // ... and initialize each one in the new scorecard
+  for (let c of categories) {
+    scorecard[c] = {} as ScorecardCategoryEntry;
+    scorecard[c]['catName'] = scorecardDefn[c]['catName'];
+    scorecard[c]['catTests'] = {} as T.TestEntries;
+    // scorecard[c]['catScore'] = undefined;
+  }
+
+  // For each scorecard category
+  for (let c of categories) {
+    // Grab the scorecard category definition
+    let { catName, catTests, catNumeric } = scorecardDefn[c];
+
+    let numericCategoryScore = 0;
+    let totalWeight = 0;
+    let booleanCategoryScore = true;
+
+    // Process the results for each test result in the category
+    for (let testDefn of catTests) {
+      // Get the config info for the test
+      let testID = testDefn['testID'];
+      // ... and the actual test result
+      let testResult = s.getTest(testID) as T.TestEntry;
+
+      // Create a new test entry for the scorecard
+      let testReport = U.deepCopy(testResult);
+      // Add the name
+      testReport['name'] = testDefns[testID]['name'];
+
+      if (catNumeric) {
+        // Normalize raw numeric scores ... moved to FIRST PASS above
+
+        // Accumulate a category score
+        let normalizedScore = testReport['normalizedScore'];
+        numericCategoryScore += normalizedScore * testDefn['testWeight'];
+        totalWeight += testDefn['testWeight'];
+      }
+      else {
+        // AND together pass/fail tests into a category score
+        if (!testReport['score']) {
+          booleanCategoryScore = false;
+        }
+      }
+      scorecard[c]['catTests'][testID] = testReport;
+    }
+
+    // Set the category score
+    if (catNumeric) {
+      scorecard[c]['catScore'] = Math.round(numericCategoryScore / totalWeight);
+    }
+    else {
+      scorecard[c]['catScore'] = booleanCategoryScore;
+    }
+  }
+  // TODO - Compute an overall score from the category weights
+
+  return scorecard;
+}
+
+// Prepare a formatted scorecard suitable for rendering
+export function doPrepareScorecard(s: AnalyticsSession): any {
+  // Initialize the output format
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  // If the plan as already been analyzed, prepare a scorecard
+  if (s.bPlanAnalyzed) {
+    // Create and cache a new, unformatted scorecard
+    s.scorecard = doGenerateScorecard(s);
+
+    // Create a scorecard header
+    blocks.push({ variant: 'h4', text: `Analysis` });
+
+    // Report district statistics
+    blocks.push({ variant: 'h5', text: `Individual Districts` });
+    let districtStatisticsText = doPrepareDistrictStatistics(s);
+    blocks.push(...districtStatisticsText);
+
+    // Prepare each scorecard category
+    blocks.push({ variant: 'h5', text: `Overall Plan` });
+    let categories = U.getNumericObjectKeys(s.scorecard);
+    for (let c of categories) {
+      let sectionPrepareFn = scorecardDefn[c]['catPrepareFn'];
+      let sectionText = sectionPrepareFn(s, c);
+      blocks.push(...sectionText);
+    }
+
+    // Report what datasets were used
+    let c = s.config['datasets'][D.Dataset.CENSUS];
+    let v = s.config['datasets'][D.Dataset.VAP];
+    let e = s.config['datasets'][D.Dataset.ELECTION];
+
+    blocks.push({ variant: 'body1', text: `Using datasets:` });
+    blocks.push({ variant: 'body1', text: `* ${c}: ${D.DatasetDescriptions[c]}` });
+    blocks.push({ variant: 'body1', text: `* ${v}: ${D.DatasetDescriptions[v]}` });
+    blocks.push({ variant: 'body1', text: `* ${e}: ${D.DatasetDescriptions[e]}` });
+  }
+  // Otherwise, return a blank scorecard
+
+  // TODO - What dra-client returns from renderAnalyzeCore()
+  // return <STV.StaticTextView text={ text } />;
+  return text;
+}
+
+function doPrepareDistrictStatistics(s: AnalyticsSession): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  blocks.push({ variant: 'beginTable' });
+  blocks.push({ variant: 'row', cells: ['ID', 'Total', 'Δ%', 'OK?', '*', 'Dem', 'Rep', 'White', 'Minority', 'Black', 'Hispanic', 'Pacific', 'Asian', 'Native'] });
+
+  for (let d = 0; d < s.districts.numberOfRows(); d++) {
+    let tot = s.districts.statistics[D.DistrictField.TotalPop][d];
+    if (tot == 0)
+      blocks.push({ variant: 'row', cells: [String(d), '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-'] });
+    else {
+      tot = Math.round(tot);
+      let dev = fractionToPercentage(s.districts.statistics[D.DistrictField.PopDevPct][d]);
+      let bEq = true;  // TODO - Set based on population threshold
+      let bC = s.districts.statistics[D.DistrictField.bContiguous][d]
+        && s.districts.statistics[D.DistrictField.bNotEmbedded][d];
+      let dPct = fractionToPercentage(s.districts.statistics[D.DistrictField.DemPct][d]);
+      let rPct = fractionToPercentage(s.districts.statistics[D.DistrictField.RepPct][d]);
+      let wPct = fractionToPercentage(s.districts.statistics[D.DistrictField.WhitePct][d]);
+      let mPct = fractionToPercentage(s.districts.statistics[D.DistrictField.MinorityPct][d]);
+      let bPct = fractionToPercentage(s.districts.statistics[D.DistrictField.BlackPct][d]);
+      let hPct = fractionToPercentage(s.districts.statistics[D.DistrictField.HispanicPct][d]);
+      let pPct = fractionToPercentage(s.districts.statistics[D.DistrictField.PacificPct][d]);
+      let aPct = fractionToPercentage(s.districts.statistics[D.DistrictField.AsianPct][d]);
+      let nPct = fractionToPercentage(s.districts.statistics[D.DistrictField.NativePct][d]);
+
+      let id: string;
+      if (d == 0) id = "??";
+      else if (d == (s.districts.numberOfRows() - 1)) id = "  ";
+      else id = String(d);
+
+      blocks.push({
+        variant: 'row',
+        cells: [
+          `${id}`,
+          `${formatInteger(tot)}`,
+          `${formatPercentage(dev)}%`,
+          `${pfBoolToString(bEq)}`,
+          `${pfBoolToString(bC)}`,
+          `${formatPercentage(dPct)}%`,
+          `${formatPercentage(rPct)}%`,
+          `${formatPercentage(wPct)}%`,
+          `${formatPercentage(mPct)}%`,
+          `${formatPercentage(bPct)}%`,
+          `${formatPercentage(hPct)}%`,
+          `${formatPercentage(pPct)}%`,
+          `${formatPercentage(aPct)}%`,
+          `${formatPercentage(nPct)}%`]
+      });
+    }
+  }
+  blocks.push({ variant: 'endTable' });
+
+  return blocks;
+}
+
+// TEST LOG
+
+// Prepare formatted test results for rendering
+export function doPrepareTestLog(s: AnalyticsSession): any {
+  // Initialize the output format
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  // If the plan as already been analyzed, prepare a test log
+  if (s.bPlanAnalyzed) {
+    if (!(s.bPostProcessingDone)) {
+      doAnalyzePostProcessing(s);
+    }
+
+    // Create a test log header
+    blocks.push({ variant: 'h4', text: `Test Log` });
+
+    let testResults = U.getNumericObjectKeys(testDefns);
+    let suitesRequested = new Set(s.config['suites']);
+
+    for (let testID of testResults) {
+      // Filter the defined tests by the requested test suites
+      let inSuites: number[] = testDefns[testID]['suites'];
+      if (!(U.isArrayEmpty(inSuites.filter(x => suitesRequested.has(x))))) {
+        // Get the test result
+        let testResult = s.getTest(testID) as T.TestEntry;
+        // Prepare the text for it, and append it to the output
+        let testText = prepareTestEntry(testID, testResult);
+        blocks.push(...testText);
+      }
+    }
+  }
+  // Otherwise, return a blank test log
+
+  // TODO - What dra-client returns from renderAnalyzeCore()
+  // return <STV.StaticTextView text={ text } />;
+  return text;
+}
+
+function prepareTestEntry(testID: number, testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  let testName = testDefns[testID]['name'];
+  let testNameTrailer: string = "";
+  if (U.keyExists('trailer', testDefns[testID])) {
+    testNameTrailer = testDefns[testID]['trailer'];
+  }
+  let testType = testDefns[testID]['externalType'];
+  let bNormalize = testDefns[testID]['normalize'];
+  let detailsFn = testDefns[testID]['detailsFn'];
+  let detailsText = detailsFn(testResult);
+  let score: number | boolean | undefined;  // NOTE - Won't be undefined here
+  let normalizedScore: number;
+  let scoreText: string;
+
+  // Get the score ...
+  score = testResult['score'];
+
+  // ... and format it for rendering
+  switch (testType) {
+    case TestType.PassFail: {
+      scoreText = pfBoolToString(score as boolean);
+      blocks.push({ variant: 'body1', text: `${testName}: ${scoreText} ${testNameTrailer}` });
+      break;
+    }
+    case TestType.Percentage: {
+      score = fractionToPercentage(score as number);
+      if (bNormalize) {
+        normalizedScore = testResult['normalizedScore'] as number;
+        blocks.push({ variant: 'body1', text: `${testName}: ${normalizedScore} / 100 : ${formatPercentage(score)}% ${testNameTrailer}` });
+      }
+      else {
+        blocks.push({ variant: 'body1', text: `${testName}: ${formatPercentage(score)}% ${testNameTrailer}` });
+      }
+      break;
+    }
+    case TestType.Number: {
+      if (bNormalize) {
+        normalizedScore = testResult['normalizedScore'] as number;
+        blocks.push({ variant: 'body1', text: `${testName}: ${normalizedScore} / 100 : ${formatNumber(score as number)} ${testNameTrailer}` });
+      }
+      else {
+        blocks.push({ variant: 'body1', text: `${testName}: ${formatNumber(score as number)} ${testNameTrailer}` });
+      }
+      break;
+    }
+    default: {
+      // Unknown test type
+      throw new RangeError();
+    }
+  }
+
+  // Add the details text
+  blocks.push(...detailsText);
+
+  return blocks;
+}
+
+
+// FORMATTERS FOR TEST DETAILS
+
+function doPrepareCompleteDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  if (!U.isObjectEmpty(testResult['details'])) {
+    let unassignedText = "";
+    let emptyText = "";
+    let missingText = "";
+
+    if (U.keyExists('unassignedFeatures', testResult['details'])) {
+      let unassignedFeatures = testResult['details']['unassignedFeatures'];
+
+      let unassignedList = prepareListItems(unassignedFeatures);
+      let unassignedTextTemplates: string[] = [
+        `GEOID ${unassignedList} is not assigned to a district.`,
+        `GEOIDs ${unassignedList} are not assigned to districts.`,
+        `Several GEOIDs are not assigned to districts, including ${unassignedList}.`
+      ];
+      unassignedText = prepareListText(unassignedFeatures, unassignedTextTemplates);
+    }
+
+    if (U.keyExists('emptyDistricts', testResult['details'])) {
+      let emptyDistricts = testResult['details']['emptyDistricts'];
+
+      let emptyList = prepareListItems(emptyDistricts);
+      let emptyTextTemplates: string[] = [
+        `District ${emptyList} is empty.`,
+        `Districts ${emptyList} are empty.`,
+        `Several districts are empty, including ${emptyList}.`
+      ];
+      emptyText = prepareListText(emptyDistricts, emptyTextTemplates);
+    }
+
+    if (U.keyExists('missingDistricts', testResult['details'])) {
+      missingText = `Not enough districts have been defined. `;
+    }
+
+    let detailsText = "  " + unassignedText + emptyText + missingText;
+    blocks.push({ variant: 'body1', text: detailsText });
+  }
+
+  return blocks;
+}
+
+function doPrepareContiguousDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  if (!U.isObjectEmpty(testResult['details'])) {
+    let discontiguousDistricts = testResult['details']['discontiguousDistricts'];
+
+    let discontiguousList = prepareListItems(discontiguousDistricts);
+    let discontiguousTextTemplates: string[] = [
+      `District ${discontiguousList} is not contiguous.`,
+      `Districts ${discontiguousList} are not contiguous.`,
+      `Several districts are not contiguous, including ${discontiguousList}.`
+    ];
+    let detailsText = prepareListText(discontiguousDistricts, discontiguousTextTemplates);
+
+    blocks.push({ variant: 'body1', text: detailsText });
+  }
+
+  return blocks;
+}
+
+function doPrepareFreeOfHolesDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  if (!U.isObjectEmpty(testResult['details'])) {
+    let embeddedDistricts = testResult['details']['embeddedDistricts'];
+
+    let embeddedList = prepareListItems(embeddedDistricts);
+    let embeddedTextTemplates: string[] = [
+      `District ${embeddedList} is fully embedded within another district.`,
+      `Both districts ${embeddedList} are fully embedded within other districts.`,
+      `Several districts are fully embedded within other districts, including ${embeddedList}.`
+    ];
+    let detailsText = prepareListText(embeddedDistricts, embeddedTextTemplates);
+
+    blocks.push({ variant: 'body1', text: detailsText });
+  }
+
+  return blocks;
+}
+
+function doPrepareEqualPopulationDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  if (!U.isObjectEmpty(testResult['details'])) {
+    let popDevPct = fractionToPercentage(testResult['details']['deviation']);
+    let thresholdPct = fractionToPercentage(1.0 - testResult['details']['thresholds'][0]);
+
+    let detailsText = '';
+    if (!(testResult['score'])) {
+      detailsText = `The ${formatPercentage(popDevPct)}% population deviation is greater than the ${formatPercentage(thresholdPct)}% threshold tolerated by courts.`;
+    }
+    blocks.push({ variant: 'body1', text: detailsText });
+  }
+
+  return blocks;
+}
+
+function doPreparePopulationDeviationDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  let n = Math.round(testResult['details']['maxDeviation']);
+  let term: string = "people";
+  if (n == 1) {
+    term = "person";
+  }
+  blocks.push({ variant: 'body1', text: `The maximum population deviation between districts is ${formatInteger(n)} ${term}.` });
+
+  return blocks;
+}
+
+function doPrepareReockDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  // TODO - No details implemented yet
+
+  return blocks;
+}
+
+function doPreparePolsbyPopperDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  // TODO - No details implemented yet
+
+  return blocks;
+}
+
+function doPrepareEfficiencyGapDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  // TODO - Not yet implemented
+
+  return blocks;
+}
+
+function doPrepareCountySplitDetails(testResult: T.TestEntry): any {
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+
+  let unexpectedAffected = fractionToPercentage(testResult['details']['unexpectedAffected']);
+  let affectedText = `affecting ${formatPercentage(unexpectedAffected)}% of the total population.`;
+
+  let countiesSplitUnexpectedly = testResult['details']['countiesSplitUnexpectedly'];
+  let nCountiesSplitUnexpectedly = countiesSplitUnexpectedly.length;
+  let nUnexpectedSplits = testResult['details']['unexpectedSplits'];
+  let splitList = prepareListItems(countiesSplitUnexpectedly);
+  let splitTextTemplates: string[] = [
+    `${splitList} county is split unexpectedly, `,
+    `${splitList} counties are split unexpectedly, `,
+    // `These ${formatInteger(nCountiesSplitUnexpectedly)} counties are split unexpectedly--${splitList}--`
+    `${splitList} counties are split unexpectedly ${formatInteger(nUnexpectedSplits)} times, `
+
+  ];
+  let detailsText = prepareListText(countiesSplitUnexpectedly, splitTextTemplates) + affectedText;
+
+  blocks.push({ variant: 'body1', text: detailsText });
+
+  return blocks;
+}
+
+
+// FORMATTERS FOR CATEGORIES
+
+// This function parses & formats the 'Valid' section of a scorecard.
+function doPrepareValidSection(s: AnalyticsSession, c: number): any {
+  // Get the category meta data
+  let { catName, catScore, catTests } = s.scorecard[c];
+  let testReport: T.TestEntry;
+
+  // Initialize the section text
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+  let testText: any;
+
+  // Section header
+  let stringScore = pfBoolToString(catScore as boolean);
+  blocks.push({ variant: 'h6', text: `${catName}: ${stringScore}` });
+
+  // Complete
+  testReport = catTests[T.Test.Complete];
+  testText = prepareTestEntry(T.Test.Complete, testReport);
+  blocks.push(...testText);
+
+  // Contiguous
+  testReport = catTests[T.Test.Contiguous];
+  testText = prepareTestEntry(T.Test.Contiguous, testReport);
+  blocks.push(...testText);
+
+  // Free of holes (no embedded districts)
+  testReport = catTests[T.Test.FreeOfHoles];
+  testText = prepareTestEntry(T.Test.FreeOfHoles, testReport);
+  blocks.push(...testText);
+
+  // Equal population (w/in the appropriate legal threshold)
+  testReport = catTests[T.Test.EqualPopulation];
+  testText = prepareTestEntry(T.Test.EqualPopulation, testReport);
+  blocks.push(...testText);
+
+  return blocks;
+}
+
+// TODO - NIY
+// This function parses & formats the 'Fair' section of a scorecard.
+function doPrepareFairSection(s: AnalyticsSession, c: number): any {
+  // Get the category meta data
+  let { catName, catScore, catTests } = s.scorecard[c];
+  let testReport: T.TestEntry;
+
+  // Initialize the section text
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+  let testText: any;
+
+  // Section header
+  blocks.push({ variant: 'h6', text: `${catName}: ${catScore}` });
+
+  // TODO - Flesh this out
+  // There's only one test: Population Deviation.
+  // testReport = catTests[T.Test.PopulationDeviation];
+  // testText = prepareTestEntry(T.Test.PopulationDeviation, testReport);
+  // blocks.push(...testText);
+
+  return blocks;
+}
+
+// This function parses & formats the 'Best' section of a scorecard.
+function doPrepareBestSection(s: AnalyticsSession, c: number): any {
+  // Get the category meta data
+  let { catName, catScore, catTests } = s.scorecard[c];
+  let testReport: T.TestEntry;
+
+  // Initialize the section text
+  let text: any = { data: [] };
+  let blocks: any = text.data;
+  let testText: any;
+
+  // Section header
+  blocks.push({ variant: 'h6', text: `${catName}: ${catScore}` });
+
+  // Population deviation
+  testReport = catTests[T.Test.PopulationDeviation];
+  testText = prepareTestEntry(T.Test.PopulationDeviation, testReport);
+  blocks.push(...testText);
+
+  // Compactness
+  testReport = catTests[T.Test.Reock];
+  let normalizedReock = testReport['normalizedScore'] as number;
+  let reockTestText = prepareTestEntry(T.Test.Reock, testReport);
+
+  testReport = catTests[T.Test.PolsbyPopper];
+  let normalizedPolsbyPopper = testReport['normalizedScore'] as number;
+  let polsbyPopperTestText = prepareTestEntry(T.Test.PolsbyPopper, testReport);
+
+  let compactnessScore = (normalizedReock + normalizedPolsbyPopper) / 2;
+  blocks.push({ variant: 'body1', text: `Compactness: ${compactnessScore} / 100` });
+
+  blocks.push(...reockTestText);
+  blocks.push(...polsbyPopperTestText);
+
+  // County splits
+  testReport = catTests[T.Test.CountySplits];
+  testText = prepareTestEntry(T.Test.CountySplits, testReport);
+  blocks.push(...testText);
+
+  return blocks;
+}
+
+// FORMATTING HELPERS
+
+// Convert a boolean representing Pass/Fail to a string
+function pfBoolToString(score: boolean): string {
+  if (score) {
+    return "Yes";
+  }
+  else {
+    return "No";
+  }
+}
+
+function fractionToPercentage(f: number): number {
+  return f * 100;
+}
+
+function formatNumber(n: number): string {
+  let p = S.PRECISION;
+
+  return n.toLocaleString('en-US', { minimumFractionDigits: p, maximumFractionDigits: p });
+}
+
+function formatPercentage(n: number): string {
+  let p = (S.PRECISION / 2);
+
+  return n.toLocaleString('en-US', { minimumFractionDigits: p, maximumFractionDigits: p });
+}
+
+function formatInteger(i: number): string {
+  return new Intl.NumberFormat().format(i);
+}
+
+// Prepare the items in a list for rendering
+function prepareListItems(list: any[]): string {
+  let nItems = list.length;
+  let listStr: string;
+
+  switch (nItems) {
+    case 1: {
+      listStr = list[0];
+      break;
+    }
+    case 2: {
+      listStr = list[0] + " and " + list[1];
+      break;
+    }
+    default: {
+      let listWithCommas = list.join(', ');
+      let lastCommaIndex = listWithCommas.length - ((list[list.length - 1].length) + 1);
+      let beforeAnd = listWithCommas.substr(0, lastCommaIndex);
+      let afterAnd = listWithCommas.substr(lastCommaIndex + 1);
+      listStr = beforeAnd + " and " + afterAnd;
+      break;
+    }
+  }
+  return listStr;
+}
+
+// Pick the rendering text for the appropriate list length
+function prepareListText(list: any[], listTemplates: string[]): string {
+  let nItems = list.length;
+  switch (nItems) {
+    case 1: {
+      return listTemplates[0];
+      break;
+    }
+    case 2: {
+      return listTemplates[1];
+      break;
+    }
+    default: {
+      return listTemplates[2];
+      break;
+    }
+  }
+}
+
+
+/* COMMAND-LINE TESTS
+
+node main.js scorecard -v -x NC -n 13 -p ~/src/district-analytics/data/SAMPLE-BG-map.csv -d ~/src/district-analytics/data/SAMPLE-BG-data2.json -s ~/src/district-analytics/data/SAMPLE-BG-shapes.geojson -g ~/src/district-analytics/data/SAMPLE-BG-graph.json -c ~/src/district-analytics/data/SAMPLE-COUNTY.geojson
+node --inspect --inspect-brk main.js scorecard -v -x NC -n 13 -p ~/src/district-analytics/data/SAMPLE-BG-map.csv -d ~/src/district-analytics/data/SAMPLE-BG-data2.json -s ~/src/district-analytics/data/SAMPLE-BG-shapes.geojson -g ~/src/district-analytics/data/SAMPLE-BG-graph.json -c ~/src/district-analytics/data/SAMPLE-COUNTY.geojson
+
+-or-
+
+./main.js scorecard -v -x NC -n 13 -p ../data/SAMPLE-BG-map.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+./main.js --inspect --inspect-brk scorecard -v -x NC -n 13 -p ../data/SAMPLE-BG-map.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+
+These calls work at the project directory, using samples in the data/ directory:
+
+./main.js testlog -v -x NC -n 13 -p ../data/SAMPLE-BG-map.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+
+TODO - Fix this
+./main.js testlog -v -x NC -n 13 -p ../data/SAMPLE-BG-map-missing.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+./main.js scorecard -v -x NC-n 13 -p ../data/SAMPLE-BG-map-missing.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -v -x NC -n 13 -p ../data/SAMPLE-BG-map-unassigned.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+./main.js scorecard -v -x NC -n 13 -p ../data/SAMPLE-BG-map-unassigned.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson
+
+TODO - HERE
+
+./main.js -v -x NC testlog -p ../data/SAMPLE-BG-map.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson --empty
+./main.js -v -x NC scorecard -p ../data/SAMPLE-BG-map.csv -d ../data/SAMPLE-BG-data2.json -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -c ../data/SAMPLE-COUNTY.geojson --empty
+
+TODO
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-discontiguous.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-discontiguous.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-hole.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-hole.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+node main.js scorecard -v -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+
+These calls test NC block-level data stored in my ~/data/redistricting-data/2010/compact/sample directory:
+
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-shapes.geojson -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/tl_2018_37_tabblock10.json -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+
+node main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-shapes.geojson -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+node main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/tl_2018_37_tabblock10.json -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+
+
+
+*/
+
+/* TODO - DELETE
+
+These calls work at the project directory, using samples in the data/ directory:
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-missing.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-missing.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-unassigned.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-unassigned.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv --empty
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv --empty
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-discontiguous.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-discontiguous.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+./main.js testlog -n 13 -p ../data/SAMPLE-BG-map-hole.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+./main.js scorecard -n 13 -p ../data/SAMPLE-BG-map-hole.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+node main.js scorecard -v -n 13 -p ../data/SAMPLE-BG-map.csv -c ../data/SAMPLE-BG-census.csv -s ../data/SAMPLE-BG-shapes.geojson -g ../data/SAMPLE-BG-graph.json -e ../data/SAMPLE-BG-election.csv -f ../data/SAMPLE-FIPS-county-name-map.csv
+
+
+These calls test NC block-level data stored in my ~/data/redistricting-data/2010/compact/sample directory:
+
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-shapes.geojson -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+node --inspect --inspect-brk main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/tl_2018_37_tabblock10.json -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+
+node main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-shapes.geojson -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+node main.js scorecard -v -n 13 -p ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-map.csv -c ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-census.csv -s ~/data/redistricting-data/2010/compact/sample/tl_2018_37_tabblock10.json -g ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-graph.json -e ~/data/redistricting-data/2010/compact/sample/SAMPLE-BLOCK-election.csv -f ~/data/redistricting-data/2010/compact/sample/SAMPLE-FIPS-county-name-map.csv
+
+*/