From: Benjamin Auder Date: Mon, 2 Feb 2015 11:51:40 +0000 (+0100) Subject: generate documentation X-Git-Url: https://git.auder.net/%7B%7B%20asset%28%27mixstore/css/static/doc/index.css?a=commitdiff_plain;h=ad26cb61b84c4d603980d0da65a9ed19cc9af778;p=synclust.git generate documentation --- diff --git a/DESCRIPTION b/DESCRIPTION old mode 100755 new mode 100644 index b9abed1..445161b --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,11 +5,14 @@ Date: 2013-01-31 Title: Delimiting synchronous population areas Author: Benjamin Auder, Christophe Giraud Maintainer: Benjamin Auder -Depends: R (>= 2.14.1), mvtnorm -Suggests: kernlab +Depends: + R (>= 2.14.1), + mvtnorm +Suggests: + kernlab Description: Provide two methods to cluster species by regions, - using temporal variations and/or geographic coordinates. - The resulting areas (should) have synchronous variations. + using temporal variations and/or geographic coordinates. + The resulting areas (should) have synchronous variations. License: GPL (>= 3) LazyData: yes LazyLoad: yes diff --git a/NAMESPACE b/NAMESPACE index 729d29a..72e0648 100755 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,8 +1,6 @@ -# Export all user-level R functions -export (findSyncVarRegions, drawMapWithSites, - drawNeighborhoodGraph, plotCurves, .Last.lib) +# Generated by roxygen2 (4.0.2): do not edit by hand -# Import all packages listed as Imports or Depends -#import (methods) - -useDynLib(synclust) +export(drawMapWithSites) +export(drawNeighborhoodGraph) +export(findSyncVarRegions) +export(plotCurves) diff --git a/R/graphics.R b/R/graphics.R index 9ce8a3a..e11a637 100644 --- a/R/graphics.R +++ b/R/graphics.R @@ -1,4 +1,9 @@ -#draw (France or...) map with all sites of colors 'cols' +#' Draw (France or...) map with all sites of colors 'cols' +#' +#' @param M Coordinates matrix (in columns) +#' @param cols Vector of colors for each row of M [default: all black] +#' @export +#' drawMapWithSites = function(M, cols=rep(1,nrow(M))) { xMin = range(M[,1])[1] @@ -17,7 +22,12 @@ drawMapWithSites = function(M, cols=rep(1,nrow(M))) } } -#draw neighborhoods graph on top of a country map (or any other map) +#' Draw neighborhoods graph on top of a country map (or any other map) +#' +#' @param M Coordinates matrix (in columns) +#' @param NI Neighborhoods of M rows (list of integer vectors) +#' @export +#' drawNeighborhoodGraph = function(M, NI) { for (i in 1:length(NI)) @@ -27,7 +37,12 @@ drawNeighborhoodGraph = function(M, NI) } } -#plot a matrix of curves (in rows) +#' Plot a matrix of curves (in rows) +#' +#' @param M Coordinates matrix (in columns) +#' @param cols Vector of colors for each row of M [default: all black] +#' @export +#' plotCurves = function(M, cols=rep(1,nrow(M))) { n = nrow(M) 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)) { diff --git a/R/zzz.R b/R/zzz.R index 189dd8f..50717b7 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,5 +1,5 @@ #called when package is detached ( detach("package:pkg_name") ) -.Last.lib = function(path) +.onDetach = function(libpath) { - library.dynam.unload("synclust", path) + library.dynam.unload("synclust", libpath) }