`habituation` detector does not implement the AHSC paper (it's plain k-means)

[xiaohanc]

Summary

The habituation detector (anoship-detection/anoship/detectors/habituation.py,
registered as habituation) is presented as a reference implementation of
peer-reviewed methods and is documented as implementing:

Anti-Drosophila Habituation Clustering for Enhanced Anomaly Detection in Data
Streams, IEEE ISCIPT 2025 (the AHSC algorithm).

In practice the current code does not implement the AHSC algorithm from that
paper. It is a plain batch k-means (Lloyd's iterations) with a "familiarity"
distance-damping term. None of the paper's distinctive contributions are present,
and the one habituation-like mechanism it does have points in the opposite
direction from the paper.

What the code actually does

HabituationClusterDetector:

1. fit: random-init k-means (n_clusters=8 by default), Lloyd iterations on the
   baseline.
2. Computes per-cluster familiarity = how often each cluster fires on baseline.
3. score: distance_to_nearest_centroid * (1 - habituation * familiarity), i.e.
   it suppresses the anomaly response for familiar clusters.

What the AHSC paper actually specifies

The paper (AHSC) is an online streaming clustering anomaly detector whose core
contributions are:

• Drosophila olfactory sparse random projection Y = M·X (Eq. 5–6), with a
  sparse binary Bernoulli matrix M (m ≈ 40·d).
• Winner-take-all sparsification (Eq. 7): keep only components within the top
  ~5% of the max, zero the rest — this is the curse-of-dimensionality fix.
• Anti-habituation enhancement function (Eq. 8–9): adaptively enhances the
  aggregation of similar data (higher intra-cluster cohesion, lower
  inter-cluster coupling). This is the paper's namesake contribution.
• Two-level micro/macro-cluster structure with core / potential /
  offline-buffer states, dynamic radius update (Eq. 1), weight decay (Eq. 3), and
  shell-region-only center update (Eq. 4).
• Macrocluster-first search reducing best-cluster lookup from O(n) to O(log n)
  (Eq. 10–11).
• k-means++ is used only for initialization, not as the detector itself.

Gap

AHSC mechanism	Present in code?
Online/streaming incremental clustering (single scan)	❌ batch k-means
Micro/macro structure, core/potential/buffer states	❌
Dynamic radius (Eq.1), weight decay (Eq.3), shell update (Eq.4)	❌
Sparse binary random projection Y=M·X (Eq.5–6)	❌
Winner-take-all sparsification (Eq.7)	❌
Anti-habituation enhancement function (Eq.8–9)	❌
Macrocluster-first search, O(log n) (Eq.10–11)	❌
k-means++ used only for init	❌ (plain random-init k-means is the whole model)
Habituation direction	⚠️ code suppresses familiar (ordinary habituation); paper enhances similar (anti-habituation) — opposite direction

Why it matters

• The README's paper→module map and the habituation.py module docstring claim a
  faithful reference implementation of the AHSC paper, which the code does not
  deliver. This is misleading to users selecting a detector based on the cited
  method.
• The reported behavior in the README comparison table is therefore not produced
  by AHSC.

Proposed resolution (pick one)

1. Implement AHSC for real — sparse random projection + winner-take-all +
   anti-habituation enhancement (Eq. 8–9) + micro/macro structure with dynamic
   radius/weight-decay + macrocluster-first search (similar in spirit to how
   mstdf vendors/wraps the real model).
2. Relabel honestly — change the README and docstring to describe this as a
   simplified, idea-adjacent k-means baseline, and stop claiming it is a
   reference implementation of the AHSC paper. (Also note the
   habituation-vs-anti-habituation direction mismatch.)

References

• File: anoship-detection/anoship/detectors/habituation.py
• Paper: H. Xiao et al., "Anti-Drosophila Habituation Clustering for Enhanced
  Anomaly Detection in Data Streams," IEEE ISCIPT 2025.