# Indonesia Smoking Dashboard Blueprint

Version: 0.1
Date: 2026-05-10
Project: ARC10 Behaviour Institute - Indonesia Smoking Dashboard
Status: preparation blueprint

## 1. Purpose

This dashboard should become the public analytic surface for tobacco use and
smoke exposure in Indonesia. It should help users answer:

- How large is active tobacco use and secondhand smoke exposure?
- Which age, sex, socioeconomic, and geography groups carry the highest burden?
- How are smoking, passive exposure, initiation, and product type changing over time?
- Where are smoke-free-area regulations strong, weak, or incomplete?
- Which results are population behaviour indicators, and which are policy/KTR document indicators?

## 2. Product Boundary

### In Scope

- Active smoking, former smoking, never smoking, and secondhand smoke exposure as one exposure cascade.
- Current smoking prevalence and total smoker estimates.
- Daily versus occasional smoking.
- Smoking initiation age and progression to daily smoking.
- Tobacco product type: kretek, manufactured cigarette, linting, e-cigarette, shisha, cigar, chewing tobacco, and poly-tobacco where available.
- Secondhand smoke exposure among former smokers, never smokers, adolescents, adults, and children under 10.
- Province and district summaries where estimates are reliable.
- KTR policy content analysis, MPOWER variables, enforcement, cessation, sales restrictions, e-cigarette coverage, and local policy stringency.
- Methods, provenance, source manifest, and caveats.

### Out Of Scope For MVP

- Intervention simulation or scenario modelling.
- Real-time database queries.
- Editing or curation workflows.
- Clinical cessation service cascade unless an audited service data source is added.
- Hidden frontend calculation of policy numbers.

## 3. Architecture

Use the ARC static health-dashboard pattern:

```text
existing R/Rmd/RDS/XLSX/JSON outputs -> R exporter -> dashboard/data/*.json -> vanilla HTML/CSS/JS
```

The frontend should only:

- route views
- render prepared arrays
- filter/sort already-exported rows
- format numbers
- draw charts/tables/maps
- download CSV from rendered tables

All estimates, CI, suppression flags, rankings, and method labels should be built in R.

## 4. Source Mapping

### Behaviour Survey Sources

Primary analytic source:

```text
/mnt/d/OneDrive - Yayasan Transformasi Kesejahteraan Bangsa/
  1. Project Center/ARC10. Behaviour Institute/
  10.1 NCD-related Behaviour/Master Data Smoking 2007-2023 V3.rds
```

Known structure:

- 4,010,363 rows x 64 columns.
- Years: 2007, 2010, 2013, 2018, 2023.
- Key fields: `year`, `age`, `age_group`, `gender`, `domicile`,
  `wealth_quintile`, `education`, `occupation`, `province_gis_name`,
  `gis_code_24`, `island`, `weight_total`, `who_age_weight`, `psu`, `strata`.
- Smoking fields include `hbv_smoking_last_month`, `hbv_current_smoking_binary`,
  `hbv_passive_smoker_freq`, `smoking_cascade`, `smoking_cascade_simple`,
  `household_smoking_exposure`, `hbv_smoking_age_start`,
  `hbv_smoking_daily_age_start`, `hbv_age_stop_smoke`, `hbv_smoking_freq_daily`,
  tobacco type variables, `poly_tobacco`, and `tobacco_type_category`.

Important R/Rmd source:

```text
10.1 NCD-related Behaviour/10.2a Indonesia Smoking Analysis.rmd
10.1 NCD-related Behaviour/Remapping Health Behavior_Rev3_20Mar25.Rmd
10.1 NCD-related Behaviour/Temp Smoking Cascade Fix.R
```

Research manuscript source:

```text
2. Research Center/ARC10. Behaviour Institute/
  10.2 Indonesia Smoking Analysis/
  10.2e Indonesia Smoking Use and Exposure (Reviewer-Zero edits).docx
```

The manuscript is useful for interpretation and QA, but dashboard numbers should
come from R-exported data, not hand-entered manuscript text.

### KTR / Policy Sources

Primary KTR source:

```text
2. Research Center/ARC10. Behaviour Institute/10.3 Smoking Subnational/
```

Key files:

