Struct GraphModularity 

pub struct GraphModularity {
    pub k: usize,
}

Modularity of the category assignment on the k-NN graph of projected positions on S².

Modularity measures how well a partition (here: categories) aligns with the community structure of a graph. Formally for a graph with m edges, each node i with degree kᵢ, and community assignment cᵢ:

Q = Σ_c [ (L_c / m) − (D_c / 2m)² ]

where L_c is the number of edges inside community c and D_c is the total degree of its members. Raw Q lies in [-0.5, 1.0]. We clamp to [0, 1] since negative modularity (anti-structured partition) is strictly worse than random assignment and shouldn’t be rewarded differentially by the tuner.

This metric is connectivity-native — it evaluates “are same-category points close in the neighbor graph” rather than “are same-category points close in raw angular distance”. That makes it an honest objective for connectivity-preserving projections like LaplacianEigenmapProjection, which otherwise get discounted by variance-centric metrics (ClusterSilhouette) that reward PCA’s spread.

Edge construction is exact (all-pairs) below [MODULARITY_ANN_THRESHOLD] items and ANN-backed above it, keeping the metric usable inside tuner loops on 100k–500k corpora.

Fields

k: usize

Number of nearest neighbors per node in the k-NN graph.

Larger k smooths local structure and blurs category boundaries; smaller k is more sensitive to noise but resolves tighter communities. Default 15.

Implementations

impl GraphModularity

pub fn new(k: usize) -> Self

Trait Implementations

impl Default for GraphModularity

fn default() -> Self

Returns the “default value” for a type.

impl QualityMetric for GraphModularity

fn name(&self) -> &str

Short identifier for logs and tuner reports.

fn score(&self, pipeline: &SphereQLPipeline) -> f64

Evaluate the pipeline. Must return a value in [0, 1].

fn score_with_components( &self, pipeline: &SphereQLPipeline, ) -> (f64, Vec<(String, f64, f64)>)

Evaluate the pipeline and report any per-component breakdown in the same pass. Returns (score, components) where each component is (name, weight, component_score).