MIH Consolidated Knowledge Package

Project: Modelling Invasive Mosquitoes in Hawaiʻi (MIH) Consolidated: April 21, 2026 Purpose: Portable knowledge bundle for collaborative sharing and agent handoff

---

Contents

docs/ — Living Documentation

The four authoritative project documents:

1. PIPELINE_SPEC.md — Stable design contract. Conventions, directory structure, per-step I/O, dependency graph. Read this first to understand how the pipeline works.

2. STATUS.md — Current state. Open decisions, blockers, data acquisition status, what-to-do-next. Read this second to understand what needs to happen.

3. PROVENANCE.md — Data lineage and institutional memory. Why data choices were made, original analysis reconstruction, email archaeology. Read this for the why behind technical decisions.

4. MIH_bibliography.md — Citation records and PDF acquisition status. ~170 entries covering Hawaii mosquito history, competition ecology, SDM methods, and climate data sources. Read this to understand what's cited and what PDFs are still needed.

scripts/ — R Pipeline Code

All numbered pipeline scripts and utility scripts:

• 00_occurrence.R — Occurrence staging (step 00)
• 01a_build_canonical_rasters.R — Canonical DEM and island index (01a)
• 01b_aggregate_rh.R — Aggregate relative humidity (01b)
• 01c_aggregate_ndvi.R — Aggregate NDVI (01c)
• 01d_decade_normals.R — Decade normals from HCDP (01d)
• 01e_extract_climate_atlas.R — Extract Climate Atlas (01e)
• 01_env_layers.R — Main environmental layers step (01)
• 02_occurrence_clean.R — QC and thinning (step 02)
• 03_enm.R — ENMeval + bootstrap MaxEnt (step 03)
• _pipeline_boilerplate.R — Shared boilerplate (resolve, push_output)

All scripts follow pipeline conventions:

• Use here::here() for path resolution
• Source _pipeline_boilerplate.R for resolve() and push_output()
• Load conflicted with explicit preferences
• Use package::function() notation throughout
• Fail loudly on missing inputs, never silently continue

---

How to Use This Package

For a new analyst joining the project:

1. Read docs in order: PIPELINE_SPEC → STATUS → PROVENANCE → bibliography
2. Understand the scientific argument: See PIPELINE_SPEC "Scientific argument"
3. Check current state: See STATUS.md for what's complete and what's blocked
4. Run a script: Pick any numbered script from scripts/ and check PIPELINE_SPEC for its I/O contract

For an AI agent being handed off the project:

1. This consolidated package contains all you need to engage with the project
2. The living docs (especially PIPELINE_SPEC.md) establish the stable contracts
3. STATUS.md tells you what decisions are open and what's blocking work
4. PROVENANCE.md explains non-obvious data choices (e.g., why ERA5-Land was retired)
5. The scripts in scripts/ are the actual implementation — read them to understand the current state

For sharing knowledge with collaborators:

This package contains all public-facing design (specs and docs) and all code. It does not contain:

• Data files (store those separately or reference via Google Drive)
• Bibliography PDFs (store in ~/MIH/bibliography/ or Drive)
• Output artifacts (generated by scripts, stored on Drive)
• Collaboration notes (keep in STATUS.md living doc on Drive)

---

Key Concepts

Scientific argument

Ae. albopictus competitively excludes Ae. aegypti wherever it can establish. Ae. aegypti persists only in hot/dry leeward coastal refugia where high vapour pressure deficit (VPD) suppresses albopictus egg survival — an abiotic refuge from competitive exclusion, not a preferred niche.

Pipeline structure

• Step 00: Occurrence staging (three datasets for two time periods)
• Step 01: Environmental layers (climate, DEM, NDVI—multiple substeps)
• Step 02: Occurrence QC and thinning
• Step 03: MaxEnt species distribution models (ENMeval + bootstrap)
• Step 04: Area statistics and Venn diagram
• Step 05: Niche overlap analysis (ecospat)
• Step 06: Survey model (ZINB on field trap data)
• Step 07: Manuscript figures
• Step 08: Future projections (climate scenarios)

Key constraints

• Terra v1.9.11 on wallypad: terra::time() unreliable for cfgrib NetCDF; use ncdf4::nc_open() with raw int64 seconds instead
• ERA5-Land retired: Structural bias over Hawaiian terrain; WorldClim v1.4 is the fallback for historic temperature
• HCDP rainfall ocean leak: Ocean cells extend beyond DEM; mask to dem_250m > 0 before averaging
• Jensen's inequality: ERA5 monthly-averaged-by-hour incomparable to HCDP monthly mean of daily min/max; fundamental mismatch, not fixable
• Drive path mirroring: Local data/field/ mirrors to Drive as data/field/; underscore vs slash mismatches cause invisible sync failures

---

Maintaining This Package

When changes are made to the living docs:

1. Update all four docs in the source (Google Drive or local project)
2. Re-export them to this consolidated package
3. Update this README if the structure changes

The scripts should be updated only in the source ~/MIH/scripts/ directory, never directly in a consolidated package (packages are read-only copies).

---

Contact & Troubleshooting

For questions about:

• Pipeline design: See PIPELINE_SPEC.md
• Current blockers: See STATUS.md
• Data choices: See PROVENANCE.md
• Citations: See MIH_bibliography.md
• Script execution: See the script's header comment and check PIPELINE_SPEC step contract