@dra2020/district-analytics 1.0.3 → 1.0.6

package/src/cohesive.ts

@@ -0,0 +1,156 @@
+//
+// "COHESIVE" - We're naming this category which is about county splitting.
+//
+
+import * as T from './types'
+import * as U from './utils';
+import * as S from './settings';
+
+import * as D from './_data'
+import { AnalyticsSession } from './_api';
+
+
+export function doCountySplits(s: AnalyticsSession): T.TestEntry {
+  let test = s.getTest(T.Test.CountySplits) as T.TestEntry;
+
+  // THE THREE VALUES TO DETERMINE FOR A PLAN
+  let unexpectedSplits: number = 0;
+  let unexpectedAffected: number = 0;
+  let countiesSplitUnexpectedly = [];
+
+  // FIRST, ANALYZE THE COUNTY SPLITING FOR THE PLAN
+
+  // Pivot census totals into county-district "splits"
+  let countiesByDistrict = s.districts.statistics[D.DistrictField.CountySplits];
+  // countiesByDistrict = countiesByDistrict.slice(1, -1);
+
+  // Find the single-county districts, i.e., districts NOT split across counties.
+  // Ignore the dummy unassigned 0 and N+1 summary "districts."
+  let singleCountyDistricts = [];
+  for (let d = 1; d <= s.state.nDistricts; d++) {
+    // See if there's only one county partition
+    let nCountiesInDistrict = 0;
+    for (let c = 0; c < s.counties.nCounties; c++) {
+      if (countiesByDistrict[d][c] > 0) {
+        nCountiesInDistrict += 1;
+        if (nCountiesInDistrict > 1) {
+          break;
+        }
+      }
+    }
+    // If so, save the district
+    if (nCountiesInDistrict == 1) {
+      singleCountyDistricts.push(d);
+    }
+  }
+
+  // Process the splits/partitions in the plan:
+  // - Count the total # of partitions,
+  // - Find the counties split across districts, and
+  // - Accumulate the number people affected (except when single-county districts)
+  let nPartitionsOverall: number = 0;
+  let splitCounties = new Set();       // The counties that are split across districts
+  let totalAffected: number = 0;       // The total population affected by those splits
+
+  for (let c = 0; c < s.counties.nCounties; c++) {
+    let nCountyParts = 0;
+    let subtotal = 0;
+
+    for (let d = 1; d <= s.state.nDistricts; d++) {
+      if (countiesByDistrict[d][c] > 0) {
+        nPartitionsOverall += 1;
+        nCountyParts += 1;
+        if (!(U.arrayContains(singleCountyDistricts, d))) {
+          subtotal += countiesByDistrict[d][c];
+        }
+      }
+    }
+    if (nCountyParts > 1) {
+      splitCounties.add(c);
+      totalAffected += subtotal;
+    }
+  }
+
+  // Convert county ordinals to FIPS codes
+  let splitCountiesFIPS = U.getSelectObjectKeys(s.counties.index, [...splitCounties]);
+
+  // THEN TAKE ACCOUNT OF THE COUNTY SPLITTING THAT IS EXPECTED (REQUIRED)
+
+  // Compute the total number of splits this way, in case any counties are split
+  // more than once. I.e., it's not just len(all_counties_split).
+  let nSplits = nPartitionsOverall - s.counties.nCounties;
+
+  // Determine the number of *unexpected* splits. NOTE: Prevent negative numbers,
+  // in case you have a plan the *doesn't* split counties that would have to be
+  // split due to their size.
+  unexpectedSplits = Math.max(0, nSplits - s.state.expectedSplits);
+
+  // Subtract off the total population that *has* to be affected by splits,
+  // because their counties are too big. NOTE: Again, prevent negative numbers, 
+  // in case you have a plan the *doesn't* split counties that would have to be
+  // split due to their size.
+  unexpectedAffected = U.trim(Math.max(0, totalAffected - s.state.expectedAffected) / s.state.totalPop);
+
+  // Find the counties that are split *unexpectedly*. From all the counties that
+  // are split, remove those that *have* to be split, because they are bigger than
+  // a district.
+  let countiesSplitUnexpectedlyFIPS = [];
+  for (let fips of splitCountiesFIPS) {
+    if (!(U.arrayContains(s.state.tooBigFIPS, fips))) {
+      countiesSplitUnexpectedlyFIPS.push(fips);
+    }
+  }
+
+  //  ... and convert the FIPS codes to county names.
+  for (let fips of countiesSplitUnexpectedlyFIPS) {
+    countiesSplitUnexpectedly.push(s.counties.nameFromFIPS(fips));
+  }
+  countiesSplitUnexpectedly = countiesSplitUnexpectedly.sort();
+
+  // Cache the results in the test
+  test['score'] = unexpectedAffected;  // TODO - Use Moon's complexity metric here
+  test['details'] = {
+    'unexpectedSplits': unexpectedSplits,
+    'unexpectedAffected': unexpectedAffected,
+    'countiesSplitUnexpectedly': countiesSplitUnexpectedly
+  };
+
+  return test;
+}
+
+
+// 2 - THE COMPLEXITY ANALYTIC NEEDS THE FOLLOWING DATA:
+//
+// If a map is already in simplified (mixed) form, the complexity analytic needs
+// two pieces of data:
+// - The counts of features by summary level--i.e., the numbers of counties, tracts,
+//   block groups, and blocks in a state; and
+// - The map -- So it can count the features by summary level in the map,
+//   as well as the number of BG’s that are split.
+//
+// TODO - Where would the state counts come from? Preprocessed and passed in, or
+//   done in a one-time initialization call (which would require a full set of
+//   block geo_id's for the state).
+//
+// However, if a map is not yet (fully) simplified, then determining the
+//   complexity of a map also requires a preprocessed summary level hierarchy, so
+//   you can get the child features (e.g., tracts) of a parent feature (e.g.,
+//   a county).
+//
+// NOTE - I have script for producing this hierarchy which we could repurpose.
+//
+// TODO - For mixed map processing--specfically to find the neighbors of a feature
+//   that are actually in the map (as opposed to just neighbors at the same
+//   summary level in the static graph)--you need a special hierarchy that
+//   distinguishes between the 'interior' and 'edge children of a feature.
+//
+// NOTE - The script noted above does this.
+
+export function doPlanComplexity(s: AnalyticsSession): T.TestEntry {
+  let test = s.getTest(T.Test.Complexity) as T.TestEntry;
+
+  console.log("TODO - Calculating plan complexity ...");
+
+  return test;
+}
+

