From eb406cbf2c23a9116be92246098c487a131e144c Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Sun, 19 Jun 2016 03:11:04 +0300 Subject: doc/ -> docs/ --- docs/images/online_duration/date.png | Bin 0 -> 14223 bytes docs/images/online_duration/hour.png | Bin 0 -> 53227 bytes docs/images/online_duration/user.png | Bin 0 -> 20610 bytes docs/images/online_duration/weekday.png | Bin 0 -> 33239 bytes docs/mutual_friends.md | 51 ++++++++++ docs/online_duration.md | 161 ++++++++++++++++++++++++++++++++ docs/track_status.md | 42 +++++++++ 7 files changed, 254 insertions(+) create mode 100644 docs/images/online_duration/date.png create mode 100644 docs/images/online_duration/hour.png create mode 100644 docs/images/online_duration/user.png create mode 100644 docs/images/online_duration/weekday.png create mode 100644 docs/mutual_friends.md create mode 100644 docs/online_duration.md create mode 100644 docs/track_status.md (limited to 'docs') diff --git a/docs/images/online_duration/date.png b/docs/images/online_duration/date.png new file mode 100644 index 0000000..477c530 Binary files /dev/null and b/docs/images/online_duration/date.png differ diff --git a/docs/images/online_duration/hour.png b/docs/images/online_duration/hour.png new file mode 100644 index 0000000..cad26b3 Binary files /dev/null and b/docs/images/online_duration/hour.png differ diff --git a/docs/images/online_duration/user.png b/docs/images/online_duration/user.png new file mode 100644 index 0000000..13a7420 Binary files /dev/null and b/docs/images/online_duration/user.png differ diff --git a/docs/images/online_duration/weekday.png b/docs/images/online_duration/weekday.png new file mode 100644 index 0000000..5cf659e Binary files /dev/null and b/docs/images/online_duration/weekday.png differ diff --git a/docs/mutual_friends.md b/docs/mutual_friends.md new file mode 100644 index 0000000..cc9396e --- /dev/null +++ b/docs/mutual_friends.md @@ -0,0 +1,51 @@ +mutual_friends.py +================= + +Learn who your ex and her new boyfriend are both friends with. + +Usage +----- + +Run from the top-level directory using `python -m`. +For example: + + > python -m bin.mutual_friends -h + usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...] + ... + +For example (using made up user IDs/"screen names"), + + > python -m bin.mutual_friends john.doe jane.doe + 89497105,John,Smith,john.smith + 3698577,Jane,Smith,jane.smith + +In the example above, both "John Doe" and "Jane Doe" are friends with "John +Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively. +Their "screen names" (the part after "vk.com/" of their personal page URLs) are +"john.smith" and "jane.smith". + +The output format is CSV (comma-separated values) by default. +You can also get a JSON document: + + > python -m bin.mutual_friends --output-format json john.doe jane.doe + [ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith", + "screen_name": "john.smith" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith", + "screen_name": "jane.smith" + } + ] + +See also +-------- + +* [License] + +[License]: ../README.md#license diff --git a/docs/online_duration.md b/docs/online_duration.md new file mode 100644 index 0000000..22af4b1 --- /dev/null +++ b/docs/online_duration.md @@ -0,0 +1,161 @@ +online_duration.py +================== + +View/visualize the amount of time people spend online. + +Usage +----- + +Run from the top-level directory using `python -m`. +For example: + + > python -m bin.online_duration -h + usage: online_duration.py [-h] [--grouping {user,date,weekday,hour}] + [--input-format {csv,log,null}] + [--output-format {csv,json,img}] [--from DATE_FROM] + [--to DATE_TO] + input [output] + +This script additionally requires [matplotlib] to be installed. + +Analyze the database produced by [track_status.py] and calculate the total +amount of time people spent online. + +For example (assuming the database in "db.csv" was generated by +[track_status.py] before): + + > python -m bin.online_duration db.csv + 89497105,John,Smith,john.smith,0:12:31 + 3698577,Jane,Smith,jane.smith,1:34:46 + +In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95 +minutes online respectively. + +The output format is CSV (comma-separated values) by default. +You can also get a JSON document: + + > python -m bin.online_duration --output-format json db.csv + [ + { + "uid": 89497105, + "first_name": "John", + "last_name": "Smith", + "screen_name": "john.smith", + "duration": "0:12:31" + }, + { + "uid": 3698577, + "first_name": "Jane", + "last_name": "Smith", + "screen_name": "jane.smith", + "duration": "1:34:46" + } + ] + +The durations are calculated on a per-user basis by default. +You can change that by supplying either `date` (to group by dates), `weekday` +(to group by weekdays) or `hour` (to group by day hours) as the `--grouping` +parameter value. +For example (assuming that both Jane and Joe spent their time online on Friday, +June 17, 2016). + +``` +> python -m bin.online_duration --output-format json --grouping date db.csv +[ + { + "date": "2016-06-17", + "duration": "1:47:17" + } +] +``` + +``` +> python -m bin.online_duration --output-format csv --grouping weekday db.csv +Monday,0:00:00 +Tuesday,0:00:00 +Wednesday,0:00:00 +Thursday,0:00:00 +Friday,1:47:17 +Saturday,0:00:00 +Sunday,0:00:00 +``` + +``` +> python -m bin.online_duration --grouping hour db.csv +0:00:00,0:00:00 +1:00:00,0:00:00 +2:00:00,0:00:00 +3:00:00,0:00:00 +4:00:00,0:03:56 +5:00:00,0:14:14 +6:00:00,0:29:30 +7:00:00,0:31:20 +8:00:00,0:12:04 +9:00:00,0:00:00 +10:00:00,0:00:00 +11:00:00,0:23:14 +12:00:00,0:06:00 +13:00:00,0:46:19 +14:00:00,0:00:00 +15:00:00,0:00:00 +16:00:00,0:00:00 +17:00:00,0:00:00 +18:00:00,0:00:00 +19:00:00,0:00:00 +20:00:00,0:00:00 +21:00:00,0:00:00 +22:00:00,0:00:00 +23:00:00,0:00:00 +``` + +In my opinion, the script's most useful feature is the ability to easily create +plots that represent the text data (like in the examples above). +To produce a plot, pass `img` as the `--output-format` parameter value and add +a file path to write the image to. + + > python -m bin.online_duration --output-format img db.csv user.png + +![user.png] + + > python -m bin.online_duration --output-format img --grouping date db.csv date.png + +![date.png] + + > python -m bin.online_duration --output-format img --grouping weekday db.csv weekday.png + +![weekday.png] + + > python -m bin.online_duration --output-format img --grouping hour db.csv hour.png + +![hour.png] + +You can limit the scope of the database by supplying a time range. +Only online durations that are within the supplied range shall then be +processed. +Set the range by specifying both or one of the `--from` and `--to` parameters. +Values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601). + +All dates and times are in UTC. + +[matplotlib]: http://matplotlib.org/ +[track_status.py]: track_status.md + +[user.png]: images/user.png +[date.png]: images/date.png +[weekday.png]: images/weekday.png +[hour.png]: images/hour.png + +Known issues +------------ + +* When people go online using the web version and don't visit other pages over +time (for example, just listening to music), they appear offline. +Hence the 0:00:00 durations you might sometimes encounter. +This might also happen using other clients. + +See also +-------- + +* [License] + +[License]: ../README.md#license diff --git a/docs/track_status.md b/docs/track_status.md new file mode 100644 index 0000000..8bbb380 --- /dev/null +++ b/docs/track_status.md @@ -0,0 +1,42 @@ +track_status.py +=============== + +Track when people go online/offline. + +Usage +----- + +Run from the top-level directory using `python -m`. +For example: + + > python -m bin.track_status -h + usage: track_status.py [-h] [-t TIMEOUT] [-l LOG] + [--output-format {csv,log,null}] [-o OUTPUT] + UID [UID ...] + ... + +For example (using made up user IDs/"screen names"), + + > track_status.py john.doe jane.smith + [2016-06-18 01:43:34] John Doe is ONLINE. + [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app. + [2016-06-18 01:43:34] Jane Smith is OFFLINE. + [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app). + [2016-06-18 01:59:09] Jane Smith went ONLINE. + [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app. + [2016-06-18 02:10:00] John Doe went OFFLINE. + [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app. + ... + +By default, the script produces a human-readable log. +Use the `--log` parameter to write the log to a file. +If you want to record when people go online/offline for [further analysis], +specify the path to a database using the `--output` parameter. +Be careful: if the file already exists, it will be overwritten! + +See also +-------- + +* [License] + +[License]: ../README.md#license -- cgit v1.2.3