First commit
[epclust.git] / pkg / man / claws.Rd
... / ...
CommitLineData
1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/main.R
3\name{claws}
4\alias{claws}
5\title{CLAWS: CLustering with wAvelets and Wer distanceS}
6\usage{
7claws(getSeries, K1, K2, wf, ctype, WER = "end", random = TRUE,
8 ntasks = 1, ncores_tasks = 1, ncores_clust = 4,
9 nb_series_per_chunk = 50 * K1, min_series_per_chunk = 5 * K1, sep = ",",
10 nbytes = 4, endian = .Platform$endian, verbose = FALSE, parll = TRUE)
11}
12\arguments{
13\item{getSeries}{Access to the (time-)series, which can be of one of the three
14following types:
15\itemize{
16 \item [big.]matrix: each line contains all the values for one time-serie, ordered by time
17 \item connection: any R connection object providing lines as described above
18 \item character: name of a CSV file containing series in rows (no header)
19 \item function: a custom way to retrieve the curves; it has only one argument:
20 the indices of the series to be retrieved. See examples
21}}
22
23\item{K1}{Number of super-consumers to be found after stage 1 (K1 << N)}
24
25\item{K2}{Number of clusters to be found after stage 2 (K2 << K1)}
26
27\item{wf}{Wavelet transform filter; see ?wavelets::wt.filter}
28
29\item{ctype}{Type of contribution: "relative" or "absolute" (or any prefix)}
30
31\item{WER}{"end" to apply stage 2 after stage 1 has fully iterated, or "mix" to apply stage 2
32at the end of each task}
33
34\item{random}{TRUE (default) for random chunks repartition}
35
36\item{ntasks}{Number of tasks (parallel iterations to obtain K1 medoids); default: 1.
37Note: ntasks << N, so that N is "roughly divisible" by N (number of series)}
38
39\item{ncores_tasks}{"MPI" number of parallel tasks (1 to disable: sequential tasks)}
40
41\item{ncores_clust}{"OpenMP" number of parallel clusterings in one task}
42
43\item{nb_series_per_chunk}{(~Maximum) number of series in each group, inside a task}
44
45\item{min_series_per_chunk}{Minimum number of series in each group}
46
47\item{sep}{Separator in CSV input file (if any provided)}
48
49\item{nbytes}{Number of bytes to serialize a floating-point number; 4 or 8}
50
51\item{endian}{Endianness to use for (de)serialization. Use "little" or "big" for portability}
52
53\item{verbose}{Level of verbosity (0/FALSE for nothing or 1/TRUE for all; devel stage)}
54
55\item{parll}{TRUE to fully parallelize; otherwise run sequentially (debug, comparison)}
56}
57\value{
58A big.matrix of the final medoids curves (K2) in rows
59}
60\description{
61Groups electricity power curves (or any series of similar nature) by applying PAM
62algorithm in parallel to chunks of size \code{nb_series_per_chunk}. Input series
63must be sampled on the same time grid, no missing values.
64}
65\examples{
66\dontrun{
67# WER distances computations are a bit too long for CRAN (for now)
68
69# Random series around cos(x,2x,3x)/sin(x,2x,3x)
70x = seq(0,500,0.05)
71L = length(x) #10001
72ref_series = matrix( c(cos(x), cos(2*x), cos(3*x), sin(x), sin(2*x), sin(3*x)),
73 byrow=TRUE, ncol=L )
74library(wmtsa)
75series = do.call( rbind, lapply( 1:6, function(i)
76 do.call(rbind, wmtsa::wavBootstrap(ref_series[i,], n.realization=400)) ) )
77#dim(series) #c(2400,10001)
78medoids_ascii = claws(series, K1=60, K2=6, "d8", "rel", nb_series_per_chunk=500)
79
80# Same example, from CSV file
81csv_file = "/tmp/epclust_series.csv"
82write.table(series, csv_file, sep=",", row.names=FALSE, col.names=FALSE)
83medoids_csv = claws(csv_file, K1=60, K2=6, "d8", "rel", nb_series_per_chunk=500)
84
85# Same example, from binary file
86bin_file = "/tmp/epclust_series.bin"
87nbytes = 8
88endian = "little"
89epclust::binarize(csv_file, bin_file, 500, nbytes, endian)
90getSeries = function(indices) getDataInFile(indices, bin_file, nbytes, endian)
91medoids_bin = claws(getSeries, K1=60, K2=6, "d8", "rel", nb_series_per_chunk=500)
92unlink(csv_file)
93unlink(bin_file)
94
95# Same example, from SQLite database
96library(DBI)
97series_db <- dbConnect(RSQLite::SQLite(), "file::memory:")
98# Prepare data.frame in DB-format
99n = nrow(series)
100time_values = data.frame(
101 id = rep(1:n,each=L),
102 time = rep( as.POSIXct(1800*(0:n),"GMT",origin="2001-01-01"), L ),
103 value = as.double(t(series)) )
104dbWriteTable(series_db, "times_values", times_values)
105# Fill associative array, map index to identifier
106indexToID_inDB <- as.character(
107 dbGetQuery(series_db, 'SELECT DISTINCT id FROM time_values')[,"id"] )
108getSeries = function(indices) {
109 request = "SELECT id,value FROM times_values WHERE id in ("
110 for (i in indices)
111 request = paste(request, i, ",", sep="")
112 request = paste(request, ")", sep="")
113 df_series = dbGetQuery(series_db, request)
114 # Assume that all series share same length at this stage
115 ts_length = sum(df_series[,"id"] == df_series[1,"id"])
116 t( as.matrix(df_series[,"value"], nrow=ts_length) )
117}
118medoids_db = claws(getSeries, K1=60, K2=6, "d8", "rel", nb_series_per_chunk=500)
119dbDisconnect(series_db)
120
121# All computed medoids should be the same:
122digest::sha1(medoids_ascii)
123digest::sha1(medoids_csv)
124digest::sha1(medoids_bin)
125digest::sha1(medoids_db)
126}
127}