Package 'spatstat.geom'

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.

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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 [email protected] and Rolf Turner [email protected]

See Also

owin, plot.owin, textureplot, texturemap.

Examples

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

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 [email protected]

and Rolf Turner [email protected]

See Also

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

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected]

and Rolf Turner [email protected]

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

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 [email protected] and Rolf Turner [email protected]

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))))
  }

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 [email protected]

and Rolf Turner [email protected]

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

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected]

Rolf Turner [email protected]

and Ege Rubak [email protected]

See Also

solist, as.solist, anylapply.

Examples

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

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

See Also

im.object

Examples

anyNA(as.im(letterR))

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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)

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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)
  }

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 [email protected]

and Rolf Turner [email protected]

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

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 [email protected] and Rolf Turner [email protected]

See Also

AreaInter, areaLoss

Examples

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

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 [email protected] and Rolf Turner [email protected]

See Also

AreaInter, areaGain, dilated.areas

Examples

areaLoss(cells, 0.1)

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected]

Rolf Turner [email protected]

and Ege Rubak [email protected]

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

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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)

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

Examples

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

   Y <- as.data.frame(Z)

   head(Y)

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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)

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 [email protected] and Rolf Turner [email protected]

Examples

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

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 [email protected] and Rolf Turner [email protected]

Examples

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

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

See Also

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

Examples

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

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 [email protected]

Rolf Turner [email protected]

and Ege Rubak [email protected]

See Also

[.im

Examples

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

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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)

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

Author(s)

Adrian Baddeley [email protected], Rolf Turner [email protected] and Ege Rubak [email protected]

See Also

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)

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 [email protected]

and Rolf Turner [email protected]

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

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 [email protected]

and Rolf Turner [email protected]

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)

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected]

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)

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

See Also

as.layered.msr, layered, split.ppp

Examples

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

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 [email protected], Rolf Turner [email protected] and Ege Rubak [email protected].

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")

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.