91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# ruv-neural-embed
|
|
|
|
Graph embedding generation for brain connectivity states using RuVector format.
|
|
|
|
## Overview
|
|
|
|
`ruv-neural-embed` converts brain connectivity graphs into fixed-dimensional
|
|
vector representations suitable for downstream classification, clustering, and
|
|
temporal analysis. It provides multiple embedding methods and supports export
|
|
to the RuVector `.rvf` binary format for interoperability with the broader
|
|
RuVector ecosystem.
|
|
|
|
## Features
|
|
|
|
- **Spectral embedding** (`spectral_embed`): Laplacian eigenvector-based positional
|
|
encoding from the graph's normalized Laplacian
|
|
- **Topology embedding** (`topology_embed`): Hand-crafted topological feature vectors
|
|
derived from graph-theoretic metrics
|
|
- **Node2Vec** (`node2vec`): Random-walk co-occurrence embeddings using configurable
|
|
walk length, return parameter (p), and in-out parameter (q)
|
|
- **Combined embedding** (`combined`): Weighted concatenation of multiple embedding
|
|
methods into a single vector
|
|
- **Temporal embedding** (`temporal`): Sliding-window context-enriched embeddings
|
|
that capture graph dynamics over time
|
|
- **Distance metrics** (`distance`): Embedding distance and similarity computations
|
|
- **RVF export** (`rvf_export`): Serialization of embeddings and trajectories to the
|
|
RuVector `.rvf` binary format
|
|
- **Helper utilities**: `default_metadata` for quick `EmbeddingMetadata` construction
|
|
|
|
## Usage
|
|
|
|
```rust
|
|
use ruv_neural_embed::{
|
|
NeuralEmbedding, EmbeddingMetadata, EmbeddingTrajectory,
|
|
default_metadata,
|
|
};
|
|
use ruv_neural_core::brain::Atlas;
|
|
|
|
// Create an embedding with metadata
|
|
let meta = default_metadata("spectral", Atlas::Schaefer100);
|
|
let emb = NeuralEmbedding::new(vec![0.1, 0.5, -0.3, 0.8], 1000.0, meta).unwrap();
|
|
assert_eq!(emb.dimension, 4);
|
|
|
|
// Compute similarity between embeddings
|
|
let other = NeuralEmbedding::new(
|
|
vec![0.2, 0.4, -0.2, 0.9],
|
|
1001.0,
|
|
default_metadata("spectral", Atlas::Schaefer100),
|
|
).unwrap();
|
|
let similarity = emb.cosine_similarity(&other).unwrap();
|
|
let distance = emb.euclidean_distance(&other).unwrap();
|
|
|
|
// Build a trajectory from a sequence of embeddings
|
|
let trajectory = EmbeddingTrajectory {
|
|
embeddings: vec![emb, other],
|
|
timestamps: vec![1000.0, 1001.0],
|
|
};
|
|
assert_eq!(trajectory.len(), 2);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
| Module | Key Types / Functions |
|
|
|------------------|-----------------------------------------------------|
|
|
| `spectral_embed` | Spectral positional encoding from graph Laplacian |
|
|
| `topology_embed` | Topological feature vector extraction |
|
|
| `node2vec` | Random-walk based node embeddings |
|
|
| `combined` | Weighted multi-method embedding concatenation |
|
|
| `temporal` | Sliding-window temporal context embeddings |
|
|
| `distance` | Distance and similarity computations |
|
|
| `rvf_export` | RVF binary format serialization |
|
|
|
|
## Feature Flags
|
|
|
|
| Feature | Default | Description |
|
|
|---------|---------|-------------------------------------|
|
|
| `std` | Yes | Standard library support |
|
|
| `wasm` | No | WASM-compatible implementations |
|
|
| `rvf` | No | RuVector RVF format export support |
|
|
|
|
## Integration
|
|
|
|
Depends on `ruv-neural-core` for `NeuralEmbedding`, `BrainGraph`, and
|
|
`EmbeddingGenerator` trait. Receives graphs from `ruv-neural-graph` or
|
|
`ruv-neural-mincut`. Produced embeddings are stored by `ruv-neural-memory`
|
|
and classified by `ruv-neural-decoder`.
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|