[R-pkg-devel] 2 Generic functions with the same name-skeleton

Dear All,

I have some problems and some questions regarding how to pass some checks
(run on my computer - new version not yet submitted).

There are 2 important notes:

1. Note 1:
checking S3 generic/method consistency ... NOTE
  Apparent methods for exported generics not registered:
    centres.ppRoll

2. Note 2:
checking Rd \usage sections ... NOTE
  S3 methods shown with full name in Rd file 'centres.ppRoll.Rd':
    'centres.ppRoll'

The current code is on GitHub:
https://github.com/discoleo/Rpdb

But let me first explain the reason and reasoning.

There are 2 generic functions: centres and centres.ppRoll, each with 3
methods for pdb objects, atoms and coords (default).

Generic function centres:
The 1st generic function, centres, computes the centres of a molecule and
has methods for 3 objects: pdb molecule, atoms and xyz-coordinates
(default). It acts on an object of type coords, while the objects atoms and
pdb include such a coords-object in their structure.

I would like to write various "specialised" versions:
- they still compute the centre, as it's the simplest summary possible for
3D objects;
- however, there are many types of molecules: proteins, nucleic acids,
other types of molecules; and each may benefit from more "specialised"
methods;
Note: all molecules are still coded as a pdb object. It's the user who
selects which method is most appropriate for a specific situation/molecule.

E.g. proteins consist of long linear chains. One such variant would be a
"rolling mean": it makes sense for polypeptide chains and nucleic acids,
but little (or no) sense for other molecules.

I wrote therefore a generic function centres.ppRoll with 3 methods for the
3 base-objects.

I would like to reuse the centres-skeleton for the name: users can then
easily check which methods are available to compute centres:
methods(centres)
# [1] centres.atoms          centres.coords         centres.pdb
# centres.ppRoll
# [5] centres.ppRoll.atoms   centres.ppRoll.default centres.ppRoll.pdb

I would like to avoid having hundreds of function names which no-one
remembers and which would be cumbersome to search for. Each method would be
useful only in particular situations and users are likely to forget the
exact names between uses.

I get the above 2 notes with this approach:
- I did not register centres.ppRoll as an S3 method to avoid the 2nd note;
- I get the 2nd note anyway (and it gets silently registered, which may be
necessary for the methods-search to work);

Another pseudo-solution would be to add a methods argument. This solution
is misused at times; unfortunately, it is really ugly here because some of
the methods may have particular arguments (e.g. window-size for the
roll-method).

Ultimately, I may end up with 50 or 100 arguments in the function, which I
also need to replicate to all the 3 methods (pdb, atoms, default/coords).

I really don't like this pseudo-solution and prefer one based on the 1st
approach.

I did not count how many function name variants are in the > 20,000
packages on CRAN. But I think that a more structured approach would be
beneficial to everyone.

Thanks in advance for any support,

Leonard

##########

### Note
- Proteins have a backbone and the amino-acids also have side chains;
- It is useful in certain situations to have additional types of centres
computed;
- The initial developer of Rpdb used it mainly for other types of
molecules (not proteins);

The code actually functions:

# pdb2z81.ent can be downloaded from the Protein Data Bank;
setwd(...)
x = read.pdb("pdb2z81.ent")
# Number of models:  0
# Warning message:
# In read.pdb("pdb2z81.ent") : The pdb contains a Caveat record!
tmp = centres.ppRoll(x)
visualize(x, type="p", pbc.box = FALSE)
# Draw a peptide-"Skeleton"
lines3d(tmp, lwd = 5, col = "red")

# A new version of the pdb-format is also out,
# but that's a horror-story in itself.


        [[alternative HTML version deleted]]