Stores one sort, by one participant as an \(i * k\) character matrix, with sorting columns as columns, sorting rows as rows and short item handles (see psItems) in cells.
psSort(sort, polygon = "rectangle", offset = NULL) # S3 method for psSort validate_S3(x, grid = NULL, items = NULL, ...) as_psSort(obj, ...) # S3 method for psGrid as_psSort(obj, ...) # S3 method for numeric as_psSort(obj, ...) # S3 method for integer as_psSort(obj, ...) # S3 method for data.frame as_psSort(obj, ...) # S3 method for matrix as_psSort(obj, grid = NULL, insert_at_grid_col = NULL, ...)
| sort |
|
|---|---|
| polygon |
Must be one of:
|
| offset |
Must be one of:
|
| x | An object with one of the pensieve S3 classes. |
| grid |
|
| items |
|
| ... | further arguments to be passed to methods. |
| obj | An object which can be coerced to a character matrix of class psSort. |
| insert_at_grid_col |
|
A character matrix of class psSort.
Sorts can be stored in the form in which they were originally created on a table or in a computer user interface.
The y-axis, though meaningless (ties) in most studies, is also stored, but this full matrix form makes it easy to reason about the data, and to validate it.
validate_S3: Validation
as_psSort: Coercion from psGrid (sets all to NA)
as_psSort: Coercion from integer(ish) vector of item positions; names are retained as item handles.
as_psSort: Coercion from a long dataframe with x/y item positions as first/second columns, and item handles as third column.
as_psSort: Coercion from a matrix similar to psSort, in accordance with a psGrid in grid:
Will place smaller matrices in bigger matrices.
Will fill in only allowed cells from the bottom (highest row) up.
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."
# 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)) # create a single sort ==== one_sort <- matrix( data = c(NA, "live_2_work", NA, "work_2_live", NA, NA), nrow = 2, dimnames = list( c(NULL), # this is for rownames, of which there are none, because those are just ties desirable = NULL # no really useful dimnames # 'desirable' is a short name for the description of the sorting axis # (here, as typically, x) ) ) one_sort <- psSort(sort = one_sort) # you can coerce an empty (all `NA`) sort from grid one_sort_from_grid <- as_psSort(obj = grid_byhand) # you can coerce a sort from an integer(ish) vector, with cells filled from the bottom up one_sort_from_vec <- as_psSort(obj = c(foo = -1, bar = 0, zap = 1, zong = 1)) # you can also pass on other arguments to `psSort()` one_sort_from_vec_hex <- as_psSort( obj = c(foo = -1, bar = 0, zap = 1, zong = 1), polygon = "hexagon", offset = "odd" ) # you can also coerce a sort from a long data.frame, like so: df <- tibble::tribble( ~x, ~y, ~cell, 1, 1, "foo", # notice that there is no item at x = 2; # the missing NA will be added by the below coercion method 3, 1, "bar" ) one_sort_from_df <- suppressMessages(as_psSort(df)) # message would inform about no item at position 2 # you can coerce a narrower matrix inside a wider one, as per grid m1 <- matrix( # a 2 x 1 matrix data = c("bar", "foo"), nrow = 2, byrow = TRUE ) one_sort_from_narrow_m1 <- as_psSort( obj = m1, # this is narrower, a 2x1 matrix grid = grid_byhand, # this is wider, a 2x3 matrix insert_at_grid_col = 2 # this is where we start placing obj into grid ) m2 <- matrix( # a 2 x 2 matrix data = c("bar", NA, "foo", "zap"), nrow = 2, byrow = TRUE ) one_sort_from_narrow_m2 <- as_psSort( obj = m2, # this is narrower, a 2x2 matrix grid = grid_byhand, # this is wider, a 2x3 matrix insert_at_grid_col = 2 # this is where we start placing obj into grid ) # coercion from a matrix will fill in available cells in grid from the bottom up grid2 <- matrix( data = c( TRUE, FALSE, TRUE, FALSE, FALSE, TRUE, TRUE, TRUE, FALSE ), ncol = 3 ) grid2 <- psGrid(grid = grid2) m3 <- matrix( data = c( NA, "foo", "bar", NA, NA, "zap", "zong", NA, NA ), ncol = 3 ) one_sort_from_m3 <- as_psSort( obj = m3, # notice how the NAs are *in the wrong order* as per grid grid = grid2 )