Skip to contents

Plot Clustering of Countries Based on Seasonal Dynamics

Source: R/plot_seasonal_clustering.R
plot_seasonal_clustering.Rd

This function visualizes the clustering of countries based on seasonal precipitation or cholera cases. It generates a map showing the clusters, and a multi-panel plot showing the fitted Fourier series values for each cluster.

Usage

plot_seasonal_clustering(
  PATHS,
  use_cases = FALSE,
  set_inferred_to_na = TRUE,
  clustering_method = c("ward.D2", "kmeans", "dbscan", "knn"),
  k = 4
)

Arguments

PATHS

A list containing paths where processed climate, cholera, and fitted data are stored. Typically generated by the get_paths() function and should include:

  • MODEL_INPUT: Path to the pred_seasonal_dynamics_day.csv and data_seasonal_precipitation.csv files written by est_seasonal_dynamics.

  • DOCS_TABLES: Path to the legacy weekly table pred_seasonal_dynamics.csv, read only when the daily fits are absent.

  • DATA_SHAPEFILES: Path to the directory containing shapefiles for African countries.

  • DOCS_FIGURES: Path to save the output plot.

use_cases

A logical value. If TRUE, clustering is based on Fourier series fitted to cholera cases. If FALSE, clustering is based on precipitation.

set_inferred_to_na

A logical value. If TRUE, inferred countries are set to NA in the clustering. Applies only with use_cases = TRUE (default TRUE); with precipitation it is ignored and treated as FALSE.

clustering_method

A character string specifying the clustering method. One of "ward.D2" (hierarchical, the default), "kmeans", "dbscan", or "knn".

k

An integer specifying the number of clusters for k-means and hierarchical clustering. Default is 4.

Value

Invisibly, a list with the combined plot (plot), the cluster of each clustered country named by ISO code (clusters) and the seasonal-fits file read (source). The plot is also saved as a PNG file in PATHS$DOCS_FIGURES.

Details

The input is the daily Fourier fits that est_seasonal_dynamics writes to MODEL_INPUT/pred_seasonal_dynamics_day.csv, averaged to weeks (week w is the mean of days 7(w - 1) + 1 to 7w); countries are clustered on, and panel B draws, those weekly means. est_seasonal_dynamics() clusters the daily fits themselves; for these two-harmonic curves a 7-day mean scales each harmonic by a near-constant factor (0.9994 and 0.9976), so clustering_method = "ward.D2" with the estimator's k (4 in the standard workflow) maps the clusters it used for its neighbour inference. When the daily fits are absent, the weekly table that earlier versions wrote to DOCS_TABLES/pred_seasonal_dynamics.csv is used instead. The years in the panel title are the calendar years of the fit window, read from the data_seasonal_precipitation.csv written next to the daily fits; the legacy table does not record its window, so its title carries no years.