Hierarchical Cluster Analysis and Phenotypic Diversity Engine — analyze

The analyze_clustering function executes an agglomerative hierarchical clustering routine over multi-trait breeding datasets. It automatically computes cluster assignments, genotype groupings, trait cluster means, intra-cluster average distances, and inter-cluster centroid distances.

Usage

analyze_clustering(
  data,
  traits,
  k = 4,
  linkage_method = "ward.D2",
  reporting_level = 1
)

Arguments

data: A data.frame containing phenotypic records with a Genotype column or purely numeric traits.
traits: A character vector specifying the quantitative traits to be integrated into the cluster matrix.
k: An integer specifying the target number of clusters to partition the tree. Defaults to 4.
linkage_method: A character string specifying the target agglomerative clustering algorithm (e.g., "ward.D2", "complete", "average"). Defaults to "ward.D2".
reporting_level: An integer flag defining console output verbosity: 0 for silent execution and 1 for detailed summary output to the console. Defaults to 1.

Value

Invisibly returns a named list of class "list" containing 9 detailed computational components:

dist_matrix: A spatial dist object representing calculated multidimensional Euclidean distances between genotypes based on standardized phenotypic scores.
hc_object: The raw hierarchical clustering output object of class hclust.
cophenetic_corr: A numeric value indicating the cophenetic correlation coefficient, validating tree fit accuracy.
cluster_assignment: A data.frame mapping each genotype/line identifier to its designated cluster label.
cluster_summary: A named list categorizing genotypes into vector groups corresponding to their assigned clusters.
cluster_means: A data.frame summarizing original trait mean values across each cluster group.
intra_cluster_dist: A named numeric vector of average within-cluster Euclidean spatial distances for each cluster.
inter_cluster_dist: A symmetric matrix representing Euclidean distances between cluster centroids in standardized space.
genotype_means: A data.frame of line-wise aggregated trait averages used as input for spatial scaling.

If reporting_level >= 1, comprehensive cluster summary tables and distance matrices are printed to the console prior to returning the list.

Examples

# Load benchmark breeding dataset
data(gv_data, package = "AgriDataTools")

# Specify trait columns matching gv_data structure
my_traits <- c("PH", "SL", "PL", "NOT", "NOSS", "TGW", "GYPM")

# Run cluster engine (Modify k as needed, e.g., 3, 4, 5, or 6)
cluster_results <- analyze_clustering(
  data = gv_data,
  traits = my_traits,
  k = 4,
  linkage_method = "ward.D2",
  reporting_level = 1
)
#> 
#> ===========================================================================
#>  HIERARCHICAL CLUSTER ANALYSIS SUMMARY
#> ===========================================================================
#>  Linkage Algorithm            : ward.D2
#>  Total Genotypes Evaluated    : 40
#>  Number of Clusters (k)       : 4
#>  Cophenetic Correlation Fit   : 0.6204
#> ---------------------------------------------------------------------------
#> 
#> --- CLUSTER MEMBERSHIP AND COUNT ---
#> Cluster_1    (n = 12) : G1, G14, G15, G19, G2, G20, G22, G25, G27, G29, G31, G38
#> Cluster_2    (n = 19) : G10, G12, G17, G18, G21, G23, G24, G26, G28, G30, G33, G34, G35, G36, G37, G4, G40, G6, G8
#> Cluster_3    (n =  5) : G11, G16, G3, G7, G9
#> Cluster_4    (n =  4) : G13, G32, G39, G5
#> 
#> --- INTRA-CLUSTER DISTANCES (Within Cluster Average) ---
#> Cluster_1    : 2.7456
#> Cluster_2    : 2.6887
#> Cluster_3    : 3.0401
#> Cluster_4    : 3.3706
#> 
#> --- INTER-CLUSTER DISTANCE MATRIX (Between Centroids) ---
#>           Cluster_1 Cluster_2 Cluster_3 Cluster_4
#> Cluster_1    0.0000    2.2830    3.1488    3.8847
#> Cluster_2    2.2830    0.0000    3.5783    3.2097
#> Cluster_3    3.1488    3.5783    0.0000    3.6038
#> Cluster_4    3.8847    3.2097    3.6038    0.0000
#> 
#> --- CLUSTER MEANS MATRIX (Original Trait Values) ---
#>     Cluster        PH       SL       PL      NOT     NOSS      TGW      GYPM
#> 1 Cluster_1  94.49722 10.48611 26.90278  8.25000 17.67639 36.75472 102.44444
#> 2 Cluster_2  90.42982 11.33333 25.43860 12.38596 18.11421 34.61456  92.49123
#> 3 Cluster_3 100.20000 11.60000 30.93333 12.26667 19.97067 37.66467 134.60000
#> 4 Cluster_4  92.33333 11.54167 26.06667 12.33333 27.30667 32.75667 134.91667
#> ===========================================================================
#>