-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | The most frequently used machine learning tools
--   
--   Please see the README on Github at
--   <a>https://github.com/masterdezign/Learning#readme</a>
@package Learning
@version 0.0.3


-- | <h1>Machine learning utilities</h1>
--   
--   A micro library containing the most common machine learning tools.
--   Check also the mltool package
--   <a>https://hackage.haskell.org/package/mltool</a>.
module Learning

-- | A dataset representation for supervised learning
data Dataset a b
Dataset :: [a] -> [b] -> [(a, b)] -> Dataset a b
[_samples] :: Dataset a b -> [a]
[_labels] :: Dataset a b -> [b]
[toList] :: Dataset a b -> [(a, b)]

-- | Create a <a>Dataset</a> from list of samples (first) and labels
--   (second)
fromList :: [(a, b)] -> Dataset a b

-- | Principal components analysis tools
data PCA
PCA :: Matrix Double -> (Vector Double -> Matrix Double) -> (Matrix Double -> Vector Double) -> PCA

-- | Compression matrix U
[_u] :: PCA -> Matrix Double

-- | Compression function
[_compress] :: PCA -> Vector Double -> Matrix Double

-- | Inverse to compression function
[_decompress] :: PCA -> Matrix Double -> Vector Double

-- | Principal components analysis resulting in <a>PCA</a> tools
pca :: Int -> [Vector Double] -> PCA

-- | Compute the covariance matrix <tt>sigma</tt> and return its
--   eigenvectors <tt>u'</tt> and eigenvalues <tt>s</tt>
pca' :: [Vector Double] -> (Matrix Double, Vector Double)

-- | Perform PCA using the minimal number of principal components required
--   to retain given variance
pcaVariance :: Double -> [Vector Double] -> PCA

-- | Teacher matrix
--   
--   <pre>
--   0 0 0 0 0
--   0 0 0 0 0
--   1 1 1 1 1 &lt;- Desired class index is 2
--   0 0 0 0 0 &lt;- Number of classes is 4
--           ^
--     5 repetitions
--   </pre>
type Teacher = Matrix Double

-- | Create a binary <a>Teacher</a> matrix with ones row corresponding to
--   the desired class index
teacher :: Int -> Int -> Int -> Teacher

-- | Classifier function that maps some measurements as matrix columns and
--   corresponding features as rows, into a categorical output.
newtype Classifier a
Classifier :: (Matrix Double -> a) -> Classifier a
[classify] :: Classifier a -> Matrix Double -> a

-- | Regressor function that maps some feature matrix into a continuous
--   multidimensional output. The feature matrix is expected to have
--   columns corresponding to measurements (data points) and rows,
--   features.
newtype Regressor
Regressor :: (Matrix Double -> Matrix Double) -> Regressor
[predict] :: Regressor -> Matrix Double -> Matrix Double

-- | Linear readout (matrix)
type Readout = Matrix Double

-- | Perform supervised learning (ridge regression) and create a linear
--   <a>Classifier</a> function. The regression is run with regularization
--   parameter μ = 1e-4.
learnClassifier :: (Storable a, Eq a) => Vector a -> Matrix Double -> Matrix Double -> Either String (Classifier a)

-- | Perform supervised learning (ridge regression) and create a linear
--   <a>Regressor</a> function.
learnRegressor :: Matrix Double -> Matrix Double -> Either String Regressor

-- | Create a linear <a>Readout</a> using the ridge regression. Similar to
--   <a>learnRegressor</a>, but instead of a <a>Regressor</a> function a
--   (already transposed) <a>Readout</a> matrix may be returned.
learn' :: Matrix Double -> Matrix Double -> Maybe Readout

-- | Evaluate the network state (nonlinear response) according to some
--   <a>Readout</a> matrix. Used by classification strategies such as
--   <a>winnerTakesAll</a>.
scores :: Readout -> Matrix Double -> Vector Double

-- | Winner-takes-all classification method
winnerTakesAll :: (Storable a, Eq a) => Readout -> Vector a -> Classifier a

-- | Accuracy of classification, <tt>100% - <a>errorRate</a></tt>
--   
--   <pre>
--   &gt;&gt;&gt; accuracy [1,2,3,4] [1,2,3,7]
--   75.0
--   </pre>
accuracy :: (Eq lab, Fractional acc) => [lab] -> [lab] -> acc

-- | Error rate in %, an error measure for classification tasks
--   
--   <pre>
--   &gt;&gt;&gt; errorRate [1,2,3,4] [1,2,3,7]
--   25.0
--   </pre>
errorRate :: (Eq a, Fractional err) => [a] -> [a] -> err

-- | Pairs of misclassified and correct values
--   
--   <pre>
--   &gt;&gt;&gt; errors $ zip ['x','y','z'] ['x','b','a']
--   [('y','b'),('z','a')]
--   </pre>
errors :: Eq lab => [(lab, lab)] -> [(lab, lab)]

-- | Confusion matrix normalized by row: ASCII representation.
--   
--   Note: it is assumed that target (true) labels list contains all
--   possible labels.
--   
--   <pre>
--         |  Predicted
--      ---+------------
--         | _ _ _ _ _
--    True | _ _ _ _ _
--         | _ _ _ _ _
--   label | _ _ _ _ _
--         | _ _ _ _ _
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putStr $ showConfusion [1, 2, 3, 1] [1, 2, 3, 2]
--         1     2     3
--   1   50.0  50.0   0.0
--   2    0.0 100.0   0.0
--   3    0.0   0.0 100.0
--   </pre>
showConfusion :: (Ord lab, Eq lab, Show lab) => [lab] -> [lab] -> String

-- | Normalized confusion matrix for arbitrary number of classes
confusion :: (Ord lab, Eq lab) => Normalize -> [lab] -> [lab] -> Map (lab, lab) Double

-- | Normalization strategies for <a>confusion</a> matrix
data Normalize
ByRow :: Normalize
ByColumn :: Normalize

-- | Confusion matrix for arbitrary number of classes (not normalized)
confusion' :: (Ord lab, Eq lab) => [lab] -> [lab] -> Map (lab, lab) Int

-- | Normalized root mean square error (NRMSE), one of the most common
--   error measures for regression tasks
nrmse :: (Storable a, Floating a) => Vector a -> Vector a -> a
instance GHC.Classes.Eq Learning.Normalize
instance GHC.Show.Show Learning.Normalize