Acute Needs Analysis (ANA)

Table of contents

1. What the ANA app does
2. Getting started — setup, dev server, all commands
3. App views
4. How it works — flagging pipeline, reference framework
5. Data model — reference.json shape, flagged row shape
6. Architecture — engine modules, stores, routes, components
7. Tech stack
8. Maintenance guide

What the ANA app does

Upload a CSV (one row per unit of analysis, columns mainly metric IDs MET001, MET002, ...). the app validates it, applies threshold-based flagging across 198 metrics and 8 humanitarian systems, and delivers two core outputs:

Everything else in the app — heatmaps, choropleth map, coverage charts, spotlight cross-tab — is designed to help analysts interpret flagging results and decide which units warrant a deep dive.

Optional: metric sources upload

Before running the pipeline, analysts can upload a second CSV that maps data sources to specific metrics and units of analysis. This annotates every metric row in the deep-dive workbooks with four extra columns: Source, Source link, Start of data collection, and End of data collection. The sources CSV is stored in localStorage and reapplied on subsequent visits until explicitly cleared.

Priority flag severity order:

EM · HO – Primary · HO – Secondary · AN – Primary · AN – Secondary · Insufficient Evidence · No Data · No Acute Needs

The priority flag is a data-driven pre-screening result, not a conclusion. Each unit requires a full deep-dive before drawing final conclusions.

Getting started

Requires Podman and podman-compose. No other tools needed on the host. The container image runs Fedora 42.

sudo dnf install podman podman-compose # Fedora / WSL Fedora

Windows / WSL 2 — install WSL 2 first (wsl --install -d FedoraLinux-42), then run all commands inside WSL.

Start the dev server

podman-compose up

Open http://localhost:5173.

Devcontainer (VS Code / Podman Desktop / GitHub Codespaces)

Open the repo in a devcontainer-aware editor. bun install runs automatically. VS Code: set "docker.dockerPath": "podman" in your user settings.

Commands

All bun run commands execute inside the container (podman exec ana-dev bun run <cmd> or via a devcontainer terminal).

# App
bun run dev # start dev server at http://localhost:5173
bun run build # production build (outputs to build/)
bun run preview # preview the production build locally
bun run check # Svelte type-checking (svelte-check)
bun run lint # ESLint
bun run format # Prettier
bun run test # run the test suite (Vitest)
# Data pipeline
bun run generate:enums # regenerate TS enums from reference CSV
bun run generate:reference-json # regenerate reference.json + reference-circlepacking.json
bun run generate:input-data # generate sample input data CSV
bun run generate:input-sources # generate sample metric sources CSV
bun run validate:reference-json # validate reference.json
bun run validate:hypotheses-json # validate hypotheses JSON
bun run validate:circlepacking-json # validate reference-circlepacking.json
bun run data:refresh # run all generation + validation in sequence

Set BASE_PATH=/repo-name when building for GitHub Pages sub-path deploys.

App views

How it works

Reference framework

The framework has five levels, from broadest to most specific:

System → Factor → Sub-Factor → Indicator → Metric

• A Metric is the leaf: one measurable value (e.g. "Acute malnutrition prevalence — MUAC"). It has a numeric threshold. If a field result crosses that threshold, the metric is flagged.
• An Indicator groups one or more metrics that measure the same concept from different angles.
• Sub-Factor, Factor, and System are progressively broader groupings. Flagging rolls upward: enough flagged metrics in a sub-factor flags the sub-factor, and so on up to system level.

Data flow

CSV Upload (src/routes/+page.svelte)
 → parser.ts PapaParse wrapper — returns headers + raw rows
 → validator.ts Checks headers against reference.json, UOA uniqueness, type constraints
 → flagger.ts Applies thresholds; rolls up metric → subfactor → factor → system → priority_flag
 → fetchAdmin.ts If p-codes detected, fetches ADM1/ADM2 GeoJSON from external API (fire-and-forget)
 → Stores flagStore, adminFeaturesStore
 → Results routes /results (heatmap, drilldown, coverage, spotlight)
 → Export download.ts (CSV/JSON/XLSX) | deepdive.ts (ZIP packages, one XLSX per UoA)

The reference CSV — static/data/reference.csv

Each row is one metric. The columns that drive the app's behaviour:

How flagging works

Sub-factor rollup

Metrics are grouped within each sub-factor by their (factor_threshold, evidence_threshold) pair. Within each group:

• Flag if flagged metrics ≥ factor_threshold
• No flag if metrics with data ≥ evidence_threshold (and flag rule not met)
• Insufficient evidence if some data is present but below the evidence threshold
• No data if no metrics have data

Sub-factor → Factor → System statuses propagate upward: flag beats no_flag beats insufficient_evidence beats no_data. Only non-supporting-evidence metrics participate.

Priority flag decision tree

Classification systems: Food Security, Health Outcomes, Livelihoods, WASH, Health/Nutrition Services (Mortality and Market Functionality have dedicated rules).

VAN strict: van_is_strict: true when the VAN threshold differs from AN. Metrics where VAN = AN are excluded from steps 3 and 4's VAN checks.

What to do after updating the reference CSV

bun run data:refresh

This regenerates all JSON files the app reads from the CSV and validates them. Without this step, changes to the spreadsheet have no effect on the app.

Data model

reference.json shape

Generated from reference.csv by scripts/generate-reference-json.ts. The root is an array of systems:

