QScript DataFile

DataFile

Represents a single data file (e.g. .sav) loaded into your project. This is where you can find your questions and variables.

canTellCategoricalFromText

Whether this file type can distinguish between true user-entered text and categorical data that has been stored as text. Useful when automatically configuring a new data file.

caseIdentifiers

Controls how we remember which data rows have been modified or deleted. It may be null (default, prevents rows being modified or deleted), "case number" (which remembers rows according to their position in the data file), or a variable (whose values are used to identify modified or deleted rows).

createBanner(question_name, blocks, add_sub_nets, add_overall_net, add_question_spans)

Creates a banner question, as in Q.

question_name	The name for the new question.
blocks	Each entry is an array of questions. Within each sub-array, every combination of codes will be produced. Can only be nested 2 levels deep.
add_sub_nets	True if the NET rows of the original input questions should be retained in the banner. False to remove these NETs from the banner. The default is true.
add_overall_net	True if a single NET row should be added to the banner that represents all of the input question categories. False to not add an overall NET row. The default is false.
add_question_spans	True if a span of each question name should be added that spans all of the question's categories. False to not add a span for each question name. The default is true.
Returns:	The new Question object.
Example:	// Creates a banner of Age, with Gender nested underneath. f.createBanner("BANNER", [[f.getQuestionByName('Age'), f.getQuestionByName('Gender')]])
Example:	// Creates a banner of Age side-by-side with Gender. f.createBanner("BANNER", [[f.getQuestionByName('Age')], [f.getQuestionByName('Gender')]], false, true, false)

createReportSummary(profile_questions, layout, create_results_summary, insert_after)

Creates a summary report for the data file

profile_questions	Questions to examine in detail, if null a short report will be generated
layout	The slide layout for the report, supported layouts are "OneTable", "OneChart", "OneTableWithText", "OneChartWithText", "TwoCharts", "TwoTables"
create_results_summary	Whether to create a results summary page, default is false
insert_after	Where to insert the report, default is to insert the report after the first page
Returns:	The first page of the report
Example:	project.dataFiles[0].createReportSummary(null, "OneChartWithText", true, null)

deleteVariables(variables)

Deletes multiiple variables. Variables must belong to the same Data Set

variables

A list of variables to be deleted

equals(obj)

Whether two objects are the same.

obj	The object to compare against.
Returns:	true or false
Example:	data_file.getQuestionByName('Q2').equals(data_file.questions()[0])

fileName

Get the data file's name, including an extension.

fileType

Returns SPSS, Triple-S, CSV, IBM SPSS Data Model or SQL, depending on the type of data.

getQuestionByName(name)

Finds a question using its name.

name	Question name. Must be matched exactly. e.g. 'Age'
Returns:	A Question object, or null if there is no such question.

getQuestionsByName(partial_name)

Finds all questions with a particular name, or part of a name.

partial_name	The text we are looking for. The match is not case sensitive.
Returns:	An array of Question objects. As always, the array begins at [0].
Example:	file.getQuestionsByName("Demographic:");

getVariableByName(name)

Finds a variable using its name.

name	Variable name (not label). e.g. 'Q1'. Must be matched exactly.
Returns:	A Variable object, or null if there is no such variable.

getVariablesByName(partial_name)

Finds all variables matching 'partial_name'.

partial_name	We look for variables with that string anywhere in their names. The match is not case sensitive.
Returns:	An array of Variable objects. As always, the array begins at [0].
Example:	file.getVariablesByName("Q1_")

id

Returns the unique internal id of the data file. This remains the same even if the data file is updated with a new name.

moveAfter(to_move, after)

Moves around variables in the list of variables and questions. Variables in a single question will always be kept together, but they will be reordered if necessary.

to_move	The variables to move. This should be an array of Variable objects.
after	The variable after which it will be placed. null to move it to the start of the list.
Example:	dataFile.moveAfter(q3.variables, gender);

name

Gets/sets the name used to refer to this data file. Normally this will be the filename of the data file, including its extension, but not including the directory.

net(variables)

Determines if the net constructed would be 100%.

variables	An array of Variable object, all from this data file.
Returns:	True if the NET constructed would be 100%.

newJavaScriptVariable(source_code, is_text, name, label, after, options)

Create a new JavaScript variable, as in Q. Get your variable code right in Q before trying it here.

source_code	A fragment of JavaScript. Use \n to separate lines.
is_text	Whether the output is a text variable (true or false).
name	The name of the new variable.
label	The label of the new variable.
after	The variable after which this new variable will be placed. Use null to put the variable at the top of your file.
options	Optional. Pass a JavaScript object with any of the following: skipValidation True to skip validation of your JavaScript code. This makes creation of variables much faster, but there is a risk that your new variable will not work. The default is false, so validation is normally performed. accessAllRows See the 'Access all data rows' checkbox in Q. Defaults to false. accelerate See the 'Accelerate (skip logic checks)' checkbox in Q. Defaults to true if the given JavaScript is safe to accelerate. useAllDataFiles See the 'Use variables from all data files' checkbox in Q. Defaults to false.
Returns:	The new Variable object.
Example:	var v = data_file.newJavaScriptVariable("Q1 == 1 ? 0.5 : 1.5", false, "weight", "Weight", null, {skipValidation:true,accelerate:true});

