Pulling a faint engineered reporter out of noisy remote hyperspectral cubes, with an MC-dropout uncertainty estimate.
We can now read living, engineered cells from a drone, ninety meters up (Chemla et al., Nature Biotechnology, 2026). But out in the real world that signal is faint: it hides inside the spectrum of soil, leaves, and water, the atmosphere distorts it, and cheap sensors bury it in noise. A hyperspectral camera hands you a mountain of data, not an answer. Pulling the answer out is an algorithm problem, and that is what HyperMix is for.
HyperMix treats detection and spectral unmixing as one regularized inverse problem, designed from the start for unknown natural backgrounds, sparse reference libraries, and low SNR. It is developed by a statistician working in medical imaging, porting the low-SNR, cross-device reconstruction toolkit from retinal OCT to biology at a distance. Everything here is MIT licensed.
- ✨ Highlights
- 🚀 Quickstart
- 🌐 Web Observatory
- 🧪 The learned detector
- 📊 Benchmarks
- 🗺️ Roadmap
- 💾 Data
⚠️ Honest limitations
- 🌍 Physics-based scene simulator with exact ground truth (NumPy only, deterministic).
- 🛰️ Real-background benchmark on an AVIRIS cube (Indian Pines) via implanted synthetic targets.
- 🧬 Espectros medidos: endmembers USGS e absorbância de pellets bioHSI para biliverdina/SmURFP e bacterioclorofila a.
- 🧠 Detector aprendido, avaliado contra baselines por pixel e com suavização espacial em 3 fundos reais.
- 🧪 Unmixing head that estimates fractional abundance (how much, not just whether).
- 🎯 Uncertainty estimate via MC-dropout, ainda sem calibração empírica.
- 🔓 100% open, MIT licensed, reproducible from a clean clone.
Run it in your browser, no setup:
Or locally:
pip install -e ".[viz]" # numpy + scipy + matplotlibfrom hypermix import simulate_scene, spectral_matched_filter, roc_auc
scene = simulate_scene(snr_db=10.0, seed=0) # cube + full ground truth
score = spectral_matched_filter(scene.cube, scene.reporter)
print("AUC:", roc_auc(score, scene.detection_gt))Reproduce everything:
python examples/run_demo.py # simulator + baseline, AUC vs SNR
python scripts/fetch_data.py # download the real AVIRIS cube
python -m hypermix.benchmark # full benchmark (synthetic + real)
python scripts/train_detector.py # train the learned detector (needs ".[train]")
python scripts/run_mismatch_experiment.py # spectral mismatch robustness
python scripts/realism_experiment.py # measured spectra + SRF + atmosphere
python scripts/target_variability_experiment.py # measured target variability
pytest -q # 25 testsExplore a fotografia auditada dos resultados em hypermix-observatory.vercel.app. O painel permite variar target SNR, mismatch espectral e tracks de variabilidade, além de comparar alvo oráculo e alvo laboratorial sob os controles físicos da Fase B.
A interface abre em inglês e oferece as bandeiras dos Estados Unidos e do Brasil no topo para alternar todo o conteúdo entre inglês e português sem sair da página.
O Map Studio permite enviar localmente um PNG, JPEG ou WebP de um mapa de scores e explorar a máscara em diferentes limiares. O brilho é interpretado como score apenas para visualização; imagens RGB não executam inferência HyperMix e nunca são enviadas ao servidor.
O observatório é uma visualização interativa dos artefatos em results/. Ele
não treina o modelo nem executa inferência no navegador, e os números não são
sincronizados automaticamente. A conclusão honesta permanece visível no
produto: o detector aprendido não supera de forma robusta um matched filter
espacial bem calibrado neste benchmark.
Para executar ou publicar o app, consulte webapp/README.md.
hypermix.detector feeds each pixel the scene's own adaptive detector
outputs (matched filter, ACE) plus spatial context, z-scored per scene, and a
small PyTorch network learns a nonlinear combination. O treinamento usa apenas
fundos simulados; os testes usam fundos reais com o mesmo alvo sintético, modelo
de mistura linear e gerador de blobs do treino. Portanto, este experimento mede
robustez à troca de fundo, não generalização completa para alvos reais. It ships
MC-dropout uncertainty.
Fundo real Indian Pines com alvo implantado a target SNR de 5 dB. O painel compara o matched filter por pixel, o detector aprendido e a incerteza estimada.
Detection AUC on the real Indian Pines background (implanted target, 3 seeds):
| Target SNR (dB) | Matched filter | Matched filter (spatial) | ACE | 🧠 Learned |
|---|---|---|---|---|
| 20 | 0.991 | 0.998 | 0.878 | 0.999 |
| 10 | 0.990 | 0.999 | 0.878 | 0.999 |
| 5 | 0.985 | 0.998 | 0.870 | 0.999 |
| 0 | 0.970 | 0.998 | 0.849 | 0.998 |
Target SNR é definido como a razão entre o RMS da contribuição espectral do
alvo, medido nos pixels positivos, e o RMS do ruído aditivo. O baseline espacial
aplica ao matched filter um blur gaussiano fixo com sigma=1,5 pixel. Na média
das três cenas e quatro níveis de target SNR, o matched filter espacial alcança
0,990 AUC e o detector aprendido 0,987. Portanto, o detector não supera o
comparador espacial neste protocolo. A vantagem sobre o MF por pixel, 0,943
AUC, não isola uma vantagem espectral.
Detection AUC across 3 real hyperspectral scenes of different sensors and band
counts (Indian Pines & Salinas: AVIRIS; Pavia University: ROSIS), 3 seeds.
Mean AUC averages over all scenes and target SNR = 20, 10, 5, 0 dB. O detector
é treinado apenas em simulação, mas treino e teste compartilham o espectro do
repórter, a mistura linear e o prior de blobs. Reproduce:
python scripts/make_leaderboard.py.
| Rank | Method | Mean AUC | AUC @ 0 dB |
|---|---|---|---|
| 1 | Matched filter (spatial) | 0.990 | 0.982 |
| 2 | 🧠 Learned detector (HyperMix) | 0.987 | 0.972 |
| 3 | Matched filter | 0.943 | 0.908 |
| 4 | ACE | 0.860 | 0.811 |
| 5 | Spectral Angle Mapper | 0.656 | 0.655 |
Per-scene AUC @ target SNR de 0 dB. Pavia usa ROSIS; Indian Pines e Salinas usam AVIRIS. A troca de sensor também altera o número de bandas, mas não torna real o alvo implantado:
| Method | Indian Pines | Salinas | Pavia U. |
|---|---|---|---|
| Matched filter (spatial) | 0.998 | 0.998 | 0.951 |
| 🧠 Learned detector | 0.998 | 0.998 | 0.919 |
| Matched filter | 0.970 | 0.969 | 0.786 |
O alvo implantado permanece fixo, mas a assinatura entregue aos detectores é deslocada no eixo normalizado de índices de bandas. AUC média em três cenas, três seeds e target SNR de 5 dB:
| Deslocamento | MF AUC (queda) | MF espacial AUC (queda) | Detector AUC (queda) |
|---|---|---|---|
| 0% | 0.940 (0.000) | 0.990 (0.000) | 0.987 (0.000) |
| 1% | 0.899 (0.041) | 0.983 (0.007) | 0.973 (0.014) |
| 2,5% | 0.781 (0.159) | 0.920 (0.070) | 0.907 (0.080) |
| 5% | 0.647 (0.293) | 0.730 (0.260) | 0.710 (0.277) |
O deslocamento é uma fração da faixa de índices, não uma distância em nanômetros, pois as grades espectrais dos sensores diferem. O experimento mede sensibilidade a mismatch controlado, não substitui validação com espectros medidos. Resultados completos em results/mismatch.md.
A Fase B adiciona quatro controles sem alterar os defaults usados nos números da Fase A: espectros medidos, SRF gaussiana parametrizada em nanômetros, atmosfera simples com absorções estruturadas e mistura bilinear generalizada. O artefato results/realism.md usa uma grade simulada calibrada em comprimento de onda, target SNR de 20, 10, 5 e 0 dB e 5 seeds.
| Cenário | MF | MF espacial | ACE | SAM | MF espacial com alvo lab |
|---|---|---|---|---|---|
| Controle estilizado, linear | 0.952 | 0.983 | 0.715 | 0.907 | 0.983 |
| Espectros medidos, linear | 0.976 | 0.995 | 0.719 | 0.968 | 0.995 |
| Medidos + SRF 10 nm | 0.976 | 0.994 | 0.719 | 0.968 | 0.995 |
| Medidos + SRF + atmosfera | 0.976 | 0.994 | 0.719 | 0.968 | 0.913 |
| Medidos + SRF + atmosfera + bilinear | 0.947 | 0.983 | 0.714 | 0.969 | 0.906 |
O alvo oráculo é a assinatura exata depois do sensor e da atmosfera. O alvo laboratorial usa a absorbância medida convertida antes dessas transformações. Por isso, SRF e atmosfera quase não penalizam o MF oráculo, mas o mismatch atmosférico reduz o MF espacial de 0,994 para 0,913. A mistura bilinear reduz o MF espacial oráculo de 0,994 para 0,983.
No teste separado com três fundos reais, o detector aprendido também não obtém vantagem robusta: sob mistura linear, MF espacial 0,986 vs aprendido 0,980; sob mistura bilinear, 0,989 vs 0,992, empate dentro da margem de 0,005. Esses MAT não carregam centros de banda, então o teste não linear real usa alvo por índice espectral e deve ser interpretado apenas como análise de sensibilidade.
O último teste da arquitetura atual usa um alvo sorteado de bibliotecas medidas, enquanto o MF e as cinco features do detector aprendido recebem apenas um alvo nominal fixo. O baseline de subespaço segue a formulação clássica de matched subspace detection. AUC média em target SNR de 20, 10, 5 e 0 dB, com 6 seeds estratificadas por ponto:
| Track | MF espacial nominal | Subespaço espacial | Aprendido | MF espacial oráculo |
|---|---|---|---|---|
| Hospedeiro, SmURFP/biliverdina | 0.996 | 0.967 | 0.997 | 0.997 |
| Hospedeiro + sensor + atmosfera | 0.993 | 0.910 | 0.996 | 0.995 |
| Qualquer repórter, BChl ou biliverdina | 0.907 | 0.948 | 0.928 | 0.996 |
Nos dois tracks intra-SmURFP, o detector aprendido fica em empate com o MF espacial nominal pela margem de 0,005. No track heterogêneo de qualquer repórter, o subespaço espacial supera o aprendido por 0,020 AUC. Portanto, variabilidade do alvo também não fornece uma vitória robusta para o MLP atual. O track de família não deve ser descrito como variabilidade intra-molécula.
O experimento usa endmembers USGS em cenas implantadas, com grade calibrada de 400-1000 nm. Ele não é validação remota de expressão biológica naturalmente observada. Resultados completos em results/target_variability.md.
Detection asks is the reporter here? Unmixing asks how much? AbundanceUnmixer
adds a regression head (same scene-adaptive features) that estimates the target's
fractional abundance. A avaliação usa apenas pixels com abundância maior que
0,02 para Pearson r e target MAE, evitando que os zeros do fundo dominem o
resultado. Target SNR de 10 dB, média de 3 seeds:
| Cena | MF target r | Unmixer target r | MF target MAE | Unmixer target MAE |
|---|---|---|---|---|
| Indian Pines | 0.966 | 0.982 | 0.0142 | 0.0081 |
| Salinas | 0.979 | 0.988 | 0.0073 | 0.0237 |
| Pavia University | 0.796 | 0.938 | 0.0177 | 0.0093 |
O unmixer tem maior correlação nas três cenas e menor target MAE em duas. Em Salinas, porém, sua target MAE é mais de três vezes a do MF, evidenciando viés de escala que a correlação isolada esconderia. A MAE em todos os pixels também é preservada em results/unmix_eval.md como diagnóstico secundário.
Reproduce: python scripts/train_unmixer.py.
dataset/ contém uma biblioteca aberta em CSV e NPZ: quatro endmembers medidos
do USGS, absorbâncias de pellets publicadas no bioHSI e os dois alvos semelhantes
a reflectância derivados por Beer-Lambert. A grade de conveniência tem 400-1000
nm em passos de 10 nm; a fonte empacotada preserva 1 nm. Veja o
data card. Reconstrua com
python scripts/fetch_reference_spectra.py e python scripts/export_dataset.py.
- Milestone 0 — scene simulator, classical baselines, metrics
- Milestone 1 — real-background benchmark (AVIRIS), implanted-target harness, paper-grounded reporters
- Milestone 2 — physics-informed learned detector with MC-dropout uncertainty, avaliado em troca de fundo simulado para real
- Milestone 3 — public release (in progress): ✅ Colab notebook · ✅ open spectral dataset + leaderboard · ✅ 3-scene cross-sensor benchmark · ✅ build + CITATION/Zenodo metadata · ⏳ PyPI publish · ⏳ DOI
Datasets are downloaded, not committed:
python scripts/fetch_data.pyIndian Pines is a public AVIRIS scene (Purdue University).
Os espectros compactos de referência são versionados no pacote. As fontes são USGS Spectral Library Version 7 e o arquivo oficial bioHSI associado a Chemla et al.; URLs, licença e checksums estão em hypermix/data/REFERENCE_SPECTRA.md.
- Os repórteres medidos são absorbâncias inferidas de pellets, não reflectância absoluta de uma superfície observada remotamente. A conversão por Beer-Lambert é explícita, mas ainda é uma hipótese do simulador.
- Os endmembers USGS são quatro amostras medidas e não cobrem a variabilidade natural de solo, vegetação e água.
- O matched filter espacial supera o detector aprendido no leaderboard atual; a vantagem sobre baselines por pixel é explicada em grande parte pelo prior espacial de alvos em blob.
- O leaderboard da Fase A ainda compartilha repórter aproximado, gerador de blobs e mistura linear entre treino e teste. Os fundos são reais a jusante, mas os alvos implantados não são.
- Mesmo treinado sobre variabilidade medida, o MLP atual só recebe MF, ACE e versões suavizadas calculadas com o alvo nominal. Ele não acessa informação espectral que esses detectores descartam.
- Um deslocamento espectral de 5% reduz a AUC do detector aprendido em 0,277; ainda não há validação remota independente com variabilidade biológica.
- Os cubos MAT atuais não incluem os centros de banda. A avaliação física calibrada em nanômetros permanece simulada até obter metadados espectrais rastreáveis para cada cena real.
- No unmixing de Salinas, maior correlação não implica menor erro: target MAE de 0,0237 no unmixer contra 0,0073 no MF.
- The first learned model is a small MLP; richer models and a true unmixing head are future work. All numbers, including failures, are tracked in STATUS.md.
If you use HyperMix, please cite it (see CITATION.cff). A Zenodo DOI is planned for the next release.
MIT. See LICENSE. Built with support from the Experiment Foundation Hyperspectral Biology grant.