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:

```sh
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:**

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

**Debian / derivatives:**

```sh
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

```sh
chmod +x event_tracker.py
./event_tracker.py
```

## 4. Optional: desktop launcher

```sh
./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).