ClusteredRandom

class braintools.conn.ClusteredRandom(prob, cluster_radius, cluster_factor=2.0, weight=None, delay=None, **kwargs)

Random connectivity with spatial clustering and distance-dependent connection enhancement.

This class creates stochastic connections where the connection probability is enhanced for spatially neighboring neurons. The connectivity combines a baseline random probability with increased connectivity within a specified spatial radius, modeling the observation that nearby neurons in cortical circuits often exhibit higher connection probabilities than distant neurons. This pattern is useful for creating spatially-aware random networks that capture local clustering while maintaining global randomness.

The connection probability is computed as:

\[\begin{split}P(d) = \begin{cases} \min(p_{\text{base}} \times f_{\text{cluster}}, 1) & \text{if } d \leq r_{\text{cluster}} \\ p_{\text{base}} & \text{if } d > r_{\text{cluster}} \end{cases}\end{split}\]

where:

• \(d\) is the distance between neurons

• \(p_{\text{base}}\) is the baseline connection probability

• \(r_{\text{cluster}}\) is the cluster radius

• \(f_{\text{cluster}}\) is the cluster enhancement factor

Parameters:

• prob (float) –

  Baseline connection probability for all neuron pairs (range: 0.0 to 1.0). This probability applies to neurons outside the cluster radius and serves as the base rate that is enhanced within clusters. For example:

  • prob=0.05: 5% baseline connectivity

  • prob=0.1: 10% baseline connectivity

  • prob=0.01: Sparse baseline connectivity

• cluster_radius (float | Quantity) – Spatial radius within which connection probability is enhanced. Neuron pairs with distance ≤ cluster_radius have their connection probability multiplied by cluster_factor. Should have spatial units (e.g., 100 * u.um) if positions have units, or be a scalar if positions are unitless.

• cluster_factor (float) –

  Multiplicative factor applied to the baseline probability within the cluster radius. For example:

  • cluster_factor=2.0: Double the probability within clusters

  • cluster_factor=5.0: Five times higher probability for nearby neurons

  • cluster_factor=10.0: Strong local clustering

  The final probability is clipped to the range [0, 1], so prob × cluster_factor can exceed 1.0.

• weight (Initialization | float | int | ndarray | Array | Quantity | None) –

  Initializer for synaptic weights. Supports:

  • Constant values (e.g., 1.0 * u.nS)

  • Stochastic initializers (e.g., Normal, Uniform, LogNormal)

  • Distance-dependent weight distributions

  • None for unweighted connections

• delay (Initialization | float | int | ndarray | Array | Quantity | None) –

  Initializer for synaptic transmission delays. Supports:

  • Constant values (e.g., 1.0 * u.ms)

  • Stochastic delay distributions

  • Distance-proportional delays

  • None for connections without explicit delays

• **kwargs – Additional arguments passed to PointConnectivity, such as seed for reproducible random number generation.

Returns:

Connection result containing pre/post indices, weights, delays, and metadata about the clustered random connectivity pattern.

Return type:

ConnectionResult

Raises:

ValueError – If pre_positions or post_positions are not provided when generating connections.

Notes

• This connectivity pattern requires neuron positions via pre_positions and post_positions arguments when calling the connector

• Position arrays should have shape (n_neurons, n_dimensions) with consistent units

• The algorithm computes all pairwise distances, which has O(N²) memory complexity

• Connection probabilities within cluster radius are: min(prob × cluster_factor, 1.0)

• The expected number of connections depends on spatial neuron distribution:

  • For uniformly distributed neurons, denser regions will have more local connections

  • The global connection density is higher than pure random connectivity

• Empty connection results are returned if no connections are established

• This pattern captures the distance-dependent connectivity observed in local cortical circuits while maintaining stochastic variability

See also

FixedProb

Simple random connectivity without spatial clustering

DistanceDependent

General distance-based connectivity

Gaussian

Smooth Gaussian distance-dependent connectivity

Exponential

Exponential distance-dependent connectivity

Examples

Basic clustered random connectivity:

>>> import brainunit as u
>>> import numpy as np
>>> from braintools.conn import ClusteredRandom
>>> from braintools.init import Constant
>>>
>>> # Create random 2D positions
>>> positions = np.random.uniform(0, 1000, (500, 2)) * u.um
>>>
>>> # 5% baseline, enhanced 5× within 100um
>>> clustered = ClusteredRandom(
...     prob=0.05,
...     cluster_radius=100 * u.um,
...     cluster_factor=5.0,
...     weight=Constant(1.0 * u.nS),
...     seed=42
... )
>>>
>>> result = clustered(
...     pre_size=500,
...     post_size=500,
...     pre_positions=positions,
...     post_positions=positions
... )

Strong local clustering:

>>> # Very strong enhancement for nearby neurons
>>> strong_cluster = ClusteredRandom(
...     prob=0.02,  # Sparse baseline
...     cluster_radius=75 * u.um,
...     cluster_factor=20.0,  # 20× enhancement within clusters
...     weight=Constant(1.5 * u.nS),
...     delay=Constant(1.0 * u.ms)
... )

Moderate clustering with stochastic weights:

>>> from braintools.init import Normal
>>>
>>> moderate_cluster = ClusteredRandom(
...     prob=0.1,
...     cluster_radius=150 * u.um,
...     cluster_factor=3.0,
...     weight=Normal(mean=2.0*u.nS, std=0.4*u.nS),
...     delay=Constant(1.0 * u.ms),
...     seed=42
... )

Modeling local cortical connectivity:

>>> # Model cortical microcircuit with local clustering
>>> cortical_positions = np.random.randn(400, 2) * 150 * u.um
>>>
>>> cortical_conn = ClusteredRandom(
...     prob=0.08,  # 8% baseline connectivity
...     cluster_radius=100 * u.um,  # Local neighborhood
...     cluster_factor=4.0,  # 4× higher within 100um
...     weight=Normal(mean=1.0*u.nS, std=0.2*u.nS),
...     delay=Constant(1.5 * u.ms),
...     seed=42
... )
>>>
>>> result = cortical_conn(
...     pre_size=400,
...     post_size=400,
...     pre_positions=cortical_positions,
...     post_positions=cortical_positions
... )

Different pre and post populations:

>>> # Clustered connectivity between different populations
>>> pre_pos = np.random.uniform(0, 500, (200, 2)) * u.um
>>> post_pos = np.random.uniform(0, 500, (300, 2)) * u.um
>>>
>>> inter_cluster = ClusteredRandom(
...     prob=0.03,
...     cluster_radius=80 * u.um,
...     cluster_factor=6.0,
...     weight=Constant(0.8 * u.nS)
... )
>>>
>>> result = inter_cluster(
...     pre_size=200,
...     post_size=300,
...     pre_positions=pre_pos,
...     post_positions=post_pos
... )

3D spatial clustering:

>>> # Clustering in 3D space (e.g., cortical volume)
>>> positions_3d = np.random.randn(300, 3) * np.array([100, 100, 200]) * u.um
>>>
>>> cluster_3d = ClusteredRandom(
...     prob=0.04,
...     cluster_radius=120 * u.um,  # Spherical clustering
...     cluster_factor=8.0,
...     weight=Constant(1.2 * u.nS)
... )
>>>
>>> result = cluster_3d(
...     pre_size=300,
...     post_size=300,
...     pre_positions=positions_3d,
...     post_positions=positions_3d
... )

Comparing with pure random connectivity:

>>> from braintools.conn import FixedProb
>>>
>>> # Pure random (no clustering)
>>> random_conn = FixedProb(prob=0.1)
>>> random_result = random_conn(pre_size=500, post_size=500)
>>>
>>> # Clustered random (same baseline probability)
>>> clustered_conn = ClusteredRandom(
...     prob=0.1,
...     cluster_radius=100 * u.um,
...     cluster_factor=3.0
... )
>>> clustered_result = clustered_conn(
...     pre_size=500,
...     post_size=500,
...     pre_positions=positions,
...     post_positions=positions
... )
>>> # clustered_result will have more connections due to spatial enhancement

generate(**kwargs)

Generate clustered random connectivity.

Return type:

ConnectionResult