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

[Ege Rubak]

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 using math.aau.dk