event-tracker/README.md

Event Tracker

Single-window GTK3 app. One button per event logs a timestamp to a CSV file; the window shows total count, avg/hour, avg/day, last logged time, and time since last event (to the minute, ticks forward live) per event, plus a line graph of today's counts by hour (whole-number y-axis).

View Stats & Trends opens a per-event breakdown: today / this week / this month, last 7 and 30 days with daily average, trend vs the prior 7 days, current/longest day streaks, busiest hour and day, a weekday breakdown, and three trend charts (by hour, by week, by month).

Settings lets you rename an existing event (renaming migrates its past log entries to the new name, nothing is lost), add a new event — each gets its own button and its own color, cycling through 6 colors if you add more than that — and relocate the data file itself (Browse to pick a new location; the existing log is moved there on Save, and anything already at the destination is backed up first).

Reset Stats clears the log after a confirmation dialog. The current log is copied to a timestamped .bak-YYYYMMDD-HHMMSS file first, so a mis-click doesn't destroy history — restore it by copying that file back over event_log.csv.

1. Check what's already installed (read-only)

Run this before installing anything — it tells you exactly what's missing:

python3 -c "import gi; gi.require_version('Gtk','3.0'); from gi.repository import Gtk; print('PyGObject/GTK3: OK')" 2>&1
python3 -c "import matplotlib; print('matplotlib:', matplotlib.__version__)" 2>&1
python3 -c "import matplotlib; matplotlib.use('GTK3Agg'); from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg; print('GTK3Agg backend: OK')" 2>&1

Any line printing a Traceback instead of "OK" / a version number tells you which piece is missing.

2. Install missing pieces

Arch / EndeavourOS:

sudo pacman -S --needed python-gobject gtk3 python-matplotlib

Debian / derivatives:

sudo apt install python3-gi gir1.2-gtk-3.0 python3-matplotlib

Don't pip install PyGObject — it needs the system GTK3 dev headers and is far more reliable installed as a distro package.

3. Run

chmod +x event_tracker.py
./event_tracker.py

4. Optional: desktop launcher

./install-launcher.sh

Generates event-tracker.desktop for wherever you actually cloned this repo (event-tracker.desktop.in is a template with no machine-specific path baked in) and installs it to ~/.local/share/applications/. Re-run it if you move the clone.

Data

Log file: ~/.local/share/event-tracker/event_log.csv by default — columns event,timestamp, plain CSV, edit by hand if you need to correct an entry. Created automatically on first run. Move it anywhere via Settings → Data file location; the app always reads its current location from config.json rather than a hardcoded path.

App settings (event list + current data file location): ~/.local/share/event-tracker/config.json — always lives here, written the first time you Save changes in Settings. This one small file isn't user-relocatable (it's the pointer to where your real data is, not the data itself); until it exists the app uses DEFAULT_EVENTS / DEFAULT_DATA_PATH from the script.

If you're upgrading from the single-event version, the old cigarette_log.csv (header: timestamp only) is auto-migrated the first time this version runs — its rows are relabelled Cigarette and written into event_log.csv in the new two-column format. The old file is left untouched on disk.

Configuration

All tunables sit at the top of event_tracker.py:

Variable	Meaning
DEFAULT_EVENTS	Starting event list, used only if config.json doesn't exist yet
COLOR_PALETTE	Colors assigned to events by list position, cycles if you have more events than colors
DEFAULT_DATA_PATH	Starting data file location, used only if config.json doesn't exist yet
CONFIG_PATH	Where app settings (event list + current data file location) are saved — fixed, not relocatable
WEEKLY_WEEKS	Trailing weeks shown in the stats popup's weekly chart
MONTHLY_MONTHS	Trailing months shown in the stats popup's monthly chart
TIMESTAMP_FORMAT	Format used to read/write timestamps in the CSV

Renaming/adding events or moving the data file day-to-day: use the in-app Settings button, not this file — it persists to config.json, migrates existing log rows on rename, and moves the CSV on relocation.

Android companion

android/ has a minimal Kivy app that reads/writes this same CSV format — point it at whatever local folder your phone's sync tool (FolderSync, DAVx5, etc.) mirrors from wherever this app's data file lives. See android/README.md for the build (you build it yourself on a Linux machine — no signing keys or accounts of ours involved).