X-Git-Url: https://git.auder.net/?p=synclust.git;a=blobdiff_plain;f=R%2Fmain.R;fp=R%2Fmain.R;h=cc9598cf0b226fbf790e768aa4d53bb1045462d1;hp=0160b581331f8f7e589b97a8928bbd6425312fec;hb=ad26cb61b84c4d603980d0da65a9ed19cc9af778;hpb=7ff8c3e6b0960158f79275fd4a407b30690fd120

diff --git a/R/main.R b/R/main.R
index 0160b58..cc9598c 100644
--- a/R/main.R
+++ b/R/main.R
@@ -1,43 +1,42 @@
-#example of "not too bad" parameters
-#~ k=10
-#~ alpha=0.1 
-#~ gmode=1 
-#~ K = 5 
-#~ dtype = "spath"
-#~ cmeth = "HC"
-#~ pcoef=??
-#~ h=??
-#~ eps=??
-#~ maxit=??
-
-#MAIN FUNCTION : direct clustering from a neighborhoods graph, or get regions
-#from (Poisson) distribution parameters optimization, using convex relaxation.
-findSyncVarRegions = function(
-	method, #global method: "direct" or "convex"
-	M, #matrix of observations in rows, the two last columns 
-	   #corresponding to geographic coordinates; 
-	   #set to NULL to use our initial dataset (625 rows / 9 years)
-	k, #number of neighbors
-	alpha, #weight parameter for intra-neighborhoods distance computations
-	       #0 = take only geographic coordinates into account
-	       #1 = take only observations over the years into account
-	       #in-between : several levels of compromise
-	       #-1 or any negative value : use a heuristic to choose alpha
-	gmode, #0 = reduced [mutual] kNN; 1 = augmented kNN; (symmetric)
-	       #2 = normal kNN; 3 = one NN in each quadrant; (NON-symmetric)
-		   #NOTE: gmode==3 automatically sets k==4 (at most!)
-	K, #number of clusters
-	dtype, #distance type, in {"simple","spath","ectd"}.
-	       #NOTE: better avoid "simple" if gmode>=2
-	cmeth, #clustering method, in {"KM","HC","spec"} for k-means (distances based) 
-	       #or hierarchical clustering, or spectral clustering (only if gmode>=2)
-	pcoef=1.0, #penalty value for convex optimization
-	h=1e-3, #step in the min LL algorithm
-	eps=1e-3, #threshold to stop min.LL iterations
-	maxit=1e3, #maximum number of iterations in the min LL algo
-	showLL=TRUE, #print trace of log-likelihood evolution
-	disp=TRUE #true for interactive display (otherwise nothing gets plotted)
-) {
+#' Direct clustering from a neighborhoods graph, or get regions from (Poisson) 
+#' distribution parameters optimization, using convex relaxation.
+#'
+#' @param method Global method: "direct" or "convex"
+#' @param M Matrix of observations in rows, the two last columns 
+#'        corresponding to geographic coordinates; 
+#'        set to NULL to use our initial dataset (625 rows / 9 years)
+#' @param k Number of neighbors
+#' @param alpha Weight parameter for intra-neighborhoods distance computations; 
+#'        0 = take only geographic coordinates into account; 
+#'        1 = take only observations over the years into account; 
+#'        in-between : several levels of compromise; 
+#'        -1 or any negative value : use a heuristic to choose alpha.
+#' @param gmode Neighborhood type. 0 = reduced [mutual] kNN; 1 = augmented kNN (symmetric); 
+#'        2 = normal kNN; 3 = one NN in each quadrant; (NON-symmetric). 
+#'        NOTE: gmode==3 automatically sets k==4 (at most!)
+#' @param K Number of clusters
+#' @param dtype Distance type, in {"simple","spath","ectd"}. 
+#'        NOTE: better avoid "simple" if gmode>=2
+#' @param cmeth Clustering method, in {"KM","HC","spec"} for k-means (distances based) 
+#'        or hierarchical clustering, or spectral clustering (only if gmode>=2)
+#' @param pcoef Penalty value for convex optimization [default: 1.0]
+#' @param h Step in the min LL algorithm [default: 1e-3]
+#' @param eps Threshold to stop min.LL iterations [default: 1e-3]
+#' @param maxit Maximum number of iterations in the min LL algo [default: 1e3]
+#' @param showLL Print trace of log-likelihood evolution [default: true]
+#' @param disp True [default] for interactive display (otherwise nothing gets plotted)
+#' @return list with the following entries. M: data matrix in input; NI: computed neighborhoods; 
+#'         dists: computed distances matrix; clusts: partition into K clusters, as an integer vector; 
+#'         cxpar: parameters obtained after convex optimization (if applicable)
+#' @export
+#' @examples
+#' cvr = findSyncVarRegions("convex",M=NULL,k=10,alpha=0.1,gmode=1,K=5,dtype="spath",cmeth="HC")
+#' drawMapWithSitez(cvr$M, cvr$clusters)
+#' drawNeighboroodGraph(cvr$M, cvr$NI)
+#'
+findSyncVarRegions = function(method, M, k, alpha, gmode, K, dtype, cmeth,
+	pcoef=1.0, h=1e-3, eps=1e-3, maxit=1e3, showLL=TRUE, disp=TRUE)
+{
 	#get matrix M if not directly provided
 	if (is.null(M))
 	{