             [forma.hadoop.io :as io]
             [forma.hadoop.predicate :as p]))
 
-;; ### Schema Application
-;;
-;; The fires dataset is different from previous MODIS datasets in that
-;; it requires us to keep track of multiple values for each MODIS
-;; pixel. We must maintain a total fire count, as well as a count of
-;; the subsets of the total that satisfy certain conditions, such as
-;; `Temp > 330 Kelvin`, `Confidence > 50`, or both at once. We
-;; abstract this complication away by wrapping up each of these into a
-;; clojure map. For example:
-;;
-;;    {:temp-330 1
-;;     :conf-50 1
-;;     :both-preds 1
-;;     :count 2}
-;;
-;; compound value, represented as a fire-value. We wrap
-;; up collections of fire values into a timeseries-value.
+(defn daily-datestring
+  "Returns a daily date string formatted as YYYY-MM-DD.
 
-;; ### Fire Predicates
+   Arguments:
+     date-str - Daily date string formatted as MM/DD/YYYY.
 
-(defn daily-datestring
-  "Takes a datestring from our daily fire datasets, formatted as
-  `MM/DD/YYYY`, and returns a date formatted as `YYYY-MM-DD`."
-  [datestring]
-  (let [[month day year] (s/split datestring #"/")]
+  Example usage:
+    > (daily->standard 1977/02/02)
+    02-1977-02"
+  [date-str]
+  (let [[month day year] (s/split date-str #"/")]
     (s/join "-" [year month day])))
 
 (defn monthly-datestring
-  "Takes a datestring from our monthly fire datasets, formatted as
-  `YYYYMMDD`, and returns a date formatted as `YYYY-MM-DD`."
-  [datestring]
-  (convert datestring :basic-date :year-month-day))
+  "Returns a monthly date string formatted as YYYY-MM-DD.
+
+   Arguments:
+     date-str - Monthly date string formatted as YYYYMMDD.
+
+  Example usage:
+    > (monthly->standard 19770202)
+    1977-02-02"  
+  [date-str]
+  (convert date-str :basic-date :year-month-day))
 
 (def fire-characteristics
-  "Predicate macro that converts confidence and temperature into a
-   tuple of fire characteristics."
+  "Returns a Cascalog predicate macro that creates a FireTuple Thrift object.
+
+  Input variables:
+    ?conf - The fire confidence value.
+    ?kelvin - The fire degress in Kelvin
+
+  Output variables:
+    ?tuple - The FireTuple Thrift object.
+
+  Example usage:
+
+    > (let [src [[60 380]]]
+            (??<-
+            [?tuple]
+            (src ?conf ?kelvin)
+            (fire-characteristics ?conf ?kelvin :> ?tuple)))"
   (<- [?conf ?kelvin :> ?tuple]
       (p/full-count ?conf :> ?count)
       (p/filtered-count [330] ?kelvin :> ?temp-330)

      (:distinct false)))

(defn reproject-fires
  "Aggregates fire data at the supplied path by modis pixel at the
  supplied resolution."
  [m-res src]
  (<- [?datachunk]
      (p/add-fields m-res :> ?m-res)

      (:distinct false)))

(defn fire-source-daily
  "Returns a Cascalog query that creates tuples for daily fires.

  Source:
    src - An hfs-textline of daily fires (lat lon kelvin _ _ date _ _ conf _ _ _)

  Output variables:
    ?dataset - The dataset name (fires).
    ?date - The fire date formatted as YYYY-MM-DD.
    ?t-res - The fire temporal resolution (1).
    ?lat - The fire latitude as a float.
    ?lon - The fire longitude as a float.
    ?tuple - The FireTuple Thrift object representing the fire."
  [src]
  (<- [?dataset ?date ?t-res ?lat ?lon ?tuple]
      (src ?line)
