corticalfields 0.1.1__py3-none-any.whl

corticalfields/__init__.py

@@ -0,0 +1,75 @@
+"""
+CorticalFields — Geodesic-aware GP normative modeling on cortical surfaces.
+
+A library for computing information-theoretic surprise maps on the cortical
+manifold using spectral Matérn Gaussian Processes, Heat Kernel Signatures,
+and Laplace–Beltrami spectral analysis. Designed for structural MRI (T1w)
+data in clinical neuroimaging, with emphasis on epilepsy (MTLE-HS).
+
+Core pipeline:
+    1. Load FreeSurfer surfaces and morphometric overlays
+    2. Compute Laplace–Beltrami eigenpairs on the cortical mesh
+    3. Extract spectral shape descriptors (HKS, WKS, GPS)
+    4. Build spectral Matérn GP kernels on the manifold
+    5. Fit normative models on a reference cohort
+    6. Generate vertex-wise surprise / anomaly maps for patients
+
+Modules
+-------
+surface     : Surface I/O — FreeSurfer, GIfTI, mesh utilities
+spectral    : Laplace–Beltrami decomposition, HKS, WKS, GPS
+kernels     : Spectral Matérn kernels for GPyTorch
+normative   : GP-based normative modeling pipeline
+surprise    : Information-theoretic anomaly scoring
+features    : Morphometric feature extraction from FreeSurfer
+graphs      : Cortical similarity network construction
+viz         : Publication-quality surface visualization
+"""
+
+__version__ = "0.1.0"
+__author__ = "Velho Mago (rdneuro)"
+
+# ── Lazy imports ────────────────────────────────────────────────────────
+# Heavy dependencies (torch, gpytorch) are only loaded when the modules
+# that need them are first accessed. This keeps `import corticalfields`
+# fast and memory-light for submodule-level usage.
+
+
+def __getattr__(name: str):
+    """Lazy attribute loader — imports submodules on first access."""
+    _MAP = {
+        # surface.py (lightweight — numpy/nibabel only)
+        "CorticalSurface": ("corticalfields.surface", "CorticalSurface"),
+        "load_freesurfer_surface": ("corticalfields.surface", "load_freesurfer_surface"),
+        # spectral.py (lightweight — numpy/scipy only)
+        "LaplaceBeltrami": ("corticalfields.spectral", "LaplaceBeltrami"),
+        "heat_kernel_signature": ("corticalfields.spectral", "heat_kernel_signature"),
+        "wave_kernel_signature": ("corticalfields.spectral", "wave_kernel_signature"),
+        "global_point_signature": ("corticalfields.spectral", "global_point_signature"),
+        # kernels.py (heavy — torch + gpytorch)
+        "SpectralMaternKernel": ("corticalfields.kernels", "SpectralMaternKernel"),
+        # normative.py (heavy — torch + gpytorch)
+        "CorticalNormativeModel": ("corticalfields.normative", "CorticalNormativeModel"),
+        # surprise.py (lightweight — numpy/scipy only)
+        "SurpriseMap": ("corticalfields.surprise", "SurpriseMap"),
+        "compute_surprise": ("corticalfields.surprise", "compute_surprise"),
+        # features.py (lightweight)
+        "MorphometricProfile": ("corticalfields.features", "MorphometricProfile"),
+    }
+    if name in _MAP:
+        module_path, attr = _MAP[name]
+        import importlib
+        mod = importlib.import_module(module_path)
+        return getattr(mod, attr)
+    raise AttributeError(f"module 'corticalfields' has no attribute {name!r}")
+
+
+__all__ = [
+    "CorticalSurface", "load_freesurfer_surface",
+    "LaplaceBeltrami", "heat_kernel_signature",
+    "wave_kernel_signature", "global_point_signature",
+    "SpectralMaternKernel",
+    "CorticalNormativeModel",
+    "SurpriseMap", "compute_surprise",
+    "MorphometricProfile",
+]

corticalfields/features.py

