Merge pull request #13 from openwashdata/dev

Complete package review and add image gallery

Author: larnsce

.Rbuildignore

@@ -3,3 +3,10 @@
 ^data-raw$
 ^LICENSE\.md$
 ^README\.Rmd$
+^CITATION\.cff$
+^CLAUDE\.md$
+^_pkgdown\.yml$
+^docs$
+^\.github$
+^\.claude$
+^vignettes/articles$

DESCRIPTION

@@ -19,6 +19,15 @@ Imports:
     dplyr,
     readxl,
     openxlsx
+Suggests:
+    gt,
+    gtExtras,
+    ggplot2,
+    tidyverse,
+    knitr,
+    rmarkdown,
+    scales
+VignetteBuilder: knitr
 Date: 2025-06-02
 URL: https://github.com/openwashdata/artesianwells
 BugReports: https://github.com/openwashdata/artesianwells/issues

NAMESPACE

@@ -1,2 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+importFrom(dplyr,"%>%")
+importFrom(openxlsx,write.xlsx)
+importFrom(readr,read_csv)
+importFrom(readxl,read_excel)

R/artesianwells.R

@@ -47,4 +47,9 @@
 #' 
 #' # Summary of districts
 #' table(artesianwells$district)
+#' 
+#' @importFrom dplyr %>%
+#' @importFrom readr read_csv
+#' @importFrom readxl read_excel
+#' @importFrom openxlsx write.xlsx
 "artesianwells"

README.Rmd

@@ -59,6 +59,41 @@ This dataset is complemented by images captured at each site, accessible
 via permanent URLs, which provide photographic evidence of physical and
 infrastructural conditions.
 
+## At a Glance
+
+```{r district-summary, echo=FALSE, message=FALSE}
+library(artesianwells)
+library(dplyr)
+library(gt)
+artesianwells |>
+  group_by(district) |>
+  summarise(
+    well_count = n(),
+    avg_fill_time = round(mean(seconds_to_fill_20L, na.rm = TRUE), 1),
+    wells_with_images = sum(!is.na(well_images)),
+    .groups = "drop"
+  ) |>
+  arrange(desc(well_count)) |>
+  gt::gt() |>
+  gt::cols_label(
+    district = "District",
+    well_count = "Total Wells",
+    avg_fill_time = "Avg. Fill Time (s)",
+    wells_with_images = "Wells with Images"
+  ) |>
+  gt::tab_header(
+    title = "Artesian Wells by District",
+    subtitle = "Summary of 44 documented well sites"
+  ) |>
+  gt::fmt_number(
+    columns = avg_fill_time,
+    decimals = 1
+  ) |>
+  gt::as_raw_html()
+```
+
+📸 **[View the Image Gallery](https://openwashdata.github.io/artesianwells/articles/image-gallery.html)** - Explore photographs from all 43 documented well sites with interactive tables and visualizations.
+
 **Potential Use Cases**
 
 Water Resource Planning and Management Government bodies and NGOs can
@@ -158,6 +193,19 @@ readr::read_csv("data-raw/dictionary.csv") |>
   kableExtra::scroll_box(height = "200px")
 ```
 
+## Use Cases
+
+### Visual Documentation and Analysis
+
+The package includes a comprehensive [**Image Gallery**](https://openwashdata.github.io/artesianwells/articles/image-gallery.html) vignette that showcases photographs from 43 artesian well sites. This visual documentation helps:
+
+- **Field verification**: Compare physical infrastructure with reported data
+- **Condition assessment**: Evaluate well structures and surrounding environments
+- **Training materials**: Use real-world examples for capacity building
+- **Stakeholder communication**: Present tangible evidence to decision-makers
+
+The gallery organizes wells by district and displays key metrics alongside images, making it easy to identify patterns and prioritize interventions.
+
 ## Example
 
 ```{r}

README.md

@@ -4,6 +4,15 @@ template:
   includes:
     in_header: |
       <script defer data-domain="openwashdata.github.io" src="https://plausible.io/js/script.js"></script>
+      
+navbar:
+  structure:
+    left:  [intro, reference, articles]
+    right: [search, github]
+  components:
+    articles:
+      text: Gallery
+      href: articles/image-gallery.html
 
 home:
   links:
@@ -31,3 +40,9 @@ reference:
   desc: "Access the artesianwells dataset"
   contents:
   - artesianwells
+
+articles:
+- title: "Gallery"
+  navbar: ~
+  contents:
+  - articles/image-gallery