 
 
 (defn conv-repness
-  ; output legend: n=#, p=prob, r=rep, t=test, a=agree, d=disagree, s=seen
+  "Computes representativeness (repness) for a given data set, group clustering and base clustering,
+  returned as a map `{:ids __ :stats __}`. The `:stats` key maps to a sequences of results, one for each
+  group cluster, each of which is a sequence where the positional index corresponds to a particular
+  comment, and each value is a hash-map of statistics for the given group/comment. The hash keys obey the
+  following legend:
+    n=#, p=prob, r=rep, t=test, a=agree, d=disagree, s=seen
+  The :ids key maps to a vector of group ids in the same order they appear in the :stats sequence."
   [data group-clusters base-clusters]
   {:ids (map :id group-clusters)
    :stats
      (->> group-clusters
-       ; Base clusters may not be necessary if we use the already compute bucket vote stats
+       ; XXX - Base clusters may not be necessary if we use the already compute bucket vote stats
+       ; A lazy-seq of 
        (mapv (comp columns get-matrix (partial rowname-subset data) #(group-members % base-clusters)))
        (apply
          map



(defn beats-best-by-test?
  [{:keys [pat rat rdt] :as comment-conv-stats} current-best-z]
  (or (nil? current-best-z)
      (> (max rat rdt) current-best-z)))


(defn passes-by-test?
  [{:keys [pat rat pdt rdt] :as comment-conv-stats}]
  (or (and (z-sig-90? rat) (z-sig-90? pat))
      (and (z-sig-90? rdt) (z-sig-90? pdt))))


(defn finalize-cmt-stats
  [tid {:keys [na nd ns pa pd pat pdt ra rd rat rdt] :as comment-conv-stats}]
  (let [[n-success n-trials p-success p-test repness repness-test repful-for]
         (if (> rat rdt)

         (apply concat))))


(defn- count-votes
  [votes & [vote]]
  "Utility function for counting the number of votes matching `vote`. Not specifying `vote` returns
  length of vote vector."
  (let [filt-fn (if vote #(= vote %) identity)]
    (count (filter filt-fn votes))))