ReferenceRoot = System[]
System { id, label, factors: Factor[] }
Factor { id, label, system, sub_factors: SubFactor[] }
SubFactor { id, label, factor, system, indicators: Indicator[] }
Indicator { id, label, sub_factor, factor, system, metrics: Metric[] }
Metric {
 metric: string // "MET001"
 label: string
 preference: 1 | 2 | 3 // 3 = excluded from pipeline
 evidence_type: "AN signal" | "Outcome" | "Predictor" | "Supporting evidence"
 type: string // e.g. "num[0:1]", "int[0+]"
 thresholds: { an: number | null; van: number | null }
 van_is_strict: boolean | null // true when VAN ≠ AN and VAN is set
 above_or_below: "above" | "below"
 evidence_threshold: number
 factor_threshold: number
 indicator, sub_factor, factor, system // parent IDs
}

Flagged row shape

Each row output by the pipeline (flagStore) extends the original CSV row with computed columns:

uoa
MET001 MET001_flag MET001_status MET001_van_flag MET001_van_status MET001_within_10perc_change
... (one block per metric)
subfactor_<subfactor_id>_<group_key>_status
factor_<factor_id>_status
system_<system_id>_status
priority_flag

Status vocabulary (applies at every rollup level):

priority_flag values (severity order): em · ho_primary · ho_secondary · an_primary · an_secondary · insufficient_evidence · no_data · no_acute_needs

Architecture

Engine — src/lib/engine/

Stores — src/lib/stores/

All stores use Svelte 5 $state runes and persist to localStorage.

Routes

Components

src/lib/components/results/

src/lib/components/viz/

src/lib/components/ui/

General-purpose primitives: TooltipCard, LegendBadge, PriorityBadge, DataGuard, NavButton, ExploreNav, and others.

DataGuard.svelte gates any page or section that requires store data — shows a loading/redirect state when flagStore or metricStore is not ready. Always wrap results pages with it.

Colour system — src/app.css

Each system colour is defined as a single base hex in :root; five depth variants are derived automatically:

--color-sys-food-system: #61d095;
--color-sys-food-system-d1: color-mix(in srgb, var(--color-sys-food-system) 10%, transparent);
--color-sys-food-system-d2: color-mix(in srgb, var(--color-sys-food-system) 40%, transparent);
/* ... d3, d4, d5 */

src/lib/utils/colors.ts exports pure var(--...) strings. For non-browser contexts (ExcelJS in deepdive.ts), hex is read at runtime via getComputedStyle.

Type system — src/lib/types/

Tech stack

SvelteKit Svelte 5 Tailwind CSS 4 DaisyUI 5 D3.js Turf.js ExcelJS Zod PapaParse tidyjs Bun Vitest Podman

Maintenance guide — data pipeline and export logic

Repository map

CSV → JSON generation

Run everything: bun run data:refresh

Adding a new metric: add the row to reference.csv, run data:refresh, confirm no validation errors.

Adding a new system/factor/subfactor: update the relevant lookup CSV first, then add the rows to reference.csv, then run data:refresh.

Renaming or removing a system/factor/subfactor ID: update the lookup CSV and reference.csv, run data:refresh + generate:enums, then search the codebase for the old ID — it may appear in src/lib/engine/flagger.ts.

CI/CD — .github/workflows/deploy.yml

• Trigger: push to main, or manually from the GitHub Actions tab
• Build steps: install Bun (via curl in Fedora 42 container) → bun run data:refresh → bun run test → bun run build → upload build/ as Pages artifact
• Key implication: data:refresh runs in CI before the build — a CSV change that fails validation will break the deployment. Always run bun run data:refresh locally first.

Flagging logic — src/lib/engine/flagger.ts

Entry point: flagData(rows, referenceJson). Five stages:

1. Metric level (makeMetricSpec) — computes {id}_flag, {id}_status, {id}_van_flag, {id}_van_status, {id}_within_10perc_change for every non-preference-3 metric
2. Sub-factor groups — non-supporting-evidence metrics only, grouped by (factor_threshold, evidence_threshold) pair
3. Sub-factor status — worst outcome across all its threshold groups
4. Factor / System rollup — rollupStatuses aggregates child statuses
5. priority_flag — 8-step decision tree over system-level statuses and metric-level VAN flags

Touch flagger.ts when: the decision-tree logic changes, new priority-flag categories are added, or the rollup rules change. Threshold values live in the CSV.

Deep-dive export — src/lib/engine/deepdive.ts

Generates a ZIP archive — one pre-populated .xlsx per Unit of Analysis. Each workbook has one worksheet per system. Each metric row carries:

• Pre-populated: Indicator label, Metric label, Metric ID, uploaded value, flag result, AN threshold, VAN threshold, direction
• Source annotation (always present): Source, Source link, Start of data collection, End of data collection — populated from the optional sources CSV if uploaded; otherwise left blank
• Editable: H1–H5 hypothesis columns, Comment field

XLSX filenames include the unit's priority flag: deepdive_{uoa}_{priority_flag}.xlsx.

Column definitions and table headers live in src/lib/types/deepdives.ts (tableHeaders, colWidths, colCount). Source column headers and widths are in SOURCE_COL_HEADERS / SOURCE_COL_WIDTHS.

Touch deepdive.ts when: export layout, cell styling, column order, or pre-population logic changes. Touch deepdives.ts when: adding or removing columns from the exported table. Touch metricSourcesValidator.ts + sources.ts when: the sources CSV format changes.

Maintenance quick-reference