README.Rmd

---
output: github_document
always_allow_html: true
editor_options: 
  markdown: 
    wrap: 72
  chunk_output_type: console
bibliography: references.bib
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  message = FALSE,
  warning = FALSE,
  fig.retina = 2,
  fig.align = 'center'
)
```

# ugabore

<!-- badges: start -->

[![License: CC BY
4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightblue.svg)](https://creativecommons.org/licenses/by/4.0/)
[![R-CMD-check](https://github.com/openwashdata/ugabore/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/openwashdata/ugabore/actions/workflows/R-CMD-check.yaml)
[![DOI](https://zenodo.org/badge/770378167.svg)](https://zenodo.org/doi/10.5281/zenodo.12188179)
<!-- badges: end -->

The goal of `ugabore` is to provide users with documentation on borehole repair data collected from two districts in central Uganda where a borehole operation and maintenance program is run. The dataset is associated with the following [project report](https://ds4owd-001.github.io/project-ljc3084/) completed by Joseph Lwere for the ["data science for openwashdata" course](https://ds4owd-001.github.io/website/) offered by [openwashdata.org](https://openwashdata.org/).

## Installation

You can install the development version of ugabore from
[GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("openwashdata/ugabore")
```

Alternatively, you can download the individual datasets as a CSV or XLSX
file from the table below.

```{r, echo=FALSE, message=FALSE, warning=FALSE}
library(dplyr)
library(knitr)
library(readr)
library(stringr)
library(gt)
library(kableExtra)
library(ggtext)

extdata_path <- "https://github.com/openwashdata/ugabore/raw/main/inst/extdata/"

read_csv("data-raw/dictionary.csv") |> 
  distinct(file_name) |> 
  dplyr::mutate(file_name = str_remove(file_name, ".rda")) |> 
  dplyr::rename(dataset = file_name) |> 
  mutate(
    CSV = paste0("[Download CSV](", extdata_path, dataset, ".csv)"),
    XLSX = paste0("[Download XLSX](", extdata_path, dataset, ".xlsx)")
  ) |> 
  knitr::kable()

```

## Project goal

Boreholes are the main technology used to access groundwater in Uganda, according to [@owor2022permeability], and they are also a source of drinking water for households in rural communities in Africa, including Uganda [@lapworth2020drinking]. Therefore, it is crucial to have good quality data to inform decision-making and planning. This project examines data collected from two districts in central Uganda where a borehole operation and maintenance program is run. As professional operation and maintenance is considered the future for borehole functionality in Uganda [@smith2023does], this project report offers more insights into research on this topic.

## Data

The dataset includes information about borehole repair records used by the borehole operation and maintenance company operating in central Uganda. The package provides access to one dataset.

```{r}
library(ugabore)
```

The `ugabore` data set has `r ncol(ugabore)` variables and `r nrow(ugabore)` observations. For an overview of the variable names, see the following table.

```{r echo=FALSE, message=FALSE, warning=FALSE}
readr::read_csv("data-raw/dictionary.csv") |>
  dplyr::filter(file_name == "ugabore.rda") |>
  dplyr::select(variable_name:description) |> 
  knitr::kable() |> 
  kableExtra::kable_styling("striped")
```


## Example: Water production capacity versus number of people collecting

Here is an example illustrating the relationship between the number of people collecting water from boreholes in a sub-county and the water production capacity of the corresponding boreholes. From the plot, we see that the sub-county of Kalagala has the highest water production capacity by far. However, it is not the sub-county that serves the most people, suggesting it may be the richest one. On another note, the sub-counties Bombo Town Council and Luwero Town Council have the most people collecting water from their boreholes but do not have high water production capacity, indicating a need for improvement.

```{r, warning=FALSE}
library(ugabore)
library(ggplot2)
library(dplyr)

# Define custom colors for plotting
custom_colors <- c(
  "Bamunanika" = "dodgerblue2", "Bombo Tc" = "#E31A1C",
  "Busukuma" = "green4",
  "Butuntumula" = "#6A3D9A",
  "Gombe" = "#FF7F00", 
  "Kajjansi Town Council" = "black", "Kakiri" = "gold1",
  "Kakiri Town Council" = "skyblue2", "Kalagala" = "#FB9A99",
  "Kamira" = "palegreen2",
  "Kasangati Town Council" = "#CAB2D6", 
  "Kasangombe" = "#FDBF6F", 
  "Katikamu" = "gray70", "Kikyusa" = "khaki2",
  "Kira" = "maroon", "Luwero" = "orchid1", "Luwero Tc" = "deeppink1", 
  "Makulubita" = "blue1", "Namayumba Town Council" = "steelblue4",
  "Wobulenzi Tc" = "darkturquoise", "Zirobwe" = "green1", 
  "NA" = "yellow4")

# Summarize data by sub_county
summary_data <- ugabore |> 
  group_by(sub_county) |> 
  summarise(mean_well_yield = mean(well_yield, na.rm = TRUE),
            mean_population_served = mean(population_served, na.rm = TRUE))

# Plot summarized data
ggplot(summary_data, aes(x = mean_well_yield, y = mean_population_served, 
                         color = sub_county)) +
  geom_point(size = 3, alpha = 0.7) +
  labs(title = "Water collection versus production by sub-county",
       x = "\naverage water production capacity in m3/h",
       y = "average number of people\n",
       color = "sub-county") +
  scale_color_manual(values = custom_colors) +
  theme_minimal() 
```

## License

Data are available as
[CC-BY](https://github.com/openwashdata/ugabore/blob/main/LICENSE.md).

## Citation

Please cite this package using:

```{r}
citation("ugabore")
```