diff --git a/README.md b/README.md index 2525db2..183c77c 100644 --- a/README.md +++ b/README.md @@ -16,21 +16,97 @@ A Clojure library designed to explore donations data for people in Gaza whose ac This is a very experimental, unfinished and unpolished library designed for use with leiningen. To use, clone this repository, connect to the directory into which you cloned it, and type `lein repl`. -At present two useful functions are implemented: +At present several useful functions are implemented: -### `(total-donations-by-weeks start-date end-date)` +### accounts-with-donations-by-date-range -Return a list of pairs [java.time.LocalDate date, float amount] representing -the total of donations made between `start-date` and `end-date`. Arguments may -be supplied as `java.time.LocalDate` objects, or as strings in the format -`yyyy-mm-dd`. If `end-date` is not supplied, data for a single week will be -returned. +``` +(accounts-with-donations-by-date-range start-date end-date) +``` -### `(chart-total-donations-by-weeks start-date end-date)` +Return a list of maps, each representing one account from the `gaza.onl` database, with a key `:donations`, whose value is a float representing the total donations received by that account between the dates `start-date` (exclusive) and `end-date` (inclusive). Date arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. -Create and return an XY chart of data on total donations made between -`start-date` and `end-date`. Arguments may be supplied as -`java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L98) + +### chart-accounts-with-donations-by-months-in-range + +``` +(chart-accounts-with-donations-by-months-in-range start-date end-date) +``` + +Return a chart with one line for each calendar month covering from `start-date` (inclusive) to `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`, showing donations as for `chart-donations-by-accounts-in-date-range`, q.v. + +TODO: There are currently two problems with this at present: chart legends are not displayed in sequential order; and there appears to be occasional spurious data (but I don’t know why). + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L138) + +### chart-donations-as-percentage-in-date-range + +``` +(chart-donations-as-percentage-in-date-range start-date end-date) +``` + +Return a chart of donations received by individual accounts between `start-date` (exclusive) and `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. Accounts are identified in the chart only by rank order. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L125) + +### chart-donations-by-accounts-in-date-range + +``` +(chart-donations-by-accounts-in-date-range start-date end-date) +``` + +Return a chart of donations received by individual accounts between `start-date` (exclusive) and `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. Accounts are identified in the chart only by rank order. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L115) + +### chart-donations-by-weeks + +``` +(chart-donations-by-weeks start-date end-date key) +``` + +Create and return an XY chart of data on field represented by `key` of donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L58) + +### chart-number-donations-by-weeks + +``` +(chart-number-donations-by-weeks start-date end-date) +``` + +Create and return an XY chart of data on number of donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L75) + +### chart-total-donations-by-weeks + +``` +(chart-total-donations-by-weeks start-date end-date) +``` + +Create and return an XY chart of data on total donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L68) + +### enhance-account-with-donations + +``` +(enhance-account-with-donations account-map sd ed) +``` + +Take this `account_map`, which must at least have a valid value for the key `:campaign_url` and return a similar map including the key `:donations`, whose value is a float representing the total donations received by that campaign URL between the dates `sd` (exclusive) and `ed` (inclusive). Date arguments should be supplied as `java.time.LocalDate` objects. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L82) + +### total-donations-by-weeks + +`(total-donations-by-weeks start-date)``(total-donations-by-weeks start-date end-date)` + +Return a list of pairs [java.time.LocalDate date, float amount](file:///home/simon/workspace/gaza-stats/docs/codox/java.time.LocalDate date, float amount) representing the total of donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. If `end-date` is not supplied, data for a single week will be returned. + +[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L18) ### Viewing charts diff --git a/project.clj b/project.clj index c781149..e6bfa22 100644 --- a/project.clj +++ b/project.clj @@ -1,4 +1,12 @@ (defproject gaza-stats "0.1.0-SNAPSHOT" + :codox {:froboz.cloverage {:output "docs/cloverage" + :codecov? true + :html? true + :debug? true} + :metadata {:doc "**TODO**: write docs" + :doc/format :markdown} + :output-path "docs/codox" + :source-uri "https://github.com/simon-brooke/gaza-stats/blob/main/{filepath}#L{line}"} :dependencies [[org.clojure/clojure "1.12.6"] [com.hypirion/clj-xchart "0.2.0"] [korma "0.4.3"] @@ -6,8 +14,8 @@ [org.xerial/sqlite-jdbc "3.7.15-M1"]] :description "FIXME: write description" ;; :jvm-opts ["-Xmx4g"] - :license {:name "GNU General Public License,version 2.0 or (at your option) an -y later version" + :license {:name "GNU General Public License,version 2.0 or (at your option) any later version" :url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"} + :plugins [[lein-codox "0.10.8"]] :repl-options {:init-ns gaza-stats.core} :url "http://example.com/FIXME") diff --git a/src/gaza_stats/core.clj b/src/gaza_stats/core.clj index 44f8bd4..94ca779 100644 --- a/src/gaza_stats/core.clj +++ b/src/gaza_stats/core.clj @@ -136,6 +136,15 @@ [(range (count data)) percentages]}))) (defn chart-accounts-with-donations-by-months-in-range + "Return a chart with one line for each calendar month covering from + `start-date` (inclusive) to `end-date` (inclusive). Arguments should be + supplied as `java.time.LocalDate` objects, or as strings in the format + `yyyy-mm-dd`, showing donations as for + `chart-donations-by-accounts-in-date-range`, q.v. + + TODO: There are currently two problems with this at present: chart legends + are not displayed in sequential order; and there appears to be occasional + spurious data (but I don't know why)." [start-date end-date] (let [sd (cond (date? start-date) start-date (string? start-date) (ld/parse start-date)