about summary refs log tree commit diff
path: root/src/routes/correlation_matrix.rs
diff options
context:
space:
mode:
Diffstat (limited to 'src/routes/correlation_matrix.rs')
-rw-r--r--src/routes/correlation_matrix.rs29
1 files changed, 29 insertions, 0 deletions
diff --git a/src/routes/correlation_matrix.rs b/src/routes/correlation_matrix.rs
index 2e6c883..9a433b6 100644
--- a/src/routes/correlation_matrix.rs
+++ b/src/routes/correlation_matrix.rs
@@ -65,6 +65,11 @@ pub struct MatrixRequest {
     /// Fewest paired observations a cell may have. Defaults to 6.
     #[serde(default)]
     pub min_overlap: Option<usize>,
+    /// Also return a clustered ordering (and its tree) for a heatmap: average
+    /// linkage on `1 - r`. The matrix is symmetric, so one order serves both
+    /// axes.
+    #[serde(default)]
+    pub cluster: Option<bool>,
     /// Also return a PCA of the matrix (eigenvalues, explained variance,
     /// loadings over the traits whose every cell is valid). Off by default:
     /// the r matrix is worth reading on its own first.
@@ -201,6 +206,16 @@ pub async fn correlation_matrix(
     if let Some(pca) = &pca {
         body["pca"] = serde_json::to_value(pca).unwrap_or(serde_json::Value::Null);
     }
+    let clustering = if wanted.cluster.unwrap_or(false) {
+        // Refused rather than guessed when a cell is missing: an unknown
+        // distance treated as 1 would invent a structure and a plot of it.
+        crate::heatmap::cluster(&matrix.r, crate::pca::MAX_PCA_TRAITS)
+    } else {
+        None
+    };
+    if let Some(clustering) = &clustering {
+        body["heatmap"] = serde_json::to_value(clustering).unwrap_or(serde_json::Value::Null);
+    }
     Ok(Json(
         ctx.envelope(body)
             .with_note(&format!(
@@ -227,6 +242,19 @@ pub async fn correlation_matrix(
                 "Cells with fewer than min_overlap observations are null in r and p, and their \
                  n still says how many there were.",
             )
+            .with_note(&match (&clustering, wanted.cluster.unwrap_or(false)) {
+                (Some(clustering), _) => format!(
+                    "Clustering: average linkage on 1 - r, {} merge(s), largest distance {:.3}; \
+                     `heatmap.order` is the drawing order for both axes.",
+                    clustering.merges.len(),
+                    clustering.max_height
+                ),
+                (None, true) => "No clustering: the matrix has a gap (a null cell), so some \
+                                 distances are unknown -- drop those traits and ask again."
+                    .to_string(),
+                (None, false) => "No clustering: pass \"cluster\": true for a heatmap order."
+                    .to_string(),
+            })
             .with_note(&match &pca {
                 Some(pca) if pca.components.is_empty() => format!(
                     "PCA: not computed -- {} trait(s) were usable and it needs at least 2, and \
@@ -448,6 +476,7 @@ mod tests {
             method: None,
             corr_samples_group: None,
             min_overlap: None,
+            cluster: None,
             pca: None,
         };
         // build() would go to the database; the arithmetic is what is tested