Initial upload: 6-class BirdNET-logit classifier, model card, docs

README.md

@@ -0,0 +1,109 @@
+---
+license: cc-by-nc-sa-4.0
+library_name: sklearn
+tags:
+- bioacoustics
+- insect-classification
+- birdnet
+- edge-ai
+- raspberry-pi
+- non-commercial
+datasets:
+- InsectSet459
+- iNatSounds
+- ESC-50
+---
+
+# InsectNet
+
+A BirdNET-Pi sidecar that classifies insect sounds in real time.
+**Research prototype — active development.**
+
+## What It Is
+
+InsectNet is a lightweight sklearn head trained on BirdNET's 6,522-dim logit
+space. It runs alongside BirdNET-Pi on a Raspberry Pi, watches the audio
+stream, and sorts captured WAVs into acoustic classes.
+
+The architecture is simple: StandardScaler → OneVsRest(LogisticRegression).
+Nothing novel — the interesting part is that BirdNET's logit space encodes
+insect acoustic structure well enough that a linear probe works for several
+classes.
+
+## What's Validated
+
+Field validation at Pine Hollow, Tennessee (35.8565, -83.3744):
+
+| Class | Status | Confidence (field) | Notes |
+|-------|--------|-------------------|-------|
+| background | Production | N/A | 0.984 F1, 1,669 public clips + field negatives |
+| cicada_drone | Working | 83-100% | Natural capture at 83%, playback at 99-100%. AC unit false positive at 92%. |
+| frog | Working | 51-99% | Natural chorus confirmed. 440+ captures in one evening, two species identified. |
+| cricket_katydid | Likely working | 99+% | Playback at 100%. Natural summer data pending. |
+| grasshopper | Data-limited | TBD | 183 training clips, 0.701 F1. Not production-ready. |
+| bee | Untrained | TBD | 43 training clips, 0.608 F1. No real field captures. Known false positives from weed whacker and night noise. |
+
+## What It's Not
+
+This is not a finished product. It's a working research prototype that has
+been field-tested enough to know it catches real insects — and also catches
+enough false positives to know it shouldn't be trusted blindly.
+
+- The F1 numbers are from cross-validation on public training data, not from
+  field deployment. Actual performance varies with environment, mic placement,
+  and insect proximity.
+- All threshold tuning was done over one month at a single location.
+- Grasshopper and bee classes need substantially more training data before
+  they can be used without human review.
+
+## Known Limitations
+
+- **BirdNET dependency.** The classifier requires BirdNET's TFLite model to
+  extract logits. Without BirdNET, the classifier can't run.
+- **Mic placement.** The outdoor mic at Pine Hollow is upward-facing for birds.
+  Ground-level insect sounds must be loud to reach it.
+- **No cicada species channels.** BirdNET has zero cicada labels. Cicada
+  detection relies on general acoustic features in the BirdNET embedding space.
+- **False positives.** AC units → cicada_drone (92%). Weed whackers → bee
+  (98%). Night noise → bee (50-70%).
+- **All BirdNET species IDs are approximate.** BirdNET maps to the closest
+  species in its 6,522-label set, which may not be the true species.
+
+## How to Use
+
+The classifier alone isn't useful standalone — it needs BirdNET's TFLite
+model to produce logits. The full capture pipeline lives on GitHub:
+
+[https://github.com/vortexpjeff/insectnet](https://github.com/vortexpjeff/insectnet)
+
+```python
+# After extracting BirdNET logits (6,522-dim vector):
+import joblib
+clf = joblib.load("classifier.joblib")
+X = clf["scaler"].transform(logits.reshape(1, -1))
+scores = clf["classifier"].predict_proba(X)[0]
+for i, cls in enumerate(clf["classes"]):
+    print(f"{cls}: {scores[i]*100:.1f}%")
+```
+
+## Training Data
+
+| Source | Clips | License | Content |
+|--------|-------|---------|---------|
+| InsectSet459 | ~1,800 | CC BY-NC-SA 4.0 | 459 insect species, primarily Orthoptera |
+| iNatSounds | ~1,041 | CC BY-NC 4.0 | iNaturalist insect observations |
+| ESC-50 | 1,519 | CC BY-NC 4.0 | Environmental noise (background class) |
+| Pine Hollow field | 38 (unreviewed) | CC BY-NC-SA 4.0 | Natural captures from Pi sidecar |
+
+All training data and the BirdNET backbone are non-commercial. Derivative
+classifiers must use a compatible license.
+
+## Project Status
+
+Actively developed. Summer 2026 is the primary field data collection window
+for improving grasshopper, bee, and cricket classes. New captures are being
+accumulated continuously via the BirdNET-Pi sidecar.
+
+## License
+
+CC BY-NC-SA 4.0 — See LICENSE file.

architecture.md

@@ -0,0 +1,122 @@
+# Architecture
+
+How InsectNet integrates with BirdNET-Pi and why it's designed this way.
+
+## BirdNET-Pi Model
+
+BirdNET-Pi uses a **socket-based client-server architecture** for audio analysis:
+
+```
+arecord (15s WAV → StreamData/)
+  └→ birdnet_analysis.sh (shell loop)
+       └→ analyze.py (socket client on port 5050)
+            └→ BirdNET-Lite server loads WAV, runs TFLite, returns CSV
+                 └→ detection: WAV → Extracted/By_Date/{species}/
+                 └→ no detection: WAV deleted
+```
+
+Key design patterns InsectNet mirrors:
+- **Binary WAV lifecycle** — every WAV is processed once. Keep or delete, no middle state.
+- **Detection-only persistence** — non-detections produce zero artifacts.
+- **Shell-based orchestration** — each service is an independent systemd unit.
+
+## InsectNet's Role
+
+InsectNet is a **read-only sidecar**. It never touches BirdNET-Pi's files — it
+reads StreamData/ via inotify and copies WAVs to its own directory before
+BirdNET-Pi deletes them.
+
+```
+StreamData/ (new WAV)
+  │
+  ├──→ BirdNET-Lite (port 5050) → CSV → keep/delete
+  │
+  └──→ InsectNet inotify → copy WAV → librosa → TFLite → logits → sklearn → keep/delete
+                                                                              │
+                                                          captures/{class}/{ts}_{cls}_{conf}.wav
+                                                          detections.jsonl (append)
+```
+
+## Why BirdNET Logits
+
+InsectNet classifiers train on BirdNET's **6,522-dim logit space**, not raw
+audio. This is possible because BirdNET v2.4 has 31 Orthoptera species in its
+label set — field crickets, tree crickets, conehead katydids, ground crickets,
+and meadow katydids. The logit space already encodes insect acoustic structure.
+
+Cicadas are absent from BirdNET's labels, but their acoustic features still
+produce distinguishable patterns in the logit space (confirmed by field
+validation with cosine similarity against training centroids).
+
+## Classifier Architecture
+
+All production InsectNet classifiers use:
+
+```
+StandardScaler → OneVsRest(LogisticRegression(C=0.1, class_weight='balanced'))
+```
+
+- **StandardScaler** normalizes the 6,522-dim logit vectors
+- **OneVsRest** trains one binary classifier per class (sigmoid output)
+- **LogisticRegression** with L2 regularization (C=0.1), balanced class weights
+
+This is the same architecture BirdNET uses internally without the softmax —
+sigmoid-per-class allows multi-label predictions (one clip can be both
+"cicada_drone" and "frog").
+
+## Multi-Label Training
+
+Training data format: clips are labeled with lists of active classes, not a
+single category. A clip containing overlapping frog and cricket calls is
+labeled `["frog", "cricket_katydid"]`.
+
+`MultiLabelBinarizer` converts to an indicator matrix. Per-class
+F1-optimized thresholds are swept 0.1-0.95 during evaluation. Each class gets
+its own decision threshold.
+
+## Background Training Data
+
+Background clips come from two sources:
+1. **BirdNET bird clips** — every labeled bird clip is confirmed non-insect
+   audio from the same microphone and environment.
+2. **Public datasets** (ESC-50 for environmental noise, iNatSounds for
+   labeled insect audio).
+
+## Two-Tier System
+
+InsectNet operates at two levels:
+
+| Layer | Runs On | Backbone | Purpose |
+|-------|---------|----------|---------|
+| **Sidecar** | BirdNET-Pi (Pi 4) | BirdNET TFLite logits | Real-time capture, keeps WAVs |
+| **Archive** | Workstation | Perch 2.0 embeddings | Offline enrichment, multi-taxa discovery |
+
+The sidecar is the edge capture system. The archive (separate repo) is the
+analysis layer that pulls captures, embeds them with Perch 2.0, and enables
+multi-taxa classification. They are complementary.
+
+## BirdNET Species Coverage
+
+BirdNET v2.4 has 6,522 species labels. Insect-relevant coverage:
+
+| Group | In BirdNET? | Notes |
+|-------|-------------|-------|
+| 31 Orthoptera (crickets, katydids) | ✅ | Field crickets, tree crickets, coneheads, ground crickets, meadow katydids |
+| 0 Cicada species | ❌ | Zero cicada labels — relies on general acoustic features |
+| 0 Bee species | ❌ | Zero Hymenoptera labels |
+| 0 Grasshopper species | ❌ | Though some Acrididae may trigger Orthoptera channels |
+
+This means 31 logit channels carry insect-class information directly; the
+other 6,491 channels may carry incidental insect structure.
+
+## BirdNET-Pi Access
+
+Default credentials:
+- **Host:** 192.168.1.223
+- **User:** birdnetpi / birdnetpi
+- **Python:** `/home/birdnetpi/BirdNET-Pi/birdnet/bin/python3`
+- **Model:** `/home/birdnetpi/BirdNET-Pi/model/BirdNET_GLOBAL_6K_V2.4_Model_FP16.tflite`
+- **StreamData:** `/home/birdnetpi/BirdSongs/StreamData/`
+
+The sidecar expects the TFLite model at `DEFAULT_BIRDNET_MODEL` and StreamData
+at `DEFAULT_STREAMDATA` (both configurable via CLI args).

classifier.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5e6ecfc68d78a2cf2e9e9e47da5cb58d696e8de354fd620cfcccc5db9da48702
+size 474892

deploy.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# deploy.sh — Deploy InsectNet sidecar + classifier to a BirdNET-Pi
+#
+# Usage:
+#   ./scripts/deploy.sh                        # Deploy to default Pi (192.168.1.223)
+#   ./scripts/deploy.sh pi@192.168.1.50        # Deploy to a different BirdNET-Pi
+#   ./scripts/deploy.sh --model 3class.joblib  # Deploy a different model
+#
+# This copies:
+#   src/insectnet/capture.py  → ~/insectnet_capture/insectnet_capture.py
+#   src/insectnet/birdnet.py  → ~/insectnet_capture/birdnet.py
+#   models/*.joblib           → ~/insectnet_capture/classifier.joblib
+
+set -euo pipefail
+
+PI_HOST="${1:-birdnetpi@192.168.1.223}"
+MODEL_SRC="${2:-models/6class.joblib}"
+CAPTURE_DIR="~/insectnet_capture"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+echo "=== Deploying InsectNet to ${PI_HOST} ==="
+echo "  Model: ${MODEL_SRC}"
+echo "  Target: ${CAPTURE_DIR}"
+echo ""
+
+# Create remote dir
+ssh "${PI_HOST}" "mkdir -p ${CAPTURE_DIR}"
+
+# Deploy capture and birdnet modules
+scp "${SCRIPT_DIR}/src/insectnet/capture.py" "${PI_HOST}:${CAPTURE_DIR}/insectnet_capture.py"
+scp "${SCRIPT_DIR}/src/insectnet/birdnet.py" "${PI_HOST}:${CAPTURE_DIR}/birdnet.py"
+echo "  ✓ capture.py deployed"
+
+# Deploy classifier
+scp "${SCRIPT_DIR}/${MODEL_SRC}" "${PI_HOST}:${CAPTURE_DIR}/classifier.joblib"
+echo "  ✓ classifier deployed ($(basename ${MODEL_SRC}))"
+
+echo ""
+echo "=== Deploy complete ==="
+echo ""
+echo "Start the sidecar on the Pi:"
+echo "  ssh ${PI_HOST}"
+echo "  cd ${CAPTURE_DIR}"
+echo "  python3 insectnet_capture.py --threshold 0.3 --show"

thresholds.md

@@ -0,0 +1,63 @@
+# Confidence Thresholds
+
+Per-class confidence guidance for interpreting InsectNet predictions.
+**Thresholds are class-specific** — a universal cutoff produces both
+false positives and false negatives.
+
+## Current Guidance
+
+| Class | Recommended Threshold | Status | Notes |
+|-------|----------------------|--------|-------|
+| cicada_drone | 0.50 | Confirmed | Natural capture at 83%, AC false positive at 92% — use RMS to disambiguate |
+| frog | 0.50 | Confirmed | Validated at 51%; chorus peaks at 80-99%. RMS >0.004 increases confidence |
+| cricket_katydid | 0.50 | Tentative | Summer chorus data needed for natural threshold |
+| grasshopper | 0.80 | Data-limited | Only 183 training clips; most captures likely noise |
+| bee | 0.80 | Data-limited | Only 43 training clips; night detections are false positives |
+
+## How Thresholds Were Determined
+
+### Cicada (83% natural confirmed)
+
+The first natural cicada capture scored 83% with RMS 0.009. Playback tests
+hit 99-100%. However, an AC window unit also scores 92% on this class with
+background <2%. The 80%+ range includes both real cicadas and false positives.
+
+**Disambiguation:** RMS. Real cicada at 83% had RMS 0.009. AC at 92% had
+RMS 0.02+. A high-confidence cicada detection with high RMS may be mechanical.
+
+### Frog (51% natural confirmed)
+
+A frog detected at only 51% was confirmed real by the user. The frog chorus
+ranged from 55% (early evening, quiet) to 99.97% (peak chorus, loud).
+
+**Guidance:** Any capture above 50% frog with RMS >0.004 is worth review.
+Loud captures (RMS >0.015) at 80-99% are highly likely real.
+
+### Bee (no natural data)
+
+The bee class has no known real detections. All captures to date are false
+positives: weed whacker at 98%, night ambient noise at 50-70%. The true bee
+threshold cannot be established without natural captures.
+
+**Guidance:** Discard bee detections at night. Treat day detections below
+80% as noise.
+
+## Production vs Testing Threshold
+
+| Context | Threshold | Rationale |
+|---------|-----------|-----------|
+| **Production capture** | 0.30 default | Favor recall — a few false positives are cheaper than missed detections |
+| **Automated decision** | 0.80 minimum | Only act on high-confidence predictions without human review |
+| **Research / scanning** | 0.30 | Cast a wide net; review all uncertain captures manually |
+
+The 0.30 default is conservative for capture. It produces some uncertain
+clips but the cost of missed insects is higher than the cost of reviewing
+a few extra WAVs.
+
+## RMS Noise Floor
+
+The sidecar skips inference for WAVs below the RMS noise floor (default
+0.002). This was calibrated from Pine Hollow ambient measurements and
+corresponds to quiet background with no detectable acoustic activity.
+
+Playback sessions may need a lower floor (0.001) for quiet phone speakers.

validation.md

@@ -0,0 +1,69 @@
+# Field Validation
+
+InsectNet field validation results from Pine Hollow, Tennessee (35.8565, -83.3744).
+All detections are human-confirmed unless marked as playback.
+
+## Confirmed Natural Detections
+
+| Date | Class | Conf. | Species | Method |
+|------|-------|-------|---------|--------|
+| May 30 | cicada_drone | 83% | Neotibicen/Megatibicen | User confirmed by ear |
+| May 30 | frog | 51% | Cope's Gray Treefrog | User heard outside + WAV confirmed |
+| May 30 | frog | 80-99.97% | Cope's Gray Treefrog + Eastern Narrow-mouthed Toad | User confirmed chorus, two species |
+| May 31 | cricket_katydid | 99% | Field cricket | User confirmed by ear |
+
+## Confirmed Playback Detections
+
+| Date | Class | Conf. | Species | Notes |
+|------|-------|-------|---------|-------|
+| May 29 | cicada_drone | 100% | Neotibicen lyricen | Phone playback at mic |
+| May 29 | frog | 64.5% | American Toad | Phone playback, BirdNET cross-validated |
+| May 29 | frog | 99.2% | Gray Treefrog (Dryophytes spp.) | Phone playback |
+| May 29 | cricket_katydid | 100% | Gryllus campestris | Phone playback; BirdNET misidentified as G. fultoni |
+
+## Known False Positives
+
+| Source | Class Triggered | Confidence | Notes |
+|--------|----------------|------------|-------|
+| AC window unit | cicada_drone | Up to 92.3% | Background <2% — very confident wrong answer |
+| Weed whacker | bee | 98.1% | User confirmed |
+| Night ambient noise | bee | 50-70% | Temporal filter needed — bees don't fly at night |
+
+## Key Validations
+
+### Frog Chorus (May 30)
+
+The first sustained natural capture event. ~440 frog detections over 2.5 hours
+(21:00-23:30). Two clear phases:
+
+1. **Early evening (17:25-18:35):** Individual frogs at 55-65% confidence,
+   RMS 0.003-0.008
+2. **Chorus peak (21:00-23:00):** Sustained 80-99.97% confidence,
+   RMS 0.01-0.08
+
+Time-resolved BirdNET logit analysis identified two species calling
+simultaneously: Cope's Gray Treefrog (dominant, throughout) and Eastern
+Narrow-mouthed Toad (secondary, second half).
+
+### First Natural Cicada (May 30, 06:59)
+
+After ~14 hours running unattended through overnight rain, the sidecar
+captured a cicada at 83% confidence (RMS 0.009). The user confirmed it
+sounded like a genuine cicada. Cosine similarity against training centroids
+matched Neotibicen/Megatibicen (0.986).
+
+### First Low-Confidence Frog (May 30, 20:08)
+
+A frog detected at only 51% confidence (RMS 0.004) was confirmed real —
+the user heard the frog near the mic and confirmed the WAV. This invalidated
+the hypothesis that real detections always clear 80% and established
+class-dependent thresholds.
+
+## Validation vs Testing
+
+- **Testing** confirms the pipeline works: inotify fires, WAVs get processed,
+  files end up in the right places. Confidence scores are not evidence.
+- **Validation** requires human listening and explicit species identification.
+  Only validated captures qualify as training data.
+
+All detections listed above are validated.