Merge pull request #144 from DemocracyDevelopers/85-add-comment-to-co…

…untycontestresult

Added comments to explain that plurality-tallying functions are not r…

server/eclipse-project/src/main/java/us/freeandfair/corla/controller/ContestCounter.java

@@ -26,16 +26,16 @@ public final class ContestCounter {
   /**
    * Class-wide logger
    */
-  public static final Logger LOGGER =
-    LogManager.getLogger(ContestCounter.class);
+  public static final Logger LOGGER = LogManager.getLogger(ContestCounter.class);
 
-  /** prevent contruction **/
+  /** private to prevent construction **/
   private ContestCounter() {
   }
 
   /**
    * Group all CountyContestResults by contest name and tally the votes
    * across all counties that have reported results.
+   * This only works for plurality - not valid, and not needed, for IRV.
    *
    * @return List<ContestResult> A high level view of contests and their
    * participants.
@@ -54,6 +54,7 @@ public static List<ContestResult> countAllContests() {
   /**
    * Calculates all the pairwise margins - like a cross product - using
    * the vote totals. When there are no losers, all margins are zero.
+   * Not valid for IRV.
    *
    * @param winners those who won the contest
    * @param losers those who did not win the contest
@@ -82,6 +83,7 @@ public static Set<Integer> pairwiseMargins(final Set<String> winners,
   /**
    * Set voteTotals on CONTEST based on all counties that have that
    * Contest name in their uploaded CVRs
+   * Not valid for IRV.
    **/
   public static ContestResult
     countContest(final Map.Entry<String, List<CountyContestResult>> countyContestResults) {
@@ -165,7 +167,7 @@ public static Map<String,Integer> addVoteTotal(final Map<String,Integer> acc,
 
   /**
    * Ranks a list of the choices in descending order by number of votes
-   * received.
+   * received. Not relevant to IRV; not related to ranked-choice voting.
    **/
   public static List<Entry<String, Integer>> rankTotals(final Map<String,Integer> voteTotals) {
     return voteTotals.entrySet().stream()
@@ -175,7 +177,7 @@ public static List<Entry<String, Integer>> rankTotals(final Map<String,Integer>
 
   /**
    * Find the set of winners for the ranking of voteTotals. Assumes only
-   * one winner allowed.
+   * one winner allowed. Not valid for IRV.
    *
    * @param voteTotals a map of choice name to number of votes
    */
@@ -184,7 +186,7 @@ public static Set<String> winners(final Map<String,Integer> voteTotals) {
   }
 
   /**
-   * Find the set of winners for the ranking of voteTotals
+   * Find the set of winners for the ranking of voteTotals. Not valid for IRV.
    *
    * @param voteTotals a map of choice name to number of votes
    * @param winnersAllowed how many can win this contest?
@@ -199,7 +201,7 @@ public static Set<String> winners(final Map<String,Integer> voteTotals,
 
   /**
    * Find the set of losers given a ranking of voteTotals and some set
-   * of contest winners.
+   * of contest winners. Not valid for IRV.
    *
    * @param voteTotals a map of choice name to number of votes
    * @param winners the choices that aren't losers

server/eclipse-project/src/main/java/us/freeandfair/corla/json/CVRContestInfoJsonAdapter.java

@@ -241,6 +241,7 @@ public CVRContestInfo read(final JsonReader the_reader)
       // included as a parameter, which is then transiently stored. We may do that again, but I am
       // leaving it out for now pending a final decision on how we store IRV Ballot interpretations.
       // See https://github.com/orgs/DemocracyDevelopers/projects/1/views/7?pane=issue&itemId=64821658
+      // It could also be stored directly here. See https://github.com/orgs/DemocracyDevelopers/projects/1/views/1?pane=issue&itemId=63351700
       return new CVRContestInfo(contest, comment, consensus, interpretedChoices);
 
     } catch (IRVParsingException e) {

server/eclipse-project/src/main/java/us/freeandfair/corla/model/ContestResult.java

@@ -40,6 +40,8 @@
 /**
  * A class representing the results for a contest across counties.
  * A roll-up  of CountyContestResults
+ * Many of these values, including the tallies, do not make sense for IRV, or are not correctly
+ * initialized for IRV. These are generally not used unless set after assertion generation.
  */
 @Entity
 @Cacheable(true)
@@ -55,8 +57,7 @@ public class ContestResult implements PersistentEntity, Serializable {
   /**
    * Class-wide logger
    */
-  public static final Logger LOGGER =
-    LogManager.getLogger(ContestResult.class);
+  public static final Logger LOGGER = LogManager.getLogger(ContestResult.class);
 
   /**
    * text
@@ -99,21 +100,23 @@ public class ContestResult implements PersistentEntity, Serializable {
   private Integer winnersAllowed;
 
   /**
-   * The set of contest winners.
+   * The set of contest winners. Not correctly initialized for IRV unless externally
+   * set after assertion generation.
    */
   @Column(name = "winners", columnDefinition = TEXT)
   @Convert(converter = StringSetConverter.class)
   private final Set<String> winners = new HashSet<>();
 
   /**
-   * The set of contest losers.
+   * The set of contest losers. Not correctly initialized for IRV unless externally
+   * set after assertion generation.
    */
   @Column(name = "losers", columnDefinition = TEXT)
   @Convert(converter = StringSetConverter.class)
   private final Set<String> losers = new HashSet<>();
 
   /**
-   * A map from choices to vote totals.
+   * A map from choices to vote totals. Not meaningful for IRV.
    */
   @ElementCollection(fetch = FetchType.EAGER)
   @CollectionTable(name = "contest_vote_total",
@@ -151,19 +154,21 @@ public class ContestResult implements PersistentEntity, Serializable {
   private String contestName;
 
   /**
-   * The margin divided by total number of ballots cast.
+   * The margin divided by total number of ballots cast. Not correct, and not used, for IRV.
    */
   @Column(name = "diluted_margin")
   private BigDecimal dilutedMargin;
 
   /**
-   * The smallest margin between any winner and loser of the contest
+   * The smallest margin between any winner and loser of the contest. Not correct, and not used,
+   * for IRV.
    */
   @Column(name = "min_margin")
   private Integer minMargin;
 
   /**
-   * The largest margin between any winner and loser of the contest.
+   * The largest margin between any winner and loser of the contest. Not correct, and not used,
+   * for IRV.
    */
   @Column(name = "max_margin")
   private Integer maxMargin;
@@ -310,7 +315,7 @@ public void setWinners(final Set<String> winners) {
   }
 
   /**
-   * @return the winners for thie ContestResult.
+   * @return the winners for this ContestResult.
    */
   public Set<String> getWinners() {
     return Collections.unmodifiableSet(this.winners);
@@ -332,7 +337,7 @@ public Set<String> getLosers() {
   }
 
   /**
-   * @return a map from choices to vote totals.
+   * @return a map from choices to vote totals. Not relevant or correct for IRV.
    */
   public Map<String, Integer> getVoteTotals() {
     return Collections.unmodifiableMap(this.vote_totals);
@@ -344,7 +349,7 @@ public Integer totalVotes() {
   }
 
   /**
-   * @param voteTotals a map from choices to vote totals.
+   * @param voteTotals a map from choices to vote totals. Not relevant or correct for IRV.
    */
   public void setVoteTotals(final Map<String, Integer> voteTotals) {
     this.vote_totals = voteTotals;
@@ -358,7 +363,8 @@ public void setDilutedMargin(final BigDecimal dilutedMargin) {
   }
 
   /**
-   * The diluted margin (μ) of this ContestResult
+   * The diluted margin (μ) of this ContestResult.  Not relevant or correct for IRV unless it has
+   * been externally set after assertion generation.
    */
   public BigDecimal getDilutedMargin() {
     return this.dilutedMargin;
@@ -372,21 +378,23 @@ public void setMinMargin(final Integer minMargin) {
   }
 
   /**
-   * The smallest margin between any winner and loser of the contest
+   * The smallest margin between any winner and loser of the contest. Not relevant or correct for
+   * IRV unless it has been externally set after assertion generation.
    */
   public Integer getMinMargin() {
     return this.minMargin;
   }
 
   /**
-   * set maxMargin.
+   * set maxMargin. Not relevant or correct for IRV.
    */
   public void setMaxMargin(final Integer maxMargin) {
     this.maxMargin = maxMargin;
   }
 
   /**
-   * The largest margin between any winner and loser of the contest
+   * The largest margin between any winner and loser of the contest. Not relevant or correct for
+   * IRV.
    */
   public Integer getMaxMargin() {
     return this.maxMargin;

server/eclipse-project/src/main/java/us/freeandfair/corla/model/CountyContestResult.java

@@ -54,6 +54,8 @@
 
 /**
  * A class representing the results for a single contest for a single county.
+ * This always does a *plurality* count, which will give wrong answers (including wrong winners)
+ * for IRV. These are never used for IRV contests.
  * 
  * @author Daniel M. Zimmerman <dmz@freeandfair.us>
  * @version 1.0.0
@@ -252,7 +254,7 @@ public Map<String, Integer> voteTotals() {
 
   /**
    * @return a list of the choices in descending order by number of votes
-   * received.
+   * received. This is a plurality tally with no connection to ranked-choice voting.
    */
   public List<String> rankedChoices() {
     final List<String> result = new ArrayList<String>();