Store item content as character strings

Source: R/psItemContent.R

Helper function to append and validate psItemContent class. See vignette for details.

psItemContent(
  items,
  dir_bin = NULL,
  lang = NULL,
  fontsize_global = NULL,
  alignment = "left",
  linestretch = 2,
  paperwidth = 8.5,
  paperheight = 5.4,
  top = 0.5,
  bottom = 0.5,
  left = 0.5,
  right = 0.5,
  unit = "cm",
  vcentering = TRUE,
  hcentering = TRUE
)

# S3 method for psItemContent
validate_S3(x, ps_coll = NULL, ...)

as_psItemContent(obj, ...)

# S3 method for character
as_psItemContent(obj, ...)

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

# S3 method for psItemContent
print(x, ...)

# S3 method for psItemContentText
knit_print(x, inline = FALSE, ...)

# S3 method for psItemContentText
export_ps(x, dir = ".", overwrite = FALSE, format = "pdf")

# S3 method for psItemContentText
plot(x)

Arguments

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.
dir_bin

[character(1)] giving the root from which items can be found, when items are paths. Defaults to NULL, in which case items are expected to be texts. Must be relative path from the working directory.
lang

[character(1)] giving a valid BCP 47 language code code, such as en_US.

Must be one of:

  • NULL in which case there is no multilingual support (default)

  • 'ar-DZ' for arabic (Algeria)

  • 'ar-IQ' for arabic (Iraq)

  • 'ar-JO' for arabic (Jordan)

  • 'ar-LB' for arabic (Lebanon)

  • 'ar-LY' for arabic (Libya)

  • 'ar-MA' for arabic (Morocco)

  • 'ar-MR' for arabic (Mauritania)

  • 'ar-PS' for arabic (Palestinian Territory)

  • 'ar-SY' for arabic (Syria)

  • 'ar-TN' for arabic (Tunisia)

  • 'de-DE' for german

  • 'de-AT' for german (Austria)

  • 'de-CH' for german (Switzerland)

  • 'dsb' for lower sorbian

  • 'hsb' for upper sorbian

  • 'el-polyton' for greek (polytonic)

  • 'en-AU' for english (Australia)

  • 'en-CA' for english (Canada)

  • 'en-GB' for english (Great Britain)

  • 'en-NZ' for english (New Zealand)

  • 'en-UK' for english (United Kingdom)

  • 'en-US' for english (United States)

  • 'grc-ancient' for greek (ancient)

  • 'la' for latin

  • 'sl' for slovenian

  • 'fr-CA' for french (Canada)

  • 'pt-BR' for portoguese (Brazil)

  • 'af' for afrikaans

  • 'am' for amharic

  • 'ar' for arabic

  • 'as' for assamese

  • 'ast' for asturian

  • 'bg' for bulgarian

  • 'bn' for bengali

  • 'bo' for tibetan

  • 'br' for breton

  • 'ca' for catalan

  • 'cy' for welsh

  • 'cs' for czech

  • 'cop' for coptic

  • 'da' for danish

  • 'dv' for divehi

  • 'el' for greek

  • 'en' for english

  • 'eo' for esperanto

  • 'es' for spanish

  • 'et' for estonian

  • 'eu' for basque

  • 'fa' for farsi

  • 'fr' for french

  • 'fur' for friulan

  • 'ga' for irish

  • 'gd' for scottish

  • 'gez' for ethiopic

  • 'gl' for galician

  • 'he' for hebrew

  • 'hi' for hindi

  • 'hr' for croatian

  • 'hu' for magyar

  • 'hy' for armenian

  • 'ia' for interlingua

  • 'id' for indonesian

  • 'is' for icelandic

  • 'it' for italian

  • 'km' for khmer

  • 'kmr' for kurmanji

  • 'kn' for kannada

  • 'ko' for korean

  • 'lo' for lao

  • 'lt' for lithuanian

  • 'lv' for latvian

  • 'ml' for malayalam

  • 'mn' for mongolian

  • 'mr' for marathi

  • 'nb' for norsk

  • 'nl' for dutch

  • 'nn' for nynorsk

  • 'no' for norsk

  • 'nqo' for nko

  • 'oc' for occitan

  • 'pa' for panjabi

  • 'pms' for piedmontese

  • 'pt' for portoguese

  • 'rm' for romanian

  • 'ro' for russian

  • 'sa' for sanskrit

  • 'se' for samin

  • 'sk' for slovak

  • 'sq' for albanian

  • 'sr' for serbian

  • 'syr' for syriac

  • 'ta' for tamil

  • 'te' for telugu

  • 'th' for thai

  • 'ti' for ethiopic

  • 'tk' for turkmen

  • 'tr' for turkish

  • 'uk' for ukrainian

  • 'ur' for urdu or

  • 'vi' for vietnamese