newLogicVariable(source_code, name, label, after)

Create a new Logic variable, as in Q. Get your variable code right in Q before trying it here.

source_code	A fragment of Logic.
name	The name of the new variable.
label	The label of the new variable.
after	The variable after which this new variable will be placed. Use null to put the variable at the top of your file.
Returns:	The new Variable object.
Example:	var v = data_file.newLogicVariable("LikesCoke OR Gender = [Male]", "weight", "Weight", null);

newRQuestion(source_code, question_name, variable_base_name, after, gui_control_code, gui_control_values)

Create a new R question, as in Q. Get your R code right in Q before trying it here.

source_code	A fragment of R code. Use \n to separate lines.
question_name	The name of the new question (must also be a suitable variable name).
variable_base_name	For single variable questions, this is the variable name. For multi-variable questions, the variable name is the base name with an integer suffix to indicate the order of the variable in the question.
after	The variable after which this new question will be placed. Use null to put the question at the top of your file.
gui_control_code	A fragment of Javascript code to generate GUI controls in the object inspector when this question is edited.
gui_control_values	A JavaScript object to set values for GUI controls. It should be in the format {control_name: control_value}.
Returns:	The new Question object.
Example:	var q = data_file.newRQuestion("as.numeric(Q3)+10*as.numeric(Q2)", "question 1", "Q1", null);

newRVariable(source_code, variable_name, variable_label, after, gui_control_code, gui_control_values)

Create a new R variable, as in Q. Get your R code right in Q before trying it here.

source_code	A fragment of R code. Use \n to separate lines.
variable_name	The name of the new variable
variable_label	The label of the new variable
after	The variable after which this new variable will be placed. Use null to put the variable at the top of your file.
gui_control_code	A fragment of Javascript code to generate GUI controls in the object inspector when this variable is edited.
gui_control_values	A JavaScript object to set values for GUI controls. It should be in the format {control_name: control_value}.
Returns:	The new Variable object.
Example:	var q = data_file.newRVariable("as.numeric(Q3)+10*as.numeric(Q2)", "rvar", null, null); // or if you want to give it a dropbox with multiple input guids: let js_code = "form.dropBox({name: 'formInputs', label: 'Inputs', multi: true, types: ['Variable']});"; let multiple_control_values = { 'formInputs': guids.join(";") }; let multi_input_q = data_file.newRVariable("rowSums(QDataFrame(formInputs))", "my_var", "label", null, js_code, multiple_control_values);

publishToDisplayrDriveFileName

When non-null, this tells Displayr to write out this data set to Displayr Drive whenever the document is published (usually using Export). The value of this field will be used as the name of the file in Displayr Drive, and will overwrite any existing file with that name.

questions

Gets an array containing all Question objects in this data file. The first question is [0].

Example:

project.dataFiles[0].questions.forEach(function(q) { if (q.isHidden) log(q.name + ' is hidden'); });

remove()

Removes a data file from a project. Once you have called this method you will not be able to use this DataFile object again.

saveAsSPSSOrCSVFile(path, is_unicode)

Exports the data that Q uses for analysis as an SPSS .sav file or .csv file, where the file type is determined by the file name extension supplied in path. Files with other extensions will be saved in CSV format. All modifications done in Q will be saved (e.g. only recoded values will be saved, changed labels will be saved instead of the originals, etc.).

path	A string specifying the path of the file. You will need to double any back slashes. e.g. 'c:\\Users\\bob\\Cola.sav'
is_unicode	Optional. If true, SPSS files will be in Unicode, which is supported by modern SPSS versions. True by default.

setQuestion(new_name, question_type, variables)

Combines the variables into a single question. The variables will be removed from any questions they are already part of. Afterwards the variables will be together and in the order supplied, in the place of the first variable.

new_name	The name for the new question.
question_type	The type of the new question. This can be one of 'Text', 'Number', 'Pick One', 'Text - Multi', 'Number - Multi', 'Pick Any', 'Pick One - Multi', 'Pick Any - Compact', 'Pick Any - Grid', 'Number - Grid', 'Experiment', 'Ranking', 'Date' (date/time).
variables	An array of Variables, all from this data file.
Returns:	The new Question object.

totalN

Returns the number of cases in this data. This count does not include cases that have been deleted.

type

Returns 'DataFile'.

variables

Gets an array containing all Variable objects in this data file. The first variable is [0].

Example:

project.dataFiles[0].variables.forEach(function(v) { log(v.name + ': ' + v.label); });