conninfpy.topologies

Named topology scenarios for benchmarking enhancement methods on synthetic connectivity. Promoted from examples/ to the public API on 2026-04-18.

Provides 19 named scenarios covering the topologies most likely to arise in real connectivity data: within-module-dense, between-modules-dense, hub, rich-club, scattered, chain, gradient-core-periphery, partial-bipartite, fragmented-within-module, cross-block-connected-chain, plus secondary variants.

Public surface:

• TopologyDatasetGenerator — main generator class

• TopologyDataset — output container (.group1, .group2, .mask, .net_labels, .scenario)

• TopologyScenario — scenario specification

• list_scenarios() — return all scenario names

• get_scenarios() — return all scenario specs

• get_scenario() — look up a specific scenario by name

The MICCAI 2026 power benchmark (examples/miccai_paper_reproducing/) sweeps all enhancement methods across all 19 topologies; its findings are summarized in the “no-method-dominates-across-topologies” empirical message of the ConnInfPy paper.

Topology-based synthetic connectivity scenarios.

Built on top of conninfpy.synth_datasets.ModularDatasetGenerator, this module adds a library of named topological effect patterns (hub, chain, rich-club, checkerboard, gradient, etc.) plus a scenario registry so callers can request a scenario by name.

Public API

• TopologyScenario — scenario specification

• TopologyDataset — generated output container

• TopologyDatasetGenerator — the main entry point

• list_scenarios(), get_scenario(), get_scenarios() — registry

Mask generator functions (_mask_*, _scenario_mask_*) are private; access them indirectly via the scenario registry.

Example

>>> from conninfpy.topologies import TopologyDatasetGenerator, list_scenarios
>>> list_scenarios()[:3]
['within_module_dense', 'between_modules_dense', 'hub']
>>> gen = TopologyDatasetGenerator(n_nodes=60, n_modules=4, seed=1)
>>> ds = gen.generate("chain", effect_size=0.3, n_samples=20, time_points=30)
>>> ds.group1.shape
(20, 60, 60)

class conninfpy.topologies.TopologyScenario(name: str, base_kind: str, mask_fn: ~typing.Callable[[...], ~numpy.ndarray], mask_params: ~typing.Dict[str, object] = <factory>, labels_fn: ~typing.Callable[[int, int], ~numpy.ndarray] = <function TopologyScenario.<lambda>>)

Bases: object

Scenario specification: how to build labels + an effect mask topology.

• mask_fn(labels, rng=…, **mask_params) returns a symmetric (N, N) matrix where: 0 means “no effect” and non-zero values scale the effect magnitude per edge.

• labels_fn(n_nodes, n_modules) returns net_labels (shape (N,)).

name: str

base_kind: str

mask_fn: Callable[[...], ndarray]

mask_params: Dict[str, object]

labels_fn(n_modules)

with_mask_params(**overrides: object) → TopologyScenario

class conninfpy.topologies.TopologyDataset(group1: ndarray, group2: ndarray, net_labels: ndarray, effect_mask: ndarray, effect_size: float, scenario: TopologyScenario, meta: Dict[str, object]=<factory>)

Bases: object

Output of a topology simulation, ready for TFNBS/NBS pipelines.

• group1/group2 are arrays of shape (n_samples, N, N) with zero diagonal.

• net_labels can be passed to cNBS/NI/FBC methods.

• effect_mask is the signed/weighted topology mask (not multiplied by effect_size).

group1: ndarray

group2: ndarray

net_labels: ndarray

effect_mask: ndarray

effect_size: float

scenario: TopologyScenario

meta: Dict[str, object]

fisher_z() → Tuple[ndarray, ndarray]

class conninfpy.topologies.TopologyDatasetGenerator(n_nodes: int = 60, n_modules: int = 4, intra_corr: float = 0.3, inter_corr: float = 0.05, uniform_corr: float = 0.15, noise_level: float = 0.05, seed: int = 42)

Bases: object

Reusable dataset generator for topology scenarios.

Example

>>> gen = TopologyDatasetGenerator(n_nodes=60, n_modules=4, seed=1)
>>> ds = gen.generate("chain", effect_size=0.3, n_samples=20, time_points=30)
>>> ds.group1.shape
(20, 60, 60)

generate(scenario: str | TopologyScenario, effect_size: float, *, n_samples: int = 20, n_samples_g1: int | None = None, n_samples_g2: int | None = None, time_points: int = 30, scenario_params: Dict[str, object] | None = None, zero_diagonal: bool = True) → TopologyDataset

conninfpy.topologies.list_scenarios() → List[str]

conninfpy.topologies.get_scenarios() → List[TopologyScenario]

conninfpy.topologies.get_scenario(scenario: str | TopologyScenario) → TopologyScenario