Store multiple sorts as a numeric matrix

Canonical storage for closed sorts.

Plot S3 class.

psClosedSorts(csorts)

# S3 method for psClosedSorts
validate_S3(x, items = NULL, grid = NULL, ...)

as_psClosedSorts(obj, ...)

# S3 method for psSort
as_psClosedSorts(obj, items = NULL, ...)

# S3 method for psClosedSorts
plot(x, column = 1, use_js = NULL, ...)

Arguments

csorts	[matrix()] An numeric matrix with people as rows, item handles as columns and item positions in cells.
x	An object with one of the pensieve S3 classes.
items	[character()] giving the participant-facing item content. Can be named to provide short, researcher-facing item handles. Names must be unique, valid R names, as per base::make.names(). If names are missing, they are automatically added using a string of the first unique words. You can also provide handles as if they were a full item wording. if dir_bin is NULL (default), items must be text. Items can be marked up using Pandoc Markdown. An additional subclass psItemContentText is prepended and validated. if dir_bin is given, items must be file paths, relative from dir_bin. An additional subclass psItemContentBin`` is prepended and validated. lang, fontsize_global, alignmentandlinestretch` are ignored.
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.
...	Arguments passed onto other methods. Not currently used.
obj	An object which can be coerced to an integer array of class psClosedSorts.
column	Positive integer scalar, giving the column of the psClosedSorts object to plot. Defaults to 1, in which case the first column is plotted.
use_js	A logical flag, indicating whether an interactive, java-script variant of the plot should be returned. Defaults to NULL, in which case the appropriate output is inferred from the runtime environment.

Value

A numeric matrix of class psClosedSorts.

Methods (by generic)

• validate_S3: Validation against items and grid (recommended)

• as_psClosedSorts: Coercion from psSort (creates one row)

• plot: plotting

See also

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

Other plotting functions: correlate(), extract()

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))
# 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
)
# create multiple sorts ====
# simple case with one condition of instruction
csorts <- matrix(
  data = c(-1, 0, 1, -1),
  nrow = 2,
  byrow = TRUE,
  dimnames = list(
    people = c("Lisa", "Peter"),
    items = c("live_2_work", "work_2_live")
  )
)
csorts <- psClosedSorts(csorts)

# you can coerce a *row* (person) of a 'psClosedSorts' object from a *single* "raw" psSort
csorts_from_one_sort <- as_psClosedSorts(obj = one_sort)
# this also works for psSort with offsets
csorts_from_one_sort_hex <- as_psClosedSorts(obj = one_sort_from_vec_hex)
# it is recommended to also supply 'items' to the coercion
# so that items are properly ordered and missing items set to NA
csorts_w_items <- as_psClosedSorts(
  obj = one_sort,
  items = c("work_2_live", "live_2_work", "enjoy_work")
  # you can pass a proper 'psItemContent' object to items, but also just item handles
)