[R] [FORGED] Re: pair correlation function of 3D points

[Adrian Baddeley]

I am the main author of spatstat, and the author of the code and documentation for pcf3est.

This is the first time in 25 years that I can remember anyone complaining about the documentation for the spatstat package.

The available documentation for spatstat includes:

                 - welcome message on startup which explains where to find help
                 - introductory vignette 'Getting Started in Spatstat'
                 - quick reference guide (in the help file 'spatstat-package' , at the front of the full manual, and on website)
                 - online help files (> 2000 help files)
                 - package manual (> 1700 pages)
                 - project website www.spatstat.org
                 - book 'Spatial Point Patterns: Methodology and Applications with R' (>700 pages)
                 - book companion website book.spatstat.org
                 - technical descriptions in journal articles
                 - ample explanatory comments in the source code

All of these sources (even the Description file) explain that spatstat is mainly focused on *two-dimensional* spatial point patterns but provides limited support for other kinds of data, including three-dimensional point patterns.

Three-dimensional point patterns are a relatively small subset of the current spatstat functionality
(covered in Section 15.3 pages 650-657 of the book, thus approximately 1% of the book).

The full manual PDF is searchable, has an index, and its internal cross-references are hyperlinks that can be followed.
Package manuals can also be accessed interactively in R through a web-like interface.
Package manuals are also available online with a web interface at some websites like rdrr.io

The help entry for 'pcf3est' says that the argument X must be a "three-dimensional point pattern (object of class 'pp3')". Most users would immediately look up 'pp3'. Apparently you were reading this from the full manual PDF and you say that you couldn't look up 'pp3'. The manual is searchable; you could have searched the PDF for keyword 'pp3', or jumped to the index, or the contents page. You could have looked at the first entry in the manual, which is the quick reference guide, which has a section on 'Three-dimensional point patterns' which would have listed all the available functionality for three-dimensional point patterns. You could have searched for 'three dimensional'.

> I was somewhat disappointed that, given how many people are/were
   > involved in this package, not one (after approx 24 hours) had tried to
   > help answer the OP's question.

That's not a complaint about the documentation. It's a complaint that no-one responded
to your query within 24 hours. Seriously? No-one is obliged to provide this level of service.
Twenty-four hours is a pretty short time scale for a response to a question that was not
addressed to anyone in particular. R-help is not a commonly used forum for asking questions about spatstat.
If you wanted a quick answer you could have emailed the package authors directly.

> I should have noted that my comments weren't directed towards the main
> authors, but to all people listed in the description file, which is
 > many, including some R core members.

The Description file says clearly that there are three main authors: Baddeley, Turner and Rubak with email addresses given.
The others are people who have contributed something at some time in the past.
I'm not sure what you hoped to achieve by addressing comments to a wider audience - most of whom are not listening on this frequency.

 > It's just I strongly feel that good documentation is crucial (especially in open source),

So do we; that's why we have put so much effort into documentation, including writing a whole book.

> I started reading the pcf function first.
> This function has the same problem, it doesn't clearly describe the function arguments.
> It doesn't say whether it applies to 2d, 3d or higher-dimensional data.
> After reading it, I had no idea whether the function could be applied to 3d data or not.
> In my opinion this is not sufficient.
> Descriptions of function arguments and return values should be clear.

pcf is generic.
The argument 'X' analysed in 'pcf(X)' could be any kind of spatial data.

The help file for a generic does not go into specific detail about 'X'; that is documented in the help files for the relevant methods.

The help file for the generic usually includes cross-references (under 'See Also') to some of the available methods.
Alternatively, to find out what classes of objects have a 'pcf' method, you can type 'methods(pcf)' in R with the package loaded. If you're reading a PDF, the methods will be listed consecutively in the file.

This would have revealed that there is a 'pcf.ppp' and a couple of other options.
The help for 'pcf.ppp' says that 'X' should be "a point pattern (object of class 'ppp')".
The help for 'ppp' or 'ppp.object' says that this class of object represents a point pattern in the two-dimensional plane.

> But here's a bigger problem.
> The documentation says the pcf function is a generic, but the pcf3est function isn't a method.

That is correct. But this is not a failure of documentation.
'pcf3est' is not a method for the generic 'pcf'.
'pcf3est' has a different, older syntax, and doesn't behave exactly the same way internally,
so it is not suitable to be a method for 'pcf'.

It would of course be logical for 'pcf' to have a method for three-dimensional point patterns,
but that depends on someone implementing it.

The software design for future versions of spatstat specifies that the summary functions such as
pcf.ppp and pcf3est should be modified to have a common syntax, which will be slightly different from
either of the current ones, and at that stage, the rewritten pcf3est will become a method for 'pcf'.

> I found the pcf function via Googling the subject.

I don't want to be rude, but this seems pretty lazy.

> But unless someone goes through a list of all the help topics, they're unlikely to find the pcf3est function.

Try Googling
         'spatstat pair correlation function three dimensions'

or searching the full spatstat manual PDF for
         'pair correlation function' or 'three dimensions'

You could also have jumped to the 'pcf' entry in the full manual, and scrolled up and down to see the other entries that begin with 'pcf'.

You complain that the documentation is insufficient, but at the same time, you complain that the manual is too long (> 1700 pages) and you seem unwilling to search the documentation or follow cross-references.

Before I answered this email, I had to answer an email from CRAN requesting me to please cut down the size of the spatstat package, including the documentation and examples, because the tarball is too large and the examples take too long to run.

So please understand that package authors have to be economical with the provision of documentation and examples. It is simply not feasible or efficient to explain everything in every help file. The user has to make some effort to follow up relevant information.

Finally, you cast doubt on whether the function pcf3est actually does calculate an estimate of the pair correlation function for a three-dimensional point pattern, as we claim in the help file. I'm at a loss to understand what you mean. The help file gives journal paper references, and indicates that the code in pcf3est calculates the estimator described in the paper by Baddeley et al (1993). I am the author of the technical paper, the code, and the documentation. What exactly are you disputing?


Regards



Prof Adrian Baddeley DSc FAA

John Curtin Distinguished Professor

Department of Mathematics and Statistics

Curtin University, Perth, Western Australia


I work Wednesdays, Thursdays and Fridays


	[[alternative HTML version deleted]]