Add warnings to help files

spatstat · Jan 17, 2025 · 20dd7df · 20dd7df
1 parent db67caf
commit 20dd7df
Show file tree

Hide file tree

Showing 18 changed files with 169 additions and 15 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: spatstat.geom
-Version: 3.3-4.010
-Date: 2025-01-07
+Version: 3.3-4.011
+Date: 2025-01-17
 Title: Geometrical Functionality of the 'spatstat' Family 
 Authors@R: c(person("Adrian", "Baddeley", 
                     role = c("aut", "cre", "cph"),
@@ -25,7 +25,7 @@ Authors@R: c(person("Adrian", "Baddeley",
 	     person("Rasmus",    "Waagepetersen", role = "ctb"))
 Maintainer: Adrian Baddeley <[email protected]>
 Depends: R (>= 3.5.0), spatstat.data (>= 3.1), spatstat.univar (>= 3.1-0), stats, graphics, grDevices, utils, methods
-Imports: spatstat.utils (>= 3.1-1.001), deldir (>= 1.0-2), polyclip (>= 1.10-0)
+Imports: spatstat.utils (>= 3.1-2), deldir (>= 1.0-2), polyclip (>= 1.10-0)
 Suggests: spatstat.random (>= 3.3), spatstat.explore (>= 3.3), spatstat.model (>= 3.3), spatstat.linnet (>= 3.2), spatial, fftwtools (>= 0.9-8), spatstat (>= 3.2)
 Description: Defines spatial data types and supports geometrical operations
 	     on them. Data types include point patterns, windows (domains),

diff --git a/NEWS b/NEWS
@@ -1,4 +1,4 @@
-        CHANGES IN spatstat.geom VERSION 3.3-4.010
+        CHANGES IN spatstat.geom VERSION 3.3-4.011
 
 OVERVIEW
 

diff --git a/inst/doc/packagesizes.txt b/inst/doc/packagesizes.txt
@@ -30,4 +30,4 @@ date version nhelpfiles nobjects ndatasets Rlines srclines
 "2024-07-09" "3.3-2" 442 1186 0 35638 15596
 "2024-09-18" "3.3-3" 443 1187 0 35818 15596
 "2024-11-18" "3.3-4" 444 1190 0 35978 15596
-"2025-01-07" "3.3-4.010" 445 1191 0 36158 15596
+"2025-01-17" "3.3-4.011" 445 1191 0 36158 15596
diff --git a/inst/info/packagesizes.txt b/inst/info/packagesizes.txt
@@ -30,4 +30,4 @@ date version nhelpfiles nobjects ndatasets Rlines srclines
 "2024-07-09" "3.3-2" 442 1186 0 35638 15596
 "2024-09-18" "3.3-3" 443 1187 0 35818 15596
 "2024-11-18" "3.3-4" 444 1190 0 35978 15596
-"2025-01-07" "3.3-4.010" 445 1191 0 36158 15596
+"2025-01-17" "3.3-4.011" 445 1191 0 36158 15596
diff --git a/man/distfun.Rd b/man/distfun.Rd
@@ -85,6 +85,18 @@
   It also belongs to the class \code{"funxy"} which has methods
   for \code{plot}, \code{contour} and \code{persp}.
 }
+\section{Distance values}{
+  The values returned by the distance function
+  \code{f <- distfun(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is
+  a composite expression such as \sQuote{2 microns},
+  then the values of \code{f} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{distmap}},
   \code{\link{summary.distfun}},

diff --git a/man/distmap.Rd b/man/distmap.Rd
@@ -35,7 +35,18 @@
   This is generic. Methods are provided for
   point patterns (\code{\link{distmap.ppp}}),
   line segment patterns  (\code{\link{distmap.psp}})
-  and windows (\code{\link{distmap.owin}}).
+  and windows (\code{\link{distmap.owin}}) as well as other classes.
+}
+\section{Distance values}{
+  The pixel values in the image \code{distmap(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite expression
+  such as \sQuote{2 microns},
+  then the values in \code{distmap(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
 }
 \seealso{
   \code{\link{distmap.ppp}},

diff --git a/man/distmap.owin.Rd b/man/distmap.owin.Rd
@@ -75,6 +75,17 @@
   
   This function is a method for the generic \code{\link{distmap}}.
 }
+\section{Distance values}{
+  The pixel values in the image \code{distmap(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values in \code{distmap(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{distmap}},
   \code{\link{distmap.ppp}},

diff --git a/man/distmap.ppp.Rd b/man/distmap.ppp.Rd
@@ -62,14 +62,28 @@
   to the nearest data point in \code{X}, use \code{\link{distfun}} or 
   \code{\link{nncross}}.
 }
+\section{Distance values}{
+  The pixel values in the image \code{distmap(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values in \code{distmap(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   Generic function \code{\link{distmap}} and other methods
   \code{\link{distmap.psp}},
   \code{\link{distmap.owin}}.
 
   Generic function \code{\link{distfun}}.
 
-  Nearest neighbour distance \code{\link{nncross}}
+  Nearest neighbour distance \code{\link{nncross}}.
+
+  \code{\link{unitname}} and \code{\link{rescale}} to control the unit
+  of length.
 }
 \examples{
   U <- distmap(cells)

diff --git a/man/distmap.psp.Rd b/man/distmap.psp.Rd
@@ -74,6 +74,17 @@
   low-level functions \code{\link{nncross}}
   or \code{\link{project2segment}}.
 }
+\section{Distance values}{
+  The pixel values in the image \code{distmap(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite expression
+  such as \sQuote{2 microns},
+  then the values in \code{distmap(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{distmap}},
   \code{\link{distmap.owin}},

diff --git a/man/nndist.Rd b/man/nndist.Rd
@@ -157,6 +157,17 @@
   distance is not defined (e.g. if there is only one point
   in the point pattern).
 }
+\section{Distance values}{
+  The values returned by \code{nndist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{nndist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{nndist.psp}},
   \code{\link{nndist.pp3}},

diff --git a/man/nndist.pp3.Rd b/man/nndist.pp3.Rd
@@ -82,6 +82,17 @@
   To find the nearest neighbour distances from one point pattern
   to another point pattern, use \code{\link{nncross}}.
 }
+\section{Distance values}{
+  The values returned by \code{nndist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{nndist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \section{Warnings}{
   An infinite or \code{NA} value is returned if the
   distance is not defined (e.g. if there is only one point

diff --git a/man/nndist.ppx.Rd b/man/nndist.ppx.Rd
@@ -83,6 +83,17 @@
   To obtain the spatial distance between points in a space-time point
   pattern, set \code{temporal=FALSE}.
 }
+\section{Distance values}{
+  The values returned by \code{nndist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{nndist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \section{Warnings}{
   An infinite or \code{NA} value is returned if the
   distance is not defined (e.g. if there is only one point

diff --git a/man/nndist.psp.Rd b/man/nndist.psp.Rd
@@ -71,6 +71,17 @@
   (the default) then compiled \code{C} code is used.
   The \code{C} code is somewhat faster.
 }
+\section{Distance values}{
+  The values returned by \code{nndist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{nndist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{nndist}},
   \code{\link{nndist.ppp}}

diff --git a/man/pairdist.Rd b/man/pairdist.Rd
@@ -36,6 +36,17 @@
   for \code{\link{pairdist.ppp}}, \code{\link{pairdist.psp}}
   or \code{\link{pairdist.default}} for details.
 }
+\section{Distance values}{
+  The values returned by \code{pairdist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{pairdist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{pairdist.ppp}},
   \code{\link{pairdist.psp}},

diff --git a/man/pairdist.pp3.Rd b/man/pairdist.pp3.Rd
@@ -36,8 +36,8 @@
   points in \code{X}, and returns the matrix of distances.
 
   Alternatively if \code{periodic=TRUE} and the window containing \code{X} is a
-  box, then the distances will be computed in the `periodic'
-  sense (also known as `torus' distance): opposite faces of the
+  box, then the distances will be computed in the \sQuote{periodic}
+  sense (also known as \sQuote{torus} distance): opposite faces of the
   box are regarded as equivalent.
   This is meaningless if the window is not a box.
 
@@ -46,6 +46,17 @@
   The squared distances are faster to calculate, and are sufficient for
   many purposes (such as finding the nearest neighbour of a point).
 }
+\section{Distance values}{
+  The values returned by \code{pairdist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{pairdist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{pairdist}},
   \code{\link{crossdist}},

diff --git a/man/pairdist.ppp.Rd b/man/pairdist.ppp.Rd
@@ -61,6 +61,17 @@
   computed using interpreted R code only. If \code{method="C"}
   (the default) then C code is used. The C code is somewhat faster.
 }
+\section{Distance values}{
+  The values returned by \code{pairdist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{pairdist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{pairdist}},
   \code{\link{pairdist.default}},

diff --git a/man/pairdist.ppx.Rd b/man/pairdist.ppx.Rd
@@ -33,6 +33,18 @@
   To obtain the spatial distance between points in a space-time point
   pattern, set \code{temporal=FALSE}.
 }
+\section{Distance values}{
+  The values returned by \code{pairdist(X, temporal=FALSE)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{pairdist(X, temporal=FALSE)}
+  are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{pairdist}},
   \code{\link{crossdist}},
@@ -45,8 +57,6 @@
 }
 \author{
   \adrian
-
-
 }
 \keyword{spatial}
 \keyword{math}

diff --git a/man/pairdist.psp.Rd b/man/pairdist.psp.Rd
@@ -56,6 +56,17 @@
   (the default) then compiled \code{C} code is used,
   which is somewhat faster.
 }
+\section{Distance values}{
+  The values returned by \code{pairdist(X)} are distances,
+  expressed as multiples of the unit of length of the spatial
+  coordinates in \code{X}.
+  The unit of length is given by \code{\link{unitname}(X)}.
+
+  Note that, if the unit of length in \code{X} is a composite
+  expression such as \sQuote{2 microns},
+  then the values of \code{pairdist(X)} are expressed as multiples
+  of 2 microns, rather than being expressed in microns.
+}
 \seealso{
   \code{\link{crossdist}},
   \code{\link{nndist}},
@@ -68,10 +79,7 @@
 }
 \author{
   \adrian
-
-
   and \rolf
-
 }
 \keyword{spatial}
 \keyword{math}