Few words about ViSiElse

VisiElse is a graphical tool designed to visualize and to give an overview of behavioural observations realized on individuals or groups. For example, ViSiElse allows visualization of raw data during experimental observations of the realization of a procedure like a medical algorithm. It graphically presents an overview of individuals and group actions usually acquired from timestamps during video recorded sessions. Options of the package allow adding graphical information as statistical indicators (mean, standard deviation, quantiles or statistical tests) but also for each action green or black zones providing visual information about the accuracy of the realized actions.

The principle

ViSiElse concerns behavioural processes that, like a simulated healthcare procedure, can be decomposed in actions. We define two different types of actions in ViSiElse: punctual and long. The actions called punctual are brief actions defined as a time points. They do not last enough to be measured on the chosen time scale. The actions called long are the ones defined by duration. They are characterized by both a beginning punctual action and an ending one. In order to model a procedure, there is a need to sort actions in the way they are supposed to be realized as defined for example by medical consensus and/or algorithms for a medical procedure. This structure is stored in a S4-class object ViSibook, it can be modified, printed or plotted.

This Package contains two S4class of object: ViSibook and ViSigrid. Basically a ViSibook object will store information on a process like a health care procedure, then a ViSigrid object is built with observations of this procedure and the procedure ViSibook, and finally the graphic is obtained by plotting this ViSigrid object.

The minimum structure for a ViSibook object must give for each action its name (without special characters but " _ " ), its label, its type (punctual or long). For a long action, in addition it is necessary to provide the two specific actions that defined its starting and ending. The order by which actions are supposed to happen is also required.

Beyond the minimum structure green zones or/and black zones can be defined to help to visualize if a behaviour is realized on time.

A ViSigrid object is built using the function buildViSiGrid with at least a ViSibook and data of individual realization times for each punctual action.

A step by step example

We are presenting how to create a completely artificial example in order to provide a simple and clear overview of this package.

The process

The process underlining corresponds to an 8 steps procedure. It is built on the basis of a behaviour structure over 6 different punctual actions (brief action that does not last enough to measure its duration) and 2 long actions defined by the duration between a beginning punctual action and an ending one.

The process time restrictions are:

Construction of a ViSibook

Minimum structure

The minimum information to create a ViSibook is:

  • vars: Name of actions.
  • label: brief description of actions.
  • typeA: type of actions, “l” for long and “p” for punctual.
  • showorder: a vector storing order in which actions will be plotted. When an action is not to be plotted showorder should be NA.
  • deb: For long actions deb stores the punctual action name corresponding to its start.
  • fin: For long actions fin stores the punctual action name corresponding to its end.
    rm(list = ls())
    library(ViSiElse)
    vars <- c( "Action1" , "Action2" , "Action3" , "Action4" , "Action5" , 
               "Action6" , "Action7","Action8")
    label <- c( "Action 1", "Action 2", "Action 3", "Action 4", "Action 5", 
                "Action 6", "Action 7","Action 8" )
    typeA <- c( "p" , "l" , "p" , "p" , "p", "l" , "p" , "p" )
    deb <- rep(NA,8)
    deb[2] <- vars[1]
    deb[6] <- vars[4]
    fin <- rep( NA, 8)
    fin[2] <- vars[3]
    fin[6] <- vars[7]
    showorder <- c(1, 2 ,3 ,NA ,4 , 5, NA, 6 )
    book_df <- data.frame(vars ,label ,typeA ,showorder, deb,fin)
    book <-  ConvertoViSibook(book_df)
## Warning in .local(.Object, ...): No green zone defined for punctuals actions 
## 
    plot(book)

    print(book)
## .......................
##  Book of the process : 
##  
##  >>Punctual actions : 6
##     -Action1 
##         label : Action 1 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action3 
##         label : Action 3 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action4 
##         label : Action 4 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action5 
##         label : Action 5 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action7 
##         label : Action 7 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action8 
##         label : Action 8 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
## 
##  >>Long actions : 2 
##     -Action2 
##        label : Action 2 
##         Starts with : Action1 
##         Ends with   : Action3 
##          Black zone : NO  
##     -Action6 
##        label : Action 6 
##         Starts with : Action4 
##         Ends with   : Action7 
##          Black zone : NO  
## 
##  >> Process to be drawn : 6 actions
##           1 >> Action1
##                    v 
##           2 >> Action2
##                    v 
##           3 >> Action3
##                    v 
##           4 >> Action5
##                    v 
##           5 >> Action6
##                    v 
##           6 >> Action8
##  
##  .......................
##

