src/Gargantext/Viz/Phylo.hs

   1 {-|
   2 Module      : Gargantext.Viz.Phylo
   3 Description : Phylomemy definitions and types.
   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 References:
  19 Chavalarias, D., Cointet, J.-P., 2013. Phylomemetic patterns
  20 in science evolution — the rise and fall of scientific fields. PloS
  21 one 8, e54847.
  22
  23 -}
  24
  25 {-# LANGUAGE DeriveGeneric     #-}
  26 {-# LANGUAGE NoImplicitPrelude #-}
  27 {-# LANGUAGE TemplateHaskell   #-}
  28
  29 module Gargantext.Viz.Phylo where
  30
  31 import Data.Aeson.TH (deriveJSON)
  32 import Data.Maybe   (Maybe)
  33 import Data.Text    (Text)
  34 import Data.Time.Clock.POSIX  (POSIXTime)
  35 import GHC.Generics (Generic)
  36 import Gargantext.Database.Ngram (NgramsId)
  37 import Gargantext.Core.Utils.Prefix (unPrefix)
  38 import Gargantext.Prelude
  39
  40 ------------------------------------------------------------------------
  41 -- | Phylo datatype descriptor of a phylomemy
  42 -- Duration : time Segment of the whole phylomemy (start,end)
  43 -- Ngrams   : list of all (possible) terms contained in the phylomemy (with their id)
  44 -- Steps    : list of all steps to build the phylomemy
  45 data Phylo =
  46      Phylo { _phylo_Duration :: (Start, End)
  47            , _phylo_Ngrams   :: [Ngram]
  48            , _phylo_Periods  :: [PhyloPeriod]
  49            }
  50            deriving (Generic)
  51
  52 -- | UTCTime in seconds since UNIX epoch
  53 type Start   = POSIXTime
  54 type End     = POSIXTime
  55
  56 -- | Indexed Ngram
  57 type Ngram   = (NgramsId, Text)
  58
  59 -- | PhyloStep : steps of phylomemy on temporal axis
  60 -- Period: tuple (start date, end date) of the step of the phylomemy
  61 -- Levels: levels of granularity
  62 data PhyloPeriod =
  63      PhyloPeriod { _phylo_PeriodId     :: PhyloPeriodId
  64                  , _phylo_PeriodLevels :: [PhyloLevel]
  65                  }
  66                  deriving (Generic)
  67
  68 type PhyloPeriodId = (Start, End)
  69
  70 -- | PhyloLevel : levels of phylomemy on level axis
  71 -- Levels description:
  72 -- Level -1: Ngram equals itself         (by identity) == _phylo_Ngrams
  73 -- Level  0: Group of synonyms           (by stems + by qualitative expert meaning)
  74 -- Level  1: First level of clustering
  75 -- Level  N: Nth   level of clustering
  76 data PhyloLevel =
  77      PhyloLevel { _phylo_LevelId     :: PhyloLevelId
  78                 , _phylo_LevelGroups :: [PhyloGroup]
  79                 }
  80                 deriving (Generic)
  81
  82 type PhyloLevelId = (PhyloPeriodId, Int)
  83
  84 -- | PhyloGroup : group of ngrams at each level and step
  85 -- Label : maybe has a label as text
  86 -- Ngrams: set of terms that build the group
  87 -- Period Parents|Childs: weighted link to Parents|Childs (Temporal Period   axis)
  88 -- Level  Parents|Childs: weighted link to Parents|Childs (Level Granularity axis)
  89 data PhyloGroup =
  90      PhyloGroup { _phylo_GroupId    :: PhyloGroupId
  91                 , _phylo_GroupLabel :: Maybe Text
  92                 , _phylo_GroupNgrams        :: [NgramsId]
  93
  94                 , _phylo_GroupPeriodParents :: [Edge]
  95                 , _phylo_GroupPeriodChilds  :: [Edge]
  96
  97                 , _phylo_GroupLevelParents  :: [Edge]
  98                 , _phylo_GroupLevelChilds   :: [Edge]
  99                 }
 100                 deriving (Generic)
 101
 102 type PhyloGroupId = (PhyloLevelId, Int)
 103 type Edge         = (PhyloGroupId, Weight)
 104 type Weight       = Double
 105
 106 -- | JSON instances
 107 $(deriveJSON (unPrefix "_phylo_"       ) ''Phylo       )
 108 $(deriveJSON (unPrefix "_phylo_Period" ) ''PhyloPeriod )
 109 $(deriveJSON (unPrefix "_phylo_Level"  ) ''PhyloLevel  )
 110 $(deriveJSON (unPrefix "_phylo_Group"  ) ''PhyloGroup  )