Function Reference — MixedDiversityAnalysis

The MixedDiversityAnalysis package provides five main functions for analysing diversity among genotypes using quantitative, qualitative, binary, and ordinal traits. Together, these functions support mixed-trait dissimilarity calculation, hierarchical clustering, Principal Coordinates Analysis (PCoA), trait separation assessment, and visualization.

1. mixed_distance()

Purpose

The mixed_distance() function calculates pairwise dissimilarities among genotypes using a combination of quantitative, qualitative, binary, and ordinal traits.

It uses a custom mixed-trait dissimilarity method and does not implement Gower’s distance.

Syntax

mixed_distance(data, types)

Arguments

• data: A data frame containing genotypes as rows and traits as columns.
• types: A character vector specifying the type of each trait. Supported values are "quantitative", "qualitative", "binary", and "ordinal".

The order of types must correspond to the order of the columns in data.

Method

• Quantitative traits: Absolute differences between two observations are divided by the observed range of the trait.
• Qualitative traits: A dissimilarity of 0 is assigned when categories match and 1 when they differ.
• Binary traits: Matching values receive 0 and differing values receive 1.
• Ordinal traits: Differences between ordered ranks are scaled by the number of intervals between the minimum and maximum ranks.

The dissimilarity between two genotypes is calculated as the mean of the available trait-specific dissimilarities. Missing trait comparisons are excluded from that pair’s mean. If no traits can be compared for a pair, its dissimilarity is returned as NA.

Return value

The function returns an object of class mixed_distance, containing:

• dissimilarity: The pairwise dissimilarity matrix.
• data: The input trait data.
• types: The specified trait types.
• method: A description of the dissimilarity method.

Example

dist_result <- mixed_distance(
  data = my_data,
  types = trait_types
)

Interpretation

Smaller dissimilarity values indicate more similar genotypes, whereas larger values indicate greater differences in their trait profiles. Values are generally scaled between 0 and 1 under the defined trait-specific calculations.

2. mixed_cluster()

Purpose

The mixed_cluster() function performs hierarchical clustering using a dissimilarity object generated by mixed_distance(). It supports different linkage methods and can select the number of clusters using average silhouette width.

Syntax

mixed_cluster(
  distance_object,
  k = "optimal",
  method = "average",
  k_range = NULL,
  min_cluster_size = 1
)

Arguments

• distance_object: An object returned by mixed_distance().
• k: The desired number of clusters or "optimal" to select the number based on average silhouette width.
• method: The hierarchical linkage method. Supported options are "average", "complete", "single", and "mcquitty".
• k_range: An optional vector of candidate cluster numbers to evaluate when k = "optimal".
• min_cluster_size: The minimum permitted size for a cluster when evaluating candidate solutions.

Method

The function performs hierarchical clustering using the selected linkage method.

When k = "optimal", candidate cluster solutions are evaluated using average silhouette width. Solutions containing clusters smaller than min_cluster_size are excluded. If multiple solutions have the same best score, the smaller number of clusters is preferred.

When a fixed integer is supplied for k, it must be between 2 and the number of observations minus 1.

Return value

The function returns an object of class mixed_cluster, containing:

• tree: The hierarchical clustering tree.
• clusters: The assigned cluster membership for each genotype.
• sizes: The size of each cluster.
• k: The selected number of clusters.
• method: The linkage method used.
• silhouette: Silhouette information for the selected solution.
• silhouette_mean: The mean silhouette width.
• comparison: Results for candidate cluster solutions, when applicable.
• min_cluster_size: The minimum cluster size setting.

Example

cluster_result <- mixed_cluster(
  distance_object = dist_result,
  k = "optimal",
  method = "average",
  k_range = 2:10,
  min_cluster_size = 5
)

Interpretation

Cluster membership groups genotypes according to their mixed-trait dissimilarities. Cluster sizes and silhouette width can help evaluate the resulting groups.

A higher average silhouette width generally indicates better separation and cohesion. However, the selected solution should also be assessed for biological relevance and whether small clusters are meaningful.

3. mixed_pcoa()

Purpose

The mixed_pcoa() function performs Principal Coordinates Analysis (PCoA) using the mixed-trait dissimilarity matrix. It provides a low-dimensional representation of relationships among genotypes.

Syntax

mixed_pcoa(distance_object, dimensions = 2)

Arguments

• distance_object: An object returned by mixed_distance().
• dimensions: The number of coordinate dimensions to calculate. The default is 2.

Method

The function uses stats::cmdscale() to perform PCoA, requesting eigenvalues and an additive correction using the Cailliez method.

This correction helps accommodate non-Euclidean dissimilarity matrices. It does not change the original dissimilarity matrix stored in the mixed_distance object.

Return value

The function returns an object of class mixed_pcoa, containing:

• coordinates: The coordinates of genotypes in the selected dimensions.
• eigenvalues: The eigenvalues from the PCoA.
• percent_explained: The percentage values calculated by the function for the reported dimensions.
• dimensions: The number of coordinate dimensions.
• correction: Information about the additive correction.

Example

pcoa_result <- mixed_pcoa(
  distance_object = dist_result,
  dimensions = 2
)

Interpretation

Genotypes plotted close together have more similar mixed-trait profiles in the ordination space, while those farther apart are generally more dissimilar.

The first two coordinates can be used to visualize broad diversity patterns. The reported percentages should be considered when interpreting the axes.

4. mixed_diversity()

Purpose

The mixed_diversity() function evaluates how strongly individual traits separate the clusters obtained from hierarchical clustering. It provides a descriptive ranking of traits according to their separation scores.

Syntax

mixed_diversity(data, types, clusters)

