kml3d-package {kml3d}

~ Overview: KmL3D, K-means for joint Longitudinal data ~

Description

KmL3D is a new implementation of k-means for longitudinal data (or trajectories). Here is an overview of the package.

Details

Package:	KmL3D
Type:	Package
Version:	2.4.2
Date:	2017-08-01
License:	GPL (>= 2)
LazyData:	yes
Depends:	methods,graphics,rgl,misc3d,longitudinalData(>=2.2),KmL(>=2.2)
URL:	http://www.r-project.org
URL:	http://christophe.genolini.free.fr/kml

Overview

To cluster data, KmL3D go through three steps, each of which is associated to some functions:

1. Data preparation

2. Building "optimal" clusterization.

3. Exporting results

4. Visualizing and exporting 3D object

1. Data preparation

kml3d works on object of class ClusterLongData3d. Data preparation therefore simply consists in transforming data into an object ClusterLongData3d. This can be done via function clusterLongData3d (cld3d in short) that converts a data.frame or an array into a ClusterLongData3d.

Working on several variables mesured on different scales can give to much weight to one of the dimension. So the function scale normalizes data.

Instead of working on real data, one can also work on artificial data. Such data can be created with generateArtificialLongData3d (gald3d in short).

2. Building "optimal" clustering

Once an object of class ClusterLongData3d has been created, the algorithm kml3d can be run.

Starting with a ClusterLongData3d, kml3d built several Partition. A object of class Partition is a partition of trajectories into subgroups. It also contains some information like the percentage of trajectories contained in each group or some quality critetion (like the Calinski & Harabasz).

k-means is a "hill-climbing" algorithm. The specificity of this kind of algorithm is that it always converges towards a maximum, but one cannot know whether it is a local or a global maximum. It offers no guarantee of optimality.

To maximize one's chances of getting a quality Partition, it is better to execute the hill climbing algorithm several times, then to choose the best solution. By default, kml3d executes the hill climbing algorithm 20 times.

To date, it is not possible to know the optimum number of clusters even if the calculatous of some qualities criterion can gives some clues. kml3d computes various of them.

In the end, kml3d tests by default 2, 3, 4, 5 et 6 clusters, 20 times each.

3. Exporting results

When kml3d has constructed some Partition, the user can examine them one by one and choose to export some. This can be done via function choice. choice opens a graphic windows showing various information including the trajectories cluterized by a specific Partition.

When some Partition has been selected (the user can select more than 1), it is possible to save them. The clusters are therefore exported towards the file name-cluster.csv. Criteria are exported towards name-criteres.csv. The graphs are exported according to their extension.

4. Visualizing and exporting 3D object

KmL3D also propose tools to visualize the trajectories in 3D. plot3d using the library rgl to plot two variables according to time (either the all set of joint-trajectories, or just the mean joint-trajectories). Then the user can make the graphical representation turn using the mouse. plot3dPdf build an Triangles object. These kind of object can be include in a pdf file using saveTrianglesAsASY and the software asymptote. Once again, it is possible to make the image in the pdf file move using the mouse -so the reader gets real 3D-.

How to get help?

For those who are not familiar with S4 programming: In S4 programming, each function can be adapted for some specific arguments.

• To get help on a function (for example plot), use: ?(plot).

• To get help on a function adapted to its argument (for example plot on argument ClusterLongData), used: ?"plot,ClusterLongData".

Examples

### Move to tempdir
wd <- getwd()
setwd(tempdir()); getwd()

### 1. Data Preparation
data(pregnandiol)
names(pregnandiol)
cld3dPregTemp <- cld3d(pregnandiol,timeInData=list(temp=1:30*2,preg=1:30*2+1))

### 2. Building "optimal" clusteration (with only 2 redrawings)
###    Real analysis needs at least 20 redrawings
kml3d(cld3dPregTemp,3:5,nbRedrawing=2,toPlot="both")

### 3. Exporting results
try(choice(cld3dPregTemp))

### 4. Visualizing in 3D
plotMeans3d(cld3dPregTemp,4)

### Go back to current dir
setwd(wd)