{"id":50364421,"url":"https://github.com/andyed/pupil-lfhf","last_synced_at":"2026-05-30T03:03:10.999Z","repository":{"id":350586815,"uuid":"1201533741","full_name":"andyed/pupil-lfhf","owner":"andyed","description":"Real-time LF/HF pupillometric cognitive load via Butterworth IIR filters (Duchowski 2026). Includes AdSERP validation on 2,719 eye-tracking trials.","archived":false,"fork":false,"pushed_at":"2026-04-11T02:47:28.000Z","size":461,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T04:27:30.454Z","etag":null,"topics":["blink-artifact-removal","butterworth-filter","cognitive-load","eye-tracking","lhipa","psychophysics","pupillometry"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T20:05:04.000Z","updated_at":"2026-04-11T02:47:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andyed/pupil-lfhf","commit_stats":null,"previous_names":["andyed/pupil-lfhf"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/andyed/pupil-lfhf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyed%2Fpupil-lfhf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyed%2Fpupil-lfhf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyed%2Fpupil-lfhf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyed%2Fpupil-lfhf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyed","download_url":"https://codeload.github.com/andyed/pupil-lfhf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyed%2Fpupil-lfhf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33678271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blink-artifact-removal","butterworth-filter","cognitive-load","eye-tracking","lhipa","psychophysics","pupillometry"],"created_at":"2026-05-30T03:03:08.166Z","updated_at":"2026-05-30T03:03:10.987Z","avatar_url":"https://github.com/andyed.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pupil-lfhf\n\nReal-time LF/HF pupillometric cognitive load measurement via Butterworth IIR filters.\n\nBased on Duchowski (2026): two 4th-order Butterworth filters split the pupil diameter signal into low-frequency (0-1.6 Hz, tonic/autonomic) and high-frequency (1.6-4 Hz, phasic/cognitive) bands. The LF/HF power ratio indexes cognitive load with a 1-second minimum window — 7.5x shorter than DWT-based approaches.\n\n## Usage\n\n```python\nfrom pupil_lfhf import PupilLFHF\n\n# Batch processing (offline, zero-phase)\ndetector = PupilLFHF(fs=150)\nratio = detector.compute(pupil_signal)  # single LF/HF value\n\n# Per-segment (e.g., per-event cognitive load)\nlf_signal, hf_signal = detector.filter(pupil_signal)\n# Then compute variance ratio on any segment of interest\n\n# Streaming (real-time, sample-by-sample)\ndetector = PupilLFHF(fs=150, mode='stream')\nfor sample in pupil_stream:\n    ratio = detector.update(sample)  # None until buffer fills\n```\n\n## Validation\n\n`validation/` contains empirical validation on the [AdSERP dataset](https://github.com/kayhan-latifzadeh/AdSERP) (2,719 eye-tracking trials, 150 Hz Gazepoint GP3 HD, Latifzadeh et al. SIGIR 2025):\n\n- Three-method convergence (Butterworth, DWT, raw PD agree on direction)\n- Per-position cognitive load trajectory during SERP evaluation\n- Head-to-head sensitivity comparison against trial-level LHIPA on 5 known effects\n\nSee `validation/README.md` for details.\n\n## Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `fs` | 60 | Sampling rate (Hz) |\n| `order` | 4 | Butterworth filter order |\n| `lf_cutoff` | 1.6 | LF band upper cutoff (Hz) |\n| `hf_band` | (1.6, 4.0) | HF band (Hz) |\n| `power_window` | 1.0 | Sliding window for variance (seconds, streaming mode) |\n\n## Minimum windows\n\nFrom Duchowski (2026), minimum signal duration for stable LF/HF estimation:\n\n| Method | Minimum | At 60 Hz | At 150 Hz |\n|--------|---------|----------|-----------|\n| FFT | 10 s | 600 samples | 1,500 samples |\n| DWT | 7.5 s | 450 samples | 1,125 samples |\n| **Butterworth** | **1 s** | **60 samples** | **150 samples** |\n\n## References\n\nDuchowski, A. T. (2026). Real-Time Cognitive Load Measurement of Pupillary Oscillation. *Proc. ACM Comput. Graph. Interact. Tech.* 9, 2. https://doi.org/10.1145/3803537\n\nDuchowski, A. T., Krejtz, K., Gehrer, N. A., Bafna, T., \u0026 Baekgaard, P. (2020). The Low/High Index of Pupillary Activity. *CHI '20*. https://doi.org/10.1145/3313831.3376394\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyed%2Fpupil-lfhf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyed%2Fpupil-lfhf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyed%2Fpupil-lfhf/lists"}