ecological-agent-skills 3.1.0

package/skills/acoustic-monitoring/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: acoustic-monitoring
+description: "Processes passive acoustic monitoring (PAM) data to compute soundscape indices and detect species from audio recordings. Use this skill when the user mentions acoustic monitoring, bioacoustics, soundscape ecology, acoustic indices (ACI, NDSI, ADI), BirdNET, AudioMoth, bat detectors, dawn chorus analysis, passive acoustic recorders, species detection from audio, or sound diversity metrics."
+skill_version: 1.0.0
+---
+
+# Skill: acoustic-monitoring
+
+**Domain:** Bioacoustics · Soundscape ecology · Acoustic indices · Species detection · PAM
+
+---
+
+## Purpose
+
+Guides the agent through processing passive acoustic monitoring (PAM) recordings to compute soundscape biodiversity indices, detect species using automated classifiers, and analyse temporal trends in acoustic diversity. Covers ACI, BI, NDSI, H, ADI, and AEI index computation; BirdNET-based species detection with confidence thresholding; rarefaction-based richness estimation; and temporal trend analysis of soundscape composition.
+
+---
+
+## When to Invoke
+
+Invoke this skill when:
+
+- A user provides a directory of WAV or FLAC recordings from autonomous recorders
+- The goal is to compute acoustic biodiversity indices across sites or time periods
+- Automated species detection from audio is requested (BirdNET, Kaleidoscope)
+- Soundscape trends over time (diel, seasonal, annual) are to be analysed
+- Acoustic data must be integrated with field survey or camera trap data
+
+**trigger_keywords:** `acoustic monitoring`, `soundscape`, `bioacoustics`, `acoustic index`, `ACI`, `NDSI`, `BirdNET`, `bird detection`, `bat echolocation`, `passive acoustic`, `PAM`, `audio recording`, `species accumulation acoustic`, `acoustic diversity`
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|---|---|---|
+| Audio recordings directory | WAV or FLAC files | Required |
+| Recording metadata CSV (site, date, time, recorder ID) | CSV | Required |
+| Species list for filtering detections | TXT | Optional |
+| Confidence threshold for species detection | Float 0–1 (default: 0.7) | Optional |
+| Time resolution for index aggregation (minutes) | Integer (default: 1) | Optional |
+
+---
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `acoustic_indices_timeseries.csv` | ACI, BI, NDSI, H, ADI, AEI per recording per time step |
+| `indices_summary.csv` | Mean ± SD of each index per site and temporal stratum |
+| `soundscape_plot.png` | Heatmap: hour of day × day × index value |
+| `detections_raw.csv` | All BirdNET detections with confidence scores |
+| `detections_filtered.csv` | Detections above confidence threshold |
+| `species_accumulation.csv` | Cumulative species richness vs. recording hours |
+| `detection_summary.png` | Detections per species × date × site |
+
+---
+
+## Steps
+
+1. **Validate recordings**
+   Check all files are WAV or FLAC, readable, and have consistent sample rates.
+   Compute SNR for a random 10% sample. Flag files with SNR < 10 dB in metadata.
+   Exclude flagged recordings from index computation.
+
+2. **Compute acoustic indices** *(invoke `compute_acoustic_indices.R` or `.py`)*
+   Calculate ACI, BI, NDSI, H, ADI, AEI for each recording at the specified time
+   resolution. Aggregate to hourly and daily summaries.
+   Output: `acoustic_indices_timeseries.csv`.
+
+3. **Run automated species detection** *(invoke `batch_species_detection.py`)*
+   Process all recordings with BirdNET-Analyzer CLI.
+   Filter detections by confidence threshold (default: 0.7).
+   Aggregate detections by species, date, and site.
+
+4. **Validate detections**
+   If the study region has a published BirdNET validation, apply region-specific
+   precision/recall. If not, flag detections > 0.7 confidence as "probable" and
+   require manual validation for species of conservation concern.
+
+5. **Compute species accumulation curve**
+   Use detection records to plot cumulative species vs. recording hours.
+   Fit a Michaelis-Menten curve to estimate asymptotic richness.
+   Flag sites with < 48h of recordings as potentially under-sampled.
+
+6. **Analyse temporal trends**
+   Use `environmental-time-series` skill if trend analysis over months/years is needed.
+   For diel patterns: compute mean index by hour-of-day, plot soundscape fingerprint.
+
+7. **Validate outputs and record decisions**
+   Confirm all output files are non-empty and timestamped.
+   Record SNR threshold, confidence threshold, and any excluded recordings in `decision_log.md`.
+
+---
+
+## Decision Points
+
+| Condition | Diagnosis | Recommended Action |
+|---|---|---|
+| SNR < 10 dB in a recording | Recording dominated by noise; indices unreliable | Exclude from index computation; document in metadata |
+| BirdNET confidence < 0.7 | Low-confidence detection; likely false positive | Flag as "unconfirmed"; require manual validation before use in analyses |
+| < 48h of recordings per site | Insufficient for rarefaction-based richness | Report observed richness only; note undersampling caveat |
+| NDSI consistently > 0.8 | Soundscape dominated by biophony | Check for equipment artefact or very remote site; validate with spectrogram |
+| NDSI consistently < -0.5 | Soundscape dominated by geophony or anthrophony | Investigate noise source; may mask biological signal in other indices |
+
+---
+
+## Key Decisions to Document
+
+Record the following in `decision_log.md` after running this skill:
+
+- SNR threshold used for recording exclusion and how many recordings were excluded
+- Confidence threshold used for BirdNET detections and rationale
+- Whether regional BirdNET validation data were available and applied
+- Which acoustic indices were prioritised and why
+- Any recordings excluded due to equipment malfunction or file corruption
+
+---
+
+## Tools and Libraries
+
+**R**
+```r
+suppressPackageStartupMessages(library(soundecology))  # acoustic indices (ACI, BI, NDSI, H, ADI, AEI)
+suppressPackageStartupMessages(library(tuneR))         # WAV file reading
+suppressPackageStartupMessages(library(seewave))       # spectrogram, SNR, dB computation
+suppressPackageStartupMessages(library(dplyr))         # data manipulation
+suppressPackageStartupMessages(library(ggplot2))       # plotting
+suppressPackageStartupMessages(library(lubridate))     # datetime handling
+```
+
+**Python**
+```python
+import librosa          # audio loading, spectral features, ACI computation
+import soundfile as sf  # WAV/FLAC reading
+import numpy as np      # numerical operations
+import pandas as pd     # data manipulation
+from pathlib import Path  # file system
+```
+
+**CLI**
+```bash
+# BirdNET-Analyzer (must be installed separately)
+python analyze.py --i <audio_dir> --o <output_dir> --min_conf 0.7
+```
+
+---
+
+## Resources
+
+- [`skills/acoustic-monitoring/resources/acoustic-indices-reference.md`](resources/acoustic-indices-reference.md) — Complete table of acoustic indices: formula, scale, interpretation, R package
+- [`skills/acoustic-monitoring/resources/species-id-tools-comparison.md`](resources/species-id-tools-comparison.md) — Comparison of BirdNET, RavenPro, Kaleidoscope, ARBIMON and validation protocols
+- [`skills/acoustic-monitoring/resources/soundscape-ecology-guide.md`](resources/soundscape-ecology-guide.md) — NDSI framework, diel and seasonal controls, rarefaction, and data integration
+
+---
+
+## Notes
+
+- **Sample rate must match index requirements:** ACI and most soundecology indices require 44.1 kHz WAV. Recordings at 22 kHz will underestimate high-frequency components. Always check sample rate before computing indices.
+- **BirdNET is trained on Cornell Lab recordings:** Performance degrades outside North America and Europe. Validate with local recordings before using for conservation decisions in other regions.
+- **Diel patterns must be controlled in trend analyses:** Acoustic diversity peaks at dawn and dusk. Never compare morning recordings from site A with midday recordings from site B without controlling for time-of-day.
+- **ACI is not equivalent to species richness:** ACI measures temporal complexity of the signal, not biological diversity. A site with heavy rain will have high ACI but low biological content. Always cross-validate with NDSI.
+- **Hardware differences between recorders bias comparisons:** AudioMoth, Song Meter, and Marantz record at different gain levels. Normalise SPL or compute indices relative to within-recorder baselines when comparing across equipment types.