Arguments

• data: The original data frame of genotype traits.
• types: A character vector identifying the type of each trait.
• clusters: A vector assigning each genotype to a cluster, typically obtained from cluster_result$clusters.

The rows of data and the entries of clusters must correspond to the same genotypes in the same order.

Method

The function calculates trait-specific separation scores according to trait type:

• Quantitative traits: The ratio of between-cluster sum of squares to total sum of squares.
• Ordinal traits: The same between-cluster to total sum-of-squares ratio, applied to the ordinal trait’s representation.
• Qualitative traits: Squared Cramér’s V.
• Binary traits: Squared Cramér’s V.

The results are sorted in descending order of separation score.

Return value

The function returns a data frame with class "mixed_trait", containing:

• trait: The trait name.
• type: The trait type.
• separation: The calculated separation score.

The "mixed_trait" class is the current return class used by the package; it does not mean the function is named mixed_trait().

Example

trait_result <- mixed_diversity(
  data = my_data,
  types = trait_types,
  clusters = cluster_result$clusters
)

print(trait_result)

Interpretation

Traits with higher separation scores show stronger descriptive association with the identified cluster structure, according to the metric used for their type.

These scores do not establish causality, statistical significance, or independent predictive importance. They should be interpreted alongside biological knowledge and, where appropriate, further statistical analyses.

5. mixed_visualize()

Purpose

The mixed_visualize() function generates graphical summaries of clustering, silhouette quality, PCoA ordination, and trait separation results.

Syntax

mixed_visualize(
  object,
  type = c("dendrogram", "silhouette", "pcoa", "trait"),
  clusters = NULL,
  labels = NULL,
  main = NULL,
  ellipse = FALSE,
  ...
)

Arguments

• object: An appropriate result object, depending on the requested visualization.
• type: The visualization type: "dendrogram", "silhouette", "pcoa", or "trait".
• clusters: Optional cluster assignments, mainly used to distinguish groups in a PCoA plot.
• labels: Optional labels for the genotypes. If omitted, row names or sequential labels are used, depending on the plot.
• main: An optional title for the plot.
• ellipse: If TRUE, attempts to add 95% covariance ellipses to a PCoA plot when cluster assignments are supplied.
• ...: Additional graphical arguments accepted by the relevant plotting branch.

Supported visualizations

Dendrogram

Displays the hierarchical relationships among genotypes or clusters. The required object is a mixed_cluster result.

mixed_visualize(
  cluster_result,
  type = "dendrogram"
)

Silhouette plot

Displays the silhouette widths of individual genotypes, helping assess cluster cohesion and separation. The required object is a mixed_cluster result.

mixed_visualize(
  cluster_result,
  type = "silhouette"
)

PCoA plot

Displays genotypes using their PCoA coordinates. The required object is a mixed_pcoa result. Cluster assignments can be supplied to distinguish groups.

mixed_visualize(
  pcoa_result,
  type = "pcoa",
  clusters = cluster_result$clusters,
  labels = rownames(my_data),
  ellipse = TRUE
)

Ellipses may be omitted when a cluster has too few distinct coordinates or when its coordinate covariance is degenerate. They are visual summaries and should not automatically be interpreted as formal confidence regions for cluster membership.

Trait separation plot

Displays the trait separation scores calculated by mixed_diversity(). The required object is the result returned by that function, which has class "mixed_trait".

mixed_visualize(
  trait_result,
  type = "trait"
)

Interpretation

The visualization options provide complementary views of the analysis:

• Dendrograms display hierarchical relationships.
• Silhouette plots assess clustering quality.
• PCoA plots show patterns of genotype similarity and separation.
• Trait plots identify traits that are descriptively associated with cluster differences.

Plots with many genotypes may become crowded. Shorter labels or a subset of labels can improve readability.

Recommended complete workflow

The five functions are designed to be used together:

# 1. Calculate mixed-trait dissimilarities
dist_result <- mixed_distance(
  data = my_data,
  types = trait_types
)

# 2. Perform hierarchical clustering
cluster_result <- mixed_cluster(
  distance_object = dist_result,
  k = "optimal",
  method = "average",
  k_range = 2:10,
  min_cluster_size = 5
)

# 3. Perform PCoA
pcoa_result <- mixed_pcoa(
  distance_object = dist_result,
  dimensions = 2
)

# 4. Assess trait separation
trait_result <- mixed_diversity(
  data = my_data,
  types = trait_types,
  clusters = cluster_result$clusters
)

# 5. Visualize the results
mixed_visualize(
  cluster_result,
  type = "dendrogram"
)

mixed_visualize(
  cluster_result,
  type = "silhouette"
)

mixed_visualize(
  pcoa_result,
  type = "pcoa",
  clusters = cluster_result$clusters
)

mixed_visualize(
  trait_result,
  type = "trait"
)

Important considerations

Before running the workflow:

• Ensure my_data contains the trait columns to be analysed, with genotypes in rows.
• Ensure trait_types correctly matches the columns of my_data.
• Represent ordinal traits as ordered factors with the intended level order.
• Check missing values and confirm that the dissimilarity matrix is suitable for clustering and PCoA. In particular, pairs with no comparable traits can produce NA dissimilarities, which may prevent downstream analyses from running.
• Choose k_range and min_cluster_size according to the size and biological context of the dataset. The example values are illustrative rather than universal recommendations.

Summary

MixedDiversityAnalysis integrates mixed-trait dissimilarity calculation, hierarchical clustering, PCoA, trait separation assessment, and visualization in one workflow. Together, these functions support the characterization of genetic diversity and the exploration of relationships among genotypes containing different types of traits.