as.im: Convert to Pixel Image

Description Usage Arguments Details Value Character-valued images Handling Character Strings Author(s) See Also Examples

View source: R/as.im.R

Description

Converts various kinds of data to a pixel image

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
  as.im(X, ...)

  ## S3 method for class 'im'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        na.replace=NULL)

  ## S3 method for class 'owin'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        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,
        na.replace=NULL)

  ## S3 method for class 'function'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        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,
        na.replace=NULL, approx=TRUE)

  ## S3 method for class 'nnfun'
as.im(X, W=NULL, ...,
        eps=NULL, dimyx=NULL, xy=NULL,
        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,
        na.replace=NULL)

Arguments

X

Data to be converted to a pixel image.

W

Window object which determines the spatial domain and pixel array geometry.

...

Additional arguments passed to X when X is a function.

eps,dimyx,xy

Optional parameters passed to as.mask which determine the pixel array geometry. See as.mask.

na.replace

Optional value to replace NA entries in the output image.

value

Optional. The value to be assigned to pixels inside the window, if X is a window.

strict

Logical value indicating whether to match formal arguments of X when X is a function. If strict=FALSE (the default), all the ... arguments are passed to X. If strict=TRUE, only named arguments are passed, and only if they match the names of formal arguments of X.

step

Optional. A single number, or numeric vector of length 2, giving the grid step lengths in the x and y directions.

fatal

Logical value indicating what to do if the resulting image would be too large for available memory. If fatal=TRUE (the default), an error occurs. If fatal=FALSE, a warning is issued and NULL is returned.

drop

Logical value indicating what to do if the result would normally be a list of pixel images but the list contains only one image. If drop=TRUE (the default), the pixel image is extracted and the result is a pixel image. If drop=FALSE, this list is returned as the result.

stringsAsFactors

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 depends on the version of R. See section Handling Character Strings.

approx

Logical value indicating whether to compute an approximate result at faster speed.

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:

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)

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.

Author(s)

\spatstatAuthors

See Also

Separate documentation for as.im.ppp

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
  data(demopat)
  # 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)

spatstat.geom documentation built on April 15, 2021, 9:06 a.m.