package/skills/acoustic-monitoring/examples/example-prompts.md

@@ -0,0 +1,100 @@
+---
+skill_id: acoustic-monitoring
+example_count: 5
+---
+
+# Acoustic Monitoring — Example Prompts
+
+## Scenario 1: Dawn Chorus Diversity Assessment
+
+**Context:** Atlantic Forest fragment, southeastern Brazil. Autonomous recorders (AudioMoth) deployed at 12 stations. Recordings at 05:00–07:00 and 17:00–19:00 for 30 consecutive days.
+
+**Prompt:**
+> "I have 30 days of AudioMoth recordings (2 × 2-hour windows per day) from 12 stations in an Atlantic Forest fragment. Compute ACI, NDSI, and H for all files, then compare dawn-chorus acoustic diversity between core forest and edge stations. Control for diel variation and test whether core stations have significantly higher ACI."
+
+**Expected workflow:**
+1. `compute_acoustic_indices.R` or `compute_acoustic_indices.py` on all audio files
+2. Merge indices CSV with station metadata (core vs. edge)
+3. Fit linear mixed model: `ACI ~ habitat + (1 | station)` with dawn window only
+4. Plot boxplots by habitat type; report effect size (Cohen's d)
+
+**Key decision points:**
+- If NDSI < 0 at dawn → high anthrophony (nearby road); flag station as disturbed
+- If n recordings per station < 10 → exclude from comparative analysis
+
+---
+
+## Scenario 2: Continuous BirdNET Monitoring — Species Phenology
+
+**Context:** Temperate oak woodland, 6 months of continuous recording. Identify seasonal arrival/departure dates for migratory species using automated detection.
+
+**Prompt:**
+> "Run BirdNET on 6 months of continuous recordings from a temperate woodland site. Filter detections with confidence ≥ 0.8, produce a species accumulation curve, and identify the first and last detection date for each migratory species."
+
+**Expected workflow:**
+1. `batch_species_detection.py --confidence 0.8 --lat 51.5 --lon -1.2` on all .wav files
+2. Load `detections_filtered.csv`; parse date from datetime column
+3. Group by species → `first_detection` and `last_detection`
+4. Flag species with < 5 detections as uncertain
+5. Plot phenology chart (horizontal bars per species × date)
+
+**Key decision points:**
+- Confidence < 0.7 → mark as "unconfirmed"; do not include in phenology table
+- If species detected only once → exclude from arrival/departure analysis
+
+---
+
+## Scenario 3: Urban Soundscape Gradient
+
+**Context:** Transect from city centre to rural area. 10 recording stations at 2-km intervals. Assess how NDSI and ACI change along the urban-rural gradient.
+
+**Prompt:**
+> "I have recordings from 10 stations along a 20 km urban-rural transect. Calculate NDSI and ACI for all stations, test for a significant linear trend with distance from city centre, and produce a gradient plot."
+
+**Expected workflow:**
+1. `compute_acoustic_indices.py` per station
+2. Join with station metadata (distance_km)
+3. Regression: `NDSI ~ distance_km`; test slope significance (p < 0.05)
+4. Plot NDSI and ACI vs distance with 95% CI ribbon
+
+**Expected outputs:**
+- NDSI should increase monotonically from urban (negative) to rural (near +1)
+- ACI typically increases but may plateau in intact habitat
+
+---
+
+## Scenario 4: Post-Restoration Acoustic Recovery
+
+**Context:** Degraded wetland restored 3 years ago. Compare pre-restoration (year 0), post-restoration year 1, and year 3 recordings to assess amphibian soundscape recovery.
+
+**Prompt:**
+> "I have 3 years of wet-season recordings (same stations, same dates ± 7 days) spanning a wetland restoration project. Compare ACI and ADI across years. Has the soundscape recovered toward reference wetland values?"
+
+**Expected workflow:**
+1. Compute indices per year; aggregate to daily means per station
+2. Linear mixed model: `ACI ~ year + (1 | station)`
+3. Compare to reference site recordings using effect size
+4. Plot time-series of monthly mean ACI with restoration milestone marked
+
+**Key decision points:**
+- If station n recordings differs between years → use rarefied means (resample to min n)
+- If recovery incomplete at year 3 → recommend extended monitoring
+
+---
+
+## Scenario 5: Multi-Index Habitat Comparison — Fire Chronosequence
+
+**Context:** Savanna sites with different fire histories (1, 3, 5, 10+ years since fire). Determine which acoustic index best discriminates fire age classes.
+
+**Prompt:**
+> "I have acoustic recordings from savanna sites with 4 fire age classes (1yr, 3yr, 5yr, 10yr post-fire). Compute all available indices (ACI, BI, NDSI, H, ADI, AEI). Run a PCA on index values to identify the main axis of acoustic variation. Which index best separates fire ages?"
+
+**Expected workflow:**
+1. `compute_acoustic_indices.R` across all sites
+2. PCA on standardised index matrix
+3. ANOVA or Kruskal-Wallis for each index across fire age class
+4. Select index with highest η² (effect size); plot boxplots by fire age
+
+**Expected findings:**
+- BI typically tracks vegetation structure recovery (increases with fire age)
+- NDSI may not discriminate if sites are far from urban influence

package/skills/acoustic-monitoring/examples/temperate_forest_birds_example.md

@@ -0,0 +1,285 @@
+---
+skill_id: acoustic-monitoring
+example_type: full_walkthrough
+taxon: Birds (Passerines)
+region: Temperate broadleaf forest, central Europe
+---
+
+# Temperate Forest Bird Monitoring — Full Acoustic Walkthrough
+
+## Study Context
+
+**Location:** Oak-beech forest complex, 2,400 ha, Thuringia, Germany (51.2° N, 11.0° E)
+**Objective:** Assess bird species richness and acoustic diversity across a habitat quality gradient (managed vs. old-growth forest patches)
+**Recorders:** 8 × AudioMoth v1.2, deployed at 50-m forest interior points
+**Recording schedule:** 04:30–07:30 UTC daily, May–July (spring migration + breeding)
+**Total recordings:** ~2,160 files (270 per station × 8 stations), each 10 minutes at 32 kHz
+
+---
+
+## Step 1 — Compute Acoustic Indices
+
+```bash
+# Run for each station directory
+Rscript compute_acoustic_indices.R \
+  data/audio/station_01/ \
+  outputs/indices/station_01/ \
+  1 \
+  0 \
+  16000
+```
+
+**Decision:** Frequency max set to 16 kHz (Nyquist for 32 kHz recorders). Passerine vocalisations fall mainly 2–10 kHz.
+
+**Flags raised during processing:**
+- Station 05: 14 files with NDSI < -0.3 during 05:00–06:00 → road noise detected
+  - **Decision:** Exclude station 05 dawn-chorus window from comparative analysis; retain for trend analysis only
+
+**Output check:**
+
+```r
+library(dplyr)
+idx <- read.csv("outputs/indices/all_stations_combined.csv")
+
+# Check recording coverage per station
+idx %>%
+  group_by(station) %>%
+  summarise(n_files = n(),
+            n_hours  = n_recordings * 10 / 60,  # 10-min files
+            pct_valid = mean(!is.na(ACI)) * 100)
+```
+
+| station    | n_files | recording_hours | pct_valid |
+|------------|---------|-----------------|-----------|
+| station_01 | 270     | 45.0            | 98.5      |
+| station_03 | 268     | 44.7            | 97.8      |
+| station_05 | 270     | 45.0            | 96.3      |
+| station_07 | 214     | 35.7            | 94.9      |
+
+**Flag:** Station 07 has only 214 files (malfunction from July 12). Recording hours < 48h for July window — flagged as under-sampled for July species richness.
+
+---
+
+## Step 2 — BirdNET Species Detection
+
+```bash
+python batch_species_detection.py \
+  data/audio/ \
+  outputs/birdnet/ \
+  --confidence 0.7 \
+  --lat 51.2 \
+  --lon 11.0 \
+  --date 2024-05-15 \
+  --overlap 1.0
+```
+
+**Confidence filtering decisions:**
+
+| Confidence band | n detections | Action |
+|-----------------|-------------|--------|
+| < 0.50          | 8,412       | Exclude (high FP rate) |
+| 0.50–0.69       | 3,201       | Retain as "unconfirmed" |
+| 0.70–0.89       | 6,847       | Retain (main analysis) |
+| ≥ 0.90          | 2,104       | High confidence |
+
+**Species accumulation check:**
+
+```python
+import pandas as pd
+import matplotlib.pyplot as plt
+
+det = pd.read_csv("outputs/birdnet/detections_filtered.csv")
+# Sort by datetime to produce accumulation curve
+det_sorted = det.sort_values("datetime")
+det_sorted["cumulative_species"] = det_sorted["common_name"].expanding().apply(
+    lambda x: x.nunique()
+)
+plt.plot(range(len(det_sorted)), det_sorted["cumulative_species"])
+plt.xlabel("Detection number")
+plt.ylabel("Cumulative species detected")
+plt.title("Species accumulation — all stations")
+```
+
+**Result:** Curve asymptotes at ~47 species by detection 5,000 of 8,951. All stations exceed 48 recording hours → richness estimates considered reliable.
+
+---
+
+## Step 3 — Diel and Temporal Analysis
+
+### Dawn Chorus Peak
+
+```r
+library(dplyr); library(lubridate); library(ggplot2)
+
+idx <- read.csv("outputs/indices/all_stations_combined.csv")
+idx$datetime <- as.POSIXct(idx$datetime, tz = "UTC")
+idx$hour     <- lubridate::hour(idx$datetime)
+
+# Filter to dawn window (04:30–07:30)
+dawn <- idx %>% filter(hour %in% c(4, 5, 6, 7))
+
+# ACI by hour
+dawn %>%
+  group_by(hour) %>%
+  summarise(ACI_mean = mean(ACI, na.rm = TRUE),
+            ACI_sd   = sd(ACI, na.rm = TRUE)) %>%
+  ggplot(aes(x = hour, y = ACI_mean)) +
+  geom_ribbon(aes(ymin = ACI_mean - ACI_sd, ymax = ACI_mean + ACI_sd),
+              alpha = 0.3) +
+  geom_line(size = 1.2) +
+  labs(x = "Hour (UTC)", y = "ACI", title = "Dawn chorus ACI")
+```
+
+**Finding:** ACI peaks at hour 05 (mean = 1,842 ± 312), declining by hour 07 (mean = 1,421 ± 287).
+
+### Seasonal Trend
+
+```r
+idx$month <- lubridate::month(idx$datetime)
+
+idx %>%
+  filter(hour == 5) %>%
+  group_by(station, month) %>%
+  summarise(ACI_mean = mean(ACI, na.rm = TRUE), .groups = "drop") %>%
+  ggplot(aes(x = month, y = ACI_mean, colour = station)) +
+  geom_line() + geom_point() +
+  labs(x = "Month", y = "ACI (hour 05)", title = "Seasonal ACI trend by station")
+```
+
+**Finding:** ACI peaks in June (breeding peak) then declines in July (post-breeding silence).
+
+---
+
+## Step 4 — Habitat Comparison
+
+### Station metadata
+
+```r
+meta <- data.frame(
+  station      = paste0("station_0", c(1,2,3,4,5,6,7,8)),
+  habitat_type = c("old_growth", "old_growth", "managed", "managed",
+                   "managed", "old_growth", "old_growth", "managed")
+)
+
+idx_meta <- left_join(idx, meta, by = "station")
+```
+
+### Mixed-effects model
+
+```r
+suppressPackageStartupMessages(library(lme4))
+suppressPackageStartupMessages(library(lmerTest))
+
+dawn_meta <- idx_meta %>%
+  filter(hour %in% c(4, 5, 6))
+
+m1 <- lmer(ACI ~ habitat_type + (1 | station),
+           data = dawn_meta, REML = TRUE)
+summary(m1)
+```
+
+**Results:**
+
+| Effect | Estimate | SE | t | p |
+|--------|----------|----|---|---|
+| Intercept (managed) | 1,312.4 | 68.3 | 19.2 | < 0.001 |
+| habitat_type [old_growth] | **+284.7** | 97.1 | 2.93 | **0.018** |
+
+**Interpretation:** Old-growth stations had significantly higher dawn ACI (+285 units, p = 0.018), consistent with higher acoustic complexity from greater species richness and vocal activity.
+
+### NDSI comparison
+
+```r
+m2 <- lmer(NDSI ~ habitat_type + cos_hour + sin_hour + (1 | station),
+           data = idx_meta %>%
+             mutate(cos_hour = cos(2 * pi * hour / 24),
+                    sin_hour = sin(2 * pi * hour / 24)))
+summary(m2)
+```
+
+**Result:** No significant habitat effect on NDSI (p = 0.21). Both habitat types are remote from roads → low anthrophony → NDSI near +0.7 across all stations. ACI is the more sensitive discriminator here.
+
+---
+
+## Step 5 — Species Richness Comparison
+
+```r
+det <- read.csv("outputs/birdnet/detections_filtered.csv")
+det <- left_join(det, meta, by = c("station" = "station"))
+
+species_richness <- det %>%
+  group_by(station, habitat_type) %>%
+  summarise(n_species = n_distinct(common_name), .groups = "drop")
+
+wilcox.test(n_species ~ habitat_type, data = species_richness)
+```
+
+| Habitat | Mean species | Median | Range |
+|---------|-------------|--------|-------|
+| Old-growth | 38.5 | 39 | 34–43 |
+| Managed | 28.3 | 28 | 24–33 |
+
+**Wilcoxon test:** W = 16, p = 0.028 — significantly more species in old-growth stations.
+
+---
+
+## Step 6 — Outputs and Reporting
+
+```
+outputs/
+├── indices/
+│   ├── all_stations_combined.csv       # 17,280 rows × 9 index columns
+│   ├── indices_summary_by_hour.csv     # mean ACI/NDSI/H by hour
+│   └── soundscape_plot.png             # heatmap: date × hour, coloured by ACI
+├── birdnet/
+│   ├── detections_raw.csv              # 20,551 total detections
+│   ├── detections_filtered.csv         # 8,951 detections (conf ≥ 0.7)
+│   ├── species_list.csv                # 53 species detected
+│   ├── detection_summary.csv           # species × hour matrix
+│   └── species_accumulation.csv
+└── figures/
+    ├── dawn_aci_by_habitat.png
+    ├── seasonal_aci_trend.png
+    └── species_richness_boxplot.png
+```
+
+### Summary table for report
+
+| Metric | Old-growth | Managed | p-value |
+|--------|-----------|---------|---------|
+| Dawn ACI (mean ± SD) | 1,597 ± 298 | 1,312 ± 245 | 0.018 |
+| NDSI (all hours) | 0.73 ± 0.12 | 0.69 ± 0.15 | 0.21 |
+| Species richness (BirdNET) | 38.5 ± 4.3 | 28.3 ± 4.7 | 0.028 |
+| Recording hours | 45.0 (8 stations) | 44.4 (8 stations) | — |
+
+---
+
+## Decision Log
+
+```yaml
+- date: 2024-08-10
+  skill_id: acoustic-monitoring
+  decision: "Excluded station 05 dawn window from ACI comparison (NDSI < -0.3)"
+  rationale: "Persistent road noise detected 04:30–06:30; n=14 files affected"
+  outputs: ["outputs/indices/station_05/acoustic_indices_timeseries.csv"]
+
+- date: 2024-08-10
+  skill_id: acoustic-monitoring
+  decision: "Confidence threshold set to 0.7 for main analysis"
+  rationale: "Precision at 0.7 band estimated 0.82 from subsample of 100 validated clips"
+  outputs: ["outputs/birdnet/detections_filtered.csv"]
+
+- date: 2024-08-11
+  skill_id: acoustic-monitoring
+  decision: "ACI selected as primary diversity metric (over ADI, H)"
+  rationale: "ACI showed highest correlation with manual point-count richness (r = 0.71)"
+  outputs: ["outputs/figures/index_correlation_matrix.png"]
+```
+
+---
+
+## References
+
+- Pieretti, N., Farina, A. & Morri, D. (2011). A new methodology to infer the singing activity of an avian community: the Acoustic Complexity Index (ACI). *Ecological Indicators*, 11(3), 868–873. DOI: 10.1016/j.ecolind.2010.11.005
+- Sueur, J., Pavoine, S., Hamerlynck, O. & Duvail, S. (2008). Rapid acoustic survey for biodiversity appraisal. *PLOS ONE*, 3(12), e4065. DOI: 10.1371/journal.pone.0004065
+- Kahl, S. et al. (2021). BirdNET: A deep learning solution for avian diversity monitoring. *Ecological Informatics*, 61, 101236. DOI: 10.1016/j.ecoinf.2021.101236

package/skills/acoustic-monitoring/resources/acoustic-indices-reference.md

@@ -0,0 +1,93 @@
+# Acoustic Indices Reference
+
+## Index Overview Table
+
+| Index | Full name | What it measures | Scale | R package | Sensitive to noise? |
+|---|---|---|---|---|---|
+| ACI | Acoustic Complexity Index | Temporal variation in spectral energy | 0–∞ (relative) | soundecology | Medium |
+| BI | Bioacoustic Index | Intensity in biological frequency band (2–8 kHz) | 0–∞ (dB·Hz) | soundecology | Low |
+| NDSI | Normalized Difference Soundscape Index | Ratio biophony/geophony | −1 to +1 | soundecology | High |
+| H | Acoustic Entropy | Spectral and temporal entropy | 0–1 | soundecology | Medium |
+| ADI | Acoustic Diversity Index | Shannon diversity of frequency bins | 0–∞ | soundecology | Medium |
+| AEI | Acoustic Evenness Index | Gini coefficient of frequency bins | 0–1 | soundecology | Medium |
+
+---
+
+## Index Formulas and Interpretation
+
+### ACI (Acoustic Complexity Index)
+Calculates the sum of absolute differences in spectral amplitudes across time steps within each frequency bin. High ACI = high temporal variation = complex biological signal.
+
+**Caution:** Heavy rain and wind also produce high ACI. Correlate with NDSI to separate biological from abiotic signals.
+
+### NDSI (Normalized Difference Soundscape Index)
+NDSI = (biophony − geophony) / (biophony + geophony)
+- Biophony band: 2–8 kHz (default)
+- Geophony band: 0.2–1 kHz (default)
+- NDSI > 0 → biophony dominant; NDSI < 0 → geophony/anthrophony dominant
+
+### H (Acoustic Entropy)
+H = Ht × Hf where Ht = temporal entropy, Hf = spectral entropy.
+Range 0–1; values close to 1 indicate highly variable, complex soundscape.
+
+---
+
+## Recommended Index Combinations
+
+| Research question | Primary index | Supporting index |
+|---|---|---|
+| Overall acoustic biodiversity | H or ADI | ACI |
+| Urbanisation gradient | NDSI | BI |
+| Diel soundscape pattern | ACI heatmap | NDSI by hour |
+| Disturbance recovery | ACI trend | H trend |
+| Biophony vs. anthrophony | NDSI | BI |
+
+---
+
+## Computing Indices in R
+
+```r
+suppressPackageStartupMessages(library(soundecology))
+suppressPackageStartupMessages(library(tuneR))
+
+wav_file <- readWave("recording.wav")
+
+# ACI (min_freq and max_freq in Hz)
+aci <- acoustic_complexity(wav_file, min_freq = 200, max_freq = 10000, j = 5)
+cat("ACI:", aci$AciTotAll_left)
+
+# NDSI
+ndsi_result <- ndsi(wav_file, fft_w = 1024, anthro_min = 1000, anthro_max = 2000,
+                    bio_min = 2000, bio_max = 8000)
+cat("NDSI:", ndsi_result$ndsi_left)
+
+# Full suite
+multi <- multiple_sounds(
+  directory   = "audio_dir/",
+  resultfile  = "outputs/acoustic_indices.csv",
+  soundindex  = "soundecology",
+  min_freq    = 200,
+  max_freq    = 10000,
+  max_duration = 60
+)
+```
+
+---
+
+## Sensitivity to Anthropogenic Noise by Index
+
+| Noise source | ACI | NDSI | H | ADI |
+|---|---|---|---|---|
+| Road traffic (low-freq) | Low | High | Medium | Low |
+| Aircraft | Medium | High | Medium | Medium |
+| Wind | High | Medium | Low | Low |
+| Rain | High | Low | Low | Low |
+| Human voices | Medium | High | Medium | Medium |
+
+---
+
+## References
+
+- Villanueva-Rivera, L.J. et al. (2011). A primer of acoustic analysis for landscape ecologists. *Landscape Ecology*, 26(9), 1233–1246. DOI: 10.1007/s10980-011-9636-9
+- Pijanowski, B.C. et al. (2011). Soundscape ecology: the science of sound in the landscape. *BioScience*, 61(3), 203–216. DOI: 10.1525/bio.2011.61.3.6
+- Pieretti, N. et al. (2011). A new methodology to infer the singing activity of an avian community: the Acoustic Complexity Index (ACI). *Ecological Indicators*, 11(3), 868–873. DOI: 10.1016/j.ecolind.2010.11.005