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

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

Dear all,
I am sorry to see all the reactions I provoked from a newbie user. Anyway, thank
you for the answer I think that the pcf3est function responds to my question.
Indeed the spatstat is a very impressive library and I am very grateful to the
the developers.
Best regards 

Eric LEROY 
Responsable de la plateforme microscopie ?lectronique 
ICMPE - UMR 7182 
2/8, rue Henri Dunant
94320 THIAIS 
T : 01.49.78.12.09
F : 01.49.78.12.03

> Le 29 avr. 2020 ? 13:04, Ege Rubak <rubak at math.aau.dk> a ?crit :
> 
> ?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

> 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
This is my last post on this subject.

I just ran R check on the source package.
After 40 minutes, R check wasn't complete.

And I note the CRAN check results show the package was checked with:

Linux: --no-tests
Windows: --no-examples --no-tests --no-vignettes

I recognize that R-help isn't the right place for this discussion.
And perhaps the last line of my first post was unfair.

But the rest of my comments about the package are objective.

On 30/04/20 12:28 am, Eric Leroy wrote:
> Dear all, I am sorry to see all the reactions I provoked from a
> newbie user. Anyway, thank you for the answer I think that the
> pcf3est function responds to my question.
> Indeed the spatstat is a very impressive library and I am very grateful to
the the developers.
(1) Not to worry.  Certainly not your fault!

(2) I'm glad that the pcf3est() function was useful to you.

(3) Thank you for your kind words about spatstat.

(4) But *please* --- spatstat is a *package* not a "library"!!!  A 
library is a *collection* of packages; the library() function "checks 
out" a package from a library, like checking a book out of a
"real"
library (biblioth?que en fran?ais, just in case there is any confusion, 
"library" and "libraire" being false cognates).  But I'm
sure you knew that.

I know that insisting on this distinction is being pedantic --- but it 
never hurts to get things right!  And saying "library" when you mean 
"package" upsets Martin Maechler!!! :-)

cheers,

Rolf

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