patternbits {ShapePattern}

Decompose a binary landscape (grid) to count its pattern elements

Description

Given an input binary (0,1) pattern as a .csv file or matrix object, this function shifts that pattern in each of the 4 cardinal directions by one location (cell) and then counts the frequency for each of the 32 hyper-local neighbourhood configurations (CODE). The frequencies are provided for each CODE along with their PROBABILITY. Finally an object that maps the CODE into a matrix that can be drawn as a map is also provided as part of the ouput list object. Note that the minimum number of grid rows or columns are 3 each if processing a non-toroidal surface. The minimum grid size can be [2,2], but in reality, to ensure sufficient opportunities for cases to present themselves, the total number of cells should be much greater than 32. Grids do not have to have an equal number of rows and columns and the option to select a toroidal versus non-toroidal surface are now operational too.

Usage

patternbits(IMGCSV="~/Desktop/Book2.csv", 
            OBJ=TRUE,
            OBJname=matrix(c(1,1,0,0,0,1,1,1,0), nrow=3, ncol=3), 
            OBJtxt="NAMEhere",  
            DRAW=TRUE, 
            VERBOSE=FALSE, 
            TORUS=TRUE, 
            rho=0, 
            proportion=0.5)

Arguments

IMGCSV

This is a .csv (comma separated values) textfile format of an input binary grid. It is read into a matrix object and needs to have an equal number of rows and columns. No header is permitted.

OBJ

This is a Boolean flag that determines whether the input grid is available as on object (TRUE) or whether it will be read from a .csv file (FALSE).

OBJname

If the input data is an object, the name of that object is provided here. If OBJ is FALSE, whatever is entered here is ignored.

OBJtxt

A character string that can be used to describe the input data or to encode a batch number, simulation identifier or other code that will be included in the output list object for later reference.

DRAW

This is a Boolean flag that is used to turn the drawing function on (TRUE) or off (FALSE). It can be useful to see the intermediate shifting layers used by the algorithm. This is often used to learn how the function works, rather than in production mode.

VERBOSE

This is a Boolean flag that is used to control the display of additional state feeback during operation (TRUE), or to suppress it (FALSE). Generally, this is used in the default FALSE mode, but since it was useful during development, it has been left in for now).

TORUS

This is a Boolean flag that determines whether the data is considered to be toroidal (continuous) by having the edges wrap around to the opposite side (TRUE), or not (FALSE). If FALSE, the outer edge of result cells are omitted and the output is 2 rows and 2 columns smaller than the input. This means that an imput must have at least 3 rows and 3 columns for a non-toroidal case to not provide an error message.

rho

A numeric element that serves the purpose of passing this pattern parameter to the function, allowng it to be added to the output list object as reference. It is not actually used to control processing. This value describes the degree of spatial autocorrelation in the input object.

proportion

A numeric element that serves the purpose of passing this pattern parameter to the function, allowng it to be added to the output list object as reference. It is not actually used to control processing. This value describes the proportion of black to white cells in the input object.

Value

The output is a list object that contains PROCESSINGDATE (when the code was run), IMAGE (the name of the image, if supplied), NCELLS (the total number of cells in the grid), TORUS (Boolean indicator of whether processing as a torus or not), RHO (spatial autocorrelation value of grid), PROPORTION (proportion value of grid categories), RESULTS (output data.frame with all frequencies and probabilities), and JOINT (the output matrix of all pattern element codes). Note that C = centre, R = right, A = above, L = left, and B = below.

Note

TBA

Author(s)

Tarmo K. Remmel

References

None currently.

See Also

See Also CARsimu.

Examples

elements <- patternbits(OBJ=TRUE, OBJtxt="Demo")
str(elements)