Skip to content

pair correlation function of 3D points

14 messages · Abby Spurdle, Jeff Newmiller, Adrian Baddeley +3 more

Original
Eric Leroy
# 
Hi,

I have the coordinates of 3D points and I want to plot the pair 
correlation function of these points 
(https://en.wikipedia.org/wiki/Radial_distribution_function). I wonder 
if it possible to calculate this function with R. Maybe with the 
spatstat library? I tried but I found the way to do this with 3D points 
but not for 3D points.

Could you help me ?

Thank you,

Best regards,

--
1 day later
Abby Spurdle
# 
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, 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...
On Tue, Apr 28, 2020 at 3:56 AM Labo Eric <leroy at icmpe.cnrs.fr> wrote:
Jeff Newmiller
# 
Technically, per the Posting Guide, help for contributed packages is supposed to come through different channel(s) than R-help as indicated in their DESCRIPTION file (typically searchable thru the package CRAN page). In practice this rule tends to only get invoked when the OT traffic gets too high, but it may be a bit much to expect maintainers to patrol R-help permanently. Feel free to direct OT questions toward the relevant CRAN page or the resources mentioned there.
On April 28, 2020 3:07:39 PM PDT, Abby Spurdle <spurdle.a at gmail.com> wrote:

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Abby Spurdle
    

    

      
      #
    

  


  

      
This is probably completely off topic.

But I get the impression the spatstat package has turned into a super-package.
Which is likely to be difficult to maintain.

Wouldn't a better result be achieved by freezing work on the package,
and creating some smaller packages with a more specific focus, that
could be more easily maintained....?

On Wed, Apr 29, 2020 at 10:18 AM Jeff Newmiller

        
<jdnewmil at dcn.davis.ca.us> wrote:

            

      
      
      
    

        

      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Rolf Turner
    

    

      
      #
    

  


  

      
On 29/04/20 10:07 am, Abby Spurdle wrote:

        

            

      
      
      
    

        
Why would you doubt that it does what it claims?

            

      
      
      
    

        
<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

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Jeff Newmiller
    

    

      
      #
    

  


  

      
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:

            

      
      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Abby Spurdle
    

    

      
      #
    

  


  

      
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.

            

      
      
      
    

        
Because I didn't test it.

            

      
      
      
    

        
No, because I was reading the PDF version of the documentation.

            

      
      
      
    

        
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.

  
  


  


      

    

    

      
      

        


  

        

      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'.

            

      
      
      
    

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

            

      
      
      
    

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

            

      
      
      
    

        
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.

            

      
      
      
    

        
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 don't want to be rude, but this seems pretty lazy.

            

      
      
      
    

        
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

  
  


  


      

    

    

      
      

        


  

        

      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:

            

      
      
      
    

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Eric Leroy
    

    

      
      #
    

  


  

      
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

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Abby Spurdle
    

    

      
      #
    

  


  

      
NOTE CITATIONS USE BRIEF EXCERPTS

            

      
      
      
    

        
Correction, it wasn't my query.
I was replying to someone else's query.

            

      
      
      
    

        
You've taken what I said out of context.
As I said in my response to Rolf, I didn't run the code.

            

      
      
      
    

        
I can't speak on behalf on CRAN.
But reiterating what I said earlier, you'd be better to create smaller
packages, each with a more specific focus.
Each package could have an unofficial co-maintainer to help you out.

            

      
      
      
    

        
Did you read my posts...

The functions DO NOT cross-reference.
The pcf generic/methods DO NOT reference the pcf3est function, at all.
The pcf3est function DOES NOT reference the pp3 function, but rather
references the class of the object.

Also, the seealso sections are minimalist.

If you are not going to create smaller packages, then the least you
could do it improve the standard of the seealso sections and
cross-referencing.

Furthermore, if functions are not cross-referenced, the reader (I this
case me) doesn't necessarily know what package those functions are
defined in.
You assume that readers will assume the functions are defined in your
package, and then do a search for them.

Instead of making assumptions about assumptions, just use hyperlinks...

            

      
      
      
    

        
Yes, seriously.

            

      
      
      
    

        
the first 24 hours, chances that they will reply later are low.
Also, I've found a bias on this forum, with few replies to
physics-related questions.

Personally, I like physicists, one of the most under-valued
professions on the planet.

            

      
      
      
    

        
That sounds like a contradiction.

Also, it's off the mark, given that I was the only one who attempted
to answer the OPs question.

  
  


  


      

    

    

      
      

        


  

        

      Abby Spurdle
    

    

      
      #
    

  


  

          

      
      
      
    

        
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.

  
  


  


      

    

    

      
      

        


  

        

      Ege Rubak
    

    

      
      #
    

  


  

      
Hi Abby,

Once again I must say your form of communication puzzles me. Do you
believe it benefits the open source community to communicate like this?
What about contacting the package maintainer in this way:

"Hi, I was helping someone else using your package to estimate a pair
correlation function. I was really puzzled that the generel help page
for `pcf` said it was a generic, but it doesn't seem to be generic for
the three dimensional case we needed, and no reference was given from
`pcf` to `pcf3est` which I had to search around to find. Maybe you
should consider throwing in a few cross references. Have a nice day."

I think this all would have played out much nicer then. None of us were
ignoring the original poster. We simply weren't aware of the OPs
problem until Rolf discovered it. I think Adrian and I focus on more
spatstat devoted channels to maximize the benefit of our time.

Regarding splitting the package into smaller pieces the thought has
occurred to us without your helpful suggestion. We started the process
of doing so years ago with the introduction of `spatstat.utils` and
`spatstat.data`. This is well documented on the spatstat GitHub page
referenced in the DESCRIPTION file. However, we have to prioritize our
time and it is quite a complex task to split out the relevant parts in
standalone packages due to all the interdependencies of the existing
code.

On a final note, to give you another example of a way to bring
attention to possible improvements of documentation: Let's say I was
looking at the function `marginal.set` in the package `probhat`, then I
would contact the author and say:

"Hi Abby, I was looking at the help for `marginal.set` and I couldn't
quite figure out what the argument constructor was supposed to be. The
help doesn't mention any class and contains no cross references
whatsoever and searching for 'constructor' in the R help system didn't
lead anywhere. Maybe a few cross references and actual usage of the
section 'See Also' would be beneficial for new users of your package.
It would be much better if instead of making assumptions about
assumptions you just use hyperlinks. Have a nice day. Kind regards,
Ege"

Where of course I would never use the sentence about hyperlinks in a
real example. I guess at this point I dug myself into the hole of bad
communication which is so killing for good software projects so
apologies for that. I do wish you a good day and hope you will consider
helping us all improve the state of open source software by
constructive suggestions rather than us claiming that each others
packages are unfit for CRAN.

Kind regards,
Ege

        
On Thu, 2020-04-30 at 06:53 +1200, Abby Spurdle wrote:

            

      
      
      
    

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Rolf Turner
    

    

      
      #
    

  


  

      
On 30/04/20 12:28 am, Eric Leroy wrote:

        

            

      
      
      
    

        
(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