[Rd] Typos/omissions/inconsistencies in man page for clusterApply

From: Hervé Pagès <hpages_at_fhcrc.org>
Date: Tue, 23 Oct 2012 15:33:48 -0700


Hi,

Here are the issues I found:

Typos


   (a) Found: It a parallel version of ‘evalq’,

"is" missing.

   (b) Found: 'parLapplyLB', 'parSapplyLB' are load-balancing versions,

       intended for use when applying ‘FUN’ to

'parLapplyLB' has no 'FUN' arg (more on this below).

   (c) Found: 'clusterApply' calls 'fun' on the first node with arguments

       'seq[[1]]' and

'clusterApply' has no 'seq' arg.

There are a few other occurences of mistake (c) in the \details and \value section, for clusterApply() and clusterApplyLB().

Omissions


   o X: A vector (atomic or list) for ‘parLapply’ and ‘parSapply’, an

        array for ‘parApply’.

==> Nothing is said for the 'X' argument of parLapplyLB()

         and parSapplyLB().

Inconsistencies


The only function in that man page with a 'seq' argument is clusterSplit(), which is a questionable choice since split() (and strsplit()) use 'x'. Choosing 'seq' is also inconsistent with all the other cluster* and par* functions in that man page which use either 'x' or 'X'. Unless this 'seq' argument is different in nature but it doesn't seem so.

Also any reason why the argument receiving the function is sometimes named 'fun' (parLapply), and sometimes 'FUN' (parSapply)? Especially since the \note section says:

      Two exceptions: ‘parLapply’ has argument ‘X’ not ‘x’ for
      consistency with ‘lapply’, and ‘parSapply’ has been updated to
      match ‘sapply’.

Well done for parSapply:

   > args(parSapply)
   function (cl = NULL, X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)    NULL
   > args(sapply)
   function (X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)    NULL Not so well for parLapply (parLapply not consistent anymore with snow:::parLapply but still not consistent with lapply):

   > args(lapply)
   function (X, FUN, ...)
   NULL
   > args(parLapply)
   function (cl = NULL, X, fun, ...)
   NULL
   > args(snow::parLapply)
   function (cl, x, fun, ...)
   NULL Same kind of problem with clusterMap (departing from snow::clusterMap but not fully embracing naming convention used by mapply):

   > args(mapply)
   function (FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)    NULL
   > args(clusterMap)
   function (cl = NULL, fun, ..., MoreArgs = NULL, RECYCLE = TRUE,

       SIMPLIFY = FALSE, USE.NAMES = TRUE, .scheduling = c("static",
           "dynamic"))

   NULL
   > args(snow::clusterMap)
   function (cl, fun, ..., MoreArgs = NULL, RECYCLE = TRUE)    NULL Same problem with parRapply and parCapply and the naming of the x/X argument:

   > args(apply)
   function (X, MARGIN, FUN, ...)
   NULL
   > args(parApply)
   function (cl = NULL, X, MARGIN, FUN, ...)    NULL
   > args(parRapply)
   function (cl = NULL, x, FUN, ...)
   NULL
   > args(parCapply)
   function (cl = NULL, x, FUN, ...)
   NULL Note that the naming of the arguments is not consistent with snow::parRapply and snow::parCapply either:

   > args(snow::parRapply)
   function (cl, x, fun, ...)
   NULL
   > args(snow::parCapply)
   function (cl, x, fun, ...)
   NULL and this exception (and maybe others) are not mentioned in the \note section.

Overall it feels like the API for the 14 functions documented in this man page could be a little bit cleaner.

Thanks,
H.

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages_at_fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Tue 23 Oct 2012 - 22:35:59 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Wed 24 Oct 2012 - 18:20:48 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive