Store sorting grid as logical matrix.

Stores sorting grid as a logical \(i * k\) matrix with sorting columns as columns, sorting rows as rows and TRUE (allowed) or FALSE (not allowed) in cells.

psGrid(grid, polygon = "rectangle", offset = NULL)

# S3 method for psGrid
validate_S3(x, ...)

as_psGrid(obj, ...)

# S3 method for integer
as_psGrid(obj, ...)

# S3 method for numeric
as_psGrid(obj, ...)

# S3 method for matrix
as_psGrid(obj, ...)

# S3 method for logical
as_psGrid(obj, ...)

# S3 method for psSort
as_psGrid(obj, ...)

# S3 method for psGrid
knit_print(
  x,
  header = TRUE,
  footer = TRUE,
  aspect_ratio_cards = 85/54,
  inline = FALSE,
  ...
)

Arguments

grid	[matrix()] giving the availability of cells for sorting as logical(1) values. The (horizontal) x-axis is assumed to be the sorting direction, the (vertical) y-axis for recording ties. Dimensions can be named (recommended), giving a short description of the sorting dimension (only applicable to the x-axis). Row and column indeces can also be named, but names are purely cosmetic.
polygon	[character(1)] giving polygon to use for tiling Must be one of: 'rectangle' (default) or 'hexagon'
offset	[character(1)] giving the rows to be offset. Must be one of: NULL in which case no offset is used for a square tiling. (default) 'even' or 'odd'
x	An object with one of the pensieve S3 classes.
...	further arguments to be passed to methods.
obj	An object which can be coerced to a logical matrix of class psGrid.
header, footer	A logical flag, defaults to TRUE, in which case column or row names from grid are included as headers or footers, respectively. Missing row or column names are replaced with sensible defaults.
aspect_ratio_cards	A numeric scalar, giving width divided by height of individual cards (such as 16/9 for screen dimensions). Aspect ratio of cards is required to appropriately set the resulting dimensions of the grid. Defaults to standard business cards.
inline	[logical(1)] indicating whether knitr is called from inline (r 1+1) or from a chunk. Defaults to FALSE.

Value

A logical matrix of class psGrid.

Details

Every sort must have a grid. Even a free distribution must have a grid, giving the maximum indices of rows and columns, but with all cells TRUE.

Methods (by generic)

• validate_S3: Validation

• as_psGrid: Coercion from (named) integer(ish) vector, giving the column height of TRUEs from the bottom (names are retained as column names).

• as_psGrid: Coercion from a logical matrix as per psGrid.

• as_psGrid: Coerction from a logical vector (very unlikely).

• as_psGrid: Coercion from a character matrix psSort (sets all cells to TRUE).

• knit_print: Printing inside knitr chunks

Hexagonal tiling

psGrid and psSort store all sorting grids as rectangular matrices, using what is known as the "offset" notation for hexagonal tiling. In offset notation, hexagonal tilings are saved as if they were normal (square) tilings, with an additional attribute giving which rows are to be offset. In this way, both square and hexagonal tilings can be stored in a similar format. They are also intuitive to use, where the outer limits of the tiling are rectangular, and rotation is not required, both of which are usually the case for sorting. However, linear algebra operations are no longer defined on such hexagonal matrices in offset notation (that would require cube or axial coordinates). Remember not to run such operations on hexagonally tiled psGrids or psSorts.

The offset argument is used to switch between loosely defined tiling patterns. Strictly speaking there are three regular tiling patterns: square, hexagonal and triangular. However, items are more easily typeset in rectangles than in squares, hexagons or triangles. You can therefore also use "square" tiling (offset = NULL) for rectangulary set items, and even "hexagonal" tiling (offset = "even" or offset = "odd") for rectangles (in a "brickwall" pattern) and irregular (stretched or squeezed) hexagons. One combination remains impossible: you cannot have "square" tiling (offset = NULL) with hexagons (polygon = 'hexagon').

The aspect ratio of the irregular polygons is currently only provided to respective knit_print() methods. To achieve regular square and hexagonal tiling (though this is unlikely to be useful), set aspect_ratio_cards to 1.

Notice that offset always refers to rows, and as such implies hexagonal tiling in "pointy"-topped rotation.

Remember that rows for offset are given using R indices, starting with 1. Examples of offset notation in most other programming languages will differ."

Printing in knitr chunks

Extends the knitr::knit_print() generic for pensieve S3 objects.

By default print() in knitr will default to knitr::knit_print(), so to nicely print some object obj inside a chunk, you can just write print(obj) or even just obj.

However, to manually invoke or preview the interactive displays in RStudio, you must call knitr::knit_print() in full. The base::print()ing method of the underlying classes is not altered outside of a knitr chunk.

See also

Other S3 classes from pensieve: correlate(), extract(), psClosedSorts(), psItemContent(), psOpenSorts(), psOpenSort(), psPeople(), score()

Other print functions: psItemContent()

Examples

# create simple grids ====

# make simple matrix by hand
m <- matrix(data = c(FALSE, TRUE, TRUE, TRUE, FALSE, TRUE), nrow = 2)
grid_byhand <- psGrid(grid = m)

# matrix with better dimnames
dimnames(m) <- list(
  c(NULL), # rows, or y-dimension is meaningless, used for ties
  desirable = NULL  # no use in adding actual column names
  # say, desirable is the short form for the sorting conditition used on x
)
grid_byhand <- psGrid(grid = m)

# coerce grid from conventional distribution notation
grid_bycoercion <- as_psGrid(obj = c(1,2,1))