135 lines
6.7 KiB
Markdown
135 lines
6.7 KiB
Markdown
# gaza-stats
|
||
|
||
A Clojure library designed to explore donations data for people in Gaza whose accounts have been verified by the [Gaza Verified volunteers](gaza-verified.org/team/).
|
||
|
||
|
||
|
||
## Dependencies
|
||
|
||
* [Leiningen](https://leiningen.org/)
|
||
* [Clojure](https://clojure.org/)
|
||
* [cljc.java-time](https://github.com/henryw374/cljc.java-time)
|
||
* [SQL Korma](https://web.archive.org/web/20190223025406/http://www.sqlkorma.com/)
|
||
* [clj-xchart](https://github.com/hypirion/clj-xchart)
|
||
|
||
## Usage
|
||
|
||
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 several useful functions are implemented:
|
||
|
||
### accounts-with-donations-by-date-range
|
||
|
||
```
|
||
(accounts-with-donations-by-date-range 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`.
|
||
|
||
[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
|
||
|
||
In your REPL, invoke `(require '[com.hypirion.clj-xchart :refer [view]])`. You
|
||
can then invoke `view` on a chart returned by the above function, for example:
|
||
|
||
```clojure
|
||
(view (chart-total-donations-by-weeks "2024-04-01" "2026-09-20"))
|
||
```
|
||
|
||
## NOTE: Data
|
||
|
||
This code is designed to explore data in a [SQLite](https://www.sqlite.org/) database which it expects to be called `app.db` and find in its `resources` directory. This database is not included in this repository but may be downloaded from [here](https://gaza.onl/app.db).
|
||
|
||
## NOTE: Use of SQL Korma
|
||
|
||
I used SQL Korma in this project because I know it and I like it, but it is no longer maintained and its website is no longer online. The last version I could find on the Internet Archive is [here](https://web.archive.org/web/20190223025406/http://www.sqlkorma.com/). The source code is on [Github](https://github.com/korma/Korma). It might be better to rewrite so as not to use it, especially given that (at present) the SQL usage is trivial.
|
||
|
||
## License
|
||
|
||
Copyright © 2026 Simon Brooke.
|
||
|
||
This program and the accompanying materials are made available under the GNU General Public License as published by
|
||
the Free Software Foundation, either version 2 of the License, or (at your
|
||
option) any later version, with the GNU Classpath Exception which is available
|
||
at https://www.gnu.org/software/classpath/license.html.
|