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
  23 module Gargantext.Types.Phylo where
  24
  25 import Data.Aeson   (ToJSON, FromJSON)
  26 import Data.Maybe   (Maybe)
  27 import Data.Text    (Text)
  28 import Data.Time    (UTCTime)
  29
  30 import GHC.Generics (Generic)
  31
  32 import Gargantext.Prelude
  33
  34 ------------------------------------------------------------------------
  35 -- | Phylo datatype descriptor:
  36 -- Period: time Segment of the whole phylomemy in UTCTime format (start,end)
  37 -- Ngrams : list of all (possible) terms contained in the phylomemy (with their id)
  38 -- Steps : list of all steps to build the phylomemy
  39 data Phylo = Phylo { _phyloPeriod :: (Start, End)
  40                    , _phyloNgrams :: [Ngram]
  41                    , _phyloSteps  :: [PhyloStep]
  42                    } deriving (Generic)
  43
  44 type Start   = UTCTime
  45 type End     = UTCTime
  46
  47 type Ngram   = (NgramId, Text)
  48 type NgramId = Int
  49
  50 -- | PhyloStep datatype descriptor:
  51 -- Period: tuple (start date, end date) of the step of the phylomemy
  52 -- Levels: levels of granularity
  53 data PhyloStep = PhyloStep { _phyloStepPeriod :: (Start, End)
  54                            , _phyloStepLevels :: [Level]
  55                            } deriving (Generic)
  56
  57 -- | Level of a step of a Phylomemy descriptor
  58 -- Label: maybe has a label as text
  59 -- Ngrams: set of terms that build the group
  60 -- Temporal Parents: directed and weighted link to Parents
  61 -- Levels description:
  62 -- Level 0: Ngram equals itself      (by identity) == _phyloNgrams
  63 -- Level 1: Semantic grouping        (by stems + by qualitative expert meaning)
  64 -- Level 2: Frequent Item Set groups (by statistics)
  65 -- Level 3: Clustering               (by statistics)
  66 data Level = Level { _levelLabel              :: Maybe Text
  67                    , _levelNgrams             :: [NgramId]
  68
  69                    , _levelTemporalParents    :: [NgramId]
  70                    , _levelTemporalChilds     :: [NgramId]
  71
  72                    , _levelGranularityParents :: [NgramId]
  73                    , _levelGranularityChilds  :: [NgramId]
  74               } deriving (Generic)
  75
  76 -- | JSON instances
  77 instance FromJSON Phylo
  78 instance ToJSON   Phylo
  79
  80 instance FromJSON PhyloStep
  81 instance ToJSON   PhyloStep
  82
  83 instance FromJSON Level
  84 instance ToJSON   Level
  85