webactogram 0.4.1

Actogram from browsers history, may help to screen sleep-wake patterns & disorders!

WebActogram

🌐🏃Use your browser's history as a novel instantaneous mass screening tool for 🌙🛌sleep patterns & maybe disorders!

Description

Python 3 tool to generate an online actogram from web browsers history files. Supports various browsers including Google Chrome, Mozilla Firefox and Safari history files (full list of supported browsers here).

To screen sleep-wake patterns and disorders, all such tools require that the user wear an actigraphic device or record themselves a sleep diary. The limitation is that first there needs to be a suspicion of a sleep disorder to request such data from a subject, and secondly it takes weeks or even months of rigorously acquired data by a very compliant subject, for the sleep clinician to then be able to interpret if there is any potential sleep disorder.

The web actogram is the first pseudo-actigraphic tool that can provide an instantaneous estimation of the user’s sleep-wake pattern, aka actogram, by inferring an actogram from the browser’s history. This could allow for mass screening of sleep-wake patterns and disorders via the simple and fast installation of an app.

Multiple web browsers are supported, and the histories of all supported browsers will be merged automatically, and include all profiles installed in all browsers.

Example plots: horizontal (landscape) mode:

Vertical (portrait) mode:

The limitations are however as follows:

• The sleep patterns - the main measure of interest - are only very indirectly estimated, as this tool is estimating the wakefulness pattern, and even that is only partially covered since this tool analyzes internet desktop browsers histories (not whole computer usage history nor mobile nor user's activity the whole day).
• The web actogram reliability depends on whether the user is an avid user of web browsers: they must use their web browsers on an almost daily basis. They do not need to use their browser all the time however, but they need to use it regularly, so that we can estimate their wakefulness period. So regularity is necessary, not quantity. But even if quantity is not necessary, the more avid use of browsers, the more datapoints and the more reliable the estimate will be.
• The user must primarily use a web browser on a computer (not on a smartphone - this will be implemented in the future).
• The more data over a longer period, the more precisely and robust the pattern will appear.
• If there are multiple users on the same desktop computer, the result will be unreliable, as the tool will currently merge all profiles histories data in one and hence merge the usage data from different users.

How the actogram is plotted was inspired by this UCSD tutorial and this scientific paper.

Install & Quickstart

First you need a modern Python 3 interpreter, such as Miniconda3.

Then, install WebActogram with:

pip install webactogram

Use in a terminal (or cmd on Windows):

webactogram

Note: First, you need to cd in a folder with write permission.

This will create a folder actograms in the current folder, and add inside a picture with the latest actogram and a csv file with all the browsers activities recorded.

More options, such as the sampling frequency (and hence granularity of the actogram and its patterns) can be shown with:

webactogram --help

Compatibility

Currently configured to import history from ALL browsers available on the system, from the default user profiles for each:

• Windows:
  • Chrome History file
  • Edge History file
  • Firefox History file
• MacOS:
  • Chrome History file
  • Safari History.db
  • Firefox History file
• Linux:
  • Firefox History file

Currently, this script may not function as intended if you use multiple profiles within one browser (especially for Firefox), or the browser's default installation profile has changed.

Usage

History files are copied from their home directories to a temporary location in the working directory. These copies are then deleted after the script has executed. Only the last_visit_time is read.

Plots are easily generated from the command line:

webactogram

Plots will be saved in a new sub-folder called "actograms" with appropriate timestamp and description.

Script now supports command line arguments for additional customizability. For example:

python actogram.py --freq '15T' --daily_blur 3 --start '2020-01-01'

python actogram.py --freq '30T' --printer_friendly True

python actogram.py --dims (8,8)

Where:

--freq determines the granularity of binned online/offline periods (default is 15 minutes increments, ex.  --freq '15T')

--start_date sets initial date to plot from, default is 180 days ago (ex. --start_date '2022-01-01')

--daily_blur applies median filtering between days (off by default, ex. --daily_blur 3)  

--period_blur applies median filtering between binned time periods (off by default, ex. --period_blur 5)

--normalize normalizes search frequency against max, then applies binary mask (plot shows periods of some search history vs. none, on by default)

--dims sets the relative dimensions of generated actogram plot (ex. --dims (4, 6))

--printer_friendly sets whether activity is shown in black on white (friendly) or vice versa (False by default, ex. --printer_friendly True)

Authors

This tool is a fork from the excellent online_actogram script by Barrett F. Davis who conceived both the idea and the first implementation initially released in July 2020.

Since then, it is maintained by Stephen Karl Larroque and the Circadiaware Collective.

Lots of awesome contributors made awesome contributions to further improve this software, we cannot thank them enough!

For a list of all contributors, please see the GitHub Contributors graph and the commits history.

License

MIT Public License.

Similar projects

Another project, inspired by this one, was written in Javascript using D3, but it cannot fetch browser's history, it can only plot from an already extracted browser’s history: Tylian's D3 Browser's History. How to generate the history.txt file (source): It's a dump of the timestamp column with some manual processing to divide every entry by 1000, since Firefox stores them as a nanosecond epoch for some reason..