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.
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.
We are presenting how to create a completely artificial example in order to provide a simple and clear overview of this package.
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:
The minimum information to create a ViSibook is:
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
##
## .......................
##
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:
To define black zone for long actions we will add:
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
##
## .......................
##
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
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
With a ViSibook and observational data stored as above, to obtain a representation of the process we need to:
x <- buildViSiGrid( X = X, book = book, pixel = 1, Xsup = Xsup )
plot(x)
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 allows choosing an indicator. Informer can take three values:
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 origin of the graphic can be set using the parameter t_0. There is two ways to define it:
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")
This parameter allows choosing the quantity represented for punctual actions.
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")
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")
ViSiElse offers the possibility to represent two groups of individuals, and proposes three graphics to do so using the parameter method:
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 ")
ViSiElse allows applying statistical tests in order to compare groups.
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")
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")