src/Gargantext/Types/Phylo.hs

   1 {-|
   2 Module      : Gargantext.Types.Phylo
   3 Description : Main Types for Phylomemy
   4 Copyright   : (c) CNRS, 2017-Present
   5 License     : AGPL + CECILL v3
   6 Maintainer  : team@gargantext.org
   7 Stability   : experimental
   8 Portability : POSIX
   9
  10 Specifications of Phylomemy format.
  11
  12 Phylomemy can be described as a Temporal Graph with different scale of
  13 granularity of group of ngrams (terms and multi-terms).
  14
  15 The main type is Phylo which is synonym of Phylomemy (only difference is
  16 the number of chars).
  17
  18 Phylomemy was first described in [REF].
  19 -}
  20
  21 {-# LANGUAGE DeriveGeneric        #-}
  22 {-# LANGUAGE TemplateHaskell      #-}
  23
  24 module Gargantext.Types.Phylo where
  25
  26 import Data.Aeson.TH (deriveJSON)
  27 import Data.Maybe   (Maybe)
  28 import Data.Text    (Text)
  29 import Data.Time    (UTCTime)
  30
  31 import GHC.Generics (Generic)
  32
  33 import Gargantext.Prelude
  34 import Gargantext.Utils.Prefix (unPrefix)
  35
  36 ------------------------------------------------------------------------
  37 -- | Phylo datatype descriptor of a phylomemy
  38 -- Period : time Segment of the whole phylomemy in UTCTime format (start,end)
  39 -- Ngrams : list of all (possible) terms contained in the phylomemy (with their id)
  40 -- Steps  : list of all steps to build the phylomemy
  41 data Phylo = Phylo { _phyloPeriod :: (Start, End)
  42                    , _phyloNgrams :: [Ngram]
  43                    , _phyloSteps  :: [PhyloStep]
  44                    } deriving (Generic)
  45
  46 type Start   = UTCTime
  47 type End     = UTCTime
  48
  49 type Ngram   = (NgramId, Text)
  50 type NgramId = Int
  51
  52 -- | PhyloStep : steps of phylomemy on temporal axis
  53 -- Period: tuple (start date, end date) of the step of the phylomemy
  54 -- Levels: levels of granularity
  55 data PhyloStep = PhyloStep { _phyloStepPeriod :: (Start, End)
  56                            , _phyloStepLevels :: [PhyloLevel]
  57                            } deriving (Generic)
  58
  59 -- | PhyloLevel : levels of phylomemy on level axis
  60 -- Levels description:
  61 -- Level 0: Ngram equals itself              (by identity) == _phyloNgrams
  62 -- Level 1: Group gathers synonyms           (by stems + by qualitative expert meaning)
  63 -- Level 2: Group is Frequent Item Set       (by statistics)
  64 -- Level 3: Group is a cluster or community  (by statistics)
  65
  66 type PhyloLevel = [PhyloGroup]
  67
  68 -- | PhyloGroup : group of ngrams at each level and step
  69 -- Label: maybe has a label as text
  70 -- Ngrams: set of terms that build the group
  71 -- Temporal Parents|Childs: directed and weighted link to Parents|Childs (Temporal axis)
  72 -- Granularity Parents|Childs: directed and weighted link to Parents|Childs (Granularity axis)
  73 data PhyloGroup = PhyloGroup { _phyloGroupLabel              :: Maybe Text
  74                              , _phyloGroupNgrams             :: [NgramId]
  75
  76                              , _phyloGroupTemporalParents    :: [Edge]
  77                              , _phyloGroupTemporalChilds     :: [Edge]
  78
  79                              , _phyloGroupGranularityParents :: [Edge]
  80                              , _phyloGroupGranularityChilds  :: [Edge]
  81                              } deriving (Generic)
  82
  83 type Edge   = (NgramId, Weight)
  84 type Weight = Double
  85
  86 -- | JSON instances
  87 $(deriveJSON (unPrefix "_phylo") ''Phylo)
  88 $(deriveJSON (unPrefix "_phyloStep")  ''PhyloStep)
  89 $(deriveJSON (unPrefix "_phyloGroup") ''PhyloGroup)