@dra2020/district-analytics 1.0.4 → 1.0.7

package/src/valid.ts

@@ -0,0 +1,275 @@
+//
+// MAP/PLAN VALIDATIONS
+//
+
+import * as T from './types'
+import * as U from './utils';
+import * as S from './settings';
+
+import * as D from './_data'
+import { AnalyticsSession } from './_api';
+
+//
+// COMPLETE - Are all geo's assigned to a district, and do all districts have
+//   at least one geo assigned to them?
+//
+
+export function doIsComplete(s: AnalyticsSession): T.TestEntry {
+  let test = s.getTest(T.Test.Complete) as T.TestEntry;
+
+  let bAllAssigned = true;
+  let bNoneEmpty = true;
+
+  let unassignedFeatures: string[] = [];
+  let emptyDistricts: number[] = [];
+
+  // Get the by district results, including the dummy unassigned district,
+  // but ignoring the N+1 summary district
+  let bNotEmptyByDistrict = s.districts.statistics[D.DistrictField.bNotEmpty];
+  bNotEmptyByDistrict = bNotEmptyByDistrict.slice(0, -1);
+
+  // Are all features assigned to districts?
+  // Check the dummy district that holds any unassigned features.
+  bAllAssigned = (!bNotEmptyByDistrict[S.NOT_ASSIGNED]);
+  if (!bAllAssigned) {
+    let unassignedDistrict = s.plan.geoIDsForDistrictID(S.NOT_ASSIGNED);
+    unassignedFeatures = Array.from(unassignedDistrict);
+    unassignedFeatures = unassignedFeatures.slice(0, S.NUMBER_OF_ITEMS_TO_REPORT);
+  }
+
+  // Do all real districts have at least one feature assigned to them?
+  bNoneEmpty = U.andArray(bNotEmptyByDistrict.slice(1));
+
+  // Case 1 - One or more districts are missing:
+  //   The # of enumerated districts minus the dummy NOT_ASSIGNED one should
+  //   equal the number apportioned districts. This guards against a district
+  //   not being included in a map that is imported.
+  //
+  // TODO - I'm no longer checking for this, but DRA should!
+
+  // Case 2 - Or a district is explicitly named but empty:
+  //   Note, this can happen if a district is created, and then all features
+  //   are removed from it (in DRA).
+
+  // Populate the test entry
+  test['score'] = bAllAssigned && bNoneEmpty;
+  if (!bAllAssigned) {
+    test['details']['unassignedFeatures'] = unassignedFeatures;
+  }
+
+  if (!bNoneEmpty) {
+    test['details']['emptyDistricts'] = emptyDistricts;
+  }
+
+  // Populate the N+1 summary "district" in district.statistics
+  let bNotEmpty = s.districts.statistics[D.DistrictField.bNotEmpty];
+  let summaryRow = s.districts.numberOfRows() - 1;
+
+  bNotEmpty[summaryRow] = test['score'];
+
+  return test;
+}
+
+//
+// CONTIGUOUS - Is each district in a plan fully connected?
+//
+//   NOTE - To check "operational contiguity," we need to use a graph, i.e.,
+//   we can't rely on just the geometric contiguity of shapes in a shapefile.
+//
+//   To test this, load the NC 2010 map 'SAMPLE-BG-map-discontiguous.csv'.
+//
+
+export function doIsContiguous(s: AnalyticsSession): T.TestEntry {
+  let test = s.getTest(T.Test.Contiguous) as T.TestEntry;
+
+  // Get the contiguity of each district. Ignore dummy unassigned district
+  // and the N+1 summary district.
+  let bContiguousByDistrict = s.districts.statistics[D.DistrictField.bContiguous];
+  bContiguousByDistrict = bContiguousByDistrict.slice(1, -1);
+
+  // If any real districts aren't contiguous, mark the plan as not contiguous
+  let bMapContiguous = U.andArray(bContiguousByDistrict);
+
+  // If the map is not contiguous, log the offending districts.
+  let discontiguousDistricts: number[] = [];
+  let districtID = 1;
+  bContiguousByDistrict.forEach(function (bDistrictContiguous: boolean): void {
+    if (!bDistrictContiguous) discontiguousDistricts.push(districtID);
+    districtID += 1;
+  });
+
+  // Populate the test entry
+  test['score'] = bMapContiguous;
+  if (!bMapContiguous) {
+    test['details'] = { 'discontiguousDistricts': discontiguousDistricts };
+  }
+
+  // Populate the N+1 summary "district" in district.statistics
+  let bContiguous = s.districts.statistics[D.DistrictField.bContiguous];
+  let summaryRow = s.districts.numberOfRows() - 1;
+
+  bContiguous[summaryRow] = test['score'];
+
+  return test;
+}
+
+// Are the features in a district fully connected?
+export function isConnected(districtGeos: Set<string>, graph: D.Graph): boolean {
+  // export function isConnected(districtGeos: Set<string>, graph: T.ContiguityGraph): boolean {
+  // TODO - Terry, why does this constructor need a <T> type specification?
+  let visited = new Set<string>();
+  let toProcess: string[] = [];
+
+  // Start processing with the first geoID in the district
+  let iter = districtGeos.values();
+  toProcess.push(iter.next().value);
+
+  // While there are geoIDs in the district that haven't been processed
+  while (toProcess.length > 0) {
+    // Grab a geoID and process it
+    let node = toProcess.pop() as string;
+    visited.add(node);
+
+    // Get its actual, in-state neighbors
+    let actualNeighbors = graph.peerNeighbors(node).filter(x => U.isInState(x));
+
+    // Add neighbors to visit, if they're in the same district Y haven't already been visited
+    let neighborsToVisit = actualNeighbors.filter(x => districtGeos.has(x) && (!visited.has(x)));
+    // TODO - Terry, is this the quickest/best way to do this?
+    toProcess.push(...neighborsToVisit);
+  }
+
+  // Stop when you've visited all the geoIDs in the district
+  return visited.size == districtGeos.size;
+}
+
+
+//
+// FREE OF HOLES - Are any districts fully embedded w/in another district?
+//
+//   A district is NOT a "donut hole" district:
+//   - If any neighbor is 'OUT_OF_STATE'; or
+//   - If there are 2 or more neighboring districts.
+//
+//   To test this, load the NC 2010 map 'SAMPLE-BG-map-hole.csv'. District 1,
+//   Buncombe County (37021), is a donut hole w/in District 3.
+//
+// TODO - Optimize this to take advantage of district boundary info, if/when
+//   we cache one to optimize compactness.
+//
+
+export function doIsFreeOfHoles(s: AnalyticsSession): T.TestEntry {
+  let test = s.getTest(T.Test.FreeOfHoles) as T.TestEntry;
+
+  // Initialize values
+  let bFreeOfHoles = true;
+  let embeddedDistricts: number[] = [];
+
+  // Get the embeddedness of each district. Ignore dummy unassigned district
+  // and the N+1 summary district.
+  let bNotEmbeddedByDistrict = s.districts.statistics[D.DistrictField.bNotEmbedded];
+  bNotEmbeddedByDistrict = bNotEmbeddedByDistrict.slice(1, -1);
+
+  let districtID = 1;
+  bNotEmbeddedByDistrict.forEach(function (bDistrictNotEmbedded: boolean): void {
+    if (!bDistrictNotEmbedded) {
+      embeddedDistricts.push(districtID);
+      bFreeOfHoles = false;
+    }
+    districtID += 1;
+  });
+
+  // Populate the test entry
+  test['score'] = bFreeOfHoles;
+  if (!bFreeOfHoles) {
+    test['details'] = { 'embeddedDistricts': embeddedDistricts };
+  }
+
+  // Populate the N+1 summary "district" in district.statistics
+  let bNotEmbedded = s.districts.statistics[D.DistrictField.bNotEmbedded];
+  let summaryRow = s.districts.numberOfRows() - 1;
+
+  bNotEmbedded[summaryRow] = test['score'];
+
+  return test;
+}
+
+// Test whether one district is embedded w/in any other.
+export function isEmbedded(districtID: number, geoIDs: Set<string>, plan: D.Plan, graph: D.Graph): boolean {
+  // TODO - Make "features" = "geoIDs." These aren't "features" proper, just
+  //   identifier strings.
+  let features = geoIDs;
+  let planByGeo = plan.byGeoID();
+
+  // Assume the district is embedded
+  let bEmbedded = true;
+  // Keep track of the neighoring districts
+  let neighboringDistricts = new Set();
+
+  // TODO - Use just the boundary features, when available
+  // Get the features for the real district
+  let featuresToCheck = Array.from(features);
+
+  // If the district has features, check whether it is embedded
+  if (!(U.isArrayEmpty(featuresToCheck))) {
+    // For each feature that needs to be checked (see above)
+    for (let feature of featuresToCheck) {
+      // Get its neighbors (including the virtual "out of state" ones)
+      let neighbors = graph.peerNeighbors(feature);
+
+      for (let neighbor of neighbors) {
+        if (U.isOutOfState(neighbor)) {
+          bEmbedded = false;
+          // No need to check any more neighbors
+          break;
+        }
+        else {
+          let neighboringDistrict = U.getDistrict(planByGeo, neighbor);
+
+          // Assume that a missing district assignment (= None) means that the
+          // feature is "water-only" AND part of the state border (vs. internal)
+          // and, therefore, not in the plan/map.
+
+          if (neighboringDistrict == undefined) {
+            bEmbedded = false;
+            // No need to check any more neighbors
+            break;
+          }
+          else {
+            // TODO - Since we're checking *all* features in a district right
+            //   now, not just boundary features and neighbors in other districts,
+            //   prune out the current district. If/when we optimize compactness
+            //   to cache district boundaries (as before in my Python implementation),
+            //   we won't have to guard adding "neighboring" districts in this way.
+            if (neighboringDistrict != districtID) {
+              neighboringDistricts.add(neighboringDistrict);
+            }
+
+            if (neighboringDistricts.size > 1) {
+              bEmbedded = false;
+              // No need to check any more neighbors
+              break;
+            }
+          }
+        }
+      }
+      // If a district is not embedded, there's no need to check anymore
+      // border geos.
+      if (!bEmbedded) {
+        break;
+      }
+    }
+
+  }
+
+  return bEmbedded;
+}
+
+// TODO - MIXED MAPS
+// - When we generalize to mixed maps, the determination of "neighbors in
+//   the map" -- which is the core function in determining connectedness -- becomes
+//   *much* more complicated and dynamic.
+// - I can write up (if not implement) the logic for this. It is a bit tricky
+//   and requires special preprocessing of the summary level hierarchy (which I
+//   also have a script for that we can repurpose) to distinguish between 'interior'
+//   and 'edge' children.

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "declaration": true,
+    "declarationDir": "dist/",
+    "strict": true,
+    "types": [ 
+      "node"
+    ], 
+    "lib": [
+      "es2016"
+    ],
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*",
+    "types/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/_tests__/*",
+    "data"
+  ]
+}

package/tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": ["tslint:recommended", "tslint-config-prettier"]
+}

package/types/polygon-clipping/index.d.ts

@@ -0,0 +1 @@
+declare module 'polygon-clipping';

package/webpack.config.js

@@ -0,0 +1,73 @@
+var path = require('path');
+var fs = require('fs');
+var externalModules = {};
+fs.readdirSync('node_modules/@dra2020')
+  .forEach((mod) => {
+    mod = '@dra2020/' + mod;
+    externalModules[mod] = 'commonjs ' + mod;
+  });
+
+var libConfig = {
+    entry: {
+      library: './src/index.ts'
+	  },
+    target: 'node',
+    mode: 'development',
+    output: {
+        library: 'district-analytics',
+        libraryTarget: 'umd',
+        path: __dirname + '/dist',
+        filename: 'district-analytics.js'
+    },
+
+    // Enable source maps
+    devtool: "source-map",
+
+    externals: externalModules,
+
+    module: {
+		rules: [
+			{ test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/ },
+			{ test: /\.json$/, loader: 'json-loader' },
+			{ test: /\.js$/, enforce: "pre", loader: "source-map-loader" }
+		]
+    },
+
+    resolve: {
+        extensions: [".webpack.js", ".web.js", ".ts", ".tsx", ".js"]
+    }
+
+};
+
+var testConfig = {
+    entry: './test/_cli.ts',
+    target: 'node',
+    mode: 'development',
+    output: {
+        path: __dirname + '/dist',
+        filename: 'cli.js'
+    },
+
+    // Enable source maps
+    devtool: "source-map",
+
+	externals: {
+    "yargs": "commonjs yargs"
+	},
+		
+
+    module: {
+		rules: [
+			{ test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/ },
+			{ test: /\.json$/, loader: 'json-loader' },
+			{ test: /\.js$/, enforce: "pre", loader: "source-map-loader" }
+		]
+    },
+
+    resolve: {
+        extensions: [".webpack.js", ".web.js", ".ts", ".tsx", ".js"]
+    }
+
+};
+
+module.exports = [ libConfig, testConfig ];