- `README.md`
- `KTR/Peraturan_KTR_Indonesia_LENGKAP.xlsx`
- `KTR/Code/data/ktr_extraction_results.csv`
- `KTR/Code/data/ktr_extraction_results.xlsx`
- `Manuscript/analysis_results.json`
- `Manuscript/province_coverage.json`
- `Manuscript/jurisdiction_results.json`

Known KTR summary:

- 445 extracted regulations.
- 86-variable codebook plus metadata columns.
- Regulation years range from 2003 to 2025.
- Main dimensions: KTR scope, enforcement, advertising, warnings, cessation,
  sales restrictions, monitoring, and Indonesia-specific policy context.

## 5. Information Architecture

Use hash routes:

```text
#/landing
#/section/exposure
#/section/subnational
#/section/policy
#/section/explorer
#/section/methods
```

### 5.1 Landing

Usable analytic summary, not a marketing page.

Panels:

- KPI strip: current smokers, adult male current smoking, adolescent male current smoking, secondhand exposure among non-smokers, under-10 household exposure, KTR documents reviewed.
- Exposure cascade snapshot: daily smoker, occasional smoker, former plus passive, never plus passive, smoke-free.
- Trend strip: selected indicators by survey year.
- Geography signal: highest and lowest province/district for selected exposure outcome.
- Policy signal: KTR coverage and policy stringency highlights.
- Caveat bar: survey years, age denominators, weighted estimates, and KTR document analysis boundary.

### 5.2 Tobacco Exposure

This combines active smoking and secondhand smoke exposure in one module.

Controls:

- population: children under 10, adolescents 10-17, adults 18+, all age-valid
- sex: all, male, female
- year
- stratifier: domicile, wealth, education, occupation, age group
- outcome: exposure cascade, current smoking, daily smoking, passive exposure,
  household exposure, initiation age, daily sticks, product type

Required panels:

- latest exposure cascade
- baseline-to-latest change
- all-year trend
- sex-age profile
- active plus passive exposure stack
- initiation age and progression to daily smoking
- tobacco product type composition
- subgroup gap table
- method note for denominator and survey design

### 5.3 Subnational

Controls:

- geography level: province, district where reliable
- outcome: current smoking, passive exposure, household exposure, cascade category,
  initiation age, KTR policy stringency
- year
- sex and age-valid population

Required panels:

- ranked table
- highest-lowest gap
- selected area trend
- island grouping
- LISA/Moran panel only if validated and clearly labelled exploratory
- suppression marker for unstable district cells

### 5.4 Policy / KTR

Controls:

- geography: province, district/city, island
- regulation type: PERDA, PERBUP, PERWALI, PERGUB, QANUN, national
- year/period
- MPOWER domain

Required panels:

- KTR document coverage and timeline
- policy stringency distribution
- KTR venue scope
- enforcement bodies and sanctions
- advertising/promotion/sponsorship restrictions
- cessation services and referral mentions
- sales restriction and age limit provisions
- e-cigarette, shisha, and chewing tobacco definition coverage
- province policy map with selected MPOWER/stringency metrics
- district/city KTR category map with three mutually exclusive categories:
  Perda + Perbup/Perwali, one instrument only, or no matched local KTR
  instrument in the reviewed corpus
- KTR theme mentions table naming policy themes covered by coded document
  content, not only binary yes/no indicator columns
- district/province policy table

### 5.5 Explorer

Searchable and downloadable table.

Recommended row types:

- survey estimate rows: year, geography, population, sex, outcome, estimate,
  CI, n, weighted population, source, suppression
- KTR rows: jurisdiction, province, regulation type, year, MPOWER variables,
  stringency, caveats, source document

### 5.6 Methods

Required content:

- source manifest
- data dictionary
- survey design and weighting
- age denominator rules
- exclusion rules
- outcome definitions
- suppression rules
- KTR extraction method and codebook
- provenance and build timestamp

## 6. Data Contract

Initial files:

```text
dashboard/data/dashboard_meta.json
dashboard/data/overview.json
dashboard/data/exposure.json
dashboard/data/subnational.json
dashboard/data/policy_ktr.json
dashboard/data/explorer_index.json
dashboard/data/geographies.json
dashboard/data/source_manifest.json
dashboard/data/validation_report.json
```

### 6.1 Common Survey Estimate Row

