Skip to content

Neighborhood

Catalog of neighborhood functions.

Neighborhood functions are defined as equinox.Module parametrized functions

AbstractNbh

Bases: Module

Ensures that all neighborhood functions have the same signatures.

Source code in src/somap/neighborhood.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class AbstractNbh(eqx.Module):
    """Ensures that all neighborhood functions have the same signatures."""

    @abstractmethod
    def __call__(
        self,
        distance_map: Float[Array, "x y"],
        t: Integer[Array, ""],
        quantization_error: Float[Array, ""],
    ) -> Float[Array, "x y"]:
        """SOM Neighborhood function.

        Args:
            distance_map: Distance of each grid elements from the winning element.
            t: Current iteration.
            quantization_error: The computed difference between the winner prototype
                and the input.

        Returns:
            The neighborhood distance.
        """
        pass

__call__(distance_map, t, quantization_error) abstractmethod

SOM Neighborhood function.

Parameters:

Name Type Description Default
distance_map Float[Array, 'x y']

Distance of each grid elements from the winning element.

 required
t Integer[Array, '']

Current iteration.

 required
quantization_error Float[Array, '']

The computed difference between the winner prototype and the input.

 required

Returns:

Type Description
Float[Array, 'x y']

The neighborhood distance.
Source code in src/somap/neighborhood.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@abstractmethod
def __call__(
    self,
    distance_map: Float[Array, "x y"],
    t: Integer[Array, ""],
    quantization_error: Float[Array, ""],
) -> Float[Array, "x y"]:
    """SOM Neighborhood function.

    Args:
        distance_map: Distance of each grid elements from the winning element.
        t: Current iteration.
        quantization_error: The computed difference between the winner prototype
            and the input.

    Returns:
        The neighborhood distance.
    """
    pass

DsomNbh

Bases: AbstractNbh

Dynamic Kohonen neighborhood function.

Source code in src/somap/neighborhood.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class DsomNbh(AbstractNbh):
    """Dynamic Kohonen neighborhood function."""

    plasticity: float | Float[Array, "..."] = 0.1

    def __call__(
        self, distance_map: Float[Array, "x y"], _, quantization_error: Float[Array, ""]
    ) -> Float[Array, "x y"]:
        """Computes the Dynamic SOM neighboring value of each grid element.

        See:
            Nicolas P. Rougier, Yann Boniface. Dynamic Self-Organising Map.
            Neurocomputing, Elsevier, 2011, 74 (11), pp.1840-1847.
            ff10.1016/j.neucom.2010.06.034ff. ffinria-00495827

        Args:
            self:
                self.plasticity: Dynamic value to compute the neighbourhood distance.
            distance_map: Distance of each element from the winner element.
            _: Not used
            quantization_error: The computed difference between the winner prototype
                and the input.

        Returns:
            The neighborhood distance, as calculated in the article.
        """
        return jnp.exp(
            -(distance_map**2) / (self.plasticity**2 * quantization_error**2)
        )

__call__(distance_map, _, quantization_error)

Computes the Dynamic SOM neighboring value of each grid element.

See

Nicolas P. Rougier, Yann Boniface. Dynamic Self-Organising Map. Neurocomputing, Elsevier, 2011, 74 (11), pp.1840-1847. ff10.1016/j.neucom.2010.06.034ff. ffinria-00495827

Parameters:

Name Type Description Default
self

self.plasticity: Dynamic value to compute the neighbourhood distance.

 required
distance_map Float[Array, 'x y']

Distance of each element from the winner element.

 required
_

Not used

 required
quantization_error Float[Array, '']

The computed difference between the winner prototype and the input.

 required

Returns:

Type Description
Float[Array, 'x y']

The neighborhood distance, as calculated in the article.
Source code in src/somap/neighborhood.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def __call__(
    self, distance_map: Float[Array, "x y"], _, quantization_error: Float[Array, ""]
) -> Float[Array, "x y"]:
    """Computes the Dynamic SOM neighboring value of each grid element.

    See:
        Nicolas P. Rougier, Yann Boniface. Dynamic Self-Organising Map.
        Neurocomputing, Elsevier, 2011, 74 (11), pp.1840-1847.
        ff10.1016/j.neucom.2010.06.034ff. ffinria-00495827

    Args:
        self:
            self.plasticity: Dynamic value to compute the neighbourhood distance.
        distance_map: Distance of each element from the winner element.
        _: Not used
        quantization_error: The computed difference between the winner prototype
            and the input.

    Returns:
        The neighborhood distance, as calculated in the article.
    """
    return jnp.exp(
        -(distance_map**2) / (self.plasticity**2 * quantization_error**2)
    )

GaussianNbh

Bases: AbstractNbh

Exponentially decreasing neighborhood function.

Source code in src/somap/neighborhood.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class GaussianNbh(AbstractNbh):
    """Exponentially decreasing neighborhood function."""

    sigma: float | Float[Array, "..."] = 0.1

    def __call__(self, distance_map: Float[Array, "x y"], t, __) -> Float[Array, "x y"]:
        """Return the Kohonen time-independent neighboring value of each element.

        Args:
            self: Module's parameters
                self.sigma: Neighbourhood distance.
            distance_map: Distance of each element from the winner element.
            t: Not used
            __: Not used

        Returns:
            The kohonen neighborhood distance.
        """
        # Surprisingly, `(t+1)/(t+1)` speeds up the jitted function on CPU with JAX.
        sigma = self.sigma * (t + 1) / (t + 1)
        return jnp.exp(-(distance_map**2) / (2 * sigma**2))

