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


-- | Generic encoding of records
--   
--   Generic encoding of records. It currently provides a single,
--   polymorphic function to encode sum types (i.e. categorical variables)
--   as one-hot vectors.
@package record-encode
@version 0.2.3

module Data.Record.Encode.Generics

-- | Compute the structural index of a value of a sum type via its Generic
--   representation e.g.:
--   
--   <pre>
--   &gt;&gt;&gt; data S = Sa | Sb | Sc deriving (Eq, Show, G.Generic)
--   
--   &gt;&gt;&gt; instance Generic S
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; gindex $ from Sb
--   1
--   </pre>
gindex :: SOP f xs -> Int

-- | Counts the number of outermost constructors ("variants" of a type)
class GVariants (f :: * -> *)
vars :: GVariants f => proxy f -> Int

-- | Counts the number of outermost constructors
gnconstructors :: forall a. (Generic a, GVariants (Rep a)) => Proxy a -> Int
instance GHC.Generics.Generic (Data.Record.Encode.Generics.X a)
instance Data.Record.Encode.Generics.GVariants (GHC.Generics.M1 GHC.Generics.C m f)
instance Data.Record.Encode.Generics.GVariants GHC.Generics.V1
instance Data.Record.Encode.Generics.GVariants f => Data.Record.Encode.Generics.GVariants (GHC.Generics.M1 GHC.Generics.D m f)
instance (Data.Record.Encode.Generics.GVariants f, Data.Record.Encode.Generics.GVariants g) => Data.Record.Encode.Generics.GVariants (f GHC.Generics.:+: g)
instance Generics.SOP.Universe.Generic (Data.Record.Encode.Generics.X a)


-- | This library provides generic machinery (via GHC.Generics and
--   `generics-sop`) to encode values of some algebraic type as points in a
--   vector space.
--   
--   Processing datasets that have one or more categorical variables (which
--   in other words are values of a sum type) typically requires a series
--   of boilerplate transformations, and the <a>encodeOneHot</a> function
--   provided here does precisely that.
--   
--   <h2>Internals</h2>
--   
--   This library makes use of generic programming to analyze both values
--   and types (see the <a>Generics</a> module).
module Data.Record.Encode

-- | Computes the one-hot encoding of a value of a sum type. A sum type is
--   defined as a choice between N type constructors, each having zero or
--   more fields.
--   
--   The number of constructors becomes the dimensionality of the embedding
--   space, and the constructor position (as defined in its implementation)
--   is interpreted as the index of the nonzero coordinate.
--   
--   NB : This function computes the generic representation <i>only</i> up
--   to the <i>outermost</i> constructor (see examples below).
--   
--   The type of the input value must be an instance of <a>Generic</a>
--   (from GHC.Generics) <i>and</i> of <a>Generic</a> (from the
--   `generics-sop` library).
--   
--   <pre>
--   &gt; :set -XDeriveGeneric
--   
--   &gt; import qualified GHC.Generics as G
--   &gt; import qualified Generics.SOP as SOP
--   &gt; import Data.Record.Encode
--   
--   &gt; data X = A | B | C deriving (Enum, G.Generic)
--   &gt; instance SOP.Generic X
--   </pre>
--   
--   The <tt>B</tt> constructor is the second (i.e. position 1 counting
--   from 0) of a choice of three :
--   
--   <pre>
--   &gt;&gt;&gt; encodeOneHot B
--   OH {oDim = 3, oIx = 1}
--   </pre>
--   
--   The <tt>Just</tt> constructor is the second of a choice of two:
--   
--   <pre>
--   &gt;&gt;&gt; encodeOneHot $ Just B
--   OH {oDim = 2, oIx = 1}
--   </pre>
--   
--   The <tt>Nothing</tt> constructor is the first:
--   
--   <pre>
--   &gt;&gt;&gt; encodeOneHot (Nothing :: Maybe Int)
--   OH {oDim = 2, oIx = 0}
--   </pre>
encodeOneHot :: forall a. G a => a -> OneHot

-- | A one-hot encoding is a d-dimensional vector having a single component
--   equal to 1 and all others equal to 0. We represent it here compactly
--   as two integers: an integer dimension and an index (which must both be
--   nonnegative).
data OneHot
OH :: !Int -> !Int -> OneHot

-- | Dimension of embedding space (i.e. number of categories)
[oDim] :: OneHot -> !Int

-- | Index of nonzero coordinate
[oIx] :: OneHot -> !Int

-- | Compares two one-hot encodings for equality. Returns Nothing if the
--   operand dimensions are not equal.
--   
--   <pre>
--   &gt;&gt;&gt; compareOH (OH 3 2) (OH 3 1)
--   Just GT
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; compareOH (OH 3 2) (OH 5 1)
--   Nothing
--   </pre>
compareOH :: OneHot -> OneHot -> Maybe Ordering

-- | Create a one-hot vector
oneHotV :: Num a => OneHot -> Vector a

-- | Constraints necessary to <a>encodeOneHot</a> a value.
--   
--   NB: <a>GVariants</a> is an internal typeclass, and this constraint is
--   automatically satisfied if the type is an instance of <a>Generic</a>
type G a = (GVariants (Rep a), Generic a, Generic a)
instance GHC.Show.Show Data.Record.Encode.OneHot
instance GHC.Classes.Eq Data.Record.Encode.OneHot