[R] Documenting S4 Methods
Martin Maechler
maechler at stat.math.ethz.ch
Wed Aug 25 11:34:33 CEST 2010
>>>>> Dario Strbenac <D.Strbenac at garvan.org.au>
>>>>> on Wed, 25 Aug 2010 13:00:03 +1000 (EST) writes:
> I'm in the process of converting some S3 methods to S4 methods.
> I have this function :
> setGeneric("enrichmentCalc", function(rs, organism, seqLen, ...){standardGeneric("enrichmentCalc")})
> setMethod("enrichmentCalc", c("GenomeDataList", "BSgenome"), function(rs, organism, seqLen, ...) {
> ... ... ...
> })
> setMethod("enrichmentCalc", c("GenomeData", "BSgenome"), function(rs, organism, seqLen=NULL, do.warn=FALSE) {
> ... ... ...
> })
> setMethod("enrichmentCalc", c("GRanges", "BSgenome"), function(rs, organism, seqLen=NULL) {
> ... ... ...
> }
> and a part of my Rd file is :
> \name{enrichmentCalc}
> \docType{methods}
> \alias{enrichmentCalc,GenomeDataList,BSgenome-method}
> \alias{enrichmentCalc,GenomeData,BSgenome-method}
> \alias{enrichmentCalc,GRanges,BSgenome-method}
> ... ... ...
> \usage{
> enrichmentCalc(rs, organism, seqLen, ...)
> enrichmentCalc(rs, organism, seqLen=NULL, do.warn=FALSE)
> enrichmentCalc(rs, organism, seqLen=NULL)
> }
> ... ... ...
> Can anyone suggest why I'm seeing this error :
> * checking for code/documentation mismatches ... WARNING
> Codoc mismatches from documentation object 'enrichmentCalc':
> enrichmentCalc
> Code: function(rs, organism, seqLen, ...)
> Docs: function(rs, organism, seqLen = NULL, do.warn = FALSE)
> Argument names in code not in docs:
> ...
> Argument names in docs not in code:
> do.warn
> Mismatches in argument names:
> Position: 4 Code: ... Docs: do.warn
> Mismatches in argument default values:
> Name: 'seqLen' Code: Docs: NULL
> enrichmentCalc
> Code: function(rs, organism, seqLen, ...)
> Docs: function(rs, organism, seqLen = NULL)
> Argument names in code not in docs:
> ...
> Mismatches in argument default values:
> Name: 'seqLen' Code: Docs: NULL
> * checking Rd \usage sections ... WARNING
> Objects in \usage without \alias in documentation object 'enrichmentCalc':
> enrichmentCalc
> Also, what is the difference between
> ... ... ...
> \docType{methods}
> ... ... ...
> \alias{methodName,class-method}
> ... ... ...
> \usage{methodName(arg1)}
> ... ... ...
> and
> ... ... ...
> \alias{methodName,class-method}
> ... ... ...
> \usage
> {
> \S4method{methodName}{class}(arg1)
> }
> ... ... ...
the last one is the one you should use.
I don't think that you can easily use \usage{..} without
\S4method{.}
and not get a warning (/error) from R CMD check.
> I've seen both ways used for S4 methods and don't know what is the underlying difference.
BTW: You should probably reread (parts of) the "Writing R Extensions" manual;
It's a good exercise ... even for me as an R core team member.
> I haven't been able to find any good tutorials for the new S4 architecture (written post 2006), so I'm not sure where to start with S4.
In R, ?Methods -> "References" ("s r" in ESS)
lists John Chambers book (with extra hints).
Chambers, John M. (2008) _Software for Data Analysis: Programming
with R_ Springer. (For the R version: see section 10.6 for method
selection and section 10.5 for generic functions).
Many people recommend learning from good examples.
As the Bioconductor project has made heavy use of S4 classes and
methods, many of their packages are good examples to follow.
To find all - locally installed - packages which depend directly
on "methods" and hence are probably using S4 methods / classes,
I do
> library(tools)
> str(meth.pkgs.direct <- dependsOnPkgs("methods", recursive=FALSE))
chr [1:313] "BufferedMatrix" "externalVector" "gdistancetest" "Matrix" ...
> sort(meth.pkgs.direct)
[1] "AcceptanceSampling" "accuracy" "adegenet"
[4] "adephylo" "amer" "aod"
[7] "apcluster" "apsrtable" "archetypes"
[10] "ArDec" "arules" "arulesNBMiner"
[13] "arulesSequences" "asuR" "automap"
[16] "aws" "aylmer" "backfitRichards"
[19] "backtest" "bbmle" "bcp"
[22] "bdsmatrix" "biclust" "bifactorial"
[25] "biganalytics" "biglm" "bigmemory"
[28] "bigtabulate" "bild" "BLCOP"
[31] "Brobdingnag" "bs" "BufferedMatrix"
[34] "calib" "catnet" "celsius"
[37] "ChainLadder" "classGraph" "clue"
[40] "clusterCons" "clValid" "CoCo"
[43] "CoCoCg" "CoCoCore" "CoCoGraph"
[46] "CoCoObjects" "coin" "colorspace"
[49] "connectedness" "copula" "crosshybDetector"
[52] "dae" "DatABEL" "DBI"
[55] "dcemriS4" "depmixS4" "DesignPatterns"
[58] "DiceKriging" "distr" "distrDoc"
[61] "distrEllipse" "distrEx" "distrMod"
[64] "distrSim" "distrTeach" "distrTEst"
[67] "diveMove" "drc" "dti"
[70] "dtw" "dynamicGraph" "EffectiveDose"
[73] "emu" "eRm" "externalVector"
[76] "FAiR" "fArma" "farmR"
[79] "fAssets" "fBasics" "fCalendar"
[82] "fCopulae" "FEST" "fExoticOptions"
[85] "fExtremes" "fGarch" "fields"
[88] "filehash" "filehashSQLite" "fImport"
[91] "fingerprint" "fisheyeR" "FLCore"
[94] "FLEDA" "flexclust" "flexmix"
[97] "fMultivar" "fNonlinear" "fOptions"
[100] "foreign" "forensim" "formula.tools"
[103] "fPortfolio" "frbf" "fRegression"
[106] "fSeries" "fTrading" "fUnitRoots"
[109] "fUtilities" "gamm4" "gcExplorer"
[112] "gdistancetest" "GenABEL" "genoPlotR"
[115] "geosphere" "ghyp" "giRaph"
[118] "glmulti" "gogarch" "gpclib"
[121] "gRain" "graph" "gRapHD"
[124] "grImport" "grplasso" "GSM"
[127] "gstat" "gWidgets" "gWidgetsRGtk2"
[130] "gWidgetstcltk" "HaploSim" "hash"
[133] "hbmem" "hexbin" "HFWutils"
[136] "HGLMMM" "HH" "Hmisc"
[139] "hopach" "HWEintrinsic" "hyperdirichlet"
[142] "hyperSpec" "ICS" "IDPmisc"
[145] "inline" "inlinedocs" "intervals"
[148] "iplots" "irtProb" "isa2"
[151] "its" "kappalab" "kernlab"
[154] "kinship" "kml" "kml3d"
[157] "languageR" "lavaan" "lcd"
[160] "leiv" "lme4" "lme4a"
[163] "logilasso" "longitudinalData" "maptools"
[166] "matlab" "Matrix" "MatrixModels"
[169] "matrixStats" "mboost" "memisc"
[172] "MIfuns" "mixer" "modeltools"
[175] "mondate" "monoProc" "mota"
[178] "mspath" "msProcess" "mugnet"
[181] "multtest" "mvabund" "mvngGrAd"
[184] "nacopula" "NADA" "nbpMatching"
[187] "NMF" "nws" "openNLP"
[190] "optparse" "orientlib" "orloca"
[193] "oro.nifti" "orth" "orthogonalsplinebasis"
[196] "packS4" "PairViz" "pARccs"
[199] "partsm" "party" "PBSmodelling"
[202] "pcalg" "pedigreemm" "penalized"
[205] "pgs" "phylobase" "pixmap"
[208] "PKtools" "plink" "portfolio"
[211] "portfolioSim" "qgen" "QRMlib"
[214] "qualityTools" "quantmod" "R2Cuba"
[217] "r2lh" "ramps" "RandVar"
[220] "raster" "RBGL" "rcdk"
[223] "Rcpp" "RCurl" "recommenderlab"
[226] "REEMtree" "relaimpo" "rEMM"
[229] "RFreak" "rgdal" "rggobi"
[232] "rgp" "RGtk2DfEdit" "RH2"
[235] "richards" "RItools" "rJava"
[238] "RJDBC" "RLadyBug" "Rmpfr"
[241] "RMySQL" "RNCBIAxis2Libs" "RNCBIEUtilsLibs"
[244] "RobAStBase" "robustbase" "ROCR"
[247] "R.oo" "ROptEst" "ROptEstOld"
[250] "ROptRegTS" "rPorta" "RQDA"
[253] "rrcov" "RSQLite" "rstream"
[256] "RUnit" "Runuran" "Ruuid"
[259] "sfsmisc" "SHARE" "simctest"
[262] "simecol" "similarityRichards" "SNPMaP"
[265] "SoDA" "sp" "spam"
[268] "SparseM" "spcosa" "spdep"
[271] "spef" "splus2R" "SRPM"
[274] "stashR" "StatDA" "stats4"
[277] "stringkernels" "surveillance" "svcR"
[280] "svMisc" "synchronicity" "tileHMM"
[283] "timeDate" "timeSeries" "tlemix"
[286] "tm" "topicmodels" "tradeCosts"
[289] "trajectories" "trip" "TSdbi"
[292] "TSfame" "TShistQuote" "TSMySQL"
[295] "TSpadi" "TSSQLite" "tuneR"
[298] "twitteR" "Umacs" "unmarked"
[301] "urca" "uroot" "UScensus2000"
[304] "UScensus2000add" "UScensus2000blkgrp" "UScensus2000cdp"
[307] "UScensus2000tract" "verification" "VGAM"
[310] "VHDClassification" "wavelets" "wq"
[313] "XML"
>
which are many, as we typically have all CRAN and Bioconductor
(at least those that do not need extra external
utilities/libraries).
Martin
More information about the R-help
mailing list