diff --git a/src/index.rst b/src/index.rst index 52cba29..08f30fb 100644 --- a/src/index.rst +++ b/src/index.rst @@ -45,6 +45,13 @@ Table of contents development forking +.. _research-docs: +.. toctree:: + :maxdepth: 2 + :caption: Research + + research/index + .. _meta-docs: .. toctree:: :maxdepth: 3 diff --git a/src/research/index.rst b/src/research/index.rst new file mode 100644 index 0000000..15d6210 --- /dev/null +++ b/src/research/index.rst @@ -0,0 +1,72 @@ +.. _research: + +ActivityWatch in research +========================= + +ActivityWatch is used as a data-collection instrument in academic studies. This section +documents the **Research Edition**, a purpose-built variant for that use, and maintains the +participant-facing instructions so that studies can link to a canonical, versioned page +rather than circulating copies over email. + +Why researchers use it +---------------------- + +- **Local-first.** Data stays on the participant's device. Nothing is transmitted + automatically. The participant creates an export file and uploads it deliberately, which + makes the data flow easy to describe in an ethics application. +- **Open source.** The collection logic can be read, audited and cited by reviewers. +- **Cross-platform.** Windows, macOS and Linux, plus Android. +- **Category-only collection.** The Research Edition can be configured to store predefined + categories rather than window titles or URLs. + +Self-reported computer use is a poor measure of actual computer use. The canonical validity +study found that self-report agreed with software registration for only 18% of participants, +and misclassified exposure for more than 80%: + + IJmker S, Leijssen JNM, Blatter BM, van der Beek AJ, van Mechelen W, Bongers PM. + *Test-retest reliability and validity of self-reported duration of computer use at work.* + Scand J Work Environ Health. 2008;34(2):113-119. `doi:10.5271/sjweh.1220 + `_ + +How to cite +----------- + +If you use ActivityWatch in published work, please cite the software: + + Bjäreholt E, Bjäreholt J. *ActivityWatch.* `doi:10.5281/zenodo.4957165 + `_ + +The repository also contains a ``CITATION.cff``, which GitHub renders as a +"Cite this repository" button. + +Studies using ActivityWatch +--------------------------- + +An incomplete list, maintained so that researchers choosing an instrument can see prior use. +ActivityWatch typically appears in methods sections rather than titles or abstracts, so it is +largely invisible to citation indexes — if you have used it and are not listed, please tell us. + +- **Psychological Wellbeing, Sleep, and Video Gaming: Analyses of Comprehensive Digital + Traces** — Oxford Internet Institute (Ballou, Földes, Hakman, Vuorre, Magnusson, Przybylski), + Stage 1 Registered Report, 2025. ActivityWatch used as the Android data-collection channel + for 2,000+ participants over three months. +- **On/Off** — imec-mict-UGent (Vanden Abeele, Perneel, Van Gaeveren), the DISCONNECT ERC + citizen-science panel. ActivityWatch used for opt-in laptop and PC collection, documented in + the study's participant information and privacy materials. +- **Traces as Data** — Parry & Klingelhoefer, handbook chapter, 2025. Named as an exemplar + desktop-logging tool. +- **Sabermetrics for Cyber** — Rivera, Booz & Hammerstein, ECCWS 2025. Used as an instrument. +- **Activity Frames** — Iyamu, 2026 (arXiv:2608.05784). +- Theses: Kroček (University of South Bohemia, 2020), Kraus (Czech Technical University in + Prague, 2021), Panchuk (NURE Kharkiv, 2026). + +Further deployments are known but unpublished or not yet listed here, including at the +University of Maryland iSchool, MIT Media Lab, Clemson University, and Lund University's IIIEE. + +If you are running or planning a study, please get in touch. We are glad to help scope the +instrument, and we keep a list of studies that have used ActivityWatch. + +.. toctree:: + :maxdepth: 2 + + participant-instructions diff --git a/src/research/participant-instructions.rst b/src/research/participant-instructions.rst new file mode 100644 index 0000000..c773a33 --- /dev/null +++ b/src/research/participant-instructions.rst @@ -0,0 +1,119 @@ +.. _research-participant-instructions: + +Participant instructions (Research Edition) +=========================================== + +.. note:: + **For researchers.** This page is maintained by the ActivityWatch project so that studies + can link to it instead of maintaining their own copy of the technical steps. It is kept in + sync with the current Research Edition build. + + Adapt freely: add your study name, your contact details, and your upload location. + Translate as needed. The parts worth linking rather than copying are the mechanics below, + because those are what change between releases. + + *Last reviewed: 2026-09-16, against v0.14.0b5-research.* + +The Research Edition is a separate build. It installs alongside a normal ActivityWatch +installation without interfering with it: the Research Edition runs on port **5667**, a +standard installation runs on port 5600. The dashboard shows a **Research Edition** badge at +the top. If you see that badge, you are in the right place. + +Installing +---------- + +Download the build for your system from the link your researcher gave you, then open the +downloaded file and follow the installation steps. + +**Windows.** The installer is not code-signed, so Windows may show a blue +"Windows protected your PC" dialog. Click **More info**, then **Run anyway**. + +During installation, leave **Start ActivityWatch when Windows starts** ticked. It is ticked +by default. + +**macOS.** The app asks for two separate permissions, and it needs both: + +1. **Accessibility.** On first launch you may see "Missing accessibility permissions". + Enable *ActivityWatch Research* under System Settings > Privacy & Security > + Accessibility, and restart the app if prompted. Without this permission the app cannot + record anything. +2. **Browser control.** If you use Chrome or Safari, macOS asks whether + *ActivityWatch Research* may control it. Click **OK**. This is only used to sort the page + into a category. The address is not stored. + +If macOS shows a notification that a background item was added, leave it allowed. + +Starting automatically +---------------------- + +The Research Edition enables start-at-login by itself the first time it runs. You do not need +to configure anything. + +It is still worth checking once or twice during the study that the icon is present: in the +system tray on Windows (bottom right, possibly hidden under the **^** arrow), or in the menu +bar on macOS (top right). If it is missing, start *ActivityWatch Research* from the Start menu +or Applications folder. + +What is recorded +---------------- + +The Research Edition records **which applications you use** (for example Word, Teams or +Chrome) and for how long. It does **not** record which websites you visit or what your window +titles say. Browser activity is converted into predefined categories on your own computer +before anything is stored, and your computer's hostname is removed from the export. + +No information about your activity is sent anywhere automatically. At the end of the study you +create a file and upload it yourself. + +(For completeness: if you open the dashboard, the web interface asks GitHub for the latest +version number. That request contains nothing about your activity.) + +Exporting your data at the end of the study +------------------------------------------- + +Do this once, at the end of the study period, and keep the Research Edition running while you +do it. It takes a couple of minutes. + +1. Click the **ActivityWatch Research** icon (macOS: menu bar, top of the screen. Windows: + bottom right near the clock, possibly under the **^** arrow) and choose **Open Dashboard**. + The dashboard opens in your browser. Check that it says **Research Edition** at the top. + If the dashboard does not open, go to http://localhost:5667 +2. Click **Raw Data** at the top right of the page. If your dashboard is not in English, + this is the same button under a translated name (Swedish: **Rådata**). +3. You will see two rows, ``aw-watcher-window_…`` and ``aw-watcher-afk_…``. That is normal. + **Do not export them one by one.** Scroll down to **Import and export buckets**, and under + **Export buckets** click **Export all buckets as JSON** (Swedish: **Importera och + exportera buckets** > **Exportera alla buckets som JSON**). +4. A file named ``aw-bucket-export.json`` appears in your Downloads folder. You do not need to + open or edit it. +5. Upload that file where your researcher has asked you to. + +If something looks wrong, contact your researcher rather than searching online. The study +version behaves differently from the public ActivityWatch. + +Notes for researchers +--------------------- + +A few things that reliably cause support questions: + +- **Two buckets is correct**, not a symptom of a double installation: one window watcher and + one AFK watcher. Four rows would mean the participant opened the standard dashboard on port + 5600 instead. +- **Use "Export all buckets as JSON", not the per-row menu.** The three-dot menu on a row + exports a single bucket. Participants following that route upload two files, or silently + omit AFK data. +- **JSON, not CSV.** CSV covers one bucket, contains events only, carries no metadata, and + does not go through the export API. +- **The interface may not be in English.** The web UI ships ``en``, ``uk``, ``de``, ``ru``, + ``zh-CN`` and ``sv`` locales, and it **selects one automatically from the browser + language** unless the participant has already chosen one. Translation coverage is + incomplete across all locales, so participants will see a mix. The tray menu is hardcoded + English regardless. + + Write button names in both languages in your participant instructions, for example + "Rådata (Raw Data)". Assuming English will send some participants looking for a label + their screen does not show. +- **The exported filename is fixed.** It cannot carry a participant number, so your upload + form needs a field or a per-participant link. +- **Live Raw Data is unsanitised by design.** The rewriting to ``research-participant`` + happens in the export.