@@ -0,0 +1,258 @@
+"""
+Morphometric feature extraction for CorticalFields.
+
+Extracts and manages multi-feature morphometric profiles from FreeSurfer
+outputs. These profiles serve as the observation vectors for GP normative
+modeling: for each vertex, we have a vector of structural features
+(cortical thickness, curvature, sulcal depth, surface area, gyrification,
+etc.) that characterise local brain morphology.
+
+The module also handles feature normalisation, missing data, and the
+construction of population-level feature matrices for training.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Union
+
+import numpy as np
+
+from corticalfields.surface import CorticalSurface, load_freesurfer_surface
+
+logger = logging.getLogger(__name__)
+
+# Default features to extract (standard FreeSurfer outputs)
+DEFAULT_FEATURES = ["thickness", "curv", "sulc", "area", "volume"]
+
+
+@dataclass
+class MorphometricProfile:
+    """
+    Multi-feature morphometric profile for one hemisphere.
+
+    Stores per-vertex feature values for a set of subjects, enabling
+    population-level analyses.
+
+    Attributes
+    ----------
+    features : dict[str, np.ndarray]
+        Feature name → array of shape (N_vertices, N_subjects).
+    feature_names : list[str]
+        Ordered list of feature names.
+    subject_ids : list[str]
+        Subject identifiers corresponding to columns.
+    n_vertices : int
+        Number of mesh vertices.
+    hemi : str
+        Hemisphere (``'lh'`` or ``'rh'``).
+    """
+
+    features: Dict[str, np.ndarray] = field(default_factory=dict)
+    feature_names: List[str] = field(default_factory=list)
+    subject_ids: List[str] = field(default_factory=list)
+    n_vertices: int = 0
+    hemi: str = "lh"
+
+    @property
+    def n_subjects(self) -> int:
+        return len(self.subject_ids)
+
+    @property
+    def n_features(self) -> int:
+        return len(self.feature_names)
+
+    def get_feature_matrix(self, feature_name: str) -> np.ndarray:
+        """
+        Get the (N_vertices, N_subjects) matrix for one feature.
+        """
+        return self.features[feature_name]
+
+    def get_subject_profile(
+        self,
+        subject_id: str,
+    ) -> Dict[str, np.ndarray]:
+        """
+        Get all features for one subject.
+
+        Returns
+        -------
+        profile : dict[str, np.ndarray]
+            Feature name → (N_vertices,) array.
+        """
+        idx = self.subject_ids.index(subject_id)
+        return {
+            name: self.features[name][:, idx]
+            for name in self.feature_names
+        }
+
+    def get_vertex_feature_vector(
+        self,
+        vertex_idx: int,
+        subject_idx: int = 0,
+    ) -> np.ndarray:
+        """
+        Get the multi-feature vector at one vertex for one subject.
+
+        Returns
+        -------
+        vec : np.ndarray, shape (n_features,)
+        """
+        return np.array([
+            self.features[name][vertex_idx, subject_idx]
+            for name in self.feature_names
+        ])
+
+    def population_mean(self, feature_name: str) -> np.ndarray:
+        """Mean across subjects for one feature. Shape: (N_vertices,)."""
+        return np.nanmean(self.features[feature_name], axis=1)
+
+    def population_std(self, feature_name: str) -> np.ndarray:
+        """Std across subjects for one feature. Shape: (N_vertices,)."""
+        return np.nanstd(self.features[feature_name], axis=1)
+
+    def normalise(
+        self,
+        method: str = "z_score",
+        reference_mean: Optional[Dict[str, np.ndarray]] = None,
+        reference_std: Optional[Dict[str, np.ndarray]] = None,
+    ) -> "MorphometricProfile":
+        """
+        Normalise features vertex-wise.
+
+        Parameters
+        ----------
+        method : ``'z_score'`` or ``'robust'``
+            Normalisation method. ``'z_score'`` uses mean/std;
+            ``'robust'`` uses median/IQR.
+        reference_mean, reference_std : dict or None
+            External reference statistics (e.g. from a normative cohort).
+            If None, uses internal population statistics.
+
+        Returns
+        -------
+        MorphometricProfile
+            New profile with normalised features.
+        """
+        norm_features = {}
+
+        for name in self.feature_names:
+            data = self.features[name].copy()
+
+            if method == "z_score":
+                mu = (
+                    reference_mean[name]
+                    if reference_mean
+                    else np.nanmean(data, axis=1)
+                )
+                sigma = (
+                    reference_std[name]
+                    if reference_std
+                    else np.nanstd(data, axis=1)
+                )
+                sigma[sigma < 1e-8] = 1.0
+                norm_features[name] = (data - mu[:, None]) / sigma[:, None]
+
+            elif method == "robust":
+                med = np.nanmedian(data, axis=1)
+                q25 = np.nanpercentile(data, 25, axis=1)
+                q75 = np.nanpercentile(data, 75, axis=1)
+                iqr = q75 - q25
+                iqr[iqr < 1e-8] = 1.0
+                norm_features[name] = (data - med[:, None]) / iqr[:, None]
+
+        return MorphometricProfile(
+            features=norm_features,
+            feature_names=self.feature_names.copy(),
+            subject_ids=self.subject_ids.copy(),
+            n_vertices=self.n_vertices,
+            hemi=self.hemi,
+        )
+
+
+def extract_cohort_profiles(
+    subjects_dir: Union[str, Path],
+    subject_ids: List[str],
+    hemi: str = "lh",
+    surface: str = "pial",
+    features: Optional[List[str]] = None,
+) -> MorphometricProfile:
+    """
+    Extract morphometric profiles for an entire cohort.
+
+    Loads FreeSurfer surface and overlays for each subject and assembles
+    them into a population-level MorphometricProfile.
+
+    Parameters
+    ----------
+    subjects_dir : path-like
+        FreeSurfer SUBJECTS_DIR.
+    subject_ids : list[str]
+        Subject folder names.
+    hemi : ``'lh'`` or ``'rh'``
+    surface : str
+        Surface type (``'pial'``, ``'white'``, etc.).
+    features : list[str] or None
+        Feature names to extract (default: ``DEFAULT_FEATURES``).
+
+    Returns
+    -------
+    MorphometricProfile
+        Population-level feature matrices.
+
+    Notes
+    -----
+    All subjects must be in the same template space (e.g. fsaverage)
+    or registered to a common surface template, so that vertex indices
+    correspond across subjects.
+    """
+    if features is None:
+        features = DEFAULT_FEATURES.copy()
+
+    profile = MorphometricProfile(
+        feature_names=features,
+        subject_ids=list(subject_ids),
+        hemi=hemi,
+    )
+
+    # Load first subject to get dimensions
+    first_surf = load_freesurfer_surface(
+        subjects_dir, subject_ids[0], hemi=hemi, surface=surface,
+        overlays=features,
+    )
+    N = first_surf.n_vertices
+    S = len(subject_ids)
+    profile.n_vertices = N
+
+    # Initialise feature matrices
+    for name in features:
+        profile.features[name] = np.full((N, S), np.nan, dtype=np.float64)
+
+    # Fill in data
+    for s_idx, sid in enumerate(subject_ids):
+        try:
+            surf = load_freesurfer_surface(
+                subjects_dir, sid, hemi=hemi, surface=surface,
+                overlays=features,
+            )
+            for name in features:
+                if name in surf.overlays:
+                    data = surf.get_overlay(name)
+                    if data.shape[0] == N:
+                        profile.features[name][:, s_idx] = data
+                    else:
+                        logger.warning(
+                            "Subject %s: %s has %d vertices (expected %d), skipping.",
+                            sid, name, data.shape[0], N,
+                        )
+        except Exception as e:
+            logger.error("Failed to load subject %s: %s", sid, e)
+
+    logger.info(
+        "Extracted profiles: %d subjects, %d vertices, %d features.",
+        S, N, len(features),
+    )
+
+    return profile

corticalfields/graphs.py

@@ -0,0 +1,234 @@
+"""
+Cortical similarity network construction from morphometric features.
+
+This module builds brain graphs from structural MRI data alone (no fMRI
+or dMRI required). Two approaches are provided:
+
+    1. **Morphometric Similarity Networks (MSN)** — inter-regional
+       Pearson/Spearman correlation of morphometric feature profiles
+       (Seidlitz et al., Neuron 2018). Each ROI has a vector of
+       features (mean thickness, curvature, sulcal depth, etc.); the
+       correlation between ROI profiles becomes the edge weight.
+
+    2. **Spectral Similarity Networks** — inter-regional similarity
+       based on spectral shape descriptors (HKS, WKS, GPS). This is
+       novel: it captures geometric similarity between regions rather
+       than just morphometric covariation.
+
+Both approaches integrate with NetworkX for graph-theoretic analysis
+(centrality, modularity, efficiency, small-worldness).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def morphometric_similarity_network(
+    feature_matrix: np.ndarray,
+    labels: np.ndarray,
+    method: str = "pearson",
+    fisher_z: bool = True,
+) -> np.ndarray:
+    """
+    Construct a Morphometric Similarity Network (MSN).
+
+    For each pair of ROIs (i, j), compute the correlation between
+    their average morphometric feature profiles across vertices.
+
+    Parameters
+    ----------
+    feature_matrix : np.ndarray, shape (N_vertices, N_features)
+        Per-vertex feature values (columns: thickness, curv, sulc, …).
+    labels : np.ndarray, shape (N_vertices,)
+        Integer parcellation labels.
+    method : ``'pearson'`` or ``'spearman'``
+        Correlation method.
+    fisher_z : bool
+        Apply Fisher z-transform to correlation values.
+
+    Returns
+    -------
+    msn : np.ndarray, shape (R, R)
+        Symmetric correlation matrix where R is the number of ROIs.
+    """
+    from scipy.stats import pearsonr, spearmanr
+
+    # Get unique ROI labels (exclude label <= 0 as medial wall/unknown)
+    roi_labels = np.sort(np.unique(labels[labels > 0]))
+    R = len(roi_labels)
+
+    # Compute mean feature profile per ROI: shape (R, F)
+    roi_profiles = np.zeros((R, feature_matrix.shape[1]), dtype=np.float64)
+    for i, lab in enumerate(roi_labels):
+        mask = labels == lab
+        roi_profiles[i] = np.nanmean(feature_matrix[mask], axis=0)
+
+    # Correlation matrix
+    msn = np.zeros((R, R), dtype=np.float64)
+    for i in range(R):
+        for j in range(i + 1, R):
+            if method == "pearson":
+                r, _ = pearsonr(roi_profiles[i], roi_profiles[j])
+            elif method == "spearman":
+                r, _ = spearmanr(roi_profiles[i], roi_profiles[j])
+            else:
+                raise ValueError(f"Unknown method: {method}")
+
+            if fisher_z:
+                r = np.arctanh(np.clip(r, -0.9999, 0.9999))
+
+            msn[i, j] = r
+            msn[j, i] = r
+
+    return msn
+
+
+def spectral_similarity_network(
+    spectral_features: np.ndarray,
+    labels: np.ndarray,
+    metric: str = "cosine",
+) -> np.ndarray:
+    """
+    Construct a similarity network from spectral shape descriptors.
+
+    Each ROI's spectral profile is the mean HKS/WKS/GPS vector across
+    its vertices. Inter-regional similarity is computed via cosine
+    similarity, correlation, or Euclidean distance.
+
+    Parameters
+    ----------
+    spectral_features : np.ndarray, shape (N_vertices, D)
+        Per-vertex spectral descriptors (e.g. from ``spectral_feature_matrix``).
+    labels : np.ndarray, shape (N_vertices,)
+        Parcellation labels.
+    metric : ``'cosine'``, ``'correlation'``, ``'euclidean'``
+        Similarity metric.
+
+    Returns
+    -------
+    ssn : np.ndarray, shape (R, R)
+        Symmetric similarity matrix.
+    """
+    from scipy.spatial.distance import cdist
+
+    roi_labels = np.sort(np.unique(labels[labels > 0]))
+    R = len(roi_labels)
+
+    # Mean spectral profile per ROI
+    roi_profiles = np.zeros((R, spectral_features.shape[1]), dtype=np.float64)
+    for i, lab in enumerate(roi_labels):
+        mask = labels == lab
+        roi_profiles[i] = np.nanmean(spectral_features[mask], axis=0)
+
+    # Distance matrix → similarity
+    if metric == "cosine":
+        dist = cdist(roi_profiles, roi_profiles, metric="cosine")
+        ssn = 1.0 - dist  # cosine similarity
+    elif metric == "correlation":
+        dist = cdist(roi_profiles, roi_profiles, metric="correlation")
+        ssn = 1.0 - dist
+    elif metric == "euclidean":
+        dist = cdist(roi_profiles, roi_profiles, metric="euclidean")
+        # Convert to similarity: exp(-d / median(d))
+        med = np.median(dist[dist > 0])
+        ssn = np.exp(-dist / max(med, 1e-8))
+    else:
+        raise ValueError(f"Unknown metric: {metric}")
+
+    np.fill_diagonal(ssn, 0.0)  # no self-loops
+    return ssn
+
+
+def graph_metrics(
+    adjacency: np.ndarray,
+    threshold: Optional[float] = None,
+    density: Optional[float] = None,
+) -> Dict[str, object]:
+    """
+    Compute standard graph-theoretic metrics from a similarity matrix.
+
+    Parameters
+    ----------
+    adjacency : np.ndarray, shape (R, R)
+        Symmetric similarity/weight matrix.
+    threshold : float or None
+        Hard threshold on edge weights.
+    density : float or None
+        Target graph density (proportion of edges to keep).
+        Overrides ``threshold`` if both provided.
+
+    Returns
+    -------
+    metrics : dict
+        Keys include: ``degree``, ``clustering``, ``efficiency``,
+        ``betweenness``, ``modularity``, ``strength``, ``assortativity``.
+    """
+    try:
+        import networkx as nx
+        from networkx.algorithms.community import greedy_modularity_communities
+    except ImportError:
+        raise ImportError("NetworkX is required for graph metrics.")
+
+    W = adjacency.copy()
+
+    # Apply threshold
+    if density is not None:
+        flat = np.sort(W[np.triu_indices_from(W, k=1)])[::-1]
+        n_edges = int(density * len(flat))
+        if n_edges > 0 and n_edges <= len(flat):
+            threshold = flat[n_edges - 1]
+
+    if threshold is not None:
+        W[W < threshold] = 0.0
+
+    # Build NetworkX graph
+    G = nx.from_numpy_array(W)
+
+    # Remove zero-weight edges
+    zero_edges = [(u, v) for u, v, d in G.edges(data=True) if d["weight"] <= 0]
+    G.remove_edges_from(zero_edges)
+
+    # Metrics
+    result = {}
+    result["n_nodes"] = G.number_of_nodes()
+    result["n_edges"] = G.number_of_edges()
+    result["density"] = nx.density(G)
+    result["strength"] = dict(G.degree(weight="weight"))
+    result["degree"] = dict(G.degree())
+    result["clustering"] = nx.clustering(G, weight="weight")
+
+    # Global efficiency
+    try:
+        result["global_efficiency"] = nx.global_efficiency(G)
+    except Exception:
+        result["global_efficiency"] = np.nan
+
+    # Betweenness centrality
+    result["betweenness"] = nx.betweenness_centrality(G, weight="weight")
+
+    # Modularity via greedy algorithm
+    try:
+        communities = list(greedy_modularity_communities(G, weight="weight"))
+        result["modularity"] = nx.community.modularity(
+            G, communities, weight="weight",
+        )
+        result["communities"] = communities
+    except Exception:
+        result["modularity"] = np.nan
+        result["communities"] = []
+
+    # Assortativity
+    try:
+        result["assortativity"] = nx.degree_assortativity_coefficient(
+            G, weight="weight",
+        )
+    except Exception:
+        result["assortativity"] = np.nan
+
+    return result