-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Self-Organising Maps -- -- A Kohonen Self-organising Map (SOM) maps input patterns onto a regular -- grid (usually two-dimensional) where each node in the grid is a model -- of the input data, and does so using a method which ensures that any -- topological relationships within the input data are also represented -- in the grid. This implementation supports the use of non-numeric -- patterns. -- -- In layman's terms, a SOM can be useful when you you want to discover -- the underlying structure of some data. -- -- The userguide is available at -- https://github.com/mhwombat/som/wiki. -- -- NOTE: Version 3.0 changed the order of parameters for many functions. -- This makes it easier for the user to write mapping and folding -- operations. @package som @version 3.1 -- | A module containing private SOM internals. Most developers -- should use SOM instead. This module is subject to change -- without notice. module Data.Datamining.Clustering.SOMInternal adjustNode :: Pattern p => p -> (Metric p, p) -> p -- | adjustVector target amount vector adjusts -- vector to move it closer to target. The amount of -- adjustment is controlled by the learning rate r, which is a -- number between 0 and 1. Larger values of r permit more -- adjustment. If r=1, the result will be identical to the -- target. If amount=0, the result will be the -- unmodified pattern. adjustVector :: (Num a, Ord a, Eq a) => [a] -> a -> [a] -> [a] -- | classify c pattern returns the position of the node in -- c whose pattern best matches the input pattern. classify :: (GridMap gm p, Pattern p, GridMap gm m, Metric p ~ m, Ord m, k ~ Index (BaseGrid gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> p -> k -- | If f is a function that returns the learning rate to apply to -- a node based on its distance from the node that best matches the -- target, then classifyAndTrain c f target -- returns a tuple containing the position of the node in c -- whose pattern best matches the input target, and a modified -- copy of the classifier c that has partially learned the -- target. Invoking classifyAndTrain c f p may be -- faster than invoking (p classify c, train c f p), but -- they should give identical results. classifyAndTrain :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> (Index (gm p), gm p) -- | diff c pattern returns the positions of all nodes in -- c, paired with the difference between pattern and -- the node's pattern. diff :: (GridMap gm p, Pattern p, GridMap gm m, Metric p ~ m, BaseGrid gm p ~ BaseGrid gm m) => gm p -> p -> gm m -- | If f is a function that returns the learning rate to apply to -- a node based on its distance from the node that best matches the -- target, then diffAndTrain c f target returns -- a tuple containing: 1. The positions of all nodes in c, -- paired with the difference between pattern and the node's -- pattern 2. A modified copy of the classifier c that has -- partially learned the target. Invoking diffAndTrain c f -- p may be faster than invoking (p diff c, train c f -- p), but they should give identical results. diffAndTrain :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> (gm m, gm p) -- | Calculates the square of the Euclidean distance between two vectors. euclideanDistanceSquared :: Num a => [a] -> [a] -> a magnitudeSquared :: Num a => [a] -> a -- | Normalises a vector normalise :: Floating a => [a] -> NormalisedVector a -- | A vector that has been normalised, i.e., the magnitude of the vector = -- 1. data NormalisedVector a -- | Given a vector qs of pairs of numbers, where each pair -- represents the maximum and minimum value to be expected at each -- position in xs, scale qs xs scales the vector -- xs element by element, mapping the maximum value expected at -- that position to one, and the minimum value to zero. scale :: Fractional a => [(a, a)] -> [a] -> ScaledVector a -- | Scales a set of vectors by determining the maximum and minimum values -- at each position in the vector, and mapping the maximum value to one, -- and the minimum value to zero. scaleAll :: (Fractional a, Ord a) => [[a]] -> [ScaledVector a] -- | A vector that has been scaled so that all elements in the vector are -- between zero and one. To scale a set of vectors, use -- scaleAll. Alternatively, if you can identify a maximum -- and minimum value for each element in a vector, you can scale -- individual vectors using scale. data ScaledVector a -- | If f d is a function that returns the learning rate to apply -- to a node based on its distance dfrom the node that best -- matches the input pattern, then train c f pattern -- returns a modified copy of the classifier c that has -- partially learned the target. train :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> gm p -- | Same as train, but applied to multiple patterns. trainBatch :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> [p] -> gm p -- | A pattern to be learned or classified by a self-organising map. class Pattern p where type family Metric p difference :: Pattern p => p -> p -> Metric p makeSimilar :: Pattern p => p -> Metric p -> p -> p instance Show a => Show (NormalisedVector a) instance Show a => Show (ScaledVector a) instance (Fractional a, Ord a, Eq a) => Pattern (ScaledVector a) instance (Floating a, Fractional a, Ord a, Eq a) => Pattern (NormalisedVector a) -- | A Kohonen Self-organising Map (SOM). A SOM maps input patterns onto a -- regular grid (usually two-dimensional) where each node in the grid is -- a model of the input data, and does so using a method which ensures -- that any topological relationships within the input data are also -- represented in the grid. This implementation supports the use of -- non-numeric patterns. -- -- In layman's terms, a SOM can be useful when you you want to discover -- the underlying structure of some data. A tutorial is available at -- https://github.com/mhwombat/som/wiki -- -- References: -- -- -- -- NOTE: Version 3.0 changed the order of parameters for many functions. -- This makes it easier for the user to write mapping and folding -- operations. module Data.Datamining.Clustering.SOM -- | A pattern to be learned or classified by a self-organising map. class Pattern p where type family Metric p difference :: Pattern p => p -> p -> Metric p makeSimilar :: Pattern p => p -> Metric p -> p -> p -- | If f d is a function that returns the learning rate to apply -- to a node based on its distance dfrom the node that best -- matches the input pattern, then train c f pattern -- returns a modified copy of the classifier c that has -- partially learned the target. train :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> gm p -- | Same as train, but applied to multiple patterns. trainBatch :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> [p] -> gm p -- | classify c pattern returns the position of the node in -- c whose pattern best matches the input pattern. classify :: (GridMap gm p, Pattern p, GridMap gm m, Metric p ~ m, Ord m, k ~ Index (BaseGrid gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> p -> k -- | If f is a function that returns the learning rate to apply to -- a node based on its distance from the node that best matches the -- target, then classifyAndTrain c f target -- returns a tuple containing the position of the node in c -- whose pattern best matches the input target, and a modified -- copy of the classifier c that has partially learned the -- target. Invoking classifyAndTrain c f p may be -- faster than invoking (p classify c, train c f p), but -- they should give identical results. classifyAndTrain :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> (Index (gm p), gm p) -- | diff c pattern returns the positions of all nodes in -- c, paired with the difference between pattern and -- the node's pattern. diff :: (GridMap gm p, Pattern p, GridMap gm m, Metric p ~ m, BaseGrid gm p ~ BaseGrid gm m) => gm p -> p -> gm m -- | If f is a function that returns the learning rate to apply to -- a node based on its distance from the node that best matches the -- target, then diffAndTrain c f target returns -- a tuple containing: 1. The positions of all nodes in c, -- paired with the difference between pattern and the node's -- pattern 2. A modified copy of the classifier c that has -- partially learned the target. Invoking diffAndTrain c f -- p may be faster than invoking (p diff c, train c f -- p), but they should give identical results. diffAndTrain :: (Ord m, GridMap gm p, GridMap gm m, GridMap gm (Int, p), GridMap gm (m, p), Grid (gm p), Pattern p, Metric p ~ m, Index (BaseGrid gm p) ~ Index (gm p), BaseGrid gm m ~ BaseGrid gm p) => gm p -> (Int -> m) -> p -> (gm m, gm p) -- | Normalises a vector normalise :: Floating a => [a] -> NormalisedVector a -- | A vector that has been normalised, i.e., the magnitude of the vector = -- 1. data NormalisedVector a -- | Given a vector qs of pairs of numbers, where each pair -- represents the maximum and minimum value to be expected at each -- position in xs, scale qs xs scales the vector -- xs element by element, mapping the maximum value expected at -- that position to one, and the minimum value to zero. scale :: Fractional a => [(a, a)] -> [a] -> ScaledVector a -- | A vector that has been scaled so that all elements in the vector are -- between zero and one. To scale a set of vectors, use -- scaleAll. Alternatively, if you can identify a maximum -- and minimum value for each element in a vector, you can scale -- individual vectors using scale. data ScaledVector a -- | adjustVector target amount vector adjusts -- vector to move it closer to target. The amount of -- adjustment is controlled by the learning rate r, which is a -- number between 0 and 1. Larger values of r permit more -- adjustment. If r=1, the result will be identical to the -- target. If amount=0, the result will be the -- unmodified pattern. adjustVector :: (Num a, Ord a, Eq a) => [a] -> a -> [a] -> [a] -- | Calculates the square of the Euclidean distance between two vectors. euclideanDistanceSquared :: Num a => [a] -> [a] -> a -- | Calculates ce^(-d^2/2w^2). This form of the Gaussian -- function is useful as a learning rate function. In gaussian -- c w d, c specifies the highest learning rate, which will -- be applied to the SOM node that best matches the input pattern. The -- learning rate applied to other nodes will be applied based on their -- distance d from the best matching node. The value w -- controls the 'width' of the Gaussian. Higher values of w -- cause the learning rate to fall off more slowly with distance. gaussian :: Double -> Double -> Int -> Double