27. Transductive API¶

def get_method_info(method_id: str) -> MethodInfo:
    """Return the :class:`~modssc.transductive.base.MethodInfo` for a method."""
    cls = get_method_class(method_id)
    info = getattr(cls, "info", None)
    if not isinstance(info, MethodInfo):
        raise TypeError(f"Method class {cls} must expose a class attribute `info: MethodInfo`")
    return info

def register_method(
    method_id: str,
    import_path: str,
    *,
    status: Literal["implemented", "planned"] = "implemented",
) -> None:
    """Register a method by id and a lazy import string."""
    if not method_id or not isinstance(method_id, str):
        raise ValueError("method_id must be a non-empty string")
    if ":" not in import_path:
        raise ValueError("import_path must be of the form 'pkg.module:ClassName'")
    existing = _REGISTRY.get(method_id)
    if existing is not None and existing.import_path != import_path:
        raise ValueError(
            f"method_id {method_id!r} already registered with import_path={existing.import_path!r}"
        )
    if status not in {"implemented", "planned"}:
        raise ValueError("status must be 'implemented' or 'planned'")
    _REGISTRY[method_id] = MethodRef(method_id=method_id, import_path=import_path, status=status)

def validate_node_dataset(data: NodeDatasetLike) -> None:
    """Validate the minimal invariants needed by transductive algorithms."""
    if data is None:
        raise TransductiveValidationError("data must not be None")

    X = _as_numpy(data.X)
    y = _as_numpy(data.y)

    if X.ndim != 2:
        raise TransductiveValidationError(f"X must be 2D (n, d), got shape {X.shape}")
    if y.ndim != 1:
        raise TransductiveValidationError(f"y must be 1D (n,), got shape {y.shape}")
    if X.shape[0] != y.shape[0]:
        raise TransductiveValidationError("X and y must have the same first dimension")

    y_arr = np.asarray(y)
    if np.issubdtype(y_arr.dtype, np.integer):
        y_int = y_arr.astype(np.int64, copy=False)
    elif np.issubdtype(y_arr.dtype, np.floating):
        if not np.isfinite(y_arr).all():
            raise TransductiveValidationError(
                "y must contain finite integer class ids; found non-finite values"
            )
        y_int = y_arr.astype(np.int64)
        if not np.all(y_arr == y_int):
            raise TransductiveValidationError(
                "y must contain integer class ids; run preprocess step 'labels.encode'"
            )
    else:
        raise TransductiveValidationError(
            "y must contain integer class ids; run preprocess step 'labels.encode'"
        )

    y_valid = y_int[y_int >= 0]
    if y_valid.size:
        classes = np.unique(y_valid)
        if not np.array_equal(classes, np.arange(int(classes.size))):
            raise TransductiveValidationError(
                "y must contain contiguous class ids starting at 0; run preprocess step 'labels.encode'"
            )

    if data.graph is None:
        raise TransductiveValidationError("data.graph must not be None")

    raw_edge_index = getattr(data.graph, "edge_index", None)
    if raw_edge_index is None:
        raise TransductiveValidationError("graph.edge_index is required")
    edge_index = _as_numpy(raw_edge_index)

    if edge_index.ndim != 2 or edge_index.shape[0] != 2:
        raise TransductiveValidationError(
            f"edge_index must have shape (2, E), got {edge_index.shape}"
        )

    n = int(X.shape[0])
    if edge_index.size > 0 and (edge_index.min() < 0 or edge_index.max() >= n):
        raise TransductiveValidationError("edge_index has out of range node indices")

    masks: Mapping[str, Any] = data.masks or {}
    for key in ("train_mask", "val_mask", "test_mask", "unlabeled_mask"):
        if key not in masks:
            continue
        m = _as_numpy(masks[key]).astype(bool)
        if m.shape != (n,):
            raise TransductiveValidationError(f"{key} must have shape (n,), got {m.shape}")