Green and black zones

Now, to add restrictions on time to the process ViSiElse proposes to define green and black zones.

To define green and black zone for punctual actions we will add:

  • GZDeb: Green zone starting time.
  • GZFin: Green zone ending time.
  • Repetition: length of the time interval between green zones.
  • BZBeforeDeb: Black zone 1 starting time.
  • BZBeforeFin: Black zone 1 ending time.
  • BZAfterDeb: Black zone 2 starting time.
  • BZAfterFin: Black zone 2 ending time.

To define black zone for long actions we will add:

  • BZLong : Black zone time.
  • BZLtype : Type of the black zone :
    • “time” if the action should be finish at a time
    • “span” if the action should be finish in a time.
  GZDeb <- rep(NA,8)
  GZDeb[1] <- 10
  GZDeb[5] <- 35
  GZDeb[8] <- 60
  
  GZFin <- rep(NA,8)
  GZFin[1] <- 25
  GZFin[5] <- 40
  GZFin[8] <- 80
  
  Repetition <- rep(NA,8)
  Repetition[5] <- 20
  
  BZBeforeDeb <- rep(NA,8)
  BZBeforeDeb[ 8 ] <- 0
  
  BZBeforeFin <- rep(NA,8)
  BZBeforeFin[ 8 ] <- 55
  
  BZAfterDeb <- rep(NA,8)
  BZAfterDeb[ 8 ] <- 95
  BZAfterDeb[ 1 ] <- 25
  
  BZAfterFin <- rep(NA,8)
  BZAfterFin[ 8 ] <- Inf
  BZAfterFin[ 1 ] <- Inf
  
  BZLong <- rep(NA,8)
  BZLong[2] <- 5
  BZLong[6] <- 40
  
  BZLtype <- rep(NA,8)
  BZLtype[2] <- "span"
  BZLtype[6] <- "time"
  
  book_df <- data.frame(vars ,label ,typeA ,showorder, deb,fin,
                        GZDeb,GZFin, Repetition,BZBeforeDeb,BZBeforeFin,
                        BZAfterDeb,BZAfterFin, BZLong, BZLtype)
    book <-  ConvertoViSibook(book_df)
    plot(book)

    print(book)
## .......................
##  Book of the process : 
##  
##  >>Punctual actions : 6
##     -Action1 
##         label : Action 1 
##          Green zone   : 10 to 25 unit of time
##          Black zone 1 : NO  
##          Black zone 2 : 25 to Inf unit of time 
##      -Action3 
##         label : Action 3 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action4 
##         label : Action 4 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action5 
##         label : Action 5 
##          Green zone   : 35 to 40 unit of time, repeated every 20 unit of time 
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action7 
##         label : Action 7 
##          Green zone   : NO  
##          Black zone 1 : NO  
##          Black zone 2 : NO  
##     -Action8 
##         label : Action 8 
##          Green zone   : 60 to 80 unit of time
##          Black zone 1 : 0 to 55 unit of time 
##          Black zone 2 : 95 to Inf unit of time 
##  
##  >>Long actions : 2 
##     -Action2 
##        label : Action 2 
##         Starts with : Action1 
##         Ends with   : Action3 
##          Black zone : type span -- 5 unit of time 
##     -Action6 
##        label : Action 6 
##         Starts with : Action4 
##         Ends with   : Action7 
##          Black zone : type time -- 40 unit of time 
## 
##  >> Process to be drawn : 6 actions
##           1 >> Action1
##                    v 
##           2 >> Action2
##                    v 
##           3 >> Action3
##                    v 
##           4 >> Action5
##                    v 
##           5 >> Action6
##                    v 
##           6 >> Action8
##  
##  .......................
##

The Dataset

First

Concerning the procedure, only time for punctual actions are needed, but for all of them. They must have the names given in the slot vars of the ViSibook. The data.frame must also have a column to identify individuals.