```json
{
  "module": "exposure",
  "outcome": "current_smoking",
  "year": 2023,
  "population": "adults_18plus",
  "age_min": 18,
  "age_max": null,
  "sex": "Male",
  "geo_level": "national",
  "geo_id": "ID",
  "geo_label": "Indonesia",
  "stratifier": null,
  "stratum": null,
  "estimate": 0.0,
  "ci_lo": 0.0,
  "ci_hi": 0.0,
  "n_unweighted": 0,
  "weighted_population": 0,
  "design_note": "survey::svydesign with available PSU/strata/weights",
  "source_id": "master_smoking_v3",
  "suppressed": false,
  "caveat": null
}
```

Estimates should be stored as proportions in JSON. The frontend formats them as
percentages.

### 6.2 Common KTR Policy Row

```json
{
  "module": "policy_ktr",
  "jurisdiction_id": "string",
  "jurisdiction_name": "string",
  "province": "string",
  "island": "string",
  "regulation_type": "PERDA",
  "regulation_year": 2023,
  "mpower_domain": "P",
  "theme_mentions": "Ruang KTR; Penegakan dan sanksi",
  "variable": "P13_ecig_covered",
  "value": true,
  "stringency_score": 0.0,
  "source_id": "ktr_extraction_results",
  "source_document": "string",
  "caveat": null
}
```

## 7. Outcome Canon

### Exposure Cascade

Use `smoking_cascade_simple` as the primary cascade unless validation shows a
better harmonized field.

Canonical categories:

- daily smoker
- occasional smoker
- former plus passive smoker
- never plus passive smoker
- former non-passive smoker
- never non-passive smoker

Keep the more detailed `smoking_cascade` categories available in explorer and
methods.

### Core Outcomes

- `current_smoking`: current daily or occasional smoking.
- `daily_smoking`: current daily smoking.
- `occasional_smoking`: current occasional smoking.
- `former_smoking`: former smoking.
- `passive_exposure`: secondhand smoke exposure among non-current smokers.
- `household_smoke_exposure_under10`: household smoke exposure among children under 10.
- `initiation_age`: age at first smoking.
- `daily_initiation_age`: age at daily smoking initiation.
- `daily_sticks`: average cigarettes/sticks per day.
- `tobacco_product_type`: product composition among current smokers.
- `poly_tobacco`: use of more than one product type.

## 8. Survey Design And Suppression

Preferred survey design:

```r
survey::svydesign(
  id = ~psu,
  strata = ~strata,
  weights = ~weight_total,
  data = df,
  nest = TRUE
)
```

If PSU/strata are unavailable or inconsistent for a panel, metadata must say so.

Suppression proposal:

- suppress cells with unweighted n < 30
- suppress cells with effective n < 30 where effective n is available
- suppress district estimates unless denominator and reliability checks pass
- keep wide CI warnings visible for small subgroups

## 9. Frontend Pattern

Use vanilla HTML/CSS/JS:

- no build step
- local vendor assets for Chart.js/D3 if charts/maps need them
- hash routing
- compact controls
- sortable tables
- CSV download
- public-grade copy
- methods/provenance visible

Use ACSC for landing/deep-dive storytelling, Anthro for repeated population
module structure, Global Surgery for explorer/export patterns, and
Cardiometabolic for data contract and source-manifest discipline.

## 10. MVP Definition

MVP v0.1:

1. Dashboard blueprint and source manifest.
2. R exporter for national exposure cascade and core smoking outcomes.
3. R exporter for under-10 household exposure.
4. Province-level smoking and passive exposure ranking.
5. KTR policy summary from `analysis_results.json` and extraction table.
6. Static shell with landing, exposure, subnational, policy, explorer, methods.

MVP v0.2:

1. District estimates with suppression.
2. Birth-cohort panels.
3. Initiation-age and progression-to-daily panels.
4. Tobacco product type and e-cigarette panels.
5. LISA/Moran spatial outputs if validated.
6. Print/PDF slide mode for stakeholder meetings.

## 11. Open Questions

1. Should the public title use "Tobacco Exposure" or "Smoking and Secondhand Smoke Exposure"?
2. Should adolescents be 10-17 throughout, with 2010 excluded from adolescent panels because the source question starts at age 15?
3. Which denominator should be headline: age >=10, adolescents 10-17 plus adults 18+, or adults 18+?
4. Should KTR stringency be shown beside behaviour estimates in subnational view, or kept in policy view only for MVP?
5. Which public route should be used: `/reports/smoking/`, `/reports/tobacco-indonesia/`, or another name?