Skip to contents

Adds a title and a description for a data set stored as .omv-file for the statistical spreadsheet 'jamovi' (https://www.jamovi.org)

Source: R/describe_omv.R
describe_omv.Rd

Adds a title and a description for a data set stored as .omv-file for the statistical spreadsheet 'jamovi' (https://www.jamovi.org)

Usage

describe_omv(
  dtaInp = NULL,
  fleOut = "",
  dtaTtl = NULL,
  dtaDsc = NULL,
  lngDsc = "EN",
  usePkg = c("foreign", "haven"),
  selSet = "",
  ...
)

Arguments

dtaInp

Either a data frame or the name of a data file to be read (including the path, if required; "FILENAME.ext"; default: NULL); files can be of any supported file type, see Details below.

fleOut

Name of the data set / file to be written (including the path, if required; "FILE_OUT.omv"; default: ""); if empty, the resulting data frame is returned instead.

dtaTtl

Character vector with a title to be added to the data set (see Details; default: "")

dtaDsc

Description of the data set, either as character vector (HTML-formatted) or as named list with the entries "description", "variables", "references", and "license" (see Details; default: "")

lngDsc

Language of the description (localizes the description components: "Description", "Variables", "References", and "License"; default: "EN")

usePkg

Name of the package: "foreign" or "haven" that shall be used to read SPSS, Stata, and SAS files; "foreign" is the default (it is included in base R), but "haven" is newer and more comprehensive; you may have to install using install.packages("haven", dep = TRUE).

selSet

Name of the object / data set that is to be selected from the workspace (only relevant when reading .RData-files which can contain several objects / data sets)

...

Additional arguments passed on to methods; see Details below

Value

a data frame (only returned if fleOut is empty) where a description and a title are added to the input data

Details

  • The aim of this function is to add a title and a data set description to jamovi data files. Two typical use cases would be (1) to help creating data sets to be used in teaching (i.e., either creating or using data sets in R, and afterwards adding a description to those), and (2) to provide "properly described" data when publishing in a repository, e.g., the OSF).

  • NB: The data set should not contain any existing analyses. These will be overwritten (a warning is issued informing you about that).

  • dtaTtl is a title for the dataset (at the top of the results output, i.e., that title which initially is "Results" when you create a new data set in jamovi).

  • dtaDsc can either be a character vector (with length = 1) containing HTML-formatted text that describes the data set (see chrDsc in the examples for HTML tags that are currently implemented; putting "unformatted" text is not a problem, but then the result is just plain text without formatting). Alternatively, dtaDcs can be a named list with the entries description, variables, references, license. All entries except from variables contain character vectors (typically with the length = 1); variables shall be a named list with the variable name as name and a description what the variable contains as entry. description and variables must be given, references and license can be left blank (""; but the names must be present in the list). license can also a character vector containing one of the following keywords, producing a license text fitting the respective license: "CC0" (Creative Commons, CC0), "DT_CC4-BY-NC-ND" and "FC_CC4-BY-NC-ND" (Creative Commons, CC BY-NC-ND 4.0, for data from scientific studies "DT_" or generated / simulated data sets "FC_"; both need the license holder to be given as the second element of the character vector for the list entry license, e.g., list(..., list = c("DT_CC4-BY-NC-ND", "John Doe")), "RP_GPL2", "RP_GPL3", "RP_AGPL3", and "RP_LGPL3" are for data sets that were originally part of R-packages under different versions of the GNU General Public License (respectively, GNU General Public License 2.x, GNU General Public License 3.0, GNU Affero General Public License 3.0, and GNU Lesser General Public License 3.0; these need the name of the R-package to be given as the second element of the character vector for the list entry license, e.g., list(..., list = c("RP_GPL2", "jmv"). Examples for both named lists with a description (lstDsc), as well as a character vector with all HTML tags that are implemented (chrDsc) can be found in the examples below.

  • The ellipsis-parameter (...) can be used to submit arguments / parameters to the functions that are used for reading the data. By clicking on the respective function under “See also”, you can get a more detailed overview over which parameters each of those functions take.

See also

describe_omv internally uses the following functions for reading and writing data files in different formats: read_omv() and write_omv() for jamovi-files, utils::read.table() for CSV / TSV files, load() for reading .RData-files, readRDS() for .rds-files, haven::read_sav() or foreign::read.spss() for SPSS-files, haven::read_dta() or foreign::read.dta() for Stata-files, haven::read_sas() for SAS-data-files, and haven::read_xpt() or foreign::read.xport() for SAS-transport-files.

Examples

nmeOut <- tempfile(fileext = ".omv")

# the paste's underneath are only for readability (without them, the vignettes are misformatted)
# example for a data set without a license
dtaFrm <- jmvReadWrite::ToothGrowth[, c("len", "supp", "dose")]
lstDsc <- list(description = paste("The response is the length of odontoblasts (cells",
                                   "responsible for tooth growth) in 60 guinea pigs. Each",
                                   "animal received one of three dose levels of vitamin C",
                                   "(0.5, 1, and 2 mg / day) by one of two delivery methods,",
                                   "orange juice or ascorbic acid (a form of vitamin C and",
                                   "coded as VC)."),
               variables = list(len  = "Tooth length",
                                supp = "Supplement type (VC or OJ)",
                                dose = "Dose (in milligrams / day)"),
               references = paste("Crampton, E. W. (1947). The growth of the odontoblast of",
                                  "the incisor teeth as a criterion of vitamin C intake of",
                                  "the guinea pig. <em>The Journal of Nutrition, 33</em>(5),",
                                  "491-504. https://doi.org/10.1093/jn/33.5.491"),
               license = "")
jmvReadWrite::describe_omv(dtaInp = dtaFrm, fleOut = nmeOut, dtaTtl = "ToothGrowth",
                           dtaDsc = lstDsc)
# don't include the unlink, if you copy the code and want to look at the resulting output file
unlink(nmeOut)

# example for a data set which is part of the R-package `datasets` under the GPL2
dtaFrm <- datasets::penguins
lstDsc <- list(description = paste("Data on adult penguins covering three species found on",
                                   "three islands in the Palmer Archipelago, Antarctica,",
                                   "including their size (flipper length, body mass, bill",
                                   "dimensions), and sex."),
               variables = list(species     = "Species (Adelie, Chinstrap, and Gentoo)",
                                island      = "Island (Biscoe, Dream, and Torgersen)",
                                bill_len    = "Bill length (in mm)",
                                bill_dep    = "Bill depth (in mm)",
                                flipper_len = "Flipper length (in mm)",
                                body_mass   = "Body mass (in g)",
                                sex         = "Sex (female and male)",
                                year        = "Study year: 2007, 2008, or 2009"),
               references = paste("Gorman, K. B., Williams, T. D., & Fraser, W. R. (2014).",
                                  "Ecological sexual dimorphism and environmental variability",
                                  "within a community of antarctic penguins (Genus pygoscelis).",
                                  "<em>PLoS ONE, 9</em>(3), e90081.",
                                  "https://doi.org/10.1371/journal.pone.0090081"),
               license = c("RP_GPL2", "datasets"))
jmvReadWrite::describe_omv(dtaInp = dtaFrm, fleOut = nmeOut, dtaTtl = "Penguins",
                           dtaDsc = lstDsc)
# don't include the unlink, if you copy the code and want to look at the resulting output file
unlink(nmeOut)

# the code underneath should cover all formatting options jamovi is able to use (paste0 is only
# for readability)
dtaFrm <- jmvReadWrite::ToothGrowth[, c("len", "supp", "dose")]
chrDsc <- paste0("<p><strong>Trial - all formattings:</strong><br/>",
                 "<strong>bold</strong><br/><strong><em>bold, italics</em></strong><br/>",
                 "<em>italics</em><br/><u>underlined</u><br/><s>strikethrough</s><br/>",
                 "C<sub>2</sub>H<sub>5</sub>OH<br/>R<sup>2</sup><br/>",
                 "<span style=\"background-color:#e60000\">background colour: red</span><br/>",
                 "<span style=\"color:#e60000\">foreground color: red</span></p>",
                 "<p class=\"ql-align-center\">centered</p>",
                 "<p class=\"ql-align-right\">right</p>",
                 "<p class=\"ql-align-justify\">justify justify justify justify justify ",
                 "justify justify justify justify justify justify justify justify justify ",
                 "justify justify justify justify justify justify justify justify justify ",
                 "justify justify</p><p><br/></p>",
                 "<ol><li>numbered list</li><li>numbered list</li></ol><p><br/></p>",
                 "<ul><li>bullet point</li><li>bullet point</li></ul>",
                 "<p class=\"ql-indent-1\">indented once</p>",
                 "<p class=\"ql-indent-2\">indented twice</p>",
                 "<p class=\"ql-indent-1\">indented once</p>",
                 "<p>Formula: <span class=\"ql-formula\">e=mc^2</span></p>",
                 "<pre>Preformatted</pre><p>normal again</p><h2>Heading</h2>")
jmvReadWrite::describe_omv(dtaInp = dtaFrm, fleOut = nmeOut, dtaTtl = "ToothGrowth",
                           dtaDsc = chrDsc)
# don't include the unlink, if you copy the code and want to look at the resulting output file
unlink(nmeOut)