__call__(distance_map, t, __)

Return the Kohonen time-independent neighboring value of each element.

Parameters:

Name Type Description Default
self

Module's parameters self.sigma: Neighbourhood distance.

 required
distance_map Float[Array, 'x y']

Distance of each element from the winner element.

 required
t

Not used

 required
__

Not used

 required

Returns:

Type Description
Float[Array, 'x y']

The kohonen neighborhood distance.
Source code in src/somap/neighborhood.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def __call__(self, distance_map: Float[Array, "x y"], t, __) -> Float[Array, "x y"]:
    """Return the Kohonen time-independent neighboring value of each element.

    Args:
        self: Module's parameters
            self.sigma: Neighbourhood distance.
        distance_map: Distance of each element from the winner element.
        t: Not used
        __: Not used

    Returns:
        The kohonen neighborhood distance.
    """
    # Surprisingly, `(t+1)/(t+1)` speeds up the jitted function on CPU with JAX.
    sigma = self.sigma * (t + 1) / (t + 1)
    return jnp.exp(-(distance_map**2) / (2 * sigma**2))

KsomNbh

Bases: AbstractNbh

Kohonen neighborhood function.

Source code in src/somap/neighborhood.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
class KsomNbh(AbstractNbh):
    """Kohonen neighborhood function."""

    t_f: int | Integer[Array, "..."] = 100000
    sigma_i: float | Float[Array, "..."] = 1.0
    sigma_f: float | Float[Array, "..."] = 0.01

    def __call__(
        self, distance_map: Float[Array, "x y"], t: Integer[Array, ""], _
    ) -> Float[Array, "x y"]:
        """Returns the Kohonen neighboring value of each element.

        Args:
            self: Module's parameters
                self.t_f: Aimed iteration.
                self.sigma_i: Current neighborhood distance.
                self.sigma_f: Aimed neighborhood distance.
            distance_map: Distance of each grid elements from the winning element.
            t: Current iteration.
            _: Not used

        Returns:
            The kohonen neighborhood distance.
        """
        sigma = self.sigma_i * (self.sigma_f / self.sigma_i) ** (t / self.t_f)
        return jnp.exp(-(distance_map**2) / (2 * sigma**2))

__call__(distance_map, t, _)

Returns the Kohonen neighboring value of each element.

Parameters:

Name Type Description Default
self

Module's parameters self.t_f: Aimed iteration. self.sigma_i: Current neighborhood distance. self.sigma_f: Aimed neighborhood distance.

 required
distance_map Float[Array, 'x y']

Distance of each grid elements from the winning element.

 required
t Integer[Array, '']

Current iteration.

 required
_

Not used

 required

Returns:

Type Description
Float[Array, 'x y']

The kohonen neighborhood distance.
Source code in src/somap/neighborhood.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def __call__(
    self, distance_map: Float[Array, "x y"], t: Integer[Array, ""], _
) -> Float[Array, "x y"]:
    """Returns the Kohonen neighboring value of each element.

    Args:
        self: Module's parameters
            self.t_f: Aimed iteration.
            self.sigma_i: Current neighborhood distance.
            self.sigma_f: Aimed neighborhood distance.
        distance_map: Distance of each grid elements from the winning element.
        t: Current iteration.
        _: Not used

    Returns:
        The kohonen neighborhood distance.
    """
    sigma = self.sigma_i * (self.sigma_f / self.sigma_i) ** (t / self.t_f)
    return jnp.exp(-(distance_map**2) / (2 * sigma**2))

MexicanHatNbh

Bases: AbstractNbh

Mexican Hat neighborhood function.

Source code in src/somap/neighborhood.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
class MexicanHatNbh(AbstractNbh):
    """Mexican Hat neighborhood function."""

    sigma: float | Float[Array, "..."] = 0.1

    def __call__(self, distance_map: Float[Array, "x y"], _, __) -> Float[Array, "x y"]:
        """Computes the Mexican Hat neighboring value of each grid element.

        Args:
            self:
                self.sigma: Scale factor for the spread of the neighborhood.
            distance_map: Distance of each element from the winner element.
            _: Not used
            __: Not used

        Returns:
            The Mexican Hat neighborhood distance.
        """
        r2_norm = distance_map**2 / self.sigma**2
        return (1 - 0.5 * r2_norm) * jnp.exp(-r2_norm / 2)

__call__(distance_map, _, __)

Computes the Mexican Hat neighboring value of each grid element.

Parameters:

Name Type Description Default
self

self.sigma: Scale factor for the spread of the neighborhood.

 required
distance_map Float[Array, 'x y']

Distance of each element from the winner element.

 required
_

Not used

 required
__

Not used

 required

Returns:

Type Description
Float[Array, 'x y']

The Mexican Hat neighborhood distance.
Source code in src/somap/neighborhood.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def __call__(self, distance_map: Float[Array, "x y"], _, __) -> Float[Array, "x y"]:
    """Computes the Mexican Hat neighboring value of each grid element.

    Args:
        self:
            self.sigma: Scale factor for the spread of the neighborhood.
        distance_map: Distance of each element from the winner element.
        _: Not used
        __: Not used

    Returns:
        The Mexican Hat neighborhood distance.
    """
    r2_norm = distance_map**2 / self.sigma**2
    return (1 - 0.5 * r2_norm) * jnp.exp(-r2_norm / 2)