ViSiElse: Function 'visielse'
In ViSiElse: A Visual Tool for Behavior Analysis over Time

Description Usage Arguments Details Value See Also Examples

visielse plots the graphic from time data and build an object class ViSigrid with, at least, the time data of each punctual action defined in the ViSibook for all subjects.

visielse(X, book = NULL, is.ViSibook = FALSE, doplot = TRUE,
  Xsup = NULL, method = "global", group = NULL, grwithin = NULL,
  informer = "median", tests = TRUE, threshold.test = 0.01,
  quantity = "N", pixel = 20, t_0 = 0, sorted.line = TRUE,
  decrgr2 = FALSE, max_tps = NULL, colvect = NULL, ncolvect = NULL,
  times = FALSE, timeformat = c("hh:mm:ss"), idsubject = 1)

`X`	A `data.frame` or `matrix`. `X` stores punctual action timestamps. The actions are defined in `book`, and X columns names should correspond to the slot "vars" of `book`. X must also have a column to identify individuals (id column).
`book`	A `data.frame` or a `ViSibook` or NULL. `book` stores the process structure. If it is a `data.frame` it should contains at least the columns vars, label, typeA, showorder, deb, fin . Optionally, other characteristics can be filled : GZDebn, GZFin, Repetition, BZBeforeDeb, BZBeforeFin, BZAfterDeb, BZAfterFin, BZLong , BZLtype . If it is a `ViSibook` it should correspond to the columns names of X. If it is `NULL` the process is the ordered list of punctual actions given by the columns names of X.
`is.ViSibook`	A logical `FALSE` if book is a `data.frame` or `NULL`. `TRUE` is book is a ViSibook.
`doplot`	A logical If `FALSE`, the graphic is not plotted.
`Xsup`	A `data.frame` or `matrix` storing supplementary time data, all individuals in `Xsup` must be in `X`.
`method`	In { `"global"` , `"cut"` , `"join"` , `"within"` }. `method` specifies the plotting method, see `details`. If `group` is `NULL`, `method` is set to `"global"`.
`group`	A `factor` with two `levels`. `group` indicates the group attributed to the individuals, it has same the length as the number of rows of `X`.
`grwithin`	A level of `group`. If `method` is set to `within`, `grwithin` specifies the group to consider.
`informer`	In { "`NULL`" , "`median`" , "`mean`" }. If `informer` is set to "median" the median and quartiles are computed, if it is set to "mean" the mean and standard deviation are. If `informer` is `NULL` no indicators are computed.
`tests`	A boolean. When `informer` is not NULL and `group` is defined, if `tests` is `TRUE`, tests are computed to compare groups. If the parameter `informer` is set to "`mean`", the function `wilcox.test()` is used, if `informer` is set to "`median`" the function `mood.test()` is used.
`threshold.test`	A numeric between 0 and 1. `threshold.test` is the value of the p-value under which the H0 hypothesis of the test is rejected when `tests` is `TRUE`.
`quantity`	In { "`N`" , "`dens`" }. `quantity` allows choosing the quantity represented for punctual action When `quantity` is set to "N" the number of individuals is considered. Otherwise when it is set to "dens" proportion of individuals is considered instead. If `group` is defined and `method` set to "cut" or "within", this proportion is calculated regarding each represented group.
`pixel`	An integer. It is the number of unit of time under which individuals are aggregated in the plot.
`t_0`	either 0, either a value of the slot "`vars`" in `book`, `t_0` indicates the starting time to plot.
`sorted.line`	A boolean. When `sorted.line` is `TRUE`, it allows long actions to be sorted by starting time.
`decrgr2`	A boolean. When sorted.line is TRUE and decrgr2 is TRUE, long actions of the second group are plotted in decreasing order by starting times.
`max_tps`	A numeric, `>0`. `max_tps` is the maximum time used to build the grid in the plot. `max_tps` is useful when `Xsup` is given. If `max_tps` is `NULL` it is automatically computed.
`colvect`	A `matrix` containing colors. Colors are automatically computed if `colvect` is `NULL`. If `group` is not `NULL` colvect should have two rows otherwise one.
`ncolvect`	A `numeric`. `ncolvect` indicates the number of columns of `colvect`. Its default setting is `dim(X)[1]`. `ncolvect` is considered only if `colvect` is `NULL`.
`times`	A boolean. If `times` is `TRUE`, it indicates that `X` contains data in a time format.
`timeformat`	time format. If `times` is `TRUE`.
`idsubject`	An integer between 1 and `dim(X)[2]`. `idsubject` indicates the number of the column of X that contains individuals id numbers.