Used for multilingual typsetting support via LaTeX's babel package and others. Careful: Depending on the local tex distribution, not all valid languages may also be supported by LaTeX. Use check_latex_lang() to verify.
fontsize_global

[character(1)] giving the document-wide font size.

Must be one of:

  • NULL in which case the system default fontsize is used. (default)

  • '10pt'

  • '11pt' or

  • '12pt'
alignment

[character(1)] giving the alignment of the text.

Must be one of:

  • 'justified' (default)

  • 'left'

  • 'right' or

  • 'center'
linestretch

[numeric()] giving the line spacing in multiples, e.g. 1.25, 1.5. Defaults to NULL for default LaTeX line spacing.
paperwidth

[numeric(1)] giving the width and height of documents in unit. For good typographical results, should be as close as possible to the actual physical measurements of documents encountered by users. Defaults to NULL.
paperheight

[numeric(1)] giving the width and height of documents in unit. For good typographical results, should be as close as possible to the actual physical measurements of documents encountered by users. Defaults to NULL.
top

[numeric(1)] giving the margin in unit. Defaults to NULL.
bottom

[numeric(1)] giving the margin in unit. Defaults to NULL.
left

[numeric(1)] giving the margin in unit. Defaults to NULL.
right

[numeric(1)] giving the margin in unit. Defaults to NULL.
unit

[character(1)] giving the units for the above dimensions.

Must be one of:

  • 'cm' for metric (default) or

  • 'in' for imperial
vcentering

[logical(1)] indicating whether content should be vertically/horizontally centered. Defaults to FALSE.
hcentering

[logical(1)] indicating whether content should be vertically/horizontally centered. Defaults to FALSE.
x

An object with one of the pensieve S3 classes.
ps_coll

AssertCollection ps_coll error collection via checkmate::makeAssertCollection(), for internal use.
...

further arguments to be passed to methods.
obj

An object which can be coerced to psItemContent, currently one of:

  • a (named) character vector.
inline

[logical(1)] indicating whether knitr is called from inline (r 1+1) or from a chunk. Defaults to FALSE.
dir

[character(1)] giving the directory where the exported objects are written to. Must be relative from the working directory. Defaults to the working directory root.
overwrite

[logical(1)] indicating whether existing files should be overwritten. Defaults to FALSE, in which case the function throws an error if a file exists already.
format

[character(1)] giving the output format to render items in.

Must be one of:

  • 'tex'

  • 'pdf' (default) or

  • 'svg'

Value

[character()] with class psItemContent.

Details

Store full items along with metadata (language, design) to enable deployment and convenience functions, as well as enhance the presentation of results.

Methods (by generic)

  • validate_S3: Validation

  • as_psItemContent: Coerce from character vector

  • as_psItemContent: Coerce from psSort

  • print: Printing to the console

  • knit_print: Printing inside knitr chunks

  • export_ps: Export rendered text items to vector formats.

  • plot: Plot rendered item. Defaults to first item.

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.

Plotting items

Plotting items to the R graphics system has some limitations:

  • You can only plot one item at a time. The function defaults to the first item.

  • The item is placed in the aspect ratio given by psItemContent() in the middle of the plotting area. There may be additional white space around the item. This is because R graphics must offer arbitrary aspect ratios, but items have a fixed aspect ratio. For good-looking results, you should set the aspect ratio of the plotting area to equal that of the items.

See also

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

Other print functions: psGrid()

Examples

# text items with handles
items_text_en <- psItemContent(
  items = c(
    "live_2_work" = "Man lives to work.",
    "work_2_live" = "Man works to live."
  ),
  lang = "en-US"
)

# text items without handles
items_text_de <- psItemContent(
  items = c(
    "Man lebt um zu arbeiten.",
    "Man arbeitet, um zu leben."
  ),
  lang = "de-DE"
)

# text items without multilingual typographic support
items_text_esperanto <- psItemContent(
  items = c(
    "Viro vivas por labori.",
    "Viro laboras vivi."
  )
)

# image items
# these images ship with pensieve
# location depends on runtime; ignore next three lines
dir_bin <- file.path("..", "..", "inst", "extdata", "fruit")
if (!dir.exists(dir_bin)) {
  dir_bin <- file.path(system.file(package = "pensieve"), "extdata", "fruit")
}
items_image <- psItemContent(
  items = c("peach.jpg", "pear.jpg"),
  dir_bin = dir_bin
)