with parallel::export

[epclust.git] / epclust / R / main.R

#' @title Cluster power curves with PAM in parallel
#'
#' @description Groups electricity power curves (or any series of similar nature) by applying PAM
#' algorithm in parallel to chunks of size \code{nb_series_per_chunk}
#'
#' @param data Access to the data, which can be of one of the three following types:
#' \itemize{
#'   \item data.frame: each line contains its ID in the first cell, and all values after
#'   \item connection: any R connection object (e.g. a file) providing lines as described above
#'   \item function: a custom way to retrieve the curves; it has two arguments: the ranks to be
#'     retrieved, and the IDs - at least one of them must be present (priority: ranks).
#' }
#' @param K1 Number of super-consumers to be found after stage 1 (K1 << N)
#' @param K2 Number of clusters to be found after stage 2 (K2 << K1)
#' @param ntasks Number of tasks (parallel iterations to obtain K1 medoids); default: 1.
#'   Note: ntasks << N, so that N is "roughly divisible" by N (number of series)
#' @param nb_series_per_chunk (Maximum) number of series in each group, inside a task
#' @param min_series_per_chunk Minimum number of series in each group
#' @param wf Wavelet transform filter; see ?wt.filter. Default: haar
#' @param WER "end" to apply stage 2 after stage 1 has iterated and finished, or "mix"
#'   to apply it after every stage 1
#' @param ncores_tasks "MPI" number of parallel tasks (1 to disable: sequential tasks)
#' @param ncores_clust "OpenMP" number of parallel clusterings in one task
#' @param random Randomize chunks repartition
#' @param ... Other arguments to be passed to \code{data} function
#'
#' @return A data.frame of the final medoids curves (identifiers + values)
#'
#' @examples
#' getData = function(start, n) {
#'   con = dbConnect(drv = RSQLite::SQLite(), dbname = "mydata.sqlite")
#'   df = dbGetQuery(con, paste(
#'     "SELECT * FROM times_values GROUP BY id OFFSET ",start,
#'     "LIMIT ", n, " ORDER BY date", sep=""))
#'   return (df)
#' }
#'   #TODO: 3 examples, data.frame / binary file / DB sqLite
#'   + sampleCurves : wavBootstrap de package wmtsa
#' cl = epclust(getData, K1=200, K2=15, ntasks=1000, nb_series_per_chunk=5000, WER="mix")
#' @export
epclust = function(series,K1,K2,ntasks=1,nb_series_per_chunk=50*K1,min_series_per_chunk=5*K1,
	wf="haar",WER="end",ncores_tasks=1,ncores_clust=4,random=TRUE,...)
{
	# Check/transform arguments
	bin_dir = "epclust.bin/"
	dir.create(bin_dir, showWarnings=FALSE, mode="0755")
	if (!is.function(series))
	{
		series_file = paste(bin_dir,"data",sep="")
		unlink(series_file)
	}
	if (is.matrix(series))
		serialize(series, series_file)
	else if (!is.function(series))
	{
		tryCatch(
			{
				if (is.character(series))
					series_con = file(series, open="r")
				else if (!isOpen(series))
				{
					open(series)
					series_con = series
				}
				serialize(series_con, series_file)
				close(series_con)
			},
			error=function(e) "series should be a data.frame, a function or a valid connection"
		)
	}
	if (!is.function(series))
		series = function(indices) getDataInFile(indices, series_file)
	getSeries = series

	K1 = toInteger(K1, function(x) x>=2)
	K2 = toInteger(K2, function(x) x>=2)
	ntasks = toInteger(ntasks, function(x) x>=1)
	nb_series_per_chunk = toInteger(nb_series_per_chunk, function(x) x>=K1)
	min_series_per_chunk = toInteger(K1, function(x) x>=K1 && x<=nb_series_per_chunk)
	ncores_tasks = toInteger(ncores_tasks, function(x) x>=1)
	ncores_clust = toInteger(ncores_clust, function(x) x>=1)
	if (WER!="end" && WER!="mix")
		stop("WER takes values in {'end','mix'}")

	# Serialize all wavelets coefficients (+ IDs) onto a file
	coefs_file = paste(bin_dir,"coefs",sep="")
	unlink(coefs_file)
	index = 1
	nb_curves = 0
	repeat
	{
		series = getSeries((index-1)+seq_len(nb_series_per_chunk))
		if (is.null(series))
			break
		coeffs_chunk = curvesToCoeffs(series, wf)
		serialize(coeffs_chunk, coefs_file)
		index = index + nb_series_per_chunk
		nb_curves = nb_curves + nrow(coeffs_chunk)
	}
	getCoefs = function(indices) getDataInFile(indices, coefs_file)
######TODO: if DB, array rank --> ID at first retrieval, when computing coeffs; so:: NO use of IDs !

	if (nb_curves < min_series_per_chunk)
		stop("Not enough data: less rows than min_series_per_chunk!")
	nb_series_per_task = round(nb_curves / ntasks)
	if (nb_series_per_task < min_series_per_chunk)
		stop("Too many tasks: less series in one task than min_series_per_chunk!")

	# Cluster coefficients in parallel (by nb_series_per_chunk)
	indices = if (random) sample(nb_curves) else seq_len(nb_curves)
	indices_tasks = lapply(seq_len(ntasks), function(i) {
		upper_bound = ifelse( i<ntasks, min(nb_series_per_task*i,nb_curves), nb_curves )
		indices[((i-1)*nb_series_per_task+1):upper_bound]
	})
	cl_tasks = parallel::makeCluster(ncores_tasks)
	parallel::clusterExport(cl_tasks,
		varlist=c("getSeries","getCoefs","K1","K2","WER","nb_series_per_chunk","ncores_clust"),
		envir=environment())
	#1000*K1 (or K2) indices (or NOTHING--> series on file)
	indices = parallel::parLapply(cl_tasks, indices_tasks, clusteringTask)
	parallel::stopCluster(cl_tasks)

	#Now series must be retrieved from synchrones_file, and have no ID
	getSeries = function(indices, ids) getDataInFile(indices, synchrones_file)

	# Run step2 on resulting indices or series (from file)
	computeClusters2(indices=if (WER=="end") indices else NULL, K2, to_file=FALSE)
}