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]]
______________________________________________
R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
