# HawaSpatial

**HawaSpatial** is an R package and a 'shiny' platform for sub-national monitoring of global development indicators using complex household surveys and administrative shapefiles.

The package supports workflows for:

- survey-shapefile integration through a spatial equalizer;
- 17 exploratory spatial data analysis methods;
- bivariate spatial association;
- small area estimation using Fay-Herriot models;
- spatial autoregressive and spatial error models;
- hierarchical multilevel modeling with `glmmTMB`;
- spatial inequality metrics including Gini, Theil, and concentration indices;
- spatial and temporal dynamics and decomposition;
- publication-ready reporting.

## Installation

After CRAN acceptance, install the released package using the standard R package installation workflow. Development versions are available from the project repository listed in `DESCRIPTION`.

## Run the app

```r
library(HawaSpatial)
run_app()
```

or:

```r
run_hawaspatial()
```

## Example files

```r
hawaspatial_example_files()
```

The package includes three example survey datasets and two shapefile archives:

1. Somalia food security example combining Somalia Health and Demographic Survey 2020 and Somalia Integrated Household Budget Survey 2022.
2. Somaliland Health and Demographic Survey 2020 district-level female genital mutilation example.
3. Somalia poverty example combining Somalia High Frequency Survey 2017 and Somalia Integrated Household Budget Survey 2022.
4. Somalia regional administrative boundaries.
5. Somaliland district administrative boundaries.

## Preserving analytical context

HawaSpatial does not rely on chat memory or informal notes as the source of analytical context. The package includes project-state helper functions so users can save selected indicators, geography, model settings, weights, time periods, and reporting metadata.

```r
state <- list(
  indicator = "poverty",
  admin_level = "region",
  survey_waves = c(2017, 2022),
  spatial_weights = "Queen contiguity"
)

save_hawaspatial_state(state, "my_hawaspatial_state.rds")
restored <- load_hawaspatial_state("my_hawaspatial_state.rds")
```

## Related applied work

HawaSpatial has been used and cited through its Zenodo software DOI in applied geospatial and multilevel health studies, including:

* Warsame et al. (2026), *The Burden of Arthritis in Somalia: A Geospatial and Multilevel Analysis to Guide Regional Orthopaedic Resource Allocation*, Journal of Orthopaedic Reports, 101000. <https://doi.org/10.1016/j.jorep.2026.101000>
* Muhumed et al. (2026), *Geospatial and multilevel determinants of childhood stunting in Somalia: A small area estimation and decomposition analysis of clinical nutrition priorities*, Clinical Nutrition Open Science, 67, 100660. <https://doi.org/10.1016/j.nutos.2026.100660>

## Citation

```r
citation("HawaSpatial")
```

Suggested software citation:

Muse, A. H. (2026). *HawaSpatial: Holistic and Areal Weighted Analysis for Global Development* (Version 0.1.10) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.18290101

## License

GPL-3 or later.
