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

[Hervé Pagès]

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