📈 index-wise — Build sdmTMB survey indices with AI agents

Version 0.2.29 (2026-11-12)

Teach your AI coding agent to build a spatiotemporal survey index for stock assessment — for any species, on your own machine.

index-wise is a knowledge pack that turns a general coding agent (Claude Code, Codex, Cursor, Gemini CLI, Mistral, …) into a competent assistant for building sdmTMB (Anderson et al., 2025) survey indices from IMR bottom-trawl data, reproducing the method of Vihtakari et al. (2026, ICES Journal of Marine Science).

Tell your agent which species you want an index for, and it will:

1. Ask you a short, structured questionnaire and confirm a plan.
2. Scaffold a new project folder with a standard structure following wise-writing (docs/, data/, R/, figures/, ai/, logs/, config/).
3. Compile the data from the IMR Biotic database (and, optionally, legacy SPD files), applying the filtering that makes catches quantitative.
4. Fit, validate, and report an sdmTMB index, using helpers from sdmTMBexperiments and maps from ggOceanMaps.

It is not a trained model. Your data never leaves your machine and never enters any model's weights. The agent simply reads this repo while it helps you. See Privacy.

🧰 Built on BAIT

index-wise owns the sdmTMB index-building workflow. BAIT handles Biotic data access, the database, privacy, maps, and life-history. Install BAIT on demand before compiling index data from Biotic; installing index-wise does not install or refresh the database.

You may install and update packs through Fiskwise's managed lifecycle, or use the standalone pack skills in this repository. Shared writing/reporting dependencies are installed on demand; they are not a prerequisite for the index-wise pack itself. The versioned assessment index also feeds survey indices of spict-wise and gadget-wise models. Use fiskwise-workflow for requests spanning packs. For managed R tasks, always use r-code-style. The coordinator's lifecycle skills are fiskwise-install, fiskwise-update, and fiskwise-uninstall.

install https://github.com/DeepWaterIMR/BAIT

🔒 Privacy first

This repo is public and contains instructions only — never data:

• No data and no private paths are ever committed here. Real data and paths live only in the project folder the agent generates for you, where data/, logs/, and ai/review/ are git-ignored.
• The Biotic database lives outside any repo (BAIT default: ~/IMR_biotic_BES_database/).
• During setup, turn off model training / data retention for your agent once — BAIT walks you through it and records the onboarding.

🚀 Quickstart

1. Before Biotic data compilation, install BAIT if needed: install https://github.com/DeepWaterIMR/BAIT. Database setup is a separate choice.
2. Install index-wise:

   install https://github.com/DeepWaterIMR/index-wise
   

   The agent runs index-install: a privacy check → cloning index-wise → installing the skills globally → verifying BAIT and the R packages (sdmTMB, sdmTMBexperiments, ggOceanMaps).
3. Start a species index:

   Let's make a biomass index for snabeluer (beaked redfish) using all bottom trawl data
   collected during surveys, using index-wise.
   

   The agent runs the questionnaire, plans, scaffolds a project, and drives the four-step workflow.

🗺️ The four-step workflow

Step	Skill
Scaffold a project (questionnaire + plan)	index-new-project
Create valid study-region polygons	index-make-regions
Ask about or review an sdmTMB index in any project	index-sdmtmb
1. Compile & report the data	index-compile-data
2. Fit the first feasible model	index-fit-model
3. Validate / select the model	index-validate-model
4. Final report + extensions	index-final-report
CPUE — prepare logbook / sales-note records	index-cpue-data
CPUE — standardise and export (glmmTMB, mgcv, sdmTMB)	index-cpue-model

The two CPUE skills are an optional track for a commercial CPUE index beside the survey index. Logbook and sales-note data are not Biotic data; the background is in knowledge/cpue.md and knowledge/cpue-models.md, and examples/snowcrab-ers-cpue/ runs all three engines on synthetic data with a known trend.

Each step's document lives in project-template/docs/ and is index-wise's own, evolving implementation — improve it directly as the routine matures. knowledge/workflow.md points to the (IMR-internal) background material the method was originally distilled from, if you want the history.

Long renders are compiled with index-render in a screen session with a log in logs/.

📚 What's in this repo

• AGENTS.md / CLAUDE.md — the agent contract.
• skills/ — the index-* skills (installed globally).
• knowledge/ — the shared source of truth (method, data filtering, sdmTMB, helpers, model selection, packages, project structure, rendering).
• project-template/ — the skeleton copied into each new project.
• scaffold.R — stamps a project from config.yaml.
• examples/redfish/ — a worked example.
• examples/snowcrab-ers-cpue/ — a simplified, synthetic snow crab ERS CPUE index with glmmTMB, mgcv and sdmTMB.

🧰 Siblings

• BAIT — IMR Biotic data access, the database, privacy, maps, life history. Required for Biotic data (Step 1); other survey data can use the own-data contract in knowledge/data-filtering.md.
• wise-writing — the writing style, document conventions, and shared project layout. Required when scaffolding reports; install it on demand.
• spict-wise — SPiCT biomass-dynamic stock assessments. The index this pack exports is what a SPiCT assessment consumes; step 4's selected index becomes SPiCT's obsI.
• wise-presentations — Quarto RevealJS slides.

🚨 You are still in charge

This repo is designed to create a survey index template. It speeds up the data and model compilation, but does not create ready indices for assessment. It provides a place to start, not a final deliverable. Expert judgment is required for the final assessment.

📖 References

Anderson, S.C., Ward, E.J., English, P.A., Barnett, L.A.K., & Thorson, J.T. (2025). sdmTMB: An R Package for Fast, Flexible, and User-Friendly Generalized Linear Mixed Effects Models with Spatial and Spatiotemporal Random Fields. Journal of Statistical Software, 115(2), 1–46. doi:10.18637/jss.v115.i02.

Vihtakari, M., Aune, M., Assmann, K.M., Howell, D., Hallfredsson, E.H., & Ward, E.J. (2026). Demersal distribution and fisheries independent trends of beaked and golden redfish in the Barents and Norwegian Seas. ICES Journal of Marine Science, 83(2), fsag009. doi:10.1093/icesjms/fsag009.

wise-writing compatibility

New projects use wise-writing's folder structure and HTML data-report conventions. Read the shared contract and the generated layout. Supply confirmed AUTHORS and AFFILIATIONS in the scaffold configuration. Existing species projects are not migrated automatically. The installed wise-writing skills govern all generated artifacts.

Run Rscript config/validate-scaffold.R to check a synthetic scaffold without accessing data or fitting models. Add --render to render a small synthetic report using the same metadata, assets, citation helper, and code-fold settings.