Action1 <- rbinom(50, 25, 0.5)
Action3 <- Action1 + rbinom(50, 10, 0.9)
Action4 <- Action3 + rbinom(50, 20, 1/2)
Action5 <- Action4 + rbinom(50, 5, 1/3)
Action7 <- Action5 + rbinom(50, 100, 1/5)
Action8 <- Action7 + rbinom(50, 110, 1/3)
X <- data.frame(id = seq(1,50), Action1, Action3, Action4, Action5, Action7, Action8)
head(X)
##   id Action1 Action3 Action4 Action5 Action7 Action8
## 1  1      11      21      29      30      44      79
## 2  2      16      24      32      34      49      87
## 3  3      15      25      39      41      61      92
## 4  4      15      24      32      35      50      79
## 5  5      13      22      31      33      53      91
## 6  6      10      19      29      29      48      76

Then supplementary times

If an action is effectuated more than once its supplementary times should be store in a separate data.frame.

Here all individuals repeat the action 5 two times and a half of them will repeat it three times.

Action5sup1 <- Action5 + rep( 20, 50)
Action5sup2 <- Action5sup1[ seq( 1,25)] +  rep( 20, 25)
Action5sup3 <- Action5sup2 +  rep( 5, 25)
Action5sup <- c(Action5sup1, Action5sup2, Action5sup3)
id <- c( seq( 1,50), seq( 1,25), seq( 1,25))
Action1sup <- rep( NA, 50 + 25  + 25  )
Action3sup <- rep( NA, 50 + 25  + 25  )
Action4sup <- rep( NA, 50 + 25  + 25  )
Action7sup <- rep( NA, 50 + 25  + 25  )
Action8sup <- rep( NA, 50 + 25  + 25  )
Xsup <- data.frame(id , Action1sup, Action3sup, 
                   Action4sup, Action5sup, Action7sup, Action8sup)
colnames(Xsup) <- colnames(X)
head(Xsup)
##   id Action1 Action3 Action4 Action5 Action7 Action8
## 1  1      NA      NA      NA      50      NA      NA
## 2  2      NA      NA      NA      54      NA      NA
## 3  3      NA      NA      NA      61      NA      NA
## 4  4      NA      NA      NA      55      NA      NA
## 5  5      NA      NA      NA      53      NA      NA
## 6  6      NA      NA      NA      49      NA      NA

Building a ViSiGrid object

buildViSiGrid + plot

With a ViSibook and observational data stored as above, to obtain a representation of the process we need to:

  • Create a ViSigrid object with the function buildViSiGrid.
  • Plot this object.
x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x)

The parameter pixel

The parameter pixel represents the number of unit of time under which individuals are aggregated for punctual action in the plot. When the parameter pixel is too small the information represented will be too much aggregated to allow interpretation.

For punctual actions data are aggregated in a matrix \(M\) . The number of row of \(M\) is the number of action and its number of columns is \([ ( max(X)-t_0 )/pixel]\).

\(M_{i,j}\) contains the number of observations of the \(i\)-th punctual action (by the order of the ViSibook object) between \(t_0 + (j-1)pixel\) included and \(t_0 + j \times pixel\) excluded.

Here the action 1 occurred within the first second so pixel should be set small enough.

x <-  buildViSiGrid( X = X, book = book, pixel = 5, Xsup = Xsup )
plot(x, main = "PIXEL = 5")

x <-  buildViSiGrid( X = X, book = book, pixel = 20, Xsup = Xsup )
plot(x, main = "PIXEL = 20")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x, main = "PIXEL = 1")

The parameter informer

The parameter informer allows choosing an indicator. Informer can take three values:

  • median: Median and quartiles are calculated for each action, using the function quantile from the package stats. This is the default value.
  • mean: Mean and standard deviation are calculated for each action, using the functions mean and var from the package stats.
  • NULL: no indicators are computed.

When a group is declared indicators are calculated by group if the method cut or within is chosen. When plotting, indicators for a punctual action are represented by white circles linked by a line. For long action, only a black line is plotted from the median (or mean) of the punctual action staring it. The line length represents the median (or mean) of the long action duration.

Informers are computed directly on the given matrix for punctual actions. For a long action it is calculated on the difference between the beginning punctual action and the ending one. 

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x, main = "informer =  Median")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup,  informer = "mean" )
plot(x, main = "informer =  Mean")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup,  informer = NULL )
plot(x, main = "informer =  NULL")

The starting time

The origin of the graphic can be set using the parameter t_0. There is two ways to define it:

  • A number: set to 0. It can be change at convenience, but for long actions black zones will not be drawn, and for punctual actions black and green zones will not be translated.
  • The name of a punctual action: To set the origin of the graphic to the moment when the action was done for each individual. Black and green zones will not be translated as well.
x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x, main = "t_0 =  0")

x <-  buildViSiGrid( X = X, book = book, pixel = 1,  t_0 = 10 )
plot(x, main = "t_0 = 10")

x <-  buildViSiGrid( X = X, book = book, pixel = 1,  t_0 = "Action1" )
plot(x, main = "t_0 = Action1")

Now, we suppress the drawing of the action 1 and the action 5 green zones.

book_change <- changeShoworder( book, c(2,3,4,5,6) )
book_change[5,7] <- NA
book_change[5,8] <- NA
book_change[5,9] <- NA
x <-  buildViSiGrid( X = X, book = book_change, pixel = 1,  t_0 = "Action1" )
plot(x, main = "t_0 = Action1")

The parameter quantity

This parameter allows choosing the quantity represented for punctual actions.

  • N: Number of individuals is considered.
  • dens: Proportion of individuals is considered. This setting is useful when representing groups. When group is defined and method set to “cut” or “within”, this proportion is calculated regarding each represented group.
x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x, main = " quantity = N")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup,  quantity = "dens" )
plot(x, main = " quantity = dens")

Sort long action: sorted.line

The parameter sorted.line allows long actions to be sorted by starting time.

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x, main = " sorted.line = TRUE")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup, sorted.line = FALSE )
plot(x, main = "sorted.line = FALSE")

Representing Groups

Three graphics to represent groups

ViSiElse offers the possibility to represent two groups of individuals, and proposes three graphics to do so using the parameter method:

  • cut: Each group will be plotted apart within each action line in the graphic.
  • join: Groups will be plotted gathered within each action line in the graphic.
  • within: For each action line in the graphic, there will be two parts, as for the method cut, the difference is that the first line will plot all individuals and the second line will concern individuals belonging to the group specified in the parameter grwithin.
group = c(rep( "G1", 15),rep("G2",35))
x <-  buildViSiGrid( X = X, book = book, pixel = 1, group = group, method = "cut" )
plot(x, main = " Method = cut ")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, group = group, method = "join" )
plot(x, main = " Method = join ")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, group = group, method = "within", 
                     grwithin = "G1"  )
plot(x, main = " Method = within ; group1 ")

x <-  buildViSiGrid( X = X, book = book, pixel = 1, group = group, method = "within", 
                     grwithin = "G2", quantity = "dens"  )
plot(x, main = " Method = within ; group2 / density of ind ")

Tests

ViSiElse allows applying statistical tests in order to compare groups.

  • When the parameter informer is set to “mean”, the function wilcox.test() is used.
  • When informer is set to “median” the function mood.test() is used.

As for the parameter informer. Tests are computed on the given data.frame X for punctual action. And for a long action it is calculated on its difference between its beginning and ending punctual actions.

Results of the tests are represented by a star only when the resulted p-value is bellow or equal to the parameter threshold.test.

x <-  buildViSiGrid( X = X, book = book, group = group, method = "cut" , pixel = 1, 
                     tests = TRUE )
plot(x, main = " test, threshold p-value 0.01")

x <-  buildViSiGrid( X = X, book = book, group = group, method = "cut" , pixel = 1, 
                     tests = TRUE, threshold.test = 0.5  )
plot(x, main = " test, threshold p-value 0.5")

Sort long actions: decrgr2

When sorted.line is TRUE, the parameter decrgr2 allows long actions of the second group to be plotted in decreasing order by starting times.

x <-  buildViSiGrid( X = X, book = book, group = group, method = "cut" , pixel = 1, 
                     Xsup = Xsup )
plot(x, main = " decrgr2=FALSE")

x <-  buildViSiGrid( X = X, book = book, group = group, method = "cut" , pixel = 1, 
                     Xsup = Xsup, decrgr2 = TRUE )
plot(x, main = "decrgr2 = TRUE")

Any question?

If you have any request or comment >> https://github.com/CEPOI/ViSiElse

…