visielse: Function `visielse`

Description

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.

Usage

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)

Arguments

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.

Value

a ViSigrid object.

Details

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

Examples

Run this code

# NOT RUN {
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")
# }