+#' CLAWS: CLustering with wAvelets and Wer distanceS
+#'
+#' Cluster electricity power curves (or any series of similar nature) by applying a
+#' two stage procedure in parallel (see details).
+#' Input series must be sampled on the same time grid, no missing values.
+#'
+#' @details Summary of the function execution flow:
+#' \enumerate{
+#' \item Compute and serialize all contributions, obtained through discrete wavelet
+#' decomposition (see Antoniadis & al. [2013])
+#' \item Divide series into \code{ntasks} groups to process in parallel. In each task:
+#' \enumerate{
+#' \item iterate the first clustering algorithm on its aggregated outputs,
+#' on inputs of size \code{nb_items_clust}
+#' \item optionally, if WER=="mix":
+#' a) compute the K1 synchrones curves,
+#' b) compute WER distances (K1xK1 matrix) between synchrones and
+#' c) apply the second clustering algorithm
+#' }
+#' \item Launch a final task on the aggregated outputs of all previous tasks:
+#' in the case WER=="end" this task takes indices in input, otherwise
+#' (medoid) curves
+#' }
+#' The main argument -- \code{getSeries} -- has a quite misleading name, since it can be
+#' either a [big.]matrix, a CSV file, a connection or a user function to retrieve
+#' series; the name was chosen because all types of arguments are converted to a function.
+#' When \code{getSeries} is given as a function, it must take a single argument,
+#' 'indices', integer vector equal to the indices of the curves to retrieve;
+#' see SQLite example. The nature and role of other arguments should be clear
+#'
+#' @param getSeries Access to the (time-)series, which can be of one of the three
+#' following types:
+#' \itemize{
+#' \item [big.]matrix: each column contains the (time-ordered) values of one time-serie
+#' \item connection: any R connection object providing lines as described above
+#' \item character: name of a CSV file containing series in rows (no header)
+#' \item function: a custom way to retrieve the curves; it has only one argument:
+#' the indices of the series to be retrieved. See SQLite example
+#' }
+#' @param K1 Number of clusters to be found after stage 1 (K1 << N [number of series])
+#' @param K2 Number of clusters to be found after stage 2 (K2 << K1)
+#' @param nb_per_chunk (Maximum) number of items to retrieve in one batch, for both types of
+#' retrieval: resp. series and contribution; in a vector of size 2
+#' @param algo_clust1 Clustering algorithm for stage 1. A function which takes (data, K)
+#' as argument where data is a matrix in columns and K the desired number of clusters,
+#' and outputs K medoids ranks. Default: PAM
+#' @param algo_clust2 Clustering algorithm for stage 2. A function which takes (dists, K)
+#' as argument where dists is a matrix of distances and K the desired number of clusters,
+#' and outputs K clusters representatives (curves). Default: k-means
+#' @param nb_items_clust1 (Maximum) number of items in input of the clustering algorithm
+#' for stage 1
+#' @param wav_filt Wavelet transform filter; see ?wavelets::wt.filter
+#' @param contrib_type Type of contribution: "relative", "logit" or "absolute" (any prefix)
+#' @param WER "end" to apply stage 2 after stage 1 has fully iterated, or "mix" to apply
+#' stage 2 at the end of each task
+#' @param random TRUE (default) for random chunks repartition
+#' @param ntasks Number of tasks (parallel iterations to obtain K1 [if WER=="end"]
+#' or K2 [if WER=="mix"] medoids); default: 1.
+#' Note: ntasks << N (number of series), so that N is "roughly divisible" by ntasks
+#' @param ncores_tasks Number of parallel tasks (1 to disable: sequential tasks)
+#' @param ncores_clust Number of parallel clusterings in one task (4 should be a minimum)
+#' @param sep Separator in CSV input file (if any provided)
+#' @param nbytes Number of bytes to serialize a floating-point number; 4 or 8
+#' @param endian Endianness for (de)serialization ("little" or "big")
+#' @param verbose Level of verbosity (0/FALSE for nothing or 1/TRUE for all; devel stage)
+#' @param parll TRUE to fully parallelize; otherwise run sequentially (debug, comparison)
+#'
+#' @return A matrix of the final K2 medoids curves, in columns
+#'
+#' @references Clustering functional data using Wavelets [2013];
+#' A. Antoniadis, X. Brossat, J. Cugliari & J.-M. Poggi.
+#' Inter. J. of Wavelets, Multiresolution and Information Procesing,
+#' vol. 11, No 1, pp.1-30. doi:10.1142/S0219691313500033