@dra2020/dra-analytics 3.3.2 → 4.0.0

package/README.md

@@ -44,6 +44,10 @@ The analytics in DRA include metrics favored by [many scholars](./docs/attributi
 
 A [command-line interface](./docs/cli.md) (CLI) was added in v3.
 
+## Updates
+
+- 12/18/21 -- Added multi-member district (MMD) support to makePopulationScorecard().
+
 ## Build status for master branch
 
 [![CircleCI](https://circleci.com/gh/dra2020/dra-graph.svg?style=svg&circle-token=5c5fdd1ea8b6aa5fc80ec7657b805b3953c58e00)](https://circleci.com/gh/dra2020/dra-analytics)

package/dist/dra-analytics.js

@@ -177,7 +177,7 @@ Object.defineProperty(exports, "avgSVError", ({ enumerable: true, get: function
 
 // Restrict package exports
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.popdevThreshold = exports.isAntimajoritarian = exports.ratePartisanBias = exports.rateDistrictSplitting = exports.rateCountySplitting = exports.rateSplitting = exports.ratePolsby = exports.rateReock = exports.rateCompactness = exports.rateMinorityRepresentation = exports.rateCompetitiveness = exports.rateProportionality = exports.ratePopulationDeviation = void 0;
+exports.popdevThreshold = exports.isAntimajoritarian = exports.normalizePartisanBias = exports.ratePartisanBias = exports.rateDistrictSplitting = exports.rateCountySplitting = exports.rateSplitting = exports.ratePolsby = exports.rateReock = exports.rateCompactness = exports.rateMinorityRepresentation = exports.rateCompetitiveness = exports.rateProportionality = exports.ratePopulationDeviation = void 0;
 var all_1 = __webpack_require__(/*! ../rate/all */ "./lib/rate/all.ts");
 // For DRA-specific ratings
 Object.defineProperty(exports, "ratePopulationDeviation", ({ enumerable: true, get: function () { return all_1.ratePopulationDeviation; } }));
@@ -194,6 +194,7 @@ Object.defineProperty(exports, "rateDistrictSplitting", ({ enumerable: true, get
 // rateSplittingLegacy, adjustSplittingRating, rateCountySplittingLegacy, rateDistrictSplittingLegacy,
 // For use in DRA client UI
 Object.defineProperty(exports, "ratePartisanBias", ({ enumerable: true, get: function () { return all_1.ratePartisanBias; } }));
+Object.defineProperty(exports, "normalizePartisanBias", ({ enumerable: true, get: function () { return all_1.normalizePartisanBias; } }));
 Object.defineProperty(exports, "isAntimajoritarian", ({ enumerable: true, get: function () { return all_1.isAntimajoritarian; } }));
 Object.defineProperty(exports, "popdevThreshold", ({ enumerable: true, get: function () { return all_1.popdevThreshold; } }));
 
@@ -848,6 +849,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.makePopulationScorecard = exports.isRoughlyEqual = exports.calcPopulationDeviation = void 0;
 const C = __importStar(__webpack_require__(/*! ../rate/dra-config */ "./lib/rate/dra-config.ts"));
 const U = __importStar(__webpack_require__(/*! ../utils/all */ "./lib/utils/all.ts"));
+// MMD - This is the same for SMD & MMD. It's the calculation of min, max, and target size that differs.
 function calcPopulationDeviation(max, min, targetSize) {
     return (max - min) / targetSize; // Don't trim the result here!
 }
@@ -857,10 +859,35 @@ function isRoughlyEqual(devation, bLegislative) {
     return (devation <= threshold) ? true : false;
 }
 exports.isRoughlyEqual = isRoughlyEqual;
-function makePopulationScorecard(totPopByDistrict, targetSize, bLegislative, bLog = false) {
-    const nonEmptyDistricts = totPopByDistrict.filter(x => x > 0);
+// MMD
+// - Add optional # of reps per district. 
+// - Assume targetSize has been calculated correctly per # of reps not districts.
+// - If it exists, handle the MMD-specific calculations.
+function makePopulationScorecard(totPopByDistrict, targetSize, bLegislative, repsByDistrict, bLog = false) {
+    const nDistricts = totPopByDistrict.length;
+    // MMD - Validate reps per district input
+    if (repsByDistrict) {
+        if (repsByDistrict.length != nDistricts)
+            throw new Error("Mismatched #'s of districts passed to makePopulationScorecard()!");
+        if (repsByDistrict.includes(0))
+            throw new Error("Zero reps for a district passed to makePopulationScorecard()!");
+        // Assume a positive integer # of reps per district
+    }
+    // MMD - Figure out the type of districts, SMD or MMD.
+    const nReps = (repsByDistrict) ? repsByDistrict.reduce((a, b) => a + b, 0) : nDistricts;
+    const bSMD = (!repsByDistrict || (nReps == nDistricts)) ? true : false;
+    // MMD - Generalize populations for non-empty districts
+    // const nonEmptyDistricts = totPopByDistrict.filter(x => x > 0);
+    let popPerRep = U.deepCopy(totPopByDistrict);
+    if (!bSMD && repsByDistrict) {
+        for (let i = 0; i < nDistricts; i += 1) {
+            popPerRep[i] = totPopByDistrict[i] / repsByDistrict[i];
+        }
+    }
+    const nonEmptyDistricts = popPerRep.filter(x => x > 0);
     let min = 0;
     let max = 0;
+    // MMD - This is already generalized, because nonEmptyDistricts is generalized.
     if (nonEmptyDistricts.length > 1) {
         min = U.minArray(nonEmptyDistricts);
         max = U.maxArray(nonEmptyDistricts);
@@ -1737,7 +1764,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.rangeUnearnedSeats = exports.estLocalUnearnedSeats = exports.rangeDisproportionalityAlt = exports.estLocalDisproportionalityAlt = exports.rangeDisproportionality = exports.estLocalDisproportionality = exports.rangeAsymmetry = exports.estLocalAsymmetry = exports.calcGamma = exports.calcMinimalInverseResponsiveness = exports.calcBigR = exports.calcDisproportionality = exports.calcGlobalSymmetry = exports.calcLopsidedOutcomes = exports.calcDeclination = exports.radiansToDegrees = exports.isASweep = exports.keyRVpoints = exports.calcMeanMedianDifference = exports.calcEfficiencyGap = exports.invertSVPoints = exports.inferGeometricSeatsBiasPoints = exports.estGeometricSeatsBias = exports.estVotesBias = exports.estSeatBias = exports.estPartisanBias = exports.calcTurnoutBias = exports.estUnearnedSeats = exports.calcDisproportionalityFromBest = exports.estSeatShare = exports.bestSeatShare = exports.bestSeats = void 0;
+exports.rangeUnearnedSeats = exports.estLocalUnearnedSeats = exports.rangeDisproportionalityAlt = exports.estLocalDisproportionalityAlt = exports.rangeDisproportionality = exports.estLocalDisproportionality = exports.rangeAsymmetry = exports.estLocalAsymmetry = exports.calcGamma = exports.calcMinimalInverseResponsiveness = exports.calcBigR = exports.calcDisproportionality = exports.calcGlobalSymmetry = exports.calcLopsidedOutcomes = exports.calcDeclination = exports.radiansToDegrees = exports.isASweep = exports.keyRVpoints = exports.calcMeanMedianDifference = exports.calcEfficiencyGapPrime = exports.calcEfficiencyGap = exports.invertSVPoints = exports.inferGeometricSeatsBiasPoints = exports.estGeometricSeatsBias = exports.estVotesBias = exports.estSeatBias = exports.estPartisanBias = exports.calcTurnoutBias = exports.estUnearnedSeats = exports.calcDisproportionalityFromBest = exports.estSeatShare = exports.bestSeatShare = exports.bestSeats = void 0;
 const U = __importStar(__webpack_require__(/*! ../utils/all */ "./lib/utils/all.ts"));
 const C = __importStar(__webpack_require__(/*! ../rate/dra-config */ "./lib/rate/dra-config.ts"));
 const method_1 = __webpack_require__(/*! ./method */ "./lib/partisan/method.ts");
@@ -1925,6 +1952,18 @@ function calcEfficiencyGap(Vf, Sf, shareType = 0 /* Democratic */) {
     return efficiencyGap;
 }
 exports.calcEfficiencyGap = calcEfficiencyGap;
+// For illustration purposes only
+// Assumes Democratic vote shares
+// Alternate specification with winner's bonus (R) heuristic built in:
+// - By convention, '+' = R bias; '-' = D bias
+// - If 1 <= R <= 2, EG is undefined (no/acceptable bias). 
+function calcEfficiencyGapPrime(Vf, Sf, R) {
+    let EG = undefined;
+    if (R && ((R > 2) || (R < 1)))
+        EG = (2.0 * (Vf - 0.5)) - (Sf - 0.5);
+    return EG;
+}
+exports.calcEfficiencyGapPrime = calcEfficiencyGapPrime;
 // MEAN–MEDIAN DIFFERENCE
 // 
 // From PlanScore.org: "The mean-median difference is a party’s median vote share
@@ -2044,7 +2083,7 @@ exports.calcLopsidedOutcomes = calcLopsidedOutcomes;
 //
 // * gSym is the area of asymmetry between the two curves.
 // * The choice of what base to normalize it by is somewhat arbitrary.
-// * We actually only infer the S–V curver over the range [0.25–0.75] <<< 101 points (not 100!)
+// * We actually only infer the S–V curve over the range [0.25–0.75] <<< 101 points (not 100!)
 // * But dividing by 100 normalizes the area of asymmetry to the area of the SxV unit square.
 function calcGlobalSymmetry(dSVpoints, rSVpoints, S50V) {
     let gSym = 0.0;
@@ -2866,10 +2905,11 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.adjustSplittingRating = exports.rateSplittingLegacy = exports.rateDistrictSplittingLegacy = exports.countySplitWorst = exports.countySplitBest = exports.rateCountySplittingLegacy = exports.rateSplitting = exports.rateDistrictSplitting = exports.rateCountySplitting = exports.bestTarget = exports.worstMultiplier = exports.minSplitting = exports.maxSplitting = exports.rateCompactness = exports.ratePolsby = exports.rateReock = exports.rateMinorityRepresentation = exports.rateCompetitiveness = exports.ratePartisanBias = exports.isAntimajoritarian = exports.adjustDeviation = exports.extraBonus = exports.rateProportionality = exports.ratePopulationDeviation = void 0;
+exports.adjustSplittingRating = exports.rateSplittingLegacy = exports.rateDistrictSplittingLegacy = exports.countySplitWorst = exports.countySplitBest = exports.rateCountySplittingLegacy = exports.rateSplitting = exports.rateDistrictSplitting = exports.rateCountySplitting = exports.bestTarget = exports.worstMultiplier = exports.minSplitting = exports.maxSplitting = exports.rateCompactness = exports.ratePolsby = exports.rateReock = exports.rateMinorityRepresentation = exports.rateCompetitiveness = exports.normalizePartisanBias = exports.ratePartisanBias = exports.isAntimajoritarian = exports.adjustDeviation = exports.extraBonus = exports.rateProportionality = exports.ratePopulationDeviation = void 0;
 const C = __importStar(__webpack_require__(/*! ./dra-config */ "./lib/rate/dra-config.ts"));
 const normalize_1 = __webpack_require__(/*! ../rate/normalize */ "./lib/rate/normalize.ts");
 const method_1 = __webpack_require__(/*! ../partisan/method */ "./lib/partisan/method.ts");
+// MMD - This is already generalized, if deviations have been calculated based on # of reps instead of districts.
 // RATE POPULATION DEVIATION
 function ratePopulationDeviation(rawDeviation, bLegislative) {
     const _normalizer = new normalize_1.Normalizer(rawDeviation);
@@ -2982,6 +3022,7 @@ function normalizePartisanBias(biasPct, pctAt50) {
     const rating = 100 * Math.exp(-Math.abs(biasPct / b));
     return Math.round(rating);
 }
+exports.normalizePartisanBias = normalizePartisanBias;
 // RATE COMPETITIVENESS
 // Normalize overall competitiveness - Raw values are in the range [0.0–1.0]. 
 // But the practical max is more like 3/4's, so unitize that range to [0.0–1.0].