Version:	3.4-1
Date:	2025-05-20
Title:	Geometrical Functionality of the 'spatstat' Family
Maintainer:	Adrian Baddeley <Adrian.Baddeley@curtin.edu.au>
Depends:	R (≥ 3.5.0), spatstat.data (≥ 3.1), spatstat.univar (≥ 3.1), stats, graphics, grDevices, utils, methods
Imports:	spatstat.utils (≥ 3.1-4), deldir (≥ 1.0-2), polyclip (≥ 1.10)
Suggests:	spatstat.random (≥ 3.3), spatstat.explore (≥ 3.3), spatstat.model (≥ 3.3), spatstat.linnet (≥ 3.2), spatial, fftwtools (≥ 0.9-8), spatstat (≥ 3.3)
Description:	Defines spatial data types and supports geometrical operations on them. Data types include point patterns, windows (domains), pixel images, line segment patterns, tessellations and hyperframes. Capabilities include creation and manipulation of data (using command line or graphical interaction), plotting, geometrical operations (rotation, shift, rescale, affine transformation), convex hull, discretisation and pixellation, Dirichlet tessellation, Delaunay triangulation, pairwise distances, nearest-neighbour distances, distance transform, morphological operations (erosion, dilation, closing, opening), quadrat counting, geometrical measurement, geometrical covariance, colour maps, calculus on spatial domains, Gaussian blur, level sets of images, transects of images, intersections between objects, minimum distance matching. (Excludes spatial data on a network, which are supported by the package 'spatstat.linnet'.)
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	http://spatstat.org/
NeedsCompilation:	yes
ByteCompile:	true
BugReports:	https://github.com/spatstat/spatstat.geom/issues
Packaged:	2025-05-20 02:46:11 UTC; adrian
Author:	Adrian Baddeley [aut, cre, cph], Rolf Turner [aut, cph], Ege Rubak [aut, cph], Warick Brown [ctb], Tilman Davies [ctb], Ute Hahn [ctb], Martin Hazelton [ctb], Abdollah Jalilian [ctb], Greg McSwiggan [ctb, cph], Sebastian Meyer [ctb, cph], Jens Oehlschlaegel [ctb, cph], Suman Rakshit [ctb], Dominic Schuhmacher [ctb], Rasmus Waagepetersen [ctb]
Repository:	CRAN
Date/Publication:	2025-05-20 05:30:02 UTC

The spatstat.geom Package

Description

The spatstat.geom package belongs to the spatstat family of packages. It defines classes of geometrical objects such as windows and point patterns, and provides functionality for geometrical operations on them.

Details

spatstat is a family of R packages for the statistical analysis of spatial data. Its main focus is the analysis of spatial patterns of points in two-dimensional space.

The original spatstat package has now been split into several sub-packages.

This sub-package spatstat.geom defines the main classes of geometrical objects (such as windows, point patterns, line segment patterns, pixel images) and supports geometrical operations (such as shifting and rotating, measuring areas and distances, finding nearest neighbours in a point pattern).

Functions for performing statistical analysis and modelling are in the separate sub-packages spatstat.explore and spatstat.model.

Functions for linear networks are in the separate sub-package spatstat.linnet.

For an overview of all the functions available in the spatstat family, see the help file for spatstat in the spatstat package.

Structure of the spatstat family

The original spatstat package grew to be very large, and CRAN requested that the package be divided into several sub-packages. Currently the sub-packages are:

• spatstat.utils containing basic utilities

• spatstat.data containing datasets

• spatstat.sparse containing linear algebra utilities

• spatstat.univar containing functions for estimating probability distributions of random variables

• spatstat.geom containing geometrical objects and geometrical operations

• spatstat.random containing code for generating random spatial patterns

• spatstat.explore containing the main functionality for exploratory and non-parametric analysis of spatial data

• spatstat.model containing the main functionality for statistical modelling and inference for spatial data

• spatstat.linnet containing functions for spatial data on a linear network

• spatstat, which simply loads the other sub-packages listed above, and provides documentation.

When you install spatstat, these sub-packages are also installed. Then if you load the spatstat package by typing library(spatstat), the other sub-packages listed above will automatically be loaded or imported. For an overview of all the functions available in these sub-packages, see the help file for spatstat in the spatstat package,

Additionally there are several extension packages:

• spatstat.gui for interactive graphics

• spatstat.local for local likelihood (including geographically weighted regression)

• spatstat.Knet for additional, computationally efficient code for linear networks

• spatstat.sphere (under development) for spatial data on a sphere, including spatial data on the earth's surface

The extension packages must be installed separately and loaded explicitly if needed. They also have separate documentation.

OVERVIEW OF CAPABILITIES

Following is an overview of the capabilities of the spatstat.geom sub-package.

Types of spatial data:

The main types of spatial data supported by spatstat.geom are:

Additional data types are supported in spatstat.linnet.

To create a point pattern:

To simulate a random point pattern:

Most of the methods for generating random data are provided in spatstat.random. The following basic methods are supplied in spatstat.geom:

Standard point pattern datasets:

Datasets installed in the spatstat family are provided in the sub-package spatstat.data.

To manipulate a point pattern:

See spatstat.options to control plotting behaviour.

To create a window:

An object of class "owin" describes a spatial region (a window of observation).

To manipulate a window:

Digital approximations:

See spatstat.options to control the approximation

Geometrical computations with windows:

Pixel images: An object of class "im" represents a pixel image. Such objects are returned by some of the functions in spatstat including Kmeasure, setcov and density.ppp.

Line segment patterns

An object of class "psp" represents a pattern of straight line segments.

Tessellations

An object of class "tess" represents a tessellation.

Functions which are constant on each tile of a tessellation:

Three-dimensional point patterns

An object of class "pp3" represents a three-dimensional point pattern in a rectangular box. The box is represented by an object of class "box3".

Multi-dimensional space-time point patterns

An object of class "ppx" represents a point pattern in multi-dimensional space and/or time.

Linear networks

An object of class "linnet" represents a linear network (for example, a road network). This is supported in the sub-package spatstat.linnet.

An object of class "lpp" represents a point pattern on a linear network (for example, road accidents on a road network).

Hyperframes

A hyperframe is like a data frame, except that the entries may be objects of any kind.

Layered objects

A layered object represents data that should be plotted in successive layers, for example, a background and a foreground.

Colour maps

A colour map is a mechanism for associating colours with data. It can be regarded as a function, mapping data to colours. Using a colourmap object in a plot command ensures that the mapping from numbers to colours is the same in different plots.

Inspection of data:

Distances in a point pattern:

Programming tools:

Distances in a three-dimensional point pattern:

Distances in multi-dimensional point pattern:

These are for multi-dimensional space-time point pattern objects (class ppx).

Licence

This library and its documentation are usable under the terms of the "GNU General Public License", a copy of which is distributed with the package.

Acknowledgements

Kasper Klitgaard Berthelsen, Ottmar Cronie, Tilman Davies, Yongtao Guan, Ute Hahn, Abdollah Jalilian, Marie-Colette van Lieshout, Greg McSwiggan, Tuomas Rajala, Suman Rakshit, Dominic Schuhmacher, Rasmus Waagepetersen and Hangsheng Wang made substantial contributions of code.

Additional contributions and suggestions from Monsuru Adepeju, Corey Anderson, Ang Qi Wei, Ryan Arellano, Jens Astrom, Robert Aue, Marcel Austenfeld, Sandro Azaele, Malissa Baddeley, Guy Bayegnak, Colin Beale, Melanie Bell, Thomas Bendtsen, Ricardo Bernhardt, Andrew Bevan, Brad Biggerstaff, Anders Bilgrau, Leanne Bischof, Christophe Biscio, Roger Bivand, Jose M. Blanco Moreno, Florent Bonneu, Jordan Brown, Ian Buller, Julian Burgos, Simon Byers, Ya-Mei Chang, Jianbao Chen, Igor Chernayavsky, Y.C. Chin, Bjarke Christensen, Lucia Cobo Sanchez, Jean-Francois Coeurjolly, Kim Colyvas, Hadrien Commenges, Rochelle Constantine, Robin Corria Ainslie, Richard Cotton, Marcelino de la Cruz, Peter Dalgaard, Mario D'Antuono, Sourav Das, Peter Diggle, Patrick Donnelly, Ian Dryden, Stephen Eglen, Ahmed El-Gabbas, Belarmain Fandohan, Olivier Flores, David Ford, Peter Forbes, Shane Frank, Janet Franklin, Funwi-Gabga Neba, Oscar Garcia, Agnes Gault, Jonas Geldmann, Marc Genton, Shaaban Ghalandarayeshi, Julian Gilbey, Jason Goldstick, Pavel Grabarnik, C. Graf, Ute Hahn, Andrew Hardegen, Martin Bogsted Hansen, Martin Hazelton, Juha Heikkinen, Mandy Hering, Markus Herrmann, Maximilian Hesselbarth, Paul Hewson, Hamidreza Heydarian, Kassel Hingee, Kurt Hornik, Philipp Hunziker, Jack Hywood, Ross Ihaka, Cenk Icos, Aruna Jammalamadaka, Robert John-Chandran, Devin Johnson, Mahdieh Khanmohammadi, Bob Klaver, Lily Kozmian-Ledward, Peter Kovesi, Mike Kuhn, Jeff Laake, Robert Lamb, Frederic Lavancier, Tom Lawrence, Tomas Lazauskas, Jonathan Lee, George Leser, Angela Li, Li Haitao, George Limitsios, Andrew Lister, Nestor Luambua, Ben Madin, Martin Maechler, Kiran Marchikanti, Jeff Marcus, Robert Mark, Peter McCullagh, Monia Mahling, Jorge Mateu Mahiques, Ulf Mehlig, Frederico Mestre, Sebastian Wastl Meyer, Mi Xiangcheng, Lore De Middeleer, Robin Milne, Enrique Miranda, Jesper Moller, Annie Mollie, Ines Moncada, Mehdi Moradi, Virginia Morera Pujol, Erika Mudrak, Gopalan Nair, Nader Najari, Nicoletta Nava, Linda Stougaard Nielsen, Felipe Nunes, Jens Randel Nyengaard, Jens Oehlschlaegel, Thierry Onkelinx, Sean O'Riordan, Evgeni Parilov, Jeff Picka, Nicolas Picard, Tim Pollington, Mike Porter, Sergiy Protsiv, Adrian Raftery, Suman Rakshit, Ben Ramage, Pablo Ramon, Xavier Raynaud, Nicholas Read, Matt Reiter, Ian Renner, Tom Richardson, Brian Ripley, Ted Rosenbaum, Barry Rowlingson, Jason Rudokas, Tyler Rudolph, John Rudge, Christopher Ryan, Farzaneh Safavimanesh, Aila Sarkka, Cody Schank, Katja Schladitz, Sebastian Schutte, Bryan Scott, Olivia Semboli, Francois Semecurbe, Vadim Shcherbakov, Shen Guochun, Shi Peijian, Harold-Jeffrey Ship, Tammy L Silva, Ida-Maria Sintorn, Yong Song, Malte Spiess, Mark Stevenson, Kaspar Stucki, Jan Sulavik, Michael Sumner, P. Surovy, Ben Taylor, Thordis Linda Thorarinsdottir, Leigh Torres, Berwin Turlach, Torben Tvedebrink, Kevin Ummer, Medha Uppala, Andrew van Burgel, Tobias Verbeke, Mikko Vihtakari, Alexendre Villers, Fabrice Vinatier, Maximilian Vogtland, Sasha Voss, Sven Wagner, Hao Wang, H. Wendrock, Jan Wild, Carl G. Witthoft, Selene Wong, Maxime Woringer, Luke Yates, Mike Zamboni and Achim Zeileis.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

Extract or Replace Subset of a List of Things

Description

Extract or replace a subset of a list of things.

Usage

  ## S3 method for class 'anylist'
x[i, ...]

  ## S3 replacement method for class 'anylist'
x[i] <- value

Arguments

Details

These are the methods for extracting and replacing subsets for the class "anylist".

The argument x should be an object of class "anylist" representing a list of things. See anylist.

The method replaces a designated subset of x, and returns an object of class "anylist".

Value

Another object of class "anylist".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

anylist, plot.anylist, summary.anylist

Examples

   x <- anylist(A=runif(10), B=runif(10), C=runif(10))
   x[1] <- list(A=rnorm(10))
 

Extract or Replace Subset of Hyperframe

Description

Extract or replace a subset of a hyperframe.

Usage

  ## S3 method for class 'hyperframe'
x[i, j, drop, strip=drop, ...]
  ## S3 replacement method for class 'hyperframe'
x[i, j] <- value
  ## S3 method for class 'hyperframe'
x$name
  ## S3 replacement method for class 'hyperframe'
x$name <- value
  ## S3 method for class 'hyperframe'
x[[...]]
  ## S3 replacement method for class 'hyperframe'
x[[i, j]] <- value

Arguments

Details

These functions extract a designated subset of a hyperframe, or replace the designated subset with another hyperframe.