package/src/compact.ts

@@ -0,0 +1,208 @@
+//
+// COMPACT
+//
+
+import { gfArea, gfPerimeter, gfDiameter } from './geofeature';
+
+import * as T from './types';
+import * as U from './utils';
+import * as S from './settings';
+
+import { AnalyticsSession } from './_api';
+
+// Measures of compactness compare district shapes to various ideally compact
+// benchmarks, such as circles. All else equal, more compact districts are better.
+// 
+// There are four popular measures of compactness. They either focus on how
+// dispersed or how indented a shapes are.
+//
+// These first two measures are the most important:
+// 
+// Reock is the primary measure of the dispersion of district shapes, calculated
+// as “the area of the district to the area of the minimum spanning circle that
+// can enclose the district.”
+//
+//    R = A / A(Minimum Bounding Circle)
+//    R = A / (π * (D / 2)^2)
+//
+//    R = 4A / πD^2
+//
+// where A is the area of the district and D is the diameter of the minimum
+// bounding circle.
+//
+// Polsby-Popper is the primary measure of the indendentation of district shapes,
+// calculated as the “the ratio of the area of the district to the area of a circle
+// whose circumference is equal to the perimeter of the district.”
+//
+//    PP = A / A(C)
+//
+// where C is that circle. In other words:
+//
+//    P = 2πRc and A(C) = π(P / 2π)^2
+//
+// where P is the perimeter of the district and Rc is the radius of the circle.
+//
+// Hence, the measure simplifies to:
+//
+//    PP = 4π * (A / P^2)
+// 
+// I propose that we use these two, normalize them, and weight equally to determine
+// our compactness value.
+// 
+// These second two measures may be used to complement the primary ones above:
+// 
+// Convex Hull is a secondary measure of the dispersion of district shapes, calculated
+// as “the ratio of the district area to the area of the minimum convex bounding
+// polygon (also known as a convex hull) enclosing the district.”
+//
+//    CH = A / A(Convex Hull)
+// 
+// where a convex hull is the minimum perimeter that encloses all points in a shape,
+// basically the shortest unstretched rubber band that fits around the shape.
+//
+// Schwartzberg is a secondary measure of the degree of indentation of district
+// shapes, calculated as “the ratio of the perimeter of the district to the circumference
+// of a circle whose area is equal to the area of the district.”
+//
+//    S = 1 / (P / C)
+//
+// where P is the perimeter of the district and C is the circumference of the circle.
+// The radius of the circle is:
+//
+//    Rc = SQRT(A / π)
+//
+// So, the circumference of the circle is:
+//
+//    C = 2πRc or C = 2π * SQRT(A / π)
+//
+// Hence:
+//
+//    S = 1 (P / 2π * SQRT(A / π))
+//
+//    S = (2π * SQRT(A / π)) / P
+//
+// All these measures produce values between 0 and 1, with 0 being the least compact
+// and 1 being the most compact. Sometimes these values are multiplied by 100 to
+// give values between 0 and 100.
+// 
+// For each measure, the compactness of a set of Congressional districts is the
+// average of that measure for all the districts.
+//
+
+// Calculate Reock compactness:
+// reock = (4 * a) / (math.pi * d**2)
+// NOTE - Depends on extractDistrictProperties running first
+export function doReock(s: AnalyticsSession, bLog: boolean = false): T.TestEntry {
+  let test = s.getTest(T.Test.Reock) as T.TestEntry;
+
+  // Calculate Reock scores by district
+  let scores: number[] = [];
+
+  for (let districtID = 1; districtID <= s.state.nDistricts; districtID++) {
+    let districtProps = s.districts.getGeoProperties(districtID);
+    let a = districtProps[T.DistrictShapeProperty.Area];
+    let d = districtProps[T.DistrictShapeProperty.Diameter];
+
+    let reock = (4 * a) / (Math.PI * d ** 2);
+
+    // Save each district score
+    scores.push(reock);
+
+    // Echo the results by district
+    if (bLog) console.log("Reock for district", districtID, "=", reock);
+  }
+
+  // Populate the test entry
+  let averageReock = U.avgArray(scores);
+
+  test['score'] = U.trim(averageReock);
+  test['details'] = {};                   // TODO - Any details?
+
+  return test;
+}
+
+// Calculate Polsby-Popper compactness measures:
+// polsby_popper = (4 * math.pi) * (a / p**2)
+// NOTE - Depends on extractDistrictProperties running first
+export function doPolsbyPopper(s: AnalyticsSession, bLog: boolean = false): T.TestEntry {
+  let test = s.getTest(T.Test.PolsbyPopper) as T.TestEntry;
+
+  // Calculate Polsby-Popper scores by district
+  let scores: number[] = [];
+
+  for (let districtID = 1; districtID <= s.state.nDistricts; districtID++) {
+    let districtProps = s.districts.getGeoProperties(districtID);
+    let a = districtProps[T.DistrictShapeProperty.Area];
+    let p = districtProps[T.DistrictShapeProperty.Perimeter];
+
+    let polsbyPopper = (4 * Math.PI) * (a / p ** 2);
+
+    // Save each district score
+    scores.push(polsbyPopper);
+
+    // Echo the results by district
+    if (bLog) console.log("Polsby-Popper for district", districtID, "=", polsbyPopper);
+  }
+
+  // Populate the test entry
+  let averagePolsbyPopper = U.avgArray(scores);
+
+  test['score'] = U.trim(averagePolsbyPopper);
+  test['details'] = {};                         // TODO - Any details?
+
+  return test;
+}
+
+
+// HELPER TO EXTRACT PROPERTIES OF DISTRICT SHAPES
+
+export function extractDistrictProperties(s: AnalyticsSession, bLog: boolean = false): void {
+  for (let i = 1; i <= s.state.nDistricts; i++) {
+    let j = i - 1;  // TODO - Terry: How do you get away w/o this?!?
+    let poly = s.districts.getShape(j);
+
+    // TODO - Bundle these calls?
+    let area: number = gfArea(poly);
+    let perimeter: number = gfPerimeter(poly);
+    let diameter: number = gfDiameter(poly);
+
+    let props: T.DistrictShapeProperties = [0, 0, 0]; // TODO - Terry?!?
+    props[T.DistrictShapeProperty.Area] = area;
+    props[T.DistrictShapeProperty.Diameter] = diameter;
+    props[T.DistrictShapeProperty.Perimeter] = perimeter;
+
+    s.districts.setGeoProperties(i, props);
+
+    if (bLog) console.log("District", i, "A =", area, "P =", perimeter, "D =", diameter);
+  }
+}
+
+
+// SAVE THESE NOTES, IN CASE WE NEED TO REWORK HOW WE PERFORM THESE CALCS.
+// THEY REFLECT HOW I DID THEM IN PYTHON.
+//
+// THE COMPACTNESS ANALYTICS NEED THE FOLLOWING DATA,
+// IN ADDITION TO THE MAP (IDEALLY, GEO_IDS INDEXED BY DISTRICT_ID)
+//
+// Shapes by geo_id
+//
+// If we need/want to speed compactness calculations up, we'll need
+//   to calculate the perimeters and diameters (and areas) of districts implicitly,
+//   which will require identifying district boundaries initially and updating
+//   them incrementally as districts are (re)assigned.
+//
+//   A district's boundary info is the set/list of features that constitute the
+//   district's border along with each boundary feature's neighbors. Hence, this
+//   requires a contiguity graph with the lengths of shared edges between features
+//   precomputed.
+//
+// NOTE - I can write up (if not implement) the logic for determining what shapes
+//   constitute a district's boundary. There are a few nuances.
+//
+//   If we have to optimize like this when we generalize to mixed maps, the
+//   determination of "neighbors in the map" and the length of shared borders
+//   (for determining a district perimeters) becomes more complicated and dynamic.
+//
+// NOTE - Again, I can write up (if not implement) the logic for both of these.
+//   They are a bit tricky and require special preprocessing of the summary level
+//   hierarchy (which I also have a script for that we can repurpose).