R help - Apr 2020 - [FORGED] Re: pair correlation function of 3D points

On 29/04/20 10:07 am, Abby Spurdle wrote:
> I haven't attempted this.
> (Mainly because I'm not familiar with the theory surrounding it).
> 
> However, I looked at the documentation for the spatstat package.
> There are are several functions prefixed with pcf, including one named
pcf3est.
> According to its description field:
> 
>            Estimates the pair correlation function
>            from a three-dimensional point pattern.
> 
> *If* it does what it claims ...
Why would you doubt that it does what it claims?
> ... would that solve your problem?
> 
> Note (to spatstat authors):
> 
> I'm not convinced this package is well documented.
> In fact, I'm not even convinced it meets CRAN standards, which require
> functions to have their arguments documented.
> 
>       X
>      Three-dimensional point pattern (object of class "pp3").
> 
> Nowhere in the help page, does it say what a pp3 object is, or how to
> create it, or where to find that information.
> Potentially requiring a user to search through a 1766 page document
> for the answer.
> (Yes, I know there's a function named pp3, but I don't think
that's
> good enough).
> 
> If people are not going to document their packages properly, they
> could try a little bit harder to answer R-help questions that involve
> their packages...
<SNIP>

Wouldn't the first thing that one would try be:

   ??"pp3"

The required information is then immediately apparent.

Moreover if one takes the trouble to look at the examples, one is led to 
the function rpoispp3() which points to the function pp3().

This reminds not a little of fortunes::fortune(9).

Of course I'm biased, but IMHO spatstat is documented not only 
"properly", but superbly well! :-)

cheers,

Rolf

-- 
Honorary Research Fellow
Department of Statistics
University of Auckland
Phone: +64-9-373-7599 ext. 88276

Hackles down, Rolf... most documentation can benefit from the perspective of a
new user. It would be helpful to link the mention of pp3 to the the pp3 function
via hyperlink to help clarify what this argument is supposed to be.

Abby, FWIW I tend to recommend reading the vignettes before trying to absorb the
function documentation... having a bird's-eye-view of how the package works
will always make the function documentation easier to follow.

On April 28, 2020 8:25:45 PM PDT, Rolf Turner <r.turner at auckland.ac.nz>
wrote:
>
>On 29/04/20 10:07 am, Abby Spurdle wrote:
>
>> I haven't attempted this.
>> (Mainly because I'm not familiar with the theory surrounding it).
>> 
>> However, I looked at the documentation for the spatstat package.
>> There are are several functions prefixed with pcf, including one
>named pcf3est.
>> According to its description field:
>> 
>>            Estimates the pair correlation function
>>            from a three-dimensional point pattern.
>> 
>> *If* it does what it claims ...
>
>Why would you doubt that it does what it claims?
>
>> ... would that solve your problem?
>> 
>> Note (to spatstat authors):
>> 
>> I'm not convinced this package is well documented.
>> In fact, I'm not even convinced it meets CRAN standards, which
>require
>> functions to have their arguments documented.
>> 
>>       X
>>      Three-dimensional point pattern (object of class "pp3").
>> 
>> Nowhere in the help page, does it say what a pp3 object is, or how to
>> create it, or where to find that information.
>> Potentially requiring a user to search through a 1766 page document
>> for the answer.
>> (Yes, I know there's a function named pp3, but I don't think
that's
>> good enough).
>> 
>> If people are not going to document their packages properly, they
>> could try a little bit harder to answer R-help questions that involve
>> their packages...
>
><SNIP>
>
>Wouldn't the first thing that one would try be:
>
>   ??"pp3"
>
>The required information is then immediately apparent.
>
>Moreover if one takes the trouble to look at the examples, one is led
>to 
>the function rpoispp3() which points to the function pp3().
>
>This reminds not a little of fortunes::fortune(9).
>
>Of course I'm biased, but IMHO spatstat is documented not only 
>"properly", but superbly well! :-)
>
>cheers,
>
>Rolf
-- 
Sent from my phone. Please excuse my brevity.

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.

Also, overall, I'm impressed by the effort here. It's just I strongly
feel that good documentation is crucial (especially in open source),
and 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.
> > *If* it does what it claims ...
> Why would you doubt that it does what it claims?
Because I didn't test it.
> Wouldn't the first thing that one would try be:
>    ??"pp3"
No, because I was reading the PDF version of the documentation.
> Of course I'm biased, but IMHO spatstat is documented not only
> "properly", but superbly well! :-)
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.

But here's a bigger problem.
The documentation says the pcf function is a generic, but the pcf3est
function isn't a method.
And the pcf documentation (along with the three methods) don't
reference the pcf3est function.

I found the pcf function via Googling the subject.
But unless someone goes through a list of all the help topics, they're
unlikely to find the pcf3est function.

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]]

Dear all,

I see two issues here:

1. A new user has a hard time finding and using a specific function in
spatstat. As package authors we are always interested in such reports
and we then try to improve documentation, which is indeed a very
important part of any software project. The package is **very**
actively developed and documented by mainly Adrian and to a lesser
extend by Rolf and I. All the other people listed as
"authors"/"contributors" have contributed things such as a
single new
function, a bug report, a documentation improvement, etc. Many of them
might not even be aware that they are mentioned on this list. This list
has developed over many years, and it is unfortunate if it gives the
impression that a lot of people are ready to help within 24 hours of a
question being posted on the general R help list because we cannot give
such guarantee -- you will have better luck with GitHub, the `spatstat`
tag on stackoverflow or the R SIG-GEO mail list, but still no 24 hour
guarantee is provided.

2. Abby replies in a very impolite tone towards the spatstat authors
and suggests that the package isn't fit for CRAN, which I consider a
direct insult to Adrian and all the hard work he has done to keep a
very well-documented package on CRAN since 2002. It would have been
nice to get a constructive suggestion on how to improve documentation
rather than a message about the alleged poor quality of the spatstat
package based on the documentation of a single function. If anyone
(Abby?) has spare time available for going through the documentation
and suggest improvements, add cross references etc. that's most
welcome. However, we would like to receive any suggestions in normal
polite manner via the project's GitHub page or by direct email to the
authors.

Regards,
Ege

On Wed, 2020-04-29 at 17:31 +1200, Abby Spurdle wrote:
> 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.
> 
> Also, overall, I'm impressed by the effort here. It's just I
strongly
> feel that good documentation is crucial (especially in open source),
> and 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.
> 
> > > *If* it does what it claims ...
> > 
> > Why would you doubt that it does what it claims?
> 
> Because I didn't test it.
> 
> > Wouldn't the first thing that one would try be:
> >    ??"pp3"
> 
> No, because I was reading the PDF version of the documentation.
> 
> > Of course I'm biased, but IMHO spatstat is documented not only
> > "properly", but superbly well! :-)
> 
> 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.
> 
> But here's a bigger problem.
> The documentation says the pcf function is a generic, but the pcf3est
> function isn't a method.
> And the pcf documentation (along with the three methods) don't
> reference the pcf3est function.
> 
> I found the pcf function via Googling the subject.
> But unless someone goes through a list of all the help topics,
> they're
> unlikely to find the pcf3est function.
-- 
Ege Rubak, Associate Professor,
Department of Mathematical Sciences, Aalborg University
Skjernvej 4A, 9220 Aalborg East, Denmark
Phone: (+45)99408861
Mobile: (+45)30230252
Email: rubak at math.aau.dk