The function [.hyperframe is a method for the subset operator [ for the class "hyperframe". It extracts the subset of x specified by the row index i and column index j.

The argument drop determines whether the array structure will be discarded if possible. The argument strip determines whether the list structure in a row or column or cell will be discarded if possible. If drop=FALSE (the default), the return value is always a hyperframe or data frame. If drop=TRUE, and if the selected subset has only one row, or only one column, or both, then

• if strip=FALSE, the result is a list, with one entry for each array cell that was selected.

• if strip=TRUE,

  • if the subset has one row containing several columns, the result is a list or (if possible) an atomic vector;

  • if the subset has one column containing several rows, the result is a list or (if possible) an atomic vector;

  • if the subset has exactly one row and exactly one column, the result is the object (or atomic value) contained in this row and column.

The function [<-.hyperframe is a method for the subset replacement operator [<- for the class "hyperframe". It replaces the designated subset with the hyperframe value. The subset of x to be replaced is designated by the arguments i and j as above. The replacement value should be a hyperframe with the appropriate dimensions, or (if the specified subset is a single column) a list of the appropriate length.

The function $.hyperframe is a method for $ for hyperframes. It extracts the relevant column of the hyperframe. The result is always a list (i.e. equivalent to using [.hyperframe with strip=FALSE).

The function $<-.hyperframe is a method for $<- for hyperframes. It replaces the relevant column of the hyperframe. The replacement value should be a list of the appropriate length.

The functions [[.hyperframe and [[<-.hyperframe are methods for [[ and [[<-.hyperframe for hyperframes. They are analogous to [[.data.frame and [[<-.data.frame in that they can be used in different ways:

• when [[.hyperframe or [[<-.hyperframe are used with a single index, as in x[[n]] or x[[n]] <- value, they index the hyperframe as if it were a list, extracting or replacing a column of the hyperframe.

• when [[.hyperframe or [[<-.hyperframe are used with two indices, as in x[[i,j]] or x[[i,j]] <- value, they index the hyperframe as if it were a matrix, and can only be used to extract or replace one element.

Value

A hyperframe (of class "hyperframe").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

hyperframe

Examples

  h <- hyperframe(X=list(square(1), square(2)), Y=list(sin, cos))
  h
  h[1, ]
  h[1, ,drop=TRUE]
  h[ , 1]
  h[ , 1, drop=TRUE]
  h[1,1]
  h[1,1,drop=TRUE]
  h[1,1,drop=TRUE,strip=FALSE]
  h[1,1] <- list(square(3))
  # extract column
  h$X
  # replace existing column
  h$Y <- list(cells, cells)
  # add new column
  h$Z <- list(tan, exp)
  #
  h[["Y"]]
  h[[2,1]]
  h[[2,1]] <- square(3)

Extract Subset of Image

Description

Extract a subset or subregion of a pixel image.

Usage

  ## S3 method for class 'im'
x[i, j, ..., drop=TRUE, tight=FALSE,
                                 raster=NULL, rescue=is.owin(i)]

Arguments

Details

This function extracts a subset of the pixel values in a pixel image. (To reassign the pixel values, see [<-.im).

The image x must be an object of class "im" representing a pixel image defined inside a rectangle in two-dimensional space (see im.object).

The subset to be extracted is determined by the arguments i,j according to the following rules (which are checked in this order):

1. i is a spatial object such as a window, a pixel image with logical values, a linear network, or a point pattern; or

2. i,j are indices for the matrix as.matrix(x); or

3. i can be converted to a point pattern by as.ppp(i, W=Window(x)), and i is not a matrix.

If i is a spatial window (an object of class "owin"), the pixels inside this window are selected.

• If drop=TRUE (the default) and either is.rectangle(i)=FALSE or rescue=FALSE, the pixel values are extracted; the result is a vector, with one entry for each pixel of x that lies inside the window i. Pixel values may be NA, indicating that the selected pixel lies outside the spatial domain of the image.

• if drop=FALSE, the result is another pixel image, obtained by setting the pixel values to NA outside the window i. The effect is that the pixel image x is clipped to the window i.

• if i is a rectangle and rescue=TRUE, the result is a pixel image as described above.

• To ensure that an image is produced in all circumstances, set drop=FALSE. To ensure that pixel values are extracted as a vector in all circumstances, set drop=TRUE, rescue=FALSE.

If i is a pixel image with logical values, it is interpreted as a spatial window (with TRUE values inside the window and FALSE outside).

If i is a linear network (object of class "linnet"), the pixels which lie on this network are selected.

• If drop=TRUE (the default), the pixel values are extracted; the result is a vector, with one entry for each pixel of x that lies along the network i. Pixel values may be NA, indicating that the selected pixel lies outside the spatial domain of the image.

• if drop=FALSE, the result is a pixel image on a linear network (object of class "linim"), obtained by setting the pixel values of x to NA except for those which lie on the network i. The effect is that the pixel image x is restricted to the network i.

If i is a point pattern (an object of class "ppp") or something that can be converted to a point pattern, then the values of the pixel image at the points of this pattern are extracted. The result is a vector of pixel values. This is a simple way to read the pixel values at a given spatial location.

• if drop=FALSE the length of the result is equal to the number of points in the pattern. It may contain NA values which indicate that the corresponding point lies outside the spatial domain of the image.

• if drop=TRUE (the default), NA values are deleted. The result is a vector whose length may be shorter than the number of points of the pattern.

If the optional argument raster is given, then it should be a binary image mask or a pixel image. Then x will first be converted to an image defined on the pixel grid implied by raster, before the subset operation is carried out. In particular, x[i, raster=i, drop=FALSE] will return an image defined on the same pixel array as the object i.

If i does not satisfy any of the conditions above, then the algorithm attempts to interpret i and j as indices for the matrix as.matrix(x). Either i or j may be missing or blank. The result is usually a vector or matrix of pixel values. Exceptionally the result is a pixel image if i,j determines a rectangular subset of the pixel grid, and if the user specifies rescue=TRUE.

Finally, if none of the above conditions is met, the object i may also be a data frame or list of x,y coordinates which will be converted to a point pattern, taking the observation window to be Window(x). Then the pixel values at these points will be extracted as a vector.

Value

Either a pixel image or a vector of pixel values. See Details.

Warnings

If you have a 2-column matrix containing the x,y coordinates of point locations, then to prevent this being interpreted as an array index, you should convert it to a data.frame or to a point pattern.

If W is a window or a pixel image, then x[W, drop=FALSE] will return an image defined on the same pixel array as the original image x. If you want to obtain an image whose pixel dimensions agree with those of W, use the raster argument, x[W, raster=W, drop=FALSE].

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

im.object, [<-.im, ppp.object, as.ppp, owin.object, plot.im

Examples

 # make up an image
 X <- setcov(unit.square())
 plot(X)

 # a rectangular subset
 W <- owin(c(0,0.5),c(0.2,0.8))
 Y <- X[W]
 plot(Y)

 # a polygonal subset
 R <- affine(letterR, diag(c(1,1)/2), c(-2,-0.7))
 plot(X[R, drop=FALSE])
 plot(X[R, drop=FALSE, tight=TRUE])

 # a point pattern
 Y <- X[cells]

 # look up a specified location
 X[list(x=0.1,y=0.2)]

 # 10 x 10 pixel array
 X <- as.im(function(x,y) { x + y }, owin(c(-1,1),c(-1,1)), dimyx=10)
 # 100 x 100 
 W <- as.mask(disc(1, c(0,0)), dimyx=100)
 # 10 x 10 raster
 X[W,drop=FALSE]
 # 100 x 100 raster
 X[W, raster=W, drop=FALSE]

Extract or Replace Subset of a Layered Object

Description

Extract or replace some or all of the layers of a layered object, or extract a spatial subset of each layer.

Usage

  ## S3 method for class 'layered'
x[i, j, drop=FALSE, ...]

  ## S3 replacement method for class 'layered'
x[i] <- value

  ## S3 replacement method for class 'layered'
x[[i]] <- value

Arguments

Details

A layered object represents data that should be plotted in successive layers, for example, a background and a foreground. See layered.

The function [.layered extracts a designated subset of a layered object. It is a method for [ for the class "layered".

The functions [<-.layered and [[<-.layered replace a designated subset or designated entry of the object by new values. They are methods for [<- and [[<- for the "layered" class.

The index i specifies which layers will be retained. It should be a valid subset index for the list of layers.

The index j will be applied to each layer. It is typically a spatial window (class "owin") so that each of the layers will be restricted to the same spatial region. Alternatively j may be any subset index which is permissible for the "[" method for each of the layers.

Value

Usually an object of class "layered".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

layered

Examples

 D <- distmap(cells)
 L <- layered(D, cells,
              plotargs=list(list(ribbon=FALSE), list(pch=16)))

 L[-2]
 L[, square(0.5)]

 L[[3]] <- japanesepines
 L

Extract or Replace Subset of a List of Things

Description

Replace a subset of a list of things.

Usage

  ## S3 replacement method for class 'listof'
x[i] <- value

Arguments

Details

This is a subset replacement method for the class "listof".

The argument x should be an object of class "listof" representing a list of things that all belong to one class.

The method replaces a designated subset of x, and returns an object of class "listof".

Value

Another object of class "listof".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

plot.listof, summary.listof

Examples

   x <- list(A=runif(10), B=runif(10), C=runif(10))
   class(x) <- c("listof", class(x))
   x[1] <- list(A=rnorm(10))
 

Extract Subset of Window

Description

Extract a subset of a window.

Usage

  ## S3 method for class 'owin'
x[i, ...]

Arguments

Details

This function computes the intersection between the window x and the domain specified by i, using intersect.owin.

This function is a method for the subset operator "[" for spatial windows (objects of class "owin"). It is provided mainly for completeness.

The index i may be either a window, or a pixel image with logical values (the TRUE values of the image specify the spatial domain).

Value

Another spatial window (object of class "owin").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

intersect.owin

Examples

 W <- owin(c(2.5, 3.2), c(1.4, 2.9))
 plot(letterR)
 plot(letterR[W], add=TRUE, col="red")

Extract or Replace Subset of Point Pattern

Description

Extract or replace a subset of a point pattern. Extraction of a subset has the effect of thinning the points and/or trimming the window.

Usage

  ## S3 method for class 'ppp'
x[i, j, drop=FALSE, ..., clip=FALSE]
  ## S3 replacement method for class 'ppp'
x[i, j] <- value

Arguments

Details

These functions extract a designated subset of a point pattern, or replace the designated subset with another point pattern.

The function [.ppp is a method for [ for the class "ppp". It extracts a designated subset of a point pattern, either by “thinning” (retaining/deleting some points of a point pattern) or “trimming” (reducing the window of observation to a smaller subregion and retaining only those points which lie in the subregion) or both.

The pattern will be “thinned” if i is a subset index in the usual R sense: either a numeric vector of positive indices (identifying the points to be retained), a numeric vector of negative indices (identifying the points to be deleted) or a logical vector of length equal to the number of points in the point pattern x. In the latter case, the points (x$x[i], x$y[i]) for which subset[i]=TRUE will be retained, and the others will be deleted.

The pattern will be “trimmed” if i is an object of class "owin" specifying a window of observation. The points of x lying inside the new window i will be retained. Alternatively i may be a pixel image (object of class "im") with logical values; the pixels with the value TRUE will be interpreted as a window.

The argument drop determines whether to remove unused levels of a factor, if the point pattern is multitype (i.e. the marks are a factor) or if the marks are a data frame in which some of the columns are factors.

The function [<-.ppp is a method for [<- for the class "ppp". It replaces the designated subset with the point pattern value. The subset of x to be replaced is designated by the argument i as above.

The replacement point pattern value must lie inside the window of the original pattern x. The ordering of points in x will be preserved if the replacement pattern value has the same number of points as the subset to be replaced. Otherwise the ordering is unpredictable.

If the original pattern x has marks, then the replacement pattern value must also have marks, of the same type.

Use the function unmark to remove marks from a marked point pattern.

Use the function split.ppp to select those points in a marked point pattern which have a specified mark.

Value

A point pattern (of class "ppp").

Warnings

The function does not check whether i is a subset of Window(x). Nor does it check whether value lies inside Window(x).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

subset.ppp.

ppp.object, owin.object, unmark, split.ppp, cut.ppp

Examples

 # Longleaf pines data
 lon <- longleaf
 if(human <- interactive()) {
 plot(lon)
 }
 

 # adult trees defined to have diameter at least 30 cm
 longadult <- subset(lon, marks >= 30)
 if(human){
 plot(longadult)
 }
 # note that the marks are still retained.
 # Use unmark(longadult) to remove the marks
 
 # New Zealand trees data
 if(human){
 plot(nztrees)          # plot shows a line of trees at the far right
 abline(v=148, lty=2)   # cut along this line
 }
 nzw <- owin(c(0,148),c(0,95)) # the subwindow
 # trim dataset to this subwindow
 nzsub <- nztrees[nzw]
 if(human){
 plot(nzsub)
 }

 # Redwood data
 if(human){
 plot(redwood)
 }
 # Random thinning: delete 60% of data
 retain <- (runif(npoints(redwood)) < 0.4)
 thinred <- redwood[retain]
 if(human){
 plot(thinred)
 }

 # Scramble 60% of data
if(require(spatstat.random)) {
 X <- redwood
 modif <- (runif(npoints(X)) < 0.6)
 X[modif] <- runifpoint(ex=X[modif])
}

 # Lansing woods data - multitype points
 lan <- lansing
 

 # Hickory trees
  hicks <- split(lansing)$hickory

 # Trees in subwindow
  win <- owin(c(0.3, 0.6),c(0.2, 0.5))
  lsub <- lan[win]

if(require(spatstat.random)) {
 # Scramble the locations of trees in subwindow, retaining their marks
  lan[win] <- runifpoint(ex=lsub) %mark% marks(lsub)
}

 # Extract oaks only
 oaknames <- c("redoak", "whiteoak", "blackoak")
 oak <- lan[marks(lan) %in% oaknames, drop=TRUE]
 oak <- subset(lan, marks %in% oaknames, drop=TRUE)

 # To clip or not to clip
 X <- unmark(demopat)
 B <- owin(c(5500, 9000), c(2500, 7400))
 opa <- par(mfrow=c(1,2))
 plot(X, main="X[B]")
 plot(X[B], add=TRUE,
      cols="blue", col="pink", border="blue",
      show.all=TRUE, main="")
 plot(Window(X), add=TRUE)
 plot(X, main="X[B, clip=TRUE]")
 plot(B, add=TRUE, lty=2)
 plot(X[B, clip=TRUE], add=TRUE,
      cols="blue", col="pink", border="blue", 
      show.all=TRUE, main="")
 par(opa)

Extract Subset of Multidimensional Point Pattern

Description

Extract a subset of a multidimensional point pattern.

Usage

  ## S3 method for class 'ppx'
x[i, drop=FALSE, clip=FALSE, ...]

Arguments

Details

This function extracts a designated subset of a multidimensional point pattern.

The function [.ppx is a method for [ for the class "ppx". It extracts a designated subset of a point pattern. The argument i may be either

• a subset index in the usual R sense: either a numeric vector of positive indices (identifying the points to be retained), a numeric vector of negative indices (identifying the points to be deleted) or a logical vector of length equal to the number of points in the point pattern x. In the latter case, the points (x$x[i], x$y[i]) for which subset[i]=TRUE will be retained, and the others will be deleted.

• a spatial domain of class "boxx" or "box3". Points falling inside this region will be retained.

The argument drop determines whether to remove unused levels of a factor, if the point pattern is multitype (i.e. the marks are a factor) or if the marks are a data frame or hyperframe in which some of the columns are factors.

Use the function unmark to remove marks from a marked point pattern.

Value

A multidimensional point pattern (of class "ppx").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

ppx

Examples

   df <- data.frame(x=runif(4),y=runif(4),z=runif(4))
   X <- ppx(data=df, coord.type=c("s","s","t"))
   X[-2]
   Y <- ppx(coords(cells), domain = boxx(c(0,1),c(0,1)))
   dom <- shift(domain(Y), vec = c(.5,.5))
   Y[dom]
   Y[dom, clip=TRUE]

Extract Subset of Line Segment Pattern

Description

Extract a subset of a line segment pattern.

Usage

  ## S3 method for class 'psp'
x[i, j, drop, ..., fragments=TRUE]

Arguments

Details

These functions extract a designated subset of a line segment pattern.

The function [.psp is a method for [ for the class "psp". It extracts a designated subset of a line segment pattern, either by “thinning” (retaining/deleting some line segments of a line segment pattern) or “trimming” (reducing the window of observation to a smaller subregion and clipping the line segments to this boundary) or both.

The pattern will be “thinned” if subset is specified. The line segments designated by subset will be retained. Here subset can be a numeric vector of positive indices (identifying the line segments to be retained), a numeric vector of negative indices (identifying the line segments to be deleted) or a logical vector of length equal to the number of line segments in the line segment pattern x. In the latter case, the line segments for which subset[i]=TRUE will be retained, and the others will be deleted.

The pattern will be “trimmed” if window is specified. This should be an object of class owin specifying a window of observation to which the line segment pattern x will be trimmed. Line segments of x lying inside the new window will be retained unchanged. Line segments lying partially inside the new window and partially outside it will, by default, be clipped so that they lie entirely inside the window; but if fragments=FALSE, such segments will be removed.

Both “thinning” and “trimming” can be performed together.

Value

A line segment pattern (of class "psp").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

psp.object, owin.object

Examples

    a <- psp(runif(20),runif(20),runif(20),runif(20), window=owin())
    plot(a)
  # thinning
    id <- sample(c(TRUE, FALSE), 20, replace=TRUE)
    b <- a[id]
    plot(b, add=TRUE, lwd=3)
 # trimming
    plot(a)
    w <- owin(c(0.1,0.7), c(0.2, 0.8))
    b <- a[w]
    plot(b, add=TRUE, col="red", lwd=2)
    plot(w, add=TRUE)
    u <- a[w, fragments=FALSE]
    plot(u, add=TRUE, col="blue", lwd=3)

Subset of Quadrature Scheme

Description

Extract a subset of a quadrature scheme.

Usage

  ## S3 method for class 'quad'
x[...]

Arguments

Details

This function extracts a designated subset of a quadrature scheme.

The function [.quad is a method for [ for the class "quad". It extracts a designated subset of a quadrature scheme.

The subset to be extracted is determined by the arguments ... which are interpreted by [.ppp. Thus it is possible to take the subset consisting of all quadrature points that lie inside a given region, or a subset of quadrature points identified by numeric indices.

Value

A quadrature scheme (object of class "quad").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

quad.object, [.ppp.

Examples

 Q <- quadscheme(nztrees)
 W <- owin(c(0,148),c(0,95)) # a subwindow
 Q[W]

Extract or Replace Subset of a List of Spatial Objects

Description

Extract or replace some entries in a list of spatial objects, or extract a designated sub-region in each object.

Usage

  ## S3 method for class 'solist'
x[i, ...]

  ## S3 replacement method for class 'solist'
x[i] <- value

Arguments

Details

These are methods for extracting and replacing subsets for the class "solist".

The argument x should be an object of class "solist" representing a list of two-dimensional spatial objects. See solist.

For the subset method, the subset index i can be either a vector index (specifying some elements of the list) or a spatial window (specifying a spatial sub-region).

For the replacement method, i must be a vector index: the designated elements will be replaced.

Value

Another object of the same class as x.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

solist, plot.solist, summary.solist

Examples

   x <- solist(japanesepines, cells, redwood)
   x[2:3]
   x[square(0.5)]
   x[1] <- list(finpines)
 

Extract or Replace Sub-Patterns

Description

Extract or replace some of the sub-patterns in a split point pattern.

Usage

  ## S3 method for class 'splitppp'
x[...]
  ## S3 replacement method for class 'splitppp'
x[...] <- value

Arguments

Details

These are subset methods for the class "splitppp".

The argument x should be an object of class "splitppp", representing a point pattern that has been separated into a list of sub-patterns. It is created by split.ppp.

The methods extract or replace a designated subset of the list x, and return an object of class "splitppp".

Value

Another object of class "splitppp".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

split.ppp, plot.splitppp, summary.splitppp

Examples

  y <- split(amacrine)
  y[[1]]
  y[["off"]]
  y[[1]] <- rsyst(Window(amacrine), 4, 3)
 

Extract or Replace Subset of Tessellation

Description

Extract, change or delete a subset of the tiles of a tessellation, to make a new tessellation.

Usage

  ## S3 method for class 'tess'
x[i, ...]
  ## S3 replacement method for class 'tess'
x[i, ...] <- value

Arguments

Details

A tessellation (object of class "tess", see tess) is effectively a list of tiles (spatial regions) that cover a spatial region. The subset operator [.tess extracts some of these tiles and forms a new tessellation, which of course covers a smaller region than the original.

For [.tess only, the subset index can also be a window (object of class "owin"). The tessellation x is then intersected with the window.

The replacement operator changes the selected tiles. The replacement value may be either NULL (which causes the selected tiles to be removed from x) or a list of the same length as the selected subset. The entries of value may be windows (objects of class "owin") or NULL to indicate that the corresponding tile should be deleted.

Generally it does not make sense to replace a tile in a tessellation with a completely different tile, because the tiles are expected to fit together. However this facility is sometimes useful for making small adjustments to polygonal tiles.

Value

A tessellation (object of class "tess").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

tess, tiles, intersect.tess.

Examples

   
   A <- tess(xgrid=0:4, ygrid=0:3)
   B <- A[c(1, 3, 7)]
   E <- A[-1]
   A[c(2, 5, 11)] <- NULL
   

Extract or Change the Containing Rectangle of a Spatial Object

Description

Given a spatial object (such as a point pattern or pixel image) in two dimensions, these functions extract or change the containing rectangle inside which the object is defined.

Usage

   Frame(X)

   ## Default S3 method:
Frame(X)

   Frame(X) <- value

   ## S3 replacement method for class 'owin'
Frame(X) <- value

   ## S3 replacement method for class 'ppp'
Frame(X) <- value

   ## S3 replacement method for class 'im'
Frame(X) <- value

   ## Default S3 replacement method:
Frame(X) <- value

Arguments

Details

The functions Frame and Frame<- are generic.

Frame(X) extracts the rectangle inside which X is defined.

Frame(X) <- R changes the rectangle inside which X is defined to the new rectangle R.

Value

The result of Frame is a rectangular window (object of class "owin" of type "rectangle").

The result of Frame<- is the updated object X, of the same class as X.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

Window

Examples

   Frame(cells)
   X <- demopat
   Frame(X)
   Frame(X) <- owin(c(0, 11000), c(400, 8000))

S3 Group Generic methods for images

Description

These are group generic methods for images of class "im", which allows for usual mathematical functions and operators to be applied directly to images. See Details for a list of implemented functions.

Usage

## S3 methods for group generics have prototypes:
Math(x, ...)
Ops(e1, e2)
Complex(z)
Summary(..., na.rm=FALSE, drop=TRUE)

Arguments

Details

Below is a list of mathematical functions and operators which are defined for images. Not all functions will make sense for all types of images. For example, none of the functions in the "Math" group make sense for character-valued images. Note that the "Ops" group methods are implemented using eval.im, which tries to harmonise images via harmonise.im if they aren't compatible to begin with.

1. Group "Math":

   • abs, sign, sqrt,
     floor, ceiling, trunc,
     round, signif

   • exp, log, expm1, log1p,
     cos, sin, tan,
     cospi, sinpi, tanpi,
     acos, asin, atan

     cosh, sinh, tanh,
     acosh, asinh, atanh

   • lgamma, gamma, digamma, trigamma

   • cumsum, cumprod, cummax, cummin

2. Group "Ops":

   • "+", "-", "*", "/", "^", "%%", "%/%"

   • "&", "|", "!"

   • "==", "!=", "<", "<=", ">=", ">"

3. Group "Summary":

   • all, any

   • sum, prod

   • min, max

   • range

4. Group "Complex":

   • Arg, Conj, Im, Mod, Re

For the Summary group, the generic has an argument na.rm=FALSE, but for pixel images it makes sense to set na.rm=TRUE so that pixels outside the domain of the image are ignored. To enable this, we added the argument drop. Pixel values that are NA are removed if drop=TRUE or if na.rm=TRUE.

For the Ops group, one of the arguments is permitted to be a single atomic value instead of an image.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk and Kassel Hingee.

See Also

eval.im for evaluating expressions involving images.

Examples

  ## Convert gradient values to angle of inclination:
  V <- atan(bei.extra$grad) * 180/pi
  ## Make logical image which is TRUE when heat equals 'Moderate': 
  A <- (gorillas.extra$heat == "Moderate")
  ## Summary:
  any(A)
  ## Complex:
  Z <- exp(1 + V * 1i)
  Z
  Re(Z)

S3 Group Generic methods for List of Images

Description

These are group generic methods for the class "imlist" of lists of images. These methods allows the usual mathematical functions and operators to be applied directly to lists of images. See Details for a list of implemented functions.

Usage

## S3 methods for group generics have prototypes:
Math(x, ...)
Ops(e1, e2)
Complex(z)
Summary(..., na.rm = TRUE)

Arguments

Details

An object of class "imlist" represents a list of pixel images. It is a list, whose entries are pixel images (objects of class "im").

The following mathematical functions and operators are defined for lists of images.

Not all functions will make sense for all types of images. For example, none of the functions in the "Math" group make sense for character-valued images. Note that the "Ops" group methods are implemented using eval.im, which tries to harmonise images via harmonise.im if they aren't compatible to begin with.

1. Group "Math":

   • abs, sign, sqrt,
     floor, ceiling, trunc,
     round, signif

   • exp, log, expm1, log1p,
     cos, sin, tan,
     cospi, sinpi, tanpi,
     acos, asin, atan

     cosh, sinh, tanh,
     acosh, asinh, atanh

   • lgamma, gamma, digamma, trigamma

   • cumsum, cumprod, cummax, cummin

2. Group "Ops":

   • "+", "-", "*", "/", "^", "%%", "%/%"

   • "&", "|", "!"

   • "==", "!=", "<", "<=", ">=", ">"

3. Group "Summary":

   • all, any

   • sum, prod

   • min, max

   • range

4. Group "Complex":

   • Arg, Conj, Im, Mod, Re

For the binary operations in "Ops", either

• e1 and e2 are lists of pixel images, and contain the same number of images.

• one of e1,e2 is a list of pixel images, and the other is a single atomic value.

Value

The result of "Math", "Ops" and "Complex" group operations is another list of images. The result of "Summary" group operations is a numeric vector of length 1 or 2.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

Math.im or eval.im for evaluating expressions involving images. solapply for a wrapper for lapply.

Examples

  a <- solist(A=setcov(square(1)), B=setcov(square(2)))
  log(a)/2 - sqrt(a)
  range(a)

Minkowski Sum of Windows

Description

Compute the Minkowski sum of two spatial windows.

Usage

MinkowskiSum(A, B)

A %(+)% B

dilationAny(A, B)

Arguments

Details

The operator A %(+)% B and function MinkowskiSum(A,B) are synonymous: they both compute the Minkowski sum of the windows A and B. The function dilationAny computes the Minkowski dilation A %(+)% reflect(B).

The Minkowski sum of two spatial regions A and B is another region, formed by taking all possible pairs of points, one in A and one in B, and adding them as vectors. The Minkowski Sum A \oplus B is the set of all points a+b where a is in A and b is in B. A few common facts about the Minkowski sum are:

• The sum is symmetric: A \oplus B = B \oplus A.

• If B is a single point, then A \oplus B is a shifted copy of A.

• If A is a square of side length a, and B is a square of side length b, with sides that are parallel to the coordinate axes, then A \oplus B is a square of side length a+b.

• If A and B are discs of radius r and s respectively, then A \oplus B is a disc of redius r+s.

• If B is a disc of radius r centred at the origin, then A \oplus B is equivalent to the morphological dilation of A by distance r. See dilation.

The Minkowski dilation is the closely-related region A \oplus (-B) where (-B) is the reflection of B through the origin. The Minkowski dilation is the set of all vectors z such that, if B is shifted by z, the resulting set B+z has nonempty intersection with A.

The algorithm currently computes the result as a polygonal window using the polyclip library. It will be quite slow if applied to binary mask windows.

The arguments A and B can also be point patterns or line segment patterns. These are interpreted as spatial regions, the Minkowski sum is computed, and the result is returned as an object of the most appropriate type. The Minkowski sum of two point patterns is another point pattern. The Minkowski sum of a point pattern and a line segment pattern is another line segment pattern.

Value

A window (object of class "owin") except that if A is a point pattern, then the result is an object of the same type as B (and vice versa).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

See Also

dilation, erosionAny

Examples

  B <- square(0.2)
  RplusB <- letterR %(+)% B

  opa <- par(mfrow=c(1,2))
  FR <- grow.rectangle(Frame(letterR), 0.3)
  plot(FR, main="")
  plot(letterR, add=TRUE, lwd=2, hatch=TRUE, hatchargs=list(texture=5))
  plot(shift(B, vec=c(3.675, 3)),
       add=TRUE, border="red", lwd=2)
  plot(FR, main="")
  plot(letterR, add=TRUE, lwd=2, hatch=TRUE, hatchargs=list(texture=5))
  plot(RplusB, add=TRUE, border="blue", lwd=2,
         hatch=TRUE, hatchargs=list(col="blue"))
  par(opa)

  plot(cells %(+)% square(0.1))

Reset Values in Subset of Image

Description

Reset the values in a subset of a pixel image.

Usage

  ## S3 replacement method for class 'im'
x[i, j, ..., drop=TRUE] <- value

Arguments

Details

This function changes some of the pixel values in a pixel image. The image x must be an object of class "im" representing a pixel image defined inside a rectangle in two-dimensional space (see im.object).

The subset to be changed is determined by the arguments i,j according to the following rules (which are checked in this order):

1. i is a spatial object such as a window, a pixel image with logical values, or a point pattern; or

2. i,j are indices for the matrix as.matrix(x); or

3. i can be converted to a point pattern by as.ppp(i, W=Window(x)), and i is not a matrix.

If i is a spatial window (an object of class "owin"), the values of the image inside this window are changed.

If i is a point pattern (an object of class "ppp"), then the values of the pixel image at the points of this pattern are changed.

If i does not satisfy any of the conditions above, then the algorithm tries to interpret i,j as indices for the matrix as.matrix(x). Either i or j may be missing or blank.

If none of the conditions above are met, and if i is not a matrix, then i is converted into a point pattern by as.ppp(i, W=Window(x)). Again the values of the pixel image at the points of this pattern are changed.

If i and j are both missing, as in the call x[] <- value, then all pixel values in x are replaced by value:

• If drop=TRUE (the default), then this replacement applies only to pixels whose values are currently defined (i.e. where the current pixel value is not NA). If value is a vector, then its length must equal the number of pixels whose values are currently defined.

• If drop=FALSE then the replacement applies to all pixels inside the rectangle Frame(x). If value is a vector, then its length must equal the number of pixels in the entire rectangle.

Value

The image x with the values replaced.

Warning

If you have a 2-column matrix containing the x,y coordinates of point locations, then to prevent this being interpreted as an array index, you should convert it to a data.frame or to a point pattern.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

im.object, [.im, [, ppp.object, as.ppp, owin.object

Examples

 # make up an image
 X <- setcov(unit.square())
 plot(X)

 # a rectangular subset
 W <- owin(c(0,0.5),c(0.2,0.8))
 X[W] <- 2
 plot(X)

 # a polygonal subset
 R <- affine(letterR, diag(c(1,1)/2), c(-2,-0.7))
 X[R] <- 3
 plot(X)

 # a point pattern
 X[cells] <- 10
 plot(X)

 # change pixel value at a specific location
 X[list(x=0.1,y=0.2)] <- 7

 # matrix indexing --- single vector index
 X[1:2570] <- 10
 plot(X)

 # matrix indexing using double indices
 X[1:257,1:10] <- 5
 plot(X)

 # matrix indexing using a matrix of indices
 X[cbind(1:257,1:257)] <- 10
 X[cbind(257:1,1:257)] <- 10
 plot(X)

 # Blank indices
 Y <- as.im(letterR)
 plot(Y)
 Y[] <- 42  # replace values only inside the window 'R'
 plot(Y)
 Y[drop=FALSE] <- 7 # replace all values in the rectangle
 plot(Y)

 Z <- as.im(letterR)
 Z[] <- raster.x(Z, drop=TRUE) # excludes NA
 plot(Z)
 Z[drop=FALSE] <- raster.y(Z, drop=FALSE) # includes NA
 plot(Z)

Extract or Change the Window of a Spatial Object

Description

Given a spatial object (such as a point pattern or pixel image) in two dimensions, these functions extract or change the window in which the object is defined.

Usage

   Window(X, ...)

   Window(X, ...) <- value

   ## S3 method for class 'ppp'
Window(X, ...)

   ## S3 replacement method for class 'ppp'
Window(X, ...) <- value

   ## S3 method for class 'quad'
Window(X, ...)

   ## S3 replacement method for class 'quad'
Window(X, ...) <- value

   ## S3 method for class 'psp'
Window(X, ...)

   ## S3 replacement method for class 'psp'
Window(X, ...) <- value

   ## S3 method for class 'im'
Window(X, ...)

   ## S3 replacement method for class 'im'
Window(X, ...) <- value

Arguments

Details

The functions Window and Window<- are generic.

Window(X) extracts the spatial window in which X is defined.

Window(X) <- W changes the window in which X is defined to the new window W, and discards any data outside W. In particular:

• If X is a point pattern (object of class "ppp") then Window(X) <- W discards any points of X which fall outside W.

• If X is a quadrature scheme (object of class "quad") then Window(X) <- W discards any points of X which fall outside W, and discards the corresponding quadrature weights.

• If X is a line segment pattern (object of class "psp") then Window(X) <- W clips the segments of X to the boundaries of W.

• If X is a pixel image (object of class "im") then Window(X) <- W has the effect that pixels lying outside W are retained but their pixel values are set to NA.

Many other classes of spatial object have a method for Window, but not Window<-. See Window.tess.

Value

The result of Window is a window (object of class "owin").

The result of Window<- is the updated object X, of the same class as X.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

Window.ppm

Examples

   ## point patterns
   Window(cells)
   X <- demopat
   Window(X)
   Window(X) <- as.rectangle(Window(X))

   ## line segment patterns
   X <- psp(runif(10), runif(10), runif(10), runif(10), window=owin())
   Window(X)
   Window(X) <- square(0.5)

   ## images
   Z <- setcov(owin())
   Window(Z)
   Window(Z) <- square(0.5)

Extract Window of Spatial Object

Description

Given a spatial object (such as a point pattern or pixel image) in two dimensions, these functions extract the window in which the object is defined.

Usage

 ## S3 method for class 'quadratcount'
Window(X, ...)

 ## S3 method for class 'tess'
Window(X, ...)

 ## S3 method for class 'layered'
Window(X, ...)

 ## S3 method for class 'distfun'
Window(X, ...)

 ## S3 method for class 'nnfun'
Window(X, ...)

 ## S3 method for class 'funxy'
Window(X, ...)

Arguments

Details

These are methods for the generic function Window which extract the spatial window in which the object X is defined.

Value

An object of class "owin" (see owin.object) specifying an observation window.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

Window, Window.ppp, Window.psp.

owin.object

Examples

   A <- quadratcount(cells, 4)
   Window(A)

Fill Plot With Texture

Description

Draws a simple texture inside a region on the plot.

Usage

add.texture(W, texture = 4, spacing = NULL, ...)

Arguments

Details

The chosen texture, confined to the window W, will be added to the current plot. The available textures are:

texture=1:

Small crosses arranged in a square grid.

texture=2:

Parallel vertical lines.

texture=3:

Parallel horizontal lines.

texture=4:

Parallel diagonal lines at 45 degrees from the horizontal.

texture=5:

Parallel diagonal lines at 135 degrees from the horizontal.

texture=6:

Grid of horizontal and vertical lines.

texture=7:

Grid of diagonal lines at 45 and 135 degrees from the horizontal.

texture=8:

Grid of hexagons.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

owin, plot.owin, textureplot, texturemap.

Examples

  W <- Window(chorley)
  plot(W, main="")
  add.texture(W, 7)

Apply Affine Transformation

Description

Applies any affine transformation of the plane (linear transformation plus vector shift) to a plane geometrical object, such as a point pattern or a window.

Usage

  affine(X, ...)

Arguments

Details

This is generic. Methods are provided for point patterns (affine.ppp) and windows (affine.owin).

Value

Another object of the same type, representing the result of applying the affine transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

affine.ppp, affine.psp, affine.owin, affine.im, flipxy, reflect, rotate, shift

Apply Affine Transformation To Pixel Image

Description

Applies any affine transformation of the plane (linear transformation plus vector shift) to a pixel image.

Usage

  ## S3 method for class 'im'
affine(X, mat=diag(c(1,1)), vec=c(0,0), ...) 

Arguments

Details

The image is subjected first to the linear transformation represented by mat (multiplying on the left by mat), and then the result is translated by the vector vec.

The argument mat must be a nonsingular 2 \times 2 matrix.

This is a method for the generic function affine.

Value

Another pixel image (of class "im") representing the result of applying the affine transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

affine, affine.ppp, affine.psp, affine.owin, rotate, shift

Examples

  X <- setcov(owin())
  stretch <- diag(c(2,3))
  Y <- affine(X, mat=stretch)
  shear <- matrix(c(1,0,0.6,1),ncol=2, nrow=2)
  Z <- affine(X, mat=shear)

Apply Affine Transformation To Window

Description

Applies any affine transformation of the plane (linear transformation plus vector shift) to a window.

Usage

  ## S3 method for class 'owin'
affine(X, mat=diag(c(1,1)), vec=c(0,0), ..., rescue=TRUE)

Arguments

Details

The window is subjected first to the linear transformation represented by mat (multiplying on the left by mat), and then the result is translated by the vector vec.

The argument mat must be a nonsingular 2 \times 2 matrix.

This is a method for the generic function affine.

Value

Another window (of class "owin") representing the result of applying the affine transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

affine, affine.ppp, affine.psp, affine.im, rotate, shift

Examples

  # shear transformation
  shear <- matrix(c(1,0,0.6,1),ncol=2)
  X <- affine(owin(), shear)
  if(interactive()) plot(X)
  affine(letterR, shear, c(0, 0.5))
  affine(as.mask(letterR), shear, c(0, 0.5))

Apply Affine Transformation To Point Pattern

Description

Applies any affine transformation of the plane (linear transformation plus vector shift) to a point pattern.

Usage

 ## S3 method for class 'ppp'
affine(X, mat=diag(c(1,1)), vec=c(0,0), ...)

Arguments

Details

The point pattern, and its window, are subjected first to the linear transformation represented by mat (multiplying on the left by mat), and are then translated by the vector vec.

The argument mat must be a nonsingular 2 \times 2 matrix.

This is a method for the generic function affine.

Value

Another point pattern (of class "ppp") representing the result of applying the affine transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

affine, affine.owin, affine.psp, affine.im, flipxy, rotate, shift

Examples

  # shear transformation
  X <- affine(cells, matrix(c(1,0,0.6,1),ncol=2))
  if(interactive()) {
    plot(X)
    # rescale y coordinates by factor 1.3
    plot(affine(cells, diag(c(1,1.3))))
  }

Apply Affine Transformation To Line Segment Pattern

Description

Applies any affine transformation of the plane (linear transformation plus vector shift) to a line segment pattern.

Usage

 ## S3 method for class 'psp'
affine(X, mat=diag(c(1,1)), vec=c(0,0), ...)

Arguments

Details

The line segment pattern, and its window, are subjected first to the linear transformation represented by mat (multiplying on the left by mat), and are then translated by the vector vec.

The argument mat must be a nonsingular 2 \times 2 matrix.

This is a method for the generic function affine.

Value

Another line segment pattern (of class "psp") representing the result of applying the affine transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

affine, affine.owin, affine.ppp, affine.im, flipxy, rotate, shift

Examples

  oldpar <- par(mfrow=c(2,1))
  X <- psp(runif(10), runif(10), runif(10), runif(10), window=owin())
  plot(X, main="original")
  # shear transformation
  Y <- affine(X, matrix(c(1,0,0.6,1),ncol=2))
  plot(Y, main="transformed")
  par(oldpar)
  # 
  # rescale y coordinates by factor 0.2
  affine(X, diag(c(1,0.2)))

Apply Geometrical Transformation To Tessellation

Description

Apply various geometrical transformations of the plane to each tile in a tessellation.

Usage

  ## S3 method for class 'tess'
reflect(X)

  ## S3 method for class 'tess'
flipxy(X)

  ## S3 method for class 'tess'
shift(X, ...)

  ## S3 method for class 'tess'
rotate(X, angle=pi/2, ..., centre=NULL)

  ## S3 method for class 'tess'
scalardilate(X, f, ...)

  ## S3 method for class 'tess'
affine(X, mat=diag(c(1,1)), vec=c(0,0), ...)

Arguments

Details

These are method for the generic functions reflect, flipxy, shift, rotate, scalardilate, affine for tessellations (objects of class "tess").

The individual tiles of the tessellation, and the window containing the tessellation, are all subjected to the same geometrical transformation.

The transformations are performed by the corresponding method for windows (class "owin") or images (class "im") depending on the type of tessellation.

If the argument origin is used in shift.tess it is interpreted as applying to the window containing the tessellation. Then all tiles are shifted by the same vector.

Value

Another tessellation (of class "tess") representing the result of applying the geometrical transformation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

Generic functions reflect, shift, rotate, scalardilate, affine.

Methods for windows: reflect.default, shift.owin, rotate.owin, scalardilate.owin, affine.owin.

Methods for images: reflect.im, shift.im, rotate.im, scalardilate.im, affine.im.

Examples

  live <- interactive()
  if(live) {
    H <- hextess(letterR, 0.2)
    plot(H)
    plot(reflect(H))
    plot(rotate(H, pi/3))
  } else H <- hextess(letterR, 0.6)

  # shear transformation
  shear <- matrix(c(1,0,0.6,1),2,2)
  sH <- affine(H, shear)
  if(live) plot(sH)

Orientation Angles of Line Segments

Description

Computes the orientation angle of each line segment in a line segment pattern.

Usage

  angles.psp(x, directed=FALSE)

Arguments

Details

For each line segment, the angle of inclination to the x-axis (in radians) is computed, and the angles are returned as a numeric vector.

If directed=TRUE, the directed angle of orientation is computed. The angle respects the sense of direction from (x0,y0) to (x1,y1). The values returned are angles in the full range from -\pi to \pi. The angle is computed as atan2(y1-y0,x1-x0). See atan2.

If directed=FALSE, the undirected angle of orientation is computed. Angles differing by \pi are regarded as equivalent. The values returned are angles in the range from 0 to \pi. These angles are computed by first computing the directed angle, then adding \pi to any negative angles.

Value

Numeric vector.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

psp, marks.psp, summary.psp, midpoints.psp, lengths_psp, endpoints.psp, extrapolate.psp.

Examples

  a <- psp(runif(10), runif(10), runif(10), runif(10), window=owin())
  b <- angles.psp(a)   

Check Whether Image Contains NA Values

Description

Checks whether any pixel values in a pixel image are NA (meaning that the pixel lies outside the domain of definition of the image).

Usage

  ## S3 method for class 'im'
anyNA(x, recursive = FALSE)

Arguments

Details

The function anyNA is generic: anyNA(x) is a faster alternative to any(is.na(x)).

This function anyNA.im is a method for the generic anyNA defined for pixel images. It returns the value TRUE if any of the pixel values in x are NA, and and otherwise returns FALSE.

Value

A single logical value.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

im.object

Examples

  anyNA(as.im(letterR))

List of Objects

Description

Make a list of objects of any type.

Usage

anylist(...)
as.anylist(x)

Arguments

Details

An object of class "anylist" is a list of objects that the user intends to treat in a similar fashion.

For example it may be desired to plot each of the objects side-by-side: this can be done using the function plot.anylist.

The objects can belong to any class; they may or may not all belong to the same class.

In the spatstat package, various functions produce an object of class "anylist".

Value

A list, belonging to the class "anylist", containing the original objects.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

Rolf Turner rolfturner@posteo.net

and Ege Rubak rubak@math.aau.dk

See Also

solist, as.solist, anylapply.

Examples

  if(require(spatstat.explore)) {
    anylist(cells, intensity(cells), Kest(cells))
  } else {
    anylist(cells, intensity(cells))
  }
  anylist()

Combine Two Line Segment Patterns

Description

Combine two line segment patterns into a single pattern.

Usage

  append.psp(A, B)

Arguments

Details

This function is used to superimpose two line segment patterns A and B.

The two patterns must have identical windows. If one pattern has marks, then the other must also have marks of the same type. It the marks are data frames then the number of columns of these data frames, and the names of the columns must be identical.

(To combine two point patterns, see superimpose).

If one of the arguments is NULL, it will be ignored and the other argument will be returned.

Value

Another line segment pattern (object of class "psp").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

psp, as.psp, superimpose,

Examples

  X <- psp(runif(20), runif(20), runif(20), runif(20),  window=owin())
  Y <- psp(runif(5), runif(5), runif(5), runif(5),  window=owin())
  append.psp(X,Y)

Apply Function to Every Neighbourhood in a Point Pattern

Description

Visit each point in a point pattern, find the neighbouring points, and apply a given function to them.

Usage

   applynbd(X, FUN, N=NULL, R=NULL, criterion=NULL, exclude=FALSE, ...)

Arguments

Details

This is an analogue of apply for point patterns. It visits each point in the point pattern X, determines which points of X are “neighbours” of the current point, applies the function FUN to this neighbourhood, and collects the values returned by FUN.

The definition of “neighbours” depends on the arguments N, R and criterion. Also the argument exclude determines whether the current point is excluded from its own neighbourhood.

• If N is given, then the neighbours of the current point are the N points of X which are closest to the current point (including the current point itself unless exclude=TRUE).

• If R is given, then the neighbourhood of the current point consists of all points of X which lie closer than a distance R from the current point.

• If criterion is given, then it must be a function with two arguments dist and drank which will be vectors of equal length. The interpretation is that dist[i] will be the distance of a point from the current point, and drank[i] will be the rank of that distance (the three points closest to the current point will have rank 1, 2 and 3). This function must return a logical vector of the same length as dist and drank whose i-th entry is TRUE if the corresponding point should be included in the neighbourhood. See the examples below.

• If more than one of the arguments N, R and criterion is given, the neighbourhood is defined as the intersection of the neighbourhoods specified by these arguments. For example if N=3 and R=5 then the neighbourhood is formed by finding the 3 nearest neighbours of current point, and retaining only those neighbours which lie closer than 5 units from the current point.

When applynbd is executed, each point of X is visited, and the following happens for each point:

• the neighbourhood of the current point is determined according to the chosen rule, and stored as a point pattern Y;

• the function FUN is called as:

  FUN(Y=Y, current=current, dists=dists, dranks=dranks, ...)

  where current is the location of the current point (in a format explained below), dists is a vector of distances from the current point to each of the points in Y, dranks is a vector of the ranks of these distances with respect to the full point pattern X, and ... are the arguments passed from the call to applynbd;

• The result of the call to FUN is stored.

The results of each call to FUN are collected and returned according to the usual rules for apply and its relatives. See the Value section of this help file.

The format of the argument current is as follows. If X is an unmarked point pattern, then current is a list of length 2 with entries current$x and current$y containing the coordinates of the current point. If X is marked, then current is a point pattern containing exactly one point, so that current$x is its x-coordinate and current$marks is its mark value. In either case, the coordinates of the current point can be referred to as current$x and current$y.

Note that FUN will be called exactly as described above, with each argument named explicitly. Care is required when writing the function FUN to ensure that the arguments will match up. See the Examples.

See markstat for a common use of this function.

To simply tabulate the marks in every R-neighbourhood, use marktable.

Value

Similar to the result of apply. If each call to FUN returns a single numeric value, the result is a vector of dimension npoints(X), the number of points in X. If each call to FUN returns a vector of the same length m, then the result is a matrix of dimensions c(m,n); note the transposition of the indices, as usual for the family of apply functions. If the calls to FUN return vectors of different lengths, the result is a list of length npoints(X).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

ppp.object, apply, markstat, marktable

Examples

  redwood
  # count the number of points within radius 0.2 of each point of X
  nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){npoints(Y)-1})
  # equivalent to:
  nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){npoints(Y)}, exclude=TRUE)

  # compute the distance to the second nearest neighbour of each point
  secondnndist <- applynbd(redwood, N = 2,
                           function(dists, ...){max(dists)},
                           exclude=TRUE)

  # marked point pattern
  trees <- longleaf
  
  # compute the median of the marks of all neighbours of a point
  # (see also 'markstat')
  dbh.med <- applynbd(trees, R=90, exclude=TRUE,
                 function(Y, ...) { median(marks(Y))})


  # ANIMATION explaining the definition of the K function
  # (arguments `fullpicture' and 'rad' are passed to FUN)

  if(interactive()) {
  showoffK <- function(Y, current, dists, dranks, fullpicture,rad) { 
	plot(fullpicture, main="")
	points(Y, cex=2)
        ux <- current[["x"]]
        uy <- current[["y"]]
	points(ux, uy, pch="+",cex=3)
	theta <- seq(0,2*pi,length=100)
	polygon(ux + rad * cos(theta), uy+rad*sin(theta))
	text(ux + rad/3, uy + rad/2,npoints(Y),cex=3)
	if(interactive()) Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
	return(npoints(Y))
  }
  applynbd(redwood, R=0.2, showoffK, fullpicture=redwood, rad=0.2, exclude=TRUE)

  # animation explaining the definition of the G function

  showoffG <- function(Y, current, dists, dranks, fullpicture) { 
	plot(fullpicture, main="")
	points(Y, cex=2)
        u <- current
	points(u[1],u[2],pch="+",cex=3)
	v <- c(Y$x[1],Y$y[1])
	segments(u[1],u[2],v[1],v[2],lwd=2)
	w <- (u + v)/2
	nnd <- dists[1]
	text(w[1],w[2],round(nnd,3),cex=2)
	if(interactive()) Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
	return(nnd)
  }

  applynbd(cells, N=1, showoffG, exclude=TRUE, fullpicture=cells)
  }

Area of a Window

Description

Computes the area of a window

Usage

 area(w)

 ## S3 method for class 'owin'
area(w)

 ## Default S3 method:
area(w)

 ## S3 method for class 'owin'
volume(x)

Arguments

Details

If the window w is of type "rectangle" or "polygonal", the area of this rectangular window is computed by analytic geometry. If w is of type "mask" the area of the discrete raster approximation of the window is computed by summing the binary image values and adjusting for pixel size.

The function volume.owin is identical to area.owin except for the argument name. It is a method for the generic function volume.

Value

A numerical value giving the area of the window.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

perimeter, diameter.owin, owin.object, as.owin

Examples

  w <- unit.square()
  area(w)
       # returns 1.00000

  k <- 6
  theta <- 2 * pi * (0:(k-1))/k
  co <- cos(theta)
  si <- sin(theta)
  mas <- owin(c(-1,1), c(-1,1), poly=list(x=co, y=si))
  area(mas)
      # returns approx area of k-gon
  
  mas <- as.mask(square(2), eps=0.01)
  X <- raster.x(mas)
  Y <- raster.y(mas)
  mas$m <- ((X - 1)^2 + (Y - 1)^2 <= 1)
  area(mas)
       # returns 3.14 approx     

Difference of Disc Areas

Description

Computes the area of that part of a disc that is not covered by other discs.

Usage

   areaGain(u, X, r, ..., W=as.owin(X), exact=FALSE,
                     ngrid=spatstat.options("ngrid.disc"))

Arguments

Details

This function computes the area of that part of the disc of radius r centred at the location u that is not covered by any of the discs of radius r centred at the points of the pattern X. This area is important in some calculations related to the area-interaction model AreaInter.

If u is a point pattern and r is a vector, the result is a matrix, with one row for each point in u and one column for each entry of r. The [i,j] entry in the matrix is the area of that part of the disc of radius r[j] centred at the location u[i] that is not covered by any of the discs of radius r[j] centred at the points of the pattern X.

If W is not NULL, then the areas are computed only inside the window W.

Value

A matrix with one row for each point in u and one column for each value in r.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

AreaInter, areaLoss

Examples

   u <- c(0.5,0.5)
   areaGain(u, cells, 0.1)

Difference of Disc Areas

Description

Computes the area of that part of a disc that is not covered by other discs.

Usage

   areaLoss(X, r, ..., W=as.owin(X), subset=NULL,
                 exact=FALSE,
                 ngrid=spatstat.options("ngrid.disc"))

Arguments

Details

This function computes, for each point X[i] in X and for each radius r, the area of that part of the disc of radius r centred at the location X[i] that is not covered by any of the other discs of radius r centred at the points X[j] for j not equal to i. This area is important in some calculations related to the area-interaction model AreaInter.

The result is a matrix, with one row for each point in X and one column for each entry of r.

Value

A matrix with one row for each point in X (or X[subset]) and one column for each value in r.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

AreaInter, areaGain, dilated.areas

Examples

   areaLoss(cells, 0.1)

Convert Data to Three-Dimensional Box

Description

Interprets data as the dimensions of a three-dimensional box.

Usage

as.box3(...)

Arguments

Details

This function converts data in various formats to an object of class "box3" representing a three-dimensional box (see box3). The arguments ... may be

• an object of class "box3"

• arguments acceptable to box3

• a numeric vector of length 6, interpreted as c(xrange[1],xrange[2],yrange[1],yrange[2],zrange[1],zrange[2])

• an object of class "pp3" representing a three-dimensional point pattern contained in a box.

Value

Object of class "box3".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

box3, pp3

Examples

    X <- c(0,10,0,10,0,5)
    as.box3(X)
    X <- pp3(runif(42),runif(42),runif(42), box3(c(0,1)))
    as.box3(X)

Convert Data to Multi-Dimensional Box

Description

Interprets data as the dimensions of a multi-dimensional box.

Usage

  as.boxx(..., warn.owin = TRUE)

Arguments

Details

Either a single argument should be provided which is one of the following:

• an object of class "boxx"

• an object of class "box3"

• an object of class "owin"

• a numeric vector of even length, specifying the corners of the box. See Examples

or a list of arguments acceptable to boxx.

Value

A "boxx" object.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

Rolf Turner rolfturner@posteo.net

and Ege Rubak rubak@math.aau.dk

Examples

 # Convert unit square to two dimensional box.
 W <- owin()
 as.boxx(W)
 # Make three dimensional box [0,1]x[0,1]x[0,1] from numeric vector
 as.boxx(c(0,1,0,1,0,1))

Convert to Colour Map

Description

Convert some other kind of data to a colour map.

Usage

  as.colourmap(x, ...)

  ## S3 method for class 'colourmap'
as.colourmap(x, ...)

  ## S3 method for class 'symbolmap'
as.colourmap(x, ..., warn=TRUE)

Arguments

Details

If x contains colour map information, it will be extracted and returned as a colour map object. Otherwise, NULL will be returned (and a warning will be issued if warn=TRUE, the default).

Value

A colour map (object of class "colourmap") or NULL.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

colourmap

Examples

  m <- pHcolourmap(c(3,8))
  g <- symbolmap(pch=21, bg=m, size=function(x){ 1.1 * x }, range=c(3,8))
  opa <- par(mfrow=c(1,2))
  plot(g, vertical=TRUE)
  plot(as.colourmap(g), vertical=TRUE)
  par(opa)

Coerce Hyperframe to Data Frame

Description

Converts a hyperframe to a data frame.

Usage

## S3 method for class 'hyperframe'
as.data.frame(x, row.names = NULL,
                                  optional = FALSE, ..., 
                                  discard=TRUE, warn=TRUE)

Arguments

Details

This is a method for the generic function as.data.frame for the class of hyperframes (see hyperframe.

If discard=TRUE, any columns of the hyperframe that do not contain atomic data will be removed (and a warning will be issued if warn=TRUE). If discard=FALSE, then such columns are converted to strings indicating what class of data they originally contained.

Value

A data frame.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

Examples

  h <- hyperframe(X=1:3, Y=letters[1:3], f=list(sin, cos, tan))
  as.data.frame(h, discard=TRUE, warn=FALSE)
  as.data.frame(h, discard=FALSE)

Convert Pixel Image to Data Frame

Description

Convert a pixel image to a data frame

Usage

  ## S3 method for class 'im'
as.data.frame(x, ...)

Arguments

Details

This function takes the pixel image x and returns a data frame with three columns containing the pixel coordinates and the pixel values.

The data frame entries are automatically sorted in increasing order of the x coordinate (and in increasing order of y within x).

Value

A data frame.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

Examples

   # artificial image
   Z <- setcov(square(1))

   Y <- as.data.frame(Z)

   head(Y)

Convert Window to Data Frame

Description

Converts a window object to a data frame.

Usage

## S3 method for class 'owin'
as.data.frame(x, ..., drop=TRUE)

Arguments

Details

This function returns a data frame specifying the coordinates of the window.

If x is a binary mask window, the result is a data frame with columns x and y containing the spatial coordinates of each pixel. If drop=TRUE (the default), only pixels inside the window are retained. If drop=FALSE, all pixels are retained, and the data frame has an extra column inside containing the logical value of each pixel (TRUE for pixels inside the window, FALSE for outside).

If x is a rectangle or a polygonal window, the result is a data frame with columns x and y containing the spatial coordinates of the vertices of the window. If the boundary consists of several polygons, the data frame has additional columns id, identifying which polygon is being traced, and sign, indicating whether the polygon is an outer or inner boundary (sign=1 and sign=-1 respectively).

Value

A data frame with columns named x and y, and possibly other columns.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

as.data.frame.im, as.owin.data.frame

Examples

   as.data.frame(square(1))

   holey <- owin(poly=list(
                        list(x=c(0,10,0), y=c(0,0,10)),
                        list(x=c(2,2,4,4), y=c(2,4,4,2))))
   as.data.frame(holey)

   M <- as.mask(holey, eps=0.5)
   Mdf <- as.data.frame(M)

Coerce Point Pattern to a Data Frame

Description

Extracts the coordinates of the points in a point pattern, and their marks if any, and returns them in a data frame.

Usage

## S3 method for class 'ppp'
as.data.frame(x, row.names = NULL, ...)

Arguments

Details

This is a method for the generic function as.data.frame for the class "ppp" of point patterns.

It extracts the coordinates of the points in the point pattern, and returns them as columns named x and y in a data frame. If the points were marked, the marks are returned as a column named marks with the same type as in the point pattern dataset.

Value

A data frame.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

Examples

  df <- as.data.frame(amacrine)
  df[1:5,]

Coerce Line Segment Pattern to a Data Frame

Description

Extracts the coordinates of the endpoints in a line segment pattern, and their marks if any, and returns them in a data frame.

Usage

## S3 method for class 'psp'
as.data.frame(x, row.names = NULL, ...)

Arguments

Details

This is a method for the generic function as.data.frame for the class "psp" of line segment patterns.

It extracts the coordinates of the endpoints of the line segments, and returns them as columns named x0, y0, x1 and y1 in a data frame. If the line segments were marked, the marks are appended as an extra column or columns to the data frame which is returned. If the marks are a vector then a single column named marks is appended. in the data frame, with the same type as in the line segment pattern dataset. If the marks are a data frame, then the columns of this data frame are appended (retaining their names).

Value

A data frame with 4 or 5 columns.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

Examples

  df <- as.data.frame(copper$Lines)

Convert Tessellation to Data Frame

Description

Converts a spatial tessellation object to a data frame.

Usage

## S3 method for class 'tess'
as.data.frame(x, ...)

Arguments

Details

This function converts the tessellation x to a data frame.

If x is a pixel image tessellation (a pixel image with factor values specifying the tile membership of each pixel) then this pixel image is converted to a data frame by as.data.frame.im. The result is a data frame with columns x and y giving the pixel coordinates, and Tile identifying the tile containing the pixel.

If x is a tessellation consisting of a rectangular grid of tiles or a list of polygonal tiles, then each tile is converted to a data frame by as.data.frame.owin, and these data frames are joined together, yielding a single large data frame containing columns x, y giving the coordinates of vertices of the polygons, and Tile identifying the tile.

Value

A data frame with columns named x, y, Tile, and possibly other columns.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

as.data.frame.owin, as.data.frame.im

Examples

  Z <- as.data.frame(dirichlet(cells))
  head(Z, 10)

Convert Pixel Image to Function of Coordinates

Description

Converts a pixel image to a function of the x and y coordinates.

Usage

 ## S3 method for class 'im'
as.function(x, ...)

Arguments

Details

This command converts a pixel image (object of class "im") to a function(x,y) where the arguments x and y are (vectors of) spatial coordinates. This function returns the pixel values at the specified locations.

Value

A function in the R language, also belonging to the class "funxy".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

Rolf Turner rolfturner@posteo.net

and Ege Rubak rubak@math.aau.dk

See Also

[.im

Examples

  d <- setcov(square(1))
  f <- as.function(d)
  f(0.1, 0.3)

Convert Window to Indicator Function

Description

Converts a spatial window to a function of the x and y coordinates returning the value 1 inside the window and 0 outside.

Usage

 ## S3 method for class 'owin'
as.function(x, ...)

Arguments

Details

This command converts a spatial window (object of class "owin") to a function(x,y) where the arguments x and y are (vectors of) spatial coordinates. This is the indicator function of the window: it returns the value 1 for locations inside the window, and returns 0 for values outside the window.

Value

A function in the R language with arguments x,y. It also belongs to the class "indicfun" which has methods for plot and print.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

as.im.owin

Examples

  W <- Window(humberside)
  f <- as.function(W)
  f
  f(5000, 4500)
  f(123456, 78910)
  X <- runifrect(5, Frame(humberside))
  f(X)
  plot(f)

Convert a Tessellation to a Function

Description

Convert a tessellation into a function of the x and y coordinates. The default function values are factor levels specifying which tile of the tessellation contains the point (x,y).

Usage

  ## S3 method for class 'tess'
as.function(x,...,values=NULL)

Arguments

Details

This command converts a tessellation (object of class "tess") to a function(x,y) where the arguments x and y are (vectors of) spatial coordinates. The corresponding function values are factor levels identifying which tile of the tessellation contains each point. Values are NA if the corresponding point lies outside the tessellation.

If the argument values is given, then it determines the value of the function in each tile of x.

Value

A function in the R language, also belonging to the class "funxy" and "tessfun".

The class "tessfun" has methods for plot, print, as.tess and integral.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

integral.tessfun for integration of the function.

tileindex for the low-level calculation of tile index.

cut.ppp and split.ppp to divide up the points of a point pattern according to a tessellation.

Examples

  X <- runifrect(7)
  V <- dirichlet(X)
  f <- as.function(V)
  f(0.1, 0.4)
  plot(f)

Convert Data to Hyperframe

Description

Converts data from any suitable format into a hyperframe.

Usage

as.hyperframe(x, ...)

## Default S3 method:
as.hyperframe(x, ...)

## S3 method for class 'data.frame'
as.hyperframe(x, ..., stringsAsFactors=FALSE)

## S3 method for class 'hyperframe'
as.hyperframe(x, ...)

## S3 method for class 'listof'
as.hyperframe(x, ...)

## S3 method for class 'anylist'
as.hyperframe(x, ...)

Arguments

Details

A hyperframe is like a data frame, except that its entries can be objects of any kind.

The generic function as.hyperframe converts any suitable kind of data into a hyperframe.

There are methods for the classes data.frame, listof, anylist and a default method, all of which convert data that is like a hyperframe into a hyperframe object. (The method for the class listof and anylist converts a list of objects, of arbitrary type, into a hyperframe with one column.) These methods do not discard any information.

There are also methods for other classes (see as.hyperframe.ppx) which extract the coordinates from a spatial dataset. These methods do discard some information.

Value

An object of class "hyperframe" created by hyperframe.

Conversion of Strings to Factors

Note that as.hyperframe.default will convert a character vector to a factor. It behaves like as.data.frame.

However as.hyperframe.data.frame does not convert strings to factors; it respects the structure of the data frame x.

The behaviour can be changed using the argument stringsAsFactors.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net.

See Also

hyperframe, as.hyperframe.ppx

Examples

   df <- data.frame(x=runif(4),y=letters[1:4])
   as.hyperframe(df)

   sims <- replicate(3, runifrect(10), simplify=FALSE)
   as.hyperframe(as.listof(sims))
   as.hyperframe(as.solist(sims))

Extract coordinates and marks of multidimensional point pattern

Description

Given any kind of spatial or space-time point pattern, extract the coordinates and marks of the points.

Usage

## S3 method for class 'ppx'
as.hyperframe(x, ...)
## S3 method for class 'ppx'
as.data.frame(x, ...)
## S3 method for class 'ppx'
as.matrix(x, ...)

Arguments

Details

An object of class "ppx" (see ppx) represents a marked point pattern in multidimensional space and/or time. There may be any number of spatial coordinates, any number of temporal coordinates, and any number of mark variables. The individual marks may be atomic (numeric values, factor values, etc) or objects of any kind.

The function as.hyperframe.ppx extracts the coordinates and the marks as a "hyperframe" (see hyperframe) with one row of data for each point in the pattern. This is a method for the generic function as.hyperframe.

The function as.data.frame.ppx discards those mark variables which are not atomic values, and extracts the coordinates and the remaining marks as a data.frame with one row of data for each point in the pattern. This is a method for the generic function as.data.frame.

Finally as.matrix(x) is equivalent to as.matrix(as.data.frame(x)) for an object of class "ppx". Be warned that, if there are any columns of non-numeric data (i.e. if there are mark variables that are factors), the result will be a matrix of character values.

Value

A hyperframe, data.frame or matrix as appropriate.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

ppx, hyperframe, as.hyperframe.

Examples

   df <- data.frame(x=runif(4),y=runif(4),t=runif(4))
   X <- ppx(data=df, coord.type=c("s","s","t"))
   as.data.frame(X)

   # ppx with marks which are point patterns
   val <- runif(4, max=10)
   num <- sapply(val, rpois, n=1)
   E <- lapply(num, runifrect)
   hf <- hyperframe(t=val, e=as.listof(E))
   Z <- ppx(data=hf, domain=c(0,10))

   # convert ppx to a hyperframe
   as.hyperframe(Z)
   as.data.frame(Z)

Convert to Pixel Image

Description

Converts various kinds of data to a pixel image

Usage

  as.im(X, ...)

  ## S3 method for class 'im'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL)

  ## S3 method for class 'owin'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL, value=1)

  ## S3 method for class 'matrix'
as.im(X, W=NULL, ...)

  ## S3 method for class 'tess'
as.im(X, W=NULL, ..., 
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL, values=NULL)

  ## S3 method for class 'function'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL,
        stringsAsFactors=NULL,
        strict=FALSE, drop=TRUE)

  ## S3 method for class 'funxy'
as.im(X, W=Window(X), ...)

  ## S3 method for class 'expression'
as.im(X, W=NULL, ...)

  ## S3 method for class 'distfun'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL, approx=TRUE)

  ## S3 method for class 'nnfun'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL, approx=TRUE)

  ## S3 method for class 'data.frame'
as.im(X, ..., step, fatal=TRUE, drop=TRUE)

  ## Default S3 method:
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"),
        na.replace=NULL)

Arguments

Details

This function converts the data X into a pixel image object of class "im" (see im.object). The function as.im is generic, with methods for the classes listed above.

Currently X may be any of the following:

• a pixel image object, of class "im".

• a window object, of class "owin" (see owin.object). The result is an image with all pixel entries equal to value inside the window X, and NA outside.

• a matrix.

• a tessellation (object of class "tess"). By default, the result is a factor-valued image, with one factor level corresponding to each tile of the tessellation. Pixels are classified according to the tile of the tessellation into which they fall. If argument values is given, the result is a pixel image in which every pixel inside the i-th tile of the tessellation has pixel value equal to values[i].

• a single number (or a single logical, complex, factor or character value). The result is an image with all pixel entries equal to this constant value inside the window W (and NA outside, unless the argument na.replace is given). Argument W is required.

• a function of the form function(x, y, ...) which is to be evaluated to yield the image pixel values. In this case, the additional argument W must be present. This window will be converted to a binary image mask. Then the function X will be evaluated in the form X(x, y, ...) where x and y are vectors containing the x and y coordinates of all the pixels in the image mask, and ... are any extra arguments given. This function must return a vector or factor of the same length as the input vectors, giving the pixel values.

• an object of class "funxy" representing a function(x,y,...) defined in a spatial region. The function will be evaluated as described above. The window W defaults to the domain of definition of the function.

• an object of class "funxy" which also belongs to one of the following special classes. If approx=TRUE (the default), the function will be evaluated approximately using a very fast algorithm. If approx=FALSE, the function will be evaluated exactly at each grid location as described above.

  • an object of class "distfun" representing a distance function (created by the command distfun). The fast approximation is the distance transform distmap.

  • an object of class "nnfun" representing a nearest neighbour function (created by the command nnfun). The fast approximation is nnmap.

  • an object of class "densityfun" representing a kernel estimate of intensity (created by the command densityfun). The fast approximation is the Fast Fourier Transform algorithm in density.ppp.

  • an object of class "Smoothfun" representing kernel-smoothed values (created by the command Smoothfun). The fast approximation is the Fast Fourier Transform algorithm in Smooth.ppp.

• An expression involving the variables x and y representing the spatial coordinates, and possibly also involving other variables. The additional argument W must be present; it will be converted to a binary image mask. The expression X will be evaluated in an environment where x and y are vectors containing the spatial coordinates of all the pixels in the image mask. Evaluation of the expression X must yield a vector or factor, of the same length as x and y, giving the pixel values.

• a list with entries x, y, z in the format expected by the standard R functions image.default and contour.default. That is, z is a matrix of pixel values, x and y are vectors of x and y coordinates respectively, and z[i,j] is the pixel value for the location (x[i],y[j]).

• a point pattern (object of class "ppp"). See the separate documentation for as.im.ppp.

• A data frame with at least three columns. Columns named x, y and z, if present, will be assumed to contain the spatial coordinates and the pixel values, respectively. Otherwise the x and y coordinates will be taken from the first two columns of the data frame, and any remaining columns will be interpreted as pixel values.

The spatial domain (enclosing rectangle) of the pixel image is determined by the argument W. If W is absent, the spatial domain is determined by X. When X is a function, a matrix, or a single numerical value, W is required.

The pixel array dimensions of the final resulting image are determined by (in priority order)

• the argument eps, dimyx or xy if present;

• the pixel dimensions of the window W, if it is present and if it is a binary mask;

• the pixel dimensions of X if it is an image, a binary mask, or a list(x,y,z);

• the default pixel dimensions, controlled by spatstat.options.

Note that if eps, dimyx or xy is given, this will override the pixel dimensions of X if it has them. Thus, as.im can be used to change an image's pixel dimensions.

If the argument na.replace is given, then all NA entries in the image will be replaced by this value. The resulting image is then defined everwhere on the full rectangular domain, instead of a smaller window. Here na.replace should be a single value, of the same type as the other entries in the image.

If X is a pixel image that was created by an older version of spatstat, the command X <- as.im(X) will repair the internal format of X so that it conforms to the current version of spatstat.

If X is a data frame with m columns, then m-2 columns of data are interpreted as pixel values, yielding m-2 pixel images. The result of as.im.data.frame is a list of pixel images, belonging to the class "imlist". If m = 3 and drop=TRUE (the default), then the result is a pixel image rather than a list containing this image.

If X is a function(x,y) which returns a matrix of values, then as.im(X, W) will be a list of pixel images.

Value

A pixel image (object of class "im"), or a list of pixel images, or NULL if the conversion failed.

Character-valued images

By default, if the pixel value data are character strings, they will be treated as levels of a factor, and the resulting image will be factor-valued. To prevent the conversion of character strings to factors, use the argument stringsAsFactors=FALSE, which is recognised by most of the methods for as.im, or alternatively set options(stringsAsFactors=FALSE).

Handling Character Strings

The argument stringsAsFactors is a logical value (passed to data.frame) specifying how to handle pixel values which are character strings. If TRUE, character values are interpreted as factor levels. If FALSE, they remain as character strings. The default values of stringsAsFactors depends on the version of R.

• In R versions < 4.1.0 the factory-fresh default is stringsAsFactors=FALSE and the default can be changed by setting options(stringsAsFactors=FALSE).

• In R versions >= 4.1.0 the default is stringsAsFactors=FALSE and there is no option to change the default.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

Separate documentation for as.im.ppp

Examples

  # window object
  W <- Window(demopat)
  plot(W)
  Z <- as.im(W)
  image(Z)
  # function
  Z <- as.im(function(x,y) {x^2 + y^2}, unit.square())
  image(Z)
  # or as an expression
  Z <- as.im(expression(x^2+y^2), square(1))

  # function with extra arguments
  f <- function(x, y, x0, y0) {
      sqrt((x - x0)^2 + (y-y0)^2)
  }
  Z <- as.im(f, unit.square(), x0=0.5, y0=0.5)
  image(Z)

  # Revisit the Sixties
  Z <- as.im(f, letterR, x0=2.5, y0=2)
  image(Z)
  # usual convention in R
  stuff <- list(x=1:10, y=1:10, z=matrix(1:100, nrow=10))
  Z <- as.im(stuff)
  # convert to finer grid
  Z <- as.im(Z, dimyx=256)

  #' distance functions
  d <- distfun(redwood)
  Zapprox <- as.im(d)
  Zexact <- as.im(d, approx=FALSE)
  plot(solist(approx=Zapprox, exact=Zexact), main="")

  # pixellate the Dirichlet tessellation
  Di <- dirichlet(redwood)
  plot(as.im(Di))
  plot(Di, add=TRUE, border="white")

  # as.im.data.frame is the reverse of as.data.frame.im
  grad <- bei.extra$grad
  slopedata <- as.data.frame(grad)
  slope <- as.im(slopedata)
  unitname(grad) <- unitname(slope) <- unitname(grad) # for compatibility
  all.equal(slope, grad) # TRUE

  ## handling of character values
  as.im("a", W=letterR, na.replace="b")
  as.im("a", W=letterR, na.replace="b", stringsAsFactors=FALSE)

Convert Data To Layered Object

Description

Converts spatial data into a layered object.

Usage

 as.layered(X)

 ## Default S3 method:
as.layered(X)

 ## S3 method for class 'ppp'
as.layered(X)

 ## S3 method for class 'splitppp'
as.layered(X)

 ## S3 method for class 'solist'
as.layered(X)

 ## S3 method for class 'listof'
as.layered(X)

Arguments

Details

This function converts the object X into an object of class "layered".

The argument X should contain some kind of spatial data such as a point pattern, window, or pixel image.

If X is a simple object then it will be converted into a layered object containing only one layer which is equivalent to X.

If X can be interpreted as consisting of multiple layers of data, then the result will be a layered object consisting of these separate layers of data.

• if X is a list of class "listof" or "solist", then as.layered(X) consists of several layers, one for each entry in the list X;

• if X is a multitype point pattern, then as.layered(X) consists of several layers, each containing the sub-pattern consisting of points of one type;

• if X is a vector-valued measure, then as.layered(X) consists of several layers, each containing a scalar-valued measure.

Value

An object of class "layered" (see layered).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

as.layered.msr, layered, split.ppp

Examples

   as.layered(cells)
   as.layered(amacrine)

Pixel Image Approximation of a Window

Description

Obtain a discrete (pixel image) approximation of a given window

Usage

 as.mask(w, eps=NULL, dimyx=NULL, xy=NULL,
         rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"))

Arguments

Details

A ‘mask’ is a spatial window that is represented by a pixel image with binary values. It is an object of class "owin" with type "mask".

This function as.mask creates a representation of any spatial window w as a mask. It generates a rectangular grid of locations in the plane, tests whether each of these locations lies inside w, and stores the results as a mask.

The most common use of this function is to approximate the shape of a rectangular or polygonal window w by a mask, for computational purposes. In this case, we will usually want to have a very fine grid of pixels.

This function can also be used to generate a coarsely-spaced grid of locations inside a window, for purposes such as subsampling and prediction.

The argument w should be a window (object of class "owin"). If it is another kind of spatial data, then the window information will be extracted using as.owin.

The grid spacing and location are controlled by the arguments eps, dimyx and xy, which are mutually incompatible.

If eps is given, then it specifies the desired grid spacing, that is, the desired size of the pixels. If eps is a single number, it specifies that the desired grid spacing is eps in both the x and y directions, that is, the desired pixels are squares with side length eps. If eps is a vector of length 2, it specifies that the desired grid spacing is eps[1] in the x direction and eps[2] in the y direction. That is, the desired pixels are rectangles of width eps[1] and height eps[2].

When eps is given, the argument rule.eps specifies what to do if pixels of the desired size would not fit exactly into the rectangular frame of w.

• if rule.eps="adjust.eps" (the default), the rectangular frame will remain unchanged, and the grid spacing (pixel size) eps will be reduced slightly so that an integer number of pixels fits exactly into the frame.

• if rule.eps="grow.frame", the grid spacing (pixel size) eps will remain unchanged, and the rectangular frame will be expanded slightly so that it consists of an integer number of pixels in each direction.

• if rule.eps="shrink.frame", the grid spacing (pixel size) eps will remain unchanged, and the rectangular frame will be contracted slightly so that it consists of an integer number of pixels in each direction.

If dimyx is given, then the pixel grid will be an m \times n rectangular grid where m, n are given by dimyx[2], dimyx[1] respectively. Warning: dimyx[1] is the number of pixels in the y direction, and dimyx[2] is the number in the x direction. The grid spacing (pixel size) is determined by the frame size and the number of pixels.

If xy is given, then this should be some kind of data specifing the coordinates of a pixel grid. It may be

• a list or structure containing elements x and y which are numeric vectors of equal length. These will be taken as x and y coordinates of the margins of the grid. The pixel coordinates will be generated from these two vectors.

• a pixel image (object of class "im").

• a window (object of class "owin") which is of type "mask" so that it contains pixel coordinates.

If xy is given and is either a pixel image or a mask, then w may be omitted, and the window information will be extracted from xy.

If neither eps nor dimyx nor xy is given, the pixel raster dimensions are obtained from spatstat.options("npixel").

There is no inverse of this function. However, the function as.polygonal will compute a polygonal approximation of a binary mask.

Value

A window (object of class "owin") of type "mask" representing a binary pixel image.

Discretisation rule

The rule used in as.mask is that a pixel is part of the discretised window if and only if the centre of the pixel falls in the original window. This is usually sufficient for most purposes, and is fast to compute.

Other discretisation rules are possible; they are available using the function owin2mask.

Converting a spatial pattern to a mask

If the intention is to discretise or pixellate a spatial pattern, such as a point pattern, line segment pattern or a linear network, then as.mask is not the appropriate function to use, because as.mask extracts only the window information and converts this window to a mask.

To discretise a point pattern, use pixellate.ppp. To discretise a line segment pattern, use pixellate.psp or psp2mask. To discretise a linear network, use pixellate.linnet.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

owin2mask.

owin.object, as.rectangle, as.polygonal, spatstat.options

Examples

  w <- owin(c(0,10),c(0,10), poly=list(x=c(1,2,3,2,1), y=c(2,3,4,6,7)))
  m <- as.mask(w)
  if(interactive()) {
     plot(w)
     plot(m)
  }
  x <- 1:9
  y <- seq(0.25, 9.75, by=0.5)
  m <- as.mask(w, xy=list(x=x, y=y))

  B <- square(1)
  as.mask(B, eps=0.3)
  as.mask(B, eps=0.3, rule.eps="g")
  as.mask(B, eps=0.3, rule.eps="s")

Convert Pixel Image to Matrix or Array

Description

Converts a pixel image to a matrix or an array.

Usage

  ## S3 method for class 'im'
as.matrix(x, ...)
  ## S3 method for class 'im'
as.array(x, ...)

Arguments

Details

The function as.matrix.im converts the pixel image x into a matrix containing the pixel values. It is handy when you want to extract a summary of the pixel values. See the Examples.

The function as.array.im converts the pixel image to an array. By default this is a three-dimensional array of dimension n by m by 1. If the extra arguments ... are given, they will be passed to array, and they may change the dimensions of the array.

Value

A matrix or array.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

as.matrix.owin

Examples

   # artificial image
   Z <- setcov(square(1))

   M <- as.matrix(Z)

   median(M)
   
   # plot the cumulative distribution function of pixel values
   # plot(ecdf(as.matrix(Z)))

Convert Pixel Image to Matrix

Description

Converts a pixel image to a matrix.

Usage

  ## S3 method for class 'owin'
as.matrix(x, ...)

Arguments

Details

The function as.matrix.owin converts a window to a logical matrux.

It first converts the window x into a binary pixel mask using as.mask. It then extracts the pixel entries as a logical matrix.

The resulting matrix has entries that are TRUE if the corresponding pixel is inside the window, and FALSE if it is outside.

The function as.matrix is generic. The function as.matrix.owin is the method for windows (objects of class "owin").

Use as.im to convert a window to a pixel image.

Value

A logical matrix.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

as.matrix.im, as.im

Examples

  m <- as.matrix(letterR)

Convert Data To Class owin

Description

Converts data specifying an observation window in any of several formats, into an object of class "owin".

Usage

 as.owin(W, ..., fatal=TRUE)

 ## Default S3 method:
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'owin'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'ppp'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'psp'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'quad'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'quadratcount'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'tess'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'im'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'layered'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'data.frame'
as.owin(W, ..., step, fatal=TRUE)

 ## S3 method for class 'distfun'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'nnfun'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'funxy'
as.owin(W, ..., fatal=TRUE)

 ## S3 method for class 'boxx'
as.owin(W, ..., fatal=TRUE)

Arguments

Details

The class "owin" is a way of specifying the observation window for a point pattern. See owin.object for an overview.

The generic function as.owin converts data in any of several formats into an object of class "owin" for use by the spatstat package. The function as.owin is generic, with methods for different classes of objects, and a default method.

The argument W may be

• an object of class "owin"

• a structure with entries xrange, yrange specifying the x and y dimensions of a rectangle

• a structure with entries named xmin, xmax, ymin, ymax (in any order) specifying the x and y dimensions of a rectangle. This will accept objects of class bbox in the sf package.

• a numeric vector of length 4 (interpreted as (xmin, xmax, ymin, ymax) in that order) specifying the x and y dimensions of a rectangle

• a structure with entries named xl, xu, yl, yu (in any order) specifying the x and y dimensions of a rectangle as (xmin, xmax) = (xl, xu) and (ymin, ymax) = (yl, yu). This will accept objects of class spp used in the Venables and Ripley spatial package.

• an object of class "ppp" representing a point pattern. In this case, the object's window structure will be extracted.

• an object of class "psp" representing a line segment pattern. In this case, the object's window structure will be extracted.

• an object of class "tess" representing a tessellation. In this case, the object's window structure will be extracted.

• an object of class "quad" representing a quadrature scheme. In this case, the window of the data component will be extracted.

• an object of class "im" representing a pixel image. In this case, a window of type "mask" will be returned, with the same pixel raster coordinates as the image. An image pixel value of NA, signifying that the pixel lies outside the window, is transformed into the logical value FALSE, which is the corresponding convention for window masks.

• an object of class "ppm", "kppm", "slrm" or "dppm" representing a fitted point process model. In this case, if from="data" (the default), as.owin extracts the original point pattern data to which the model was fitted, and returns the observation window of this point pattern. If from="covariates" then as.owin extracts the covariate images to which the model was fitted, and returns a binary mask window that specifies the pixel locations.

• an object of class "lpp" representing a point pattern on a linear network. In this case, as.owin extracts the linear network and returns a window containing this network.

• an object of class "lppm" representing a fitted point process model on a linear network. In this case, as.owin extracts the linear network and returns a window containing this network.

• A data.frame with exactly three columns. Each row of the data frame corresponds to one pixel. Each row contains the x and y coordinates of a pixel, and a logical value indicating whether the pixel lies inside the window.

• A data.frame with exactly two columns. Each row of the data frame contains the x and y coordinates of a pixel that lies inside the window.

• an object of class "distfun", "nnfun" or "funxy" representing a function of spatial location, defined on a spatial domain. The spatial domain of the function will be extracted.

• an object of class "rmhmodel" representing a point process model that can be simulated using rmh. The window (spatial domain) of the model will be extracted. The window may be NULL in some circumstances (indicating that the simulation window has not yet been determined). This is not treated as an error, because the argument fatal defaults to FALSE for this method.

• an object of class "layered" representing a list of spatial objects. See layered. In this case, as.owin will be applied to each of the objects in the list, and the union of these windows will be returned.

• an object of another suitable class from another package. For full details, see vignette('shapefiles').

If the argument W is not in one of these formats and cannot be converted to a window, then an error will be generated (if fatal=TRUE) or a value of NULL will be returned (if fatal=FALSE).

When W is a data frame, the argument step can be used to specify the pixel grid spacing; otherwise, the spacing will be guessed from the data.

Value

An object of class "owin" (see owin.object) specifying an observation window.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

as.owin.ppm, as.owin.rmhmodel, as.owin.lpp.

owin.object, owin.

Additional methods for as.owin may be provided by other packages outside the spatstat family.

Examples

 w <- as.owin(c(0,1,0,1))
 w <- as.owin(list(xrange=c(0,5),yrange=c(0,10)))
 # point pattern
 w <- as.owin(demopat)
 # image
 Z <- as.im(function(x,y) { x + 3}, unit.square())
 w <- as.owin(Z)

 # Venables & Ripley 'spatial' package
 spatialpath <- system.file(package="spatial")
 if(nchar(spatialpath) > 0) {
   require(spatial)
   towns <- ppinit("towns.dat")
   w <- as.owin(towns)
   detach(package:spatial)
 }

Convert a Window to a Polygonal Window

Description

Given a window W of any geometric type (rectangular, polygonal or binary mask), this function returns a polygonal window that represents the same spatial domain.

Usage

as.polygonal(W, repair=FALSE)

Arguments

Details

Given a window W of any geometric type (rectangular, polygonal or binary mask), this function returns a polygonal window that represents the same spatial domain.

If W is a rectangle, it is converted to a polygon with 4 vertices.

If W is already polygonal, it is returned unchanged, by default. However if repair=TRUE then the validity of the polygonal coordinates will be checked (for example to check the boundary is not self-intersecting) and repaired if necessary, so that the result could be different from W.

If W is a binary mask, then each pixel in the mask is replaced by a small square or rectangle, and the union of these squares or rectangles is computed. The result is a polygonal window that has only horizontal and vertical edges. (Use simplify.owin to remove the staircase appearance, if desired).

Value

A polygonal window (object of class "owin" and of type "polygonal").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

owin, as.owin, as.mask, simplify.owin

Examples

   m <- as.mask(letterR, dimyx=32)
   p <- as.polygonal(m)
   if(interactive()) {
      plot(m)
      plot(p, add=TRUE, lwd=2)
   }

Convert Data To Class ppp

Description

Tries to coerce any reasonable kind of data to a spatial point pattern (an object of class "ppp") for use by the spatstat package).

Usage

  as.ppp(X, ..., fatal=TRUE)

  ## S3 method for class 'ppp'
as.ppp(X, ..., fatal=TRUE)

  ## S3 method for class 'psp'
as.ppp(X, ..., fatal=TRUE)

  ## S3 method for class 'quad'
as.ppp(X, ..., fatal=TRUE)

  ## S3 method for class 'matrix'
as.ppp(X, W=NULL, ..., fatal=TRUE)

  ## S3 method for class 'data.frame'
as.ppp(X, W=NULL, ..., fatal=TRUE)

  ## Default S3 method:
as.ppp(X, W=NULL, ..., fatal=TRUE)

Arguments

Details

Converts the dataset X to a point pattern (an object of class "ppp"; see ppp.object for an overview).

This function is normally used to convert an existing point pattern dataset, stored in another format, to the "ppp" format. To create a new point pattern from raw data such as x,y coordinates, it is normally easier to use the creator function ppp.

The function as.ppp is generic, with methods for the classes "ppp", "psp", "quad", "matrix", "data.frame" and a default method.

The dataset X may be:

• an object of class "ppp"

• an object of class "psp"

• a point pattern object created by the spatial library

• an object of class "quad" representing a quadrature scheme (see quad.object)

• a matrix or data frame with at least two columns

• a structure with entries x, y which are numeric vectors of equal length

• a numeric vector of length 2, interpreted as the coordinates of a single point.

In the last three cases, we need the second argument W which is converted to a window object by the function as.owin. In the first four cases, W will be ignored.

If X is a line segment pattern (an object of class psp) the point pattern returned consists of the endpoints of the segments. If X is marked then the point pattern returned will also be marked, the mark associated with a point being the mark of the segment of which that point was an endpoint.

If X is a matrix or data frame, the first and second columns will be interpreted as the x and y coordinates respectively. Any additional columns will be interpreted as marks.

The argument fatal indicates what to do when W is missing and X contains no information about the window. If fatal=TRUE, a fatal error will be generated; if fatal=FALSE, the value NULL is returned.

In the spatial library, a point pattern is represented in either of the following formats:

• (in spatial versions 1 to 6) a structure with entries x, y xl, xu, yl, yu

• (in spatial version 7) a structure with entries x, y and area, where area is a structure with entries xl, xu, yl, yu

where x and y are vectors of equal length giving the point coordinates, and xl, xu, yl, yu are numbers giving the dimensions of a rectangular window.

Point pattern datasets can also be created by the function ppp.

Methods for as.ppp exist for some other classes of data; they are listed by methods(as.ppp).

Value

An object of class "ppp" (see ppp.object) describing the point pattern and its window of observation. The value NULL may also be returned; see Details.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk

See Also

ppp, ppp.object, as.owin, owin.object.

Methods for as.ppp exist for some other classes of data; they are listed by methods(as.ppp).

Examples

 xy <- matrix(runif(40), ncol=2)
 pp <- as.ppp(xy, c(0,1,0,1))

 # Venables-Ripley format
 # check for 'spatial' package
 spatialpath <- system.file(package="spatial")
 if(nchar(spatialpath) > 0) {
   require(spatial)
   towns <- ppinit("towns.dat")
   pp <- as.ppp(towns) # converted to our format
   detach(package:spatial)
 }

 xyzt <- matrix(runif(40), ncol=4)
 Z <- as.ppp(xyzt, square(1))

Convert Data To Class psp

Description

Tries to coerce any reasonable kind of data object to a line segment pattern (an object of class "psp") for use by the spatstat package.

Usage

  as.psp(x, ..., from=NULL, to=NULL)

  ## S3 method for class 'psp'
as.psp(x, ..., check=FALSE, fatal=TRUE)

  ## S3 method for class 'data.frame'
as.psp(x, ..., window=NULL, marks=NULL,
      check=spatstat.options("checksegments"), fatal=TRUE)

  ## S3 method for class 'matrix'
as.psp(x, ..., window=NULL, marks=NULL,
       check=spatstat.options("checksegments"), fatal=TRUE)

  ## Default S3 method:
as.psp(x, ..., window=NULL, marks=NULL,
       check=spatstat.options("checksegments"), fatal=TRUE)

Arguments

Details

Converts the dataset x to a line segment pattern (an object of class "psp"; see psp.object for an overview).

This function is normally used to convert an existing line segment pattern dataset, stored in another format, to the "psp" format. To create a new point pattern from raw data such as x,y coordinates, it is normally easier to use the creator function psp.

The dataset x may be:

• an object of class "psp"

• a data frame with at least 4 columns

• a structure (list) with elements named x0, y0, x1, y1 or elements named xmid, ymid, length, angle and possibly a fifth element named marks

If x is a data frame the interpretation of its columns is as follows:

• If there are columns named x0, y0, x1, y1 then these will be interpreted as the coordinates of the endpoints of the segments and used to form the ends component of the psp object to be returned.

• If there are columns named xmid, ymid, length, angle then these will be interpreted as the coordinates of the segment midpoints, the lengths of the segments, and the orientations of the segments in radians and used to form the ends component of the psp object to be returned.

• If there is a column named marks then this will be interpreted as the marks of the pattern provided that the argument marks of this function is NULL. If argument marks is not NULL then the value of this argument is taken to be the marks of the pattern and the column named marks is ignored (with a warning). In either case the column named marks is deleted and omitted from further consideration.

• If there is no column named marks and if the marks argument of this function is NULL, and if after interpreting 4 columns of x as determining the ends component of the psp object to be returned, there remain other columns of x, then these remaining columns will be taken to form a data frame of marks for the psp object to be returned.

If x is a structure (list) with elements named x0, y0, x1, y1, marks or xmid, ymid, length, angle, marks, then the element named marks will be interpreted as the marks of the pattern provide that the argument marks of this function is NULL. If this argument is non-NULL then it is interpreted as the marks of the pattern and the element marks of x is ignored — with a warning.

Alternatively, you may specify two point patterns from and to containing the first and second endpoints of the line segments.

The argument window is converted to a window object by the function as.owin.

The argument fatal indicates what to do when the data cannot be converted to a line segment pattern. If fatal=TRUE, a fatal error will be generated; if fatal=FALSE, the value NULL is returned.

The function as.psp is generic, with methods for the classes "psp", "data.frame", "matrix" and a default method.

Point pattern datasets can also be created by the function psp.

Value

An object of class "psp" (see psp.object) describing the line segment pattern and its window of observation. The value NULL may also be returned; see Details.

Warnings

If only a proper subset of the names x0,y0,x1,y1 or xmid,ymid,length,angle appear amongst the names of the columns of x where x is a data frame, then these special names are ignored.

For example if the names of the columns were xmid,ymid,length,degrees, then these columns would be interpreted as if the represented x0,y0,x1,y1 in that order.

Whether it gets used or not, column named marks is always removed from x before any attempt to form the ends component of the psp object that is returned.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

psp, psp.object, as.owin, owin.object.

See edges for extracting the edges of a polygonal window as a "psp" object.

Examples

   mat <- matrix(runif(40), ncol=4)
   mx <- data.frame(v1=sample(1:4,10,TRUE),
                    v2=factor(sample(letters[1:4],10,TRUE),levels=letters[1:4]))
   a <- as.psp(mat, window=owin(),marks=mx)
   mat <- cbind(as.data.frame(mat),mx)
   b <- as.psp(mat, window=owin()) # a and b are identical.
   stuff <- list(xmid=runif(10),
                 ymid=runif(10),
                 length=rep(0.1, 10),
                 angle=runif(10, 0, 2 * pi))
   a <- as.psp(stuff, window=owin())
   b <- as.psp(from=runifrect(10), to=runifrect(10))

Window Frame

Description

Extract the window frame of a window or other spatial dataset

Usage

 as.rectangle(w, ...)

Arguments

Details

This function is the quickest way to determine a bounding rectangle for a spatial dataset.

If w is a window, the function just extracts the outer bounding rectangle of w as given by its elements xrange,yrange.

The function can also be applied to any spatial dataset that has a window: for example, a point pattern (object of class "ppp") or a line segment pattern (object of class "psp"). The bounding rectangle of the window of the dataset is extracted.

Use the function boundingbox to compute the smallest bounding rectangle of a dataset.

Value

A window (object of class "owin") of type "rectangle" representing a rectangle.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

owin, as.owin, boundingbox

Examples

  w <- owin(c(0,10),c(0,10), poly=list(x=c(1,2,3,2,1), y=c(2,3,4,6,7)))
  r <- as.rectangle(w)
  # returns a 10 x 10 rectangle

  as.rectangle(lansing)

  as.rectangle(copper$SouthLines)

Convert List of Two-Dimensional Spatial Objects

Description

Given a list of two-dimensional spatial objects, convert it to the class "solist".

Usage

as.solist(x, ...)

Arguments

Details

This command makes the list x into an object of class "solist" (spatial object list). See solist for details.

The entries in the list x should be two-dimensional spatial datasets (not necessarily of the same class).

Value

A list, usually of class "solist".

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

solist, as.anylist, solapply.

Examples

  x <- list(cells, Window(cells), setcov(Window(cells)))
  y <- as.solist(x)

Convert Data To Tessellation

Description

Converts data specifying a tessellation, in any of several formats, into an object of class "tess".

Usage

 as.tess(X)
 ## S3 method for class 'tess'
as.tess(X)
 ## S3 method for class 'im'
as.tess(X)
 ## S3 method for class 'owin'
as.tess(X)
 ## S3 method for class 'quadratcount'
as.tess(X)
 ## S3 method for class 'list'
as.tess(X)

Arguments

Details

A tessellation is a collection of disjoint spatial regions (called tiles) that fit together to form a larger spatial region. This command creates an object of class "tess" that represents a tessellation.

This function converts data in any of several formats into an object of class "tess" for use by the spatstat package. The argument X may be

• an object of class "tess". The object will be stripped of any extraneous attributes and returned.

• a pixel image (object of class "im") with pixel values that are logical or factor values. Each level of the factor will determine a tile of the tessellation.

• a window (object of class "owin"). The result will be a tessellation consisting of a single tile.

• a set of quadrat counts (object of class "quadratcount") returned by the command quadratcount. The quadrats used to generate the counts will be extracted and returned as a tessellation.

• a quadrat test (object of class "quadrattest") returned by the command quadrat.test. The quadrats used to perform the test will be extracted and returned as a tessellation.

• a list of windows (objects of class "owin") giving the tiles of the tessellation.

The function as.tess is generic, with methods for various classes, as listed above.

Value

An object of class "tess" specifying a tessellation.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

tess

quadratcount

Examples

 # pixel image
 v <- as.im(function(x,y){factor(round(5 * (x^2 + y^2)))}, W=owin())
 levels(v) <- letters[seq(length(levels(v)))]
 as.tess(v)
 # quadrat counts
 qNZ <- quadratcount(nztrees, nx=4, ny=3)
 as.tess(qNZ)

Distance to Boundary of Window

Description

Computes the distances from each pixel in a window to the boundary of the window.

Usage

 bdist.pixels(w, ..., style=c("image", "matrix", "coords"), method=c("C", "interpreted"))

Arguments

Details

This function computes, for each pixel u in the Frame containing the window w, the shortest distance d(u, w^c) from u to the complement of w. This value is zero for pixels lying outside w, and is positive for pixels inside w.

If the window is a binary mask then the distance from each pixel to the boundary is computed using the distance transform algorithm distmap.owin. The result is equivalent to distmap(W, invert=TRUE).

If the window is a rectangle or a polygonal region, the grid of pixels is determined by the arguments "\dots" passed to as.mask. The distance from each pixel to the boundary is calculated exactly, using analytic geometry. This is slower but more accurate than in the case of a binary mask.

For software testing purposes, there are two implementations available when w is a polygon: the default is method="C" which is much faster than method="interpreted".

To compute the distance from each pixel to the bounding rectangular frame Frame(W), use framedist.pixels.

Value

If style="image", a pixel image (object of class "im") containing the distances from each pixel in the image raster to the boundary of the window.

If style="matrix", a matrix giving the distances. Rows of this matrix correspond to the y coordinate and columns to the x coordinate.

If style="coords", a list with three components x,y,z, where x,y are vectors of length m,n giving the x and y coordinates respectively, and z is an m \times n matrix such that z[i,j] is the distance from (x[i],y[j]) to the boundary of the window. Rows of this matrix correspond to the x coordinate and columns to the y coordinate. This result can be plotted with persp, image or contour.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

framedist.pixels

owin.object, erosion, bdist.points, bdist.tiles, distmap.owin.

Examples

  u <- owin(c(0,1),c(0,1))
  d <- bdist.pixels(u, eps=0.01)
  image(d)
  d <- bdist.pixels(u, eps=0.01, style="matrix")
  mean(d >= 0.1)
  # value is approx (1 - 2 * 0.1)^2 = 0.64
  opa <- par(mfrow=c(1,2))
  plot(bdist.pixels(letterR))
  plot(framedist.pixels(letterR))
  par(opa)

Distance to Boundary of Window

Description

Computes the distances from each point of a point pattern to the boundary of the window.

Usage

 bdist.points(X)

Arguments

Details

This function computes, for each point x_i in the point pattern X, the shortest distance d(x_i, W^c) from x_i to the boundary of the window W of observation.

If the window Window(X) is of type "rectangle" or "polygonal", then these distances are computed by analytic geometry and are exact, up to rounding errors. If the window is of type "mask" then the distances are computed using the real-valued distance transform, which is an approximation with maximum error equal to the width of one pixel in the mask.

Value

A numeric vector, giving the distances from each point of the pattern to the boundary of the window.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

See Also

bdist.pixels, bdist.tiles, ppp.object, erosion

Examples

  d <- bdist.points(cells)

Distance to Boundary of Window

Description

Computes the shortest distances from each tile in a tessellation to the boundary of the window.

Usage

 bdist.tiles(X)

Arguments

Details

This function computes, for each tile s_i in the tessellation X, the shortest distance from s_i to the boundary of the window W containing the tessellation.

Value

A numeric vector, giving the shortest distance from each tile in the tessellation to the boundary of the window. Entries of the vector correspond to the entries of tiles(X).

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

tess, bdist.points, bdist.pixels

Examples

  P <- runifrect(15)
  X <- dirichlet(P)
  plot(X, col="red")
  B <- bdist.tiles(X)
  # identify tiles that do not touch the boundary
  plot(X[B > 0], add=TRUE, col="green", lwd=3)

Create Colour Scheme for a Range of Numbers

Description

Given a range of numerical values, this command creates a colour scheme that would be appropriate if the numbers were altitudes (elevation above or below sea level).

Usage

beachcolours(range, sealevel = 0, monochrome = FALSE,
             ncolours = if (monochrome) 16 else 64,
             nbeach = 1)
beachcolourmap(range, ...) 

Arguments

Details

Given a range of numerical values, these commands create a colour scheme that would be appropriate if the numbers were altitudes (elevation above or below sea level).

Numerical values close to zero are portrayed in green (representing the waterline). Negative values are blue (representing water) and positive values are yellow to red (representing land). At least, these are the colours of land and sea in Western Australia. This colour scheme was proposed by Baddeley et al (2005).

The function beachcolours returns these colours as a character vector, while beachcolourmap returns a colourmap object.

The argument range should be a numeric vector of length 2 giving a range of numerical values.

The argument sealevel specifies the height value that will be treated as zero, and mapped to the colour green. A vector of ncolours colours will be created, of which nbeach colours will be green.

The argument monochrome is included for convenience when preparing publications. If monochrome=TRUE the colour map will be a simple grey scale containing ncolours shades from black to white.

Value

For beachcolours, a character vector of length ncolours specifying colour values. For beachcolourmap, a colour map (object of class "colourmap").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner rolfturner@posteo.net

References

Baddeley, A., Turner, R., Moller, J. and Hazelton, M. (2005) Residual analysis for spatial point processes. Journal of the Royal Statistical Society, Series B 67, 617–666.

See Also

colourmap, colourtools.

Examples

  plot(beachcolourmap(c(-2,2)))

Border Region of a Window

Description

Computes the border region of a window, that is, the region lying within a specified distance of the boundary of a window.

Usage

border(w, r, outside=FALSE, ...)

Arguments

Details

By default (if outside=FALSE), the border region is the subset of w lying within a distance r of the boundary of w. It is computed by eroding w by the distance r (using erosion) and subtracting this eroded window from the original window w.

If outside=TRUE, the border region is the set of locations outside w lying within a distance r of w. It is computed by dilating w by the distance r (using dilation) and subtracting the original window w from the dilated window.

Value

A window (object of class "owin").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

erosion, dilation

Examples

# rectangle
   u <- unit.square()
   border(u, 0.1)
   border(u, 0.1, outside=TRUE)
# polygon
   
   plot(letterR)
   plot(border(letterR, 0.1), add=TRUE)
   plot(border(letterR, 0.1, outside=TRUE), add=TRUE)
   

Convex Hull of Points

Description

Computes the smallest rectangle containing a set of points.

Usage

bounding.box.xy(x, y=NULL)

Arguments

Details

Given an observed pattern of points with coordinates given by x and y, this function finds the smallest rectangle, with sides parallel to the coordinate axes, that contains all the points, and returns it as a window.

Value

A window (an object of class "owin").

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

owin, as.owin, convexhull.xy, ripras

Examples

  x <- runif(30)
  y <- runif(30)
  w <- bounding.box.xy(x,y)
  plot(owin(), main="bounding.box.xy(x,y)")
  plot(w, add=TRUE)
  points(x,y)

  X <- runifrect(30)
  plot(X, main="bounding.box.xy(X)")
  plot(bounding.box.xy(X), add=TRUE)

Bounding Box of a Window, Image, or Point Pattern

Description

Find the smallest rectangle containing a given window(s), image(s) or point pattern(s).

Usage

boundingbox(...)

## Default S3 method:
boundingbox(...)

## S3 method for class 'im'
boundingbox(...)

## S3 method for class 'owin'
boundingbox(...)

## S3 method for class 'ppp'
boundingbox(...)

## S3 method for class 'psp'
boundingbox(...)

## S3 method for class 'lpp'
boundingbox(...)

## S3 method for class 'linnet'
boundingbox(...)

## S3 method for class 'solist'
boundingbox(...)

Arguments

Details

This function finds the smallest rectangle (with sides parallel to the coordinate axes) that contains all the given objects.

For a window (object of class "owin"), the bounding box is the smallest rectangle that contains all the vertices of the window (this is generally smaller than the enclosing frame, which is returned by as.rectangle).

For a point pattern (object of class "ppp" or "lpp"), the bounding box is the smallest rectangle that contains all the points of the pattern. This is usually smaller than the bounding box of the window of the point pattern.

For a line segment pattern (object of class "psp") or a linear network (object of class "linnet"), the bounding box is the smallest rectangle that contains all endpoints of line segments.

For a pixel image (object of class "im"), the image will be converted to a window using as.owin, and the bounding box of this window is obtained.

If the argument is a list of several objects, then this function finds the smallest rectangle that contains all the bounding boxes of the objects.

Value

owin, as.owin, as.rectangle

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

Examples

  w <- owin(c(0,10),c(0,10), poly=list(x=c(1,2,3,2,1), y=c(2,3,4,6,7)))
  r <- boundingbox(w)
  # returns rectangle [1,3] x [2,7]

  w2 <- unit.square()
  r <- boundingbox(w, w2)
  # returns rectangle [0,3] x [0,7]

Smallest Enclosing Circle

Description

Find the smallest circle enclosing a spatial window or other object. Return its radius, or the location of its centre, or the circle itself.

Usage

boundingradius(x, ...)

boundingcentre(x, ...)

boundingcircle(x, ...)

## S3 method for class 'owin'
boundingradius(x, ...)

## S3 method for class 'owin'
boundingcentre(x, ...)

## S3 method for class 'owin'
boundingcircle(x, ...)

## S3 method for class 'ppp'
boundingradius(x, ...)

## S3 method for class 'ppp'
boundingcentre(x, ...)

## S3 method for class 'ppp'
boundingcircle(x, ...)

Arguments

Details

The boundingcircle of a spatial region W is the smallest circle that contains W. The boundingradius is the radius of this circle, and the boundingcentre is the centre of the circle.

The functions boundingcircle, boundingcentre and boundingradius are generic. There are methods for objects of class "owin", "ppp" and "linnet".

Value

The result of boundingradius is a single numeric value.

The result of boundingcentre is a point pattern containing a single point.

The result of boundingcircle is a window representing the boundingcircle.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

See Also

diameter

Examples

  boundingradius(letterR)

  plot(grow.rectangle(Frame(letterR), 0.2), main="", type="n")
  plot(letterR, add=TRUE, col="grey")
  plot(boundingcircle(letterR), add=TRUE, border="green", lwd=2)
  plot(boundingcentre(letterR), pch="+", cex=2, col="blue", add=TRUE)

  X <- runifrect(5)
  plot(X)
  plot(boundingcircle(X), add=TRUE)
  plot(boundingcentre(X), pch="+", cex=2, col="blue", add=TRUE)

Three-Dimensional Box

Description

Creates an object representing a three-dimensional box.

Usage

box3(xrange = c(0, 1), yrange = xrange, zrange = yrange, unitname = NULL)

Arguments

Details

This function creates an object representing a three-dimensional rectangular parallelepiped (box) with sides parallel to the coordinate axes.

The object can be used to specify the domain of a three-dimensional point pattern (see pp3) and in various geometrical calculations (see volume.box3, diameter.box3, eroded.volumes).

The optional argument unitname specifies the name of the unit of length. See unitname for valid formats.

The function as.box3 can be used to convert other kinds of data to this format.

Value

An object of class "box3". There is a print method for this class.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

and Rolf Turner rolfturner@posteo.net

See Also

as.box3, pp3, volume.box3, diameter.box3, eroded.volumes.

Examples

    box3()
    box3(c(0,10),c(0,10),c(0,5), unitname=c("metre","metres"))
    box3(c(-1,1))

Multi-Dimensional Box

Description

Creates an object representing a multi-dimensional box.

Usage

boxx(..., unitname = NULL)

Arguments

Details

This function creates an object representing a multi-dimensional rectangular parallelepiped (box) with sides parallel to the coordinate axes.

The object can be used to specify the domain of a multi-dimensional point pattern (see ppx) and in various geometrical calculations (see volume.boxx, diameter.boxx, eroded.volumes).

The optional argument unitname specifies the name of the unit of length. See unitname for valid formats.

Value

An object of class "boxx". There is a print method for this class.

Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.

See Also

ppx, volume.boxx, diameter.boxx, eroded.volumes.boxx.

Examples

    boxx(c(0,10),c(0,10),c(0,5),c(0,1), unitname=c("metre","metres"))

Buffer Distance Tessellation

Description

Constructs a spatial tessellation, composed of rings or buffers at specified distances away from the given spatial object.

Usage

bufftess(X, breaks, W = Window(X), ..., polygonal = TRUE)

Arguments