gabogg/hikcentral
Watch
1
0
Fork
You've already forked hikcentral
 0
Code Issues 113 Pull requests 8 Projects Releases Packages Wiki Activity Actions

feat(analytics): usual-weekday baselines for intraday routes #88

New issue
Closed
opened 2026-09-24 23:23:43 +00:00 by gabogg · 1 comment
gabogg commented 2026-09-24 23:23:43 +00:00
Owner
Copy link

Change

Add a baseline to two existing routes instead of creating new ones:

  • GET /api/analytics/timeseries/hourly?date=…&baseline=same_weekday_4w: adds the mean of the previous 4 same weekdays per bucket.
  • GET /api/analytics/dwell/dayparts?day=…&baseline=same_weekday_4w: adds the usual daypart split.

Used by

Day view: visitors by hour against a usual weekday, and the daypart split against usual.

Notes

  • Baseline days that are holidays, gap-estimated or low-trust should be skipped (or reported) so they don't distort the "usual" line.
  • /dwell/dayparts currently defaults to the calendar date, not the business day (#77 item 2).

Context

Part of the statistics deck redesign, draft RFC in #80 (docs/architecture/rfc-statistics-deck-display-model.md; mockup linked there). Period selection was decided in #81 (closed): a period is identified by granularity (day / week / month) and its first business day; see the glossary terms Complete Period and Partial Period. A year period is out of scope.

Shared constraints (all statistics-deck routes)

  • Periods are closed business periods in facility time (daily_reset_time boundaries, app/facility_time.py); an in-progress cycle is never returned.
  • Only counted cameras contribute (_COUNTED_CAMERA_JOIN / _COUNTED_CAMERA_FILTER); quarantined events never do.
  • Every period-level figure carries its data quality: gap-estimated days (ingestion anomaly ledger), Data Trust and Cycle Completeness for the cycles involved, so the deck can mark estimates.
  • Dwell means the open-window Mean Dwell (ADR 0006), not the retired definitions.
  • Access: any logged-in user, read-only (require_auth). Deck routes live in a separate /api/statistics/ router so admin-only /api/analytics/ routes can't leak into the deck.
  • Controllers stay thin; aggregation lives in analytics_service, SQL in repositories.

Triage decisions (2026-09-24)

  • Usual Weekday Baseline (glossary): mean of the previous 4 same weekdays, skipping holidays, gap-estimated days and low-Data-Trust days, looking back up to 8 weeks to find 4. With fewer than 2 usable days there is no baseline (null plus a reason).
  • The response lists which dates formed the baseline.
  • The two admin routes gain the baseline parameter; the deck reaches them through thin wrappers under /api/statistics/ (login, read-only).
  • Fix #77 item 2 (business-day default for /dwell/dayparts) first or in the same change.
## Change Add a baseline to two existing routes instead of creating new ones: - `GET /api/analytics/timeseries/hourly?date=…&baseline=same_weekday_4w`: adds the mean of the previous 4 same weekdays per bucket. - `GET /api/analytics/dwell/dayparts?day=…&baseline=same_weekday_4w`: adds the usual daypart split. ## Used by Day view: visitors by hour against a usual weekday, and the daypart split against usual. ## Notes - Baseline days that are holidays, gap-estimated or low-trust should be skipped (or reported) so they don't distort the "usual" line. - `/dwell/dayparts` currently defaults to the calendar date, not the business day (#77 item 2). ## Context Part of the statistics deck redesign, draft RFC in #80 (`docs/architecture/rfc-statistics-deck-display-model.md`; mockup linked there). Period selection was decided in #81 (closed): a period is identified by `granularity` (`day` / `week` / `month`) and its first business day; see the glossary terms **Complete Period** and **Partial Period**. A year period is out of scope. ## Shared constraints (all statistics-deck routes) - Periods are **closed** business periods in facility time (`daily_reset_time` boundaries, `app/facility_time.py`); an in-progress cycle is never returned. - Only **counted cameras** contribute (`_COUNTED_CAMERA_JOIN` / `_COUNTED_CAMERA_FILTER`); quarantined events never do. - Every period-level figure carries its data quality: gap-estimated days (ingestion anomaly ledger), **Data Trust** and **Cycle Completeness** for the cycles involved, so the deck can mark estimates. - Dwell means the open-window **Mean Dwell** (ADR 0006), not the retired definitions. - Access: any logged-in user, read-only (`require_auth`). Deck routes live in a separate `/api/statistics/` router so admin-only `/api/analytics/` routes can't leak into the deck. - Controllers stay thin; aggregation lives in `analytics_service`, SQL in repositories. ## Triage decisions (2026-09-24) - **Usual Weekday Baseline** (glossary): mean of the previous 4 same weekdays, skipping holidays, gap-estimated days and low-Data-Trust days, looking back up to 8 weeks to find 4. With fewer than 2 usable days there is no baseline (`null` plus a reason). - The response lists which dates formed the baseline. - The two admin routes gain the `baseline` parameter; the deck reaches them through thin wrappers under `/api/statistics/` (login, read-only). - Fix #77 item 2 (business-day default for `/dwell/dayparts`) first or in the same change.
gabogg commented 2026-09-25 17:09:03 +00:00
Author
Owner
Copy link

Implemented by #90, merged into master as d2f8bd2 after two review passes (Standards + Spec). Non-blocking follow-ups are tracked in #96–#100. Closing; this unblocks #80.

🤖 Generated with Claude Code

Implemented by #90, merged into `master` as d2f8bd2 after two review passes (Standards + Spec). Non-blocking follow-ups are tracked in #96–#100. Closing; this unblocks #80. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
feat/historical-flow-statistics
feat/historical-flow-publication
docs/test-policy-217
feat/historical-flow-curation
fix/holiday-stamping-followups
chore/schedule-p3-followups-186
fix/test-isolation
test/silent-camera-trace-199
No results found.
Labels
Clear labels   
blocked
Waits on the issues listed in its "Blocked by:" line before implementation

  
bug
Category: something is broken; behaviour differs from the spec or docs

  
enhancement
Category: new feature or improvement, including refactors, chores and docs

  
high-priority
Address before ordinary-priority work; independent of triage readiness and blockers

  
low-priority
Address after ordinary-priority work; independent of triage readiness and blockers

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

  
referenced
Previously closed issue reopened or referenced by an open issue; visible history marker

  
research
Needs investigation (internet or local resources) before it can be triaged down; used alongside a category and a triage role

  
wontfix
Will not be actioned

No labels
blocked
bug
enhancement
high-priority
low-priority
needs-info
needs-triage
ready-for-agent
ready-for-human
referenced
research
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
gabogg/hikcentral#88
No description provided.