README.md

---
title: Bee Colony Survival Multimodal
emoji: 🐝
colorFrom: gray
colorTo: gray
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
---

# Bee Colony Survival — multi-modal (audio + virus) batch predictor

Upload one or more hive **audio recordings** (batch supported). The model predicts
**Survivor (S)** vs **Terminal / died (T)** for the next **0–3 months** and
**4–6 months**, and shows the prediction next to the ground truth.

## The model (audio + virus)

A class-balanced **HistGradientBoosting** classifier on a **775-dimensional
multi-modal feature vector**, one model per horizon:

```
audio .wav ─► AST (Audio Spectrogram Transformer, pretrained)
              MIT/ast-finetuned-audioset-10-10-0.4593 ─► 768-d embedding ─┐
                                                                          ├─► gradient boosting
viral loads (CBPV, DWV, KBV) + country + month ──────► 7-d tabular ───────┘   → P(Terminal)
```

- The **audio** is embedded by AST at inference time from the uploaded file.
- The **viral loads + metadata** are read from the bundled `AI_Data_Training.xlsx`
  by matching the file name.
- A **strict, high-precision threshold** is used so a "Terminal" call is trustworthy.
- Domain constraint enforced: a colony predicted Terminal in 0–3 months is Terminal
  in 4–6 months.

## Ground truth from the Excel workbook

`AI_Data_Training.xlsx` is bundled in the Space. On upload, each file name is matched
to a row to read its viral loads and true labels. **If a file is not in the workbook,
the app still predicts** (from audio + parsed metadata, viral loads default to 0) and
reports the ground truth as *not available*.

## Bundled examples

`examples/` contains **20 recordings of Terminal colonies that the model correctly
detects** (the 9 highest-confidence cases plus 11 more). Drag them into the upload box
to run a batch and see prediction vs ground truth.

## Honest performance note

The 20 bundled files are reproduced correctly because the deployed models are trained
on the full reference set. Generalisation to **unseen colonies** (leakage-free
colony-grouped cross-validation) is more modest — a strict "Terminal" call is
high-precision but catches only the clearest cases, because most colony deaths in this
data occur with zero measured viral load and no strong acoustic signature. See the
project notes for the full colony-grouped metrics.

## Files

```
app.py            Gradio batch app (white background, black text/buttons)
ast_encoder.py    pretrained-AST audio encoder (identical at train and inference)
bee_features.py   filename parser + tabular feature builder
xls_lookup.py     ground-truth / viral-load lookup from the Excel workbook
model/            model_03.joblib, model_46.joblib, config.json
AI_Data_Training.xlsx   reference workbook (ground truth + viral loads)
examples/         20 example recordings
requirements.txt
```

## Run locally

```bash
pip install -r requirements.txt
python app.py            # http://127.0.0.1:7860  (first run downloads AST weights)
```

## Deploy to Hugging Face Spaces

```bash
git clone https://huggingface.co/spaces/<user>/<space>
cp -r hf_space_final/* <space>/
cd <space>
git lfs install && git lfs track "*.wav" "*.joblib" "*.xlsx"
git add . && git commit -m "Bee colony survival multimodal batch app" && git push
```