These functions first import data from a 'data format', such as spreadsheets
in .xlsx
format, comma-separated values files (.csv
), or SPSS data
files (.sav
). You can also just use R data frames (imported however you
want). These functions then use the columns you specified to convert these
data to one (oneFile=TRUE
) or more (oneFile=FALSE
) rock
source file(s), optionally including class instance
identifiers (such as case identifiers to identify participants, or location
identifiers, or moment identifiers, etc) and using those to link the
utterances to attributes from columns you specified. You can also precode
the utterances with codes you specify (if you ever would want to for some
reason).
convert_df_to_source(
data,
output = NULL,
omit_empty_rows = TRUE,
cols_to_utterances = NULL,
cols_to_ciids = NULL,
cols_to_codes = NULL,
cols_to_attributes = NULL,
utterance_classId = NULL,
oneFile = TRUE,
cols_to_sourceFilename = cols_to_ciids,
cols_in_sourceFilename_sep = "=",
sourceFilename_prefix = "source_",
sourceFilename_suffix = "",
ciid_labels = NULL,
ciid_separator = "=",
attributesFile = NULL,
preventOverwriting = rock::opts$get(preventOverwriting),
encoding = rock::opts$get(encoding),
silent = rock::opts$get(silent)
)convert_csv_to_source(
file,
importArgs = NULL,
omit_empty_rows = TRUE,
output = NULL,
cols_to_utterances = NULL,
cols_to_ciids = NULL,
cols_to_codes = NULL,
cols_to_attributes = NULL,
oneFile = TRUE,
cols_to_sourceFilename = cols_to_ciids,
cols_in_sourceFilename_sep = "=",
sourceFilename_prefix = "source_",
sourceFilename_suffix = "",
ciid_labels = NULL,
ciid_separator = "=",
attributesFile = NULL,
preventOverwriting = rock::opts$get(preventOverwriting),
encoding = rock::opts$get(encoding),
silent = rock::opts$get(silent)
)
convert_csv2_to_source(
file,
importArgs = NULL,
omit_empty_rows = TRUE,
output = NULL,
cols_to_utterances = NULL,
cols_to_ciids = NULL,
cols_to_codes = NULL,
cols_to_attributes = NULL,
oneFile = TRUE,
cols_to_sourceFilename = cols_to_ciids,
cols_in_sourceFilename_sep = "=",
sourceFilename_prefix = "source_",
sourceFilename_suffix = "",
ciid_labels = NULL,
ciid_separator = "=",
attributesFile = NULL,
preventOverwriting = rock::opts$get(preventOverwriting),
encoding = rock::opts$get(encoding),
silent = rock::opts$get(silent)
)
convert_xlsx_to_source(
file,
importArgs = list(),
omit_empty_rows = TRUE,
output = NULL,
cols_to_utterances = NULL,
cols_to_ciids = NULL,
cols_to_codes = NULL,
cols_to_attributes = NULL,
oneFile = TRUE,
cols_to_sourceFilename = cols_to_ciids,
cols_in_sourceFilename_sep = "=",
sourceFilename_prefix = "source_",
sourceFilename_suffix = "",
ciid_labels = NULL,
ciid_separator = "=",
attributesFile = NULL,
preventOverwriting = rock::opts$get(preventOverwriting),
encoding = rock::opts$get(encoding),
silent = rock::opts$get(silent)
)
convert_sav_to_source(
file,
importArgs = NULL,
omit_empty_rows = TRUE,
output = NULL,
cols_to_utterances = NULL,
cols_to_ciids = NULL,
cols_to_codes = NULL,
cols_to_attributes = NULL,
oneFile = TRUE,
cols_to_sourceFilename = cols_to_ciids,
cols_in_sourceFilename_sep = "=",
sourceFilename_prefix = "source_",
sourceFilename_suffix = "",
ciid_labels = NULL,
ciid_separator = "=",
attributesFile = NULL,
preventOverwriting = rock::opts$get(preventOverwriting),
encoding = rock::opts$get(encoding),
silent = rock::opts$get(silent)
)
A source as a character vector.
The data frame containing the data to convert.
If oneFile=TRUE
(the default), the name (and path)
of the file in which to save the processed source (if it is NULL
, the
resulting character vector will be returned visibly instead of invisibly).
Note that the ROCK convention is to use .rock
as extension.
If oneFile=FALSE
, the path to which to write the
sources (if it is NULL
, as a result a list of character vectors will be
returned visibly instead of invisibly).
Whether to omit rows where the values in the columns specified to convert to utterances are all empty (or contain only whitespace).
The names of the columns to convert to utterances, as a character vector.
The names of the columns to convert to class instance
identifiers (e.g. case identifiers), as a named character vector, with
the values being the column names in the data frame, and the names being the
class instance identifiers (e.g. "sourceId"
, "fieldId"
, "caseId"
, etc).
The names of the columns to convert to codes (i.e.
codes appended to every utterance), as a character vector. When writing codes,
it is not possible to also write multiple utterance columns
(i.e. utterance_classId
must be NULL
).
The names of the columns to convert to attributes,
as a named character vector, where each name is the name of the class
instance identifier to attach the attribute to. If only one column is passed
in cols_to_ciids
, names can be omitted and a regular unnamed character
vector can be passed.
When specifying multiple columns with utterances,
and utterance_classId
is not NULL
, the column names are considered to be
class instance identifiers, and specified above each utterance using the
class identifier specified here (e.g. "utterance_classId="originalColName"
"
yields something like "[[originalColName=colName_1]]
" above all utterances
from the column named colName_1
). When writing multiple utterance columns,
it is not possible to also write codes (i.e. cols_to_codes
must be NULL
).
Whether to store everything in one source, or create one
source for each row of the data (if this is set to FALSE
, make sure that
cols_to_sourceFilename
specifies one or more columns that together
uniquely identify each row; also, in that case, output
must be an existing
directory on your PC).
The columns to use as unique part of the
filename of each source. These will be concatenated using
cols_in_sourceFilename_sep
as a separator. Note that the final string
must be unique for each row in the dataset, otherwise the filenames for
multiple rows will be the same and will be overwritten! By default, the
columns specified with class instance identifiers are used.
The separator to use when concatenating
the cols_to_sourceFilename
.
Strings that are
prepended and appended to the col_to_sourceFilename
to create the full
filenames. Note that .rock
will always be added to the end as extension.
The labels for the class instance identifiers. Class instance identifiers have brief codes used in coding (e.g. 'cid' is the default for Case Identifiers, often used to identify participants) as well as more 'readable' labels that are used in the attributes (e.g. 'caseId' is the default class instance identifier for Case Identifiers). These can be specified here as a named vector, with each element being the label and the element's name the identifier.
The separator for the class instance identifier - by
default, either an equals sign (=
) or a colon (:
) are supported, but
an equals sign is less ambiguous.
Optionally, a file to write the attributes to if you don't want them to be written to the source file(s).
Whether to prevent overwriting of output files.
The encoding of the source(s).
Whether to suppress the warning about not editing the cleaned source.
The path to a file containing the data to convert.
Optionally, a list with named elements representing arguments to pass when importing the file.
### Get path to example files
examplePath <-
system.file("extdata", package="rock");
### Get a path to file with example data frame
exampleFile <-
file.path(examplePath, "spreadsheet-import-test.csv");
### Read data into a data frame
dat <-
read.csv(exampleFile);
### Convert data frame to a source
source_from_df <-
convert_df_to_source(
dat,
cols_to_utterances = c("open_question_1",
"open_question_2"),
cols_to_ciids = c(cid = "id"),
cols_to_attributes = c("age", "gender"),
cols_to_codes = c("code_1", "code_2"),
ciid_labels = c(cid = "caseId")
);
### Show the result
cat(
source_from_df,
sep = "\n"
);
Run the code above in your browser using DataLab