method
- global : The plot of the ViSigrid object will not consider the parameter group and plot indistinctly all individuals.
- cut : In the plot of the ViSigrid object, each group will be plotted separately, one under the other with different colors.
- join : In the plot of the ViSigrid object, groups are spatially mixed but they are represented by different colors.
- within : In the plot of the ViSigrid object, all individuals are plotted together then the group specified in grwithin is plotted another time underneath.
informer

The parameter informer allows users to choose the statistics to be plotted. 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 defined, statistics are calculated per group if the method cut or within is chosen.

When plotting the ViSigrid object, statistics for punctual actions are represented by white circles linked by a line. For long action, only a black line is plotted starting at the median (or mean) value of the punctual action staring times. The line length represents the median (or mean) of the long action duration. Informers are computed directly on the given matrix for punctual action. And for long actions, it is based on the difference between the punctual action defining its beginning and the one defining its ending.
tests and threshold.test

As for the parameter informer, tests are computed on the given matrix or data.frame X for a punctual action. And for a long action, it is calculated on its difference between its beginning and its ending punctual actions. In plot-ViSigrid-method, results of the tests are represented by a star only when the resulted p-value is bellow or equal to value defined by the parameter threshold.test.
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*pixel excluded.
t_0

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 can also has the columns : GZDebn, GZFin, Repetition, BZBeforeDeb, BZBeforeFin, BZAfterDeb, BZAfterFin, BZLong , BZLtype

a ViSigrid object.

Classes ViSigrid and ViSibook. The method plot for ViSigrid object plot-ViSigrid-method for examples.

coffee <- c(  58, 11,  5, 53, 53, 59, 24, 59, 46, 20)
fill_coffee <- c(162,  57,103,154,165,132,  74, 107, 104,  93)
fill_water <- c(  66,  92,54, 78, 74, 114, 91, 129, 71, 56)
push_B <- c( 74, 99, 62, 84, 83, 120, 95, 129, 80, 63 )
drink <- c( 472, 176, 475, 283, 265, 207, 234, 184, 490, 520)
X <- data.frame(id = seq(1,10), coffee, fill_coffee,fill_water,push_B,drink)
library(ViSiElse)
visi1 <- visielse(X)

#### Changing the pixel of time

visi1 <- visielse(X, pixel = 10)
# Plot the mean and standart deviation

visi1 <- visielse(X,informer = "mean")

#### Do not plot indicators
visi1 <- visielse(X,informer = NULL)


# Extraction of the visibook from the data

visi1 <- visielse(X,informer = NULL, doplot = FALSE)
book <- visi1@book
plot(book)

#### Changing labels

book[,2]<- c("Taking the coffee",
             "Fill the machine with coffee",
             "Fill the tank with water",
             "Push the Button",
             "Drink the coffee")
plot(book)
visi1 <- visielse(X, book=book, is.ViSibook = TRUE,informer = NULL)


#### Change the order of Actions in the process

book[,4]<- c(5,1,2,4,3)
plot(book)
visi1 <- visielse(X, book=book, is.ViSibook = TRUE)



#### Adding a long Actions

visi1 <- visielse( X )
book <- ConvertFromViSibook( visi1@book ) # Convert book into data.frame
add_delay <- c( "delay_coffee_push","Preparation","l","6","coffee","push_B")
book[6,] <- add_delay
book


### ViSiElse representation of long actions

visi2 <- visielse( X=X , book=book,informer=NULL)

## Green & Black zones

book$GZDeb <- c(NA,60,NA,NA,NA,NA)
book$GZFin <- c(NA,120,NA,NA,NA,NA)
book$BZBeforeDeb <- c(NA,0,NA,NA,NA,NA)
book$BZBeforeFin <- c(NA,30,NA,NA,NA,NA)
book$BZAfterDeb <- c(NA,180,NA,NA,NA,NA)
book$BZAfterFin <- c(NA,Inf,NA,NA,NA,NA)
book$BZLong <- c(rep(NA,5),150)
book$BZLtype <- c(rep(NA,5),"time")
visi1 <- visielse( X, book=book , informer = NULL)

book$BZLtype <- c(rep(NA,5),"span")
visi1 <- visielse( X, book=book ,informer = NULL)


## Group

### Method : Cut
group <- c( "group2","group1","group2","group1","group1",
             "group2","group1","group1","group1","group2")
visi1 <- visielse( X,group=group, book=book ,informer = NULL, method = "cut")

visi1 <- visielse( X,group=group, book=book ,informer = NULL, method = "join")

visi1 <- visielse( X,group=group, book=book ,informer = NULL, method = "within",grwithin = "group1")