feat: add parameter importance via Spearman rank correlation

Compute per-parameter importance scores by measuring the absolute
Spearman rank correlation between each parameter's values and the
objective across completed trials. Scores are normalized to sum to 1.0
and returned sorted by descending importance.

src/importance.rs

@@ -0,0 +1,93 @@
+//! Parameter importance via Spearman rank correlation.
+
+/// Assign average ranks to a slice of `f64` values (handles ties).
+#[allow(clippy::cast_precision_loss, clippy::float_cmp)]
+pub(crate) fn rank(values: &[f64]) -> Vec<f64> {
+    let n = values.len();
+    let mut indexed: Vec<(usize, f64)> = values.iter().copied().enumerate().collect();
+    indexed.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(core::cmp::Ordering::Equal));
+
+    let mut ranks = vec![0.0; n];
+    let mut i = 0;
+    while i < n {
+        // Find the run of tied values.
+        let mut j = i + 1;
+        while j < n && indexed[j].1 == indexed[i].1 {
+            j += 1;
+        }
+        // Average rank for the tie group (1-based ranks).
+        let avg = (i + 1..=j).sum::<usize>() as f64 / (j - i) as f64;
+        for item in &indexed[i..j] {
+            ranks[item.0] = avg;
+        }
+        i = j;
+    }
+    ranks
+}
+
+/// Pearson correlation coefficient on two equal-length slices.
+#[allow(clippy::cast_precision_loss)]
+fn pearson(x: &[f64], y: &[f64]) -> f64 {
+    let n = x.len() as f64;
+    let mean_x = x.iter().sum::<f64>() / n;
+    let mean_y = y.iter().sum::<f64>() / n;
+
+    let mut cov = 0.0;
+    let mut var_x = 0.0;
+    let mut var_y = 0.0;
+    for (xi, yi) in x.iter().zip(y.iter()) {
+        let dx = xi - mean_x;
+        let dy = yi - mean_y;
+        cov += dx * dy;
+        var_x += dx * dx;
+        var_y += dy * dy;
+    }
+
+    let denom = (var_x * var_y).sqrt();
+    if denom == 0.0 { 0.0 } else { cov / denom }
+}
+
+/// Spearman rank correlation (Pearson on ranks).
+pub(crate) fn spearman(x: &[f64], y: &[f64]) -> f64 {
+    pearson(&rank(x), &rank(y))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rank_no_ties() {
+        let ranks = rank(&[30.0, 10.0, 20.0]);
+        assert_eq!(ranks, vec![3.0, 1.0, 2.0]);
+    }
+
+    #[test]
+    fn rank_with_ties() {
+        let ranks = rank(&[10.0, 20.0, 20.0, 30.0]);
+        assert_eq!(ranks, vec![1.0, 2.5, 2.5, 4.0]);
+    }
+
+    #[test]
+    fn perfect_positive_correlation() {
+        let x = vec![1.0, 2.0, 3.0, 4.0, 5.0];
+        let y = vec![2.0, 4.0, 6.0, 8.0, 10.0];
+        let r = spearman(&x, &y);
+        assert!((r - 1.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn perfect_negative_correlation() {
+        let x = vec![1.0, 2.0, 3.0, 4.0, 5.0];
+        let y = vec![10.0, 8.0, 6.0, 4.0, 2.0];
+        let r = spearman(&x, &y);
+        assert!((r + 1.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn zero_variance_returns_zero() {
+        let x = vec![5.0, 5.0, 5.0];
+        let y = vec![1.0, 2.0, 3.0];
+        assert!(spearman(&x, &y).abs() < f64::EPSILON);
+    }
+}

src/lib.rs

@@ -216,6 +216,7 @@ macro_rules! trace_debug {
 
 mod distribution;
 mod error;
+mod importance;
 mod kde;
 mod param;
 pub mod parameter;

src/study.rs

@@ -1812,6 +1812,110 @@ where
     }
 }
 
+impl<V> Study<V>
+where
+    V: PartialOrd + Clone + Into<f64>,
+{
+    /// Computes parameter importance scores using Spearman rank correlation.
+    ///
+    /// For each parameter, the absolute Spearman correlation between its values
+    /// and the objective values is computed across all completed trials. Scores
+    /// are normalized so they sum to 1.0 and sorted in descending order.
+    ///
+    /// Parameters that appear in fewer than 2 trials are omitted.
+    /// Returns an empty `Vec` if the study has fewer than 2 completed trials.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use optimizer::parameter::{FloatParam, Parameter};
+    /// use optimizer::{Direction, Study};
+    ///
+    /// let study: Study<f64> = Study::new(Direction::Minimize);
+    /// let x = FloatParam::new(0.0, 10.0).name("x");
+    ///
+    /// study
+    ///     .optimize(20, |trial| {
+    ///         let xv = x.suggest(trial)?;
+    ///         Ok::<_, optimizer::Error>(xv * xv)
+    ///     })
+    ///     .unwrap();
+    ///
+    /// let importance = study.param_importance();
+    /// assert_eq!(importance.len(), 1);
+    /// assert_eq!(importance[0].0, "x");
+    /// ```
+    #[must_use]
+    #[allow(clippy::cast_precision_loss)]
+    pub fn param_importance(&self) -> Vec<(String, f64)> {
+        use std::collections::BTreeSet;
+
+        use crate::importance::spearman;
+        use crate::param::ParamValue;
+        use crate::types::TrialState;
+
+        let trials = self.completed_trials.read();
+        let complete: Vec<_> = trials
+            .iter()
+            .filter(|t| t.state == TrialState::Complete)
+            .collect();
+
+        if complete.len() < 2 {
+            return Vec::new();
+        }
+
+        // Collect all parameter IDs across trials.
+        let all_param_ids: BTreeSet<_> = complete.iter().flat_map(|t| t.params.keys()).collect();
+
+        let mut scores: Vec<(String, f64)> = Vec::new();
+
+        for &param_id in &all_param_ids {
+            // Collect (param_value_f64, objective_f64) for trials that have this param.
+            let mut param_vals = Vec::new();
+            let mut obj_vals = Vec::new();
+
+            for trial in &complete {
+                if let Some(pv) = trial.params.get(param_id) {
+                    let f = match *pv {
+                        ParamValue::Float(v) => v,
+                        ParamValue::Int(v) => v as f64,
+                        ParamValue::Categorical(v) => v as f64,
+                    };
+                    param_vals.push(f);
+                    obj_vals.push(trial.value.clone().into());
+                }
+            }
+
+            if param_vals.len() < 2 {
+                continue;
+            }
+
+            let corr = spearman(&param_vals, &obj_vals).abs();
+
+            // Determine label: use param_labels if available, else "param_{id}".
+            let label = complete
+                .iter()
+                .find_map(|t| t.param_labels.get(param_id))
+                .map_or_else(|| param_id.to_string(), Clone::clone);
+
+            scores.push((label, corr));
+        }
+
+        // Normalize so scores sum to 1.0.
+        let sum: f64 = scores.iter().map(|(_, s)| *s).sum();
+        if sum > 0.0 {
+            for entry in &mut scores {
+                entry.1 /= sum;
+            }
+        }
+
+        // Sort descending by score.
+        scores.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(core::cmp::Ordering::Equal));
+
+        scores
+    }
+}
+
 impl<V> IntoIterator for &Study<V>
 where
     V: PartialOrd + Clone,