QScript DataFile

From Q
Jump to: navigation, search

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_nameThe name for the new question.
blocksEach entry is an array of questions. Within each sub-array, every combination of codes will be produced.
add_sub_netsTrue 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_netTrue 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_spansTrue 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_questionsQuestions to examine in detail, if null a short report will be generated
layoutThe slide layout for the report, supported layouts are "OneTable", "OneChart", "OneTableWithText", "OneChartWithText", "TwoCharts", "TwoTables"
create_results_summaryWhether to create a results summary page, default is false
insert_afterWhere 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
variablesA list of variables to be deleted

equals(obj)

Whether two objects are the same.
objThe 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.
nameQuestion 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_nameThe 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.
nameVariable 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_nameWe 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_moveThe variables to move. This should be an array of Variable objects.
afterThe 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%.
variablesAn 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_codeA fragment of JavaScript. Use \n to separate lines.
is_textWhether the output is a text variable (true or false).
nameThe name of the new variable.
labelThe label of the new variable.
afterThe variable after which this new variable will be placed. Use null to put the variable at the top of your file.
optionsOptional. 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 false. 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_codeA fragment of Logic.
nameThe name of the new variable.
labelThe label of the new variable.
afterThe 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_codeA fragment of R code. Use \n to separate lines.
question_nameThe name of the new question (must also be a suitable variable name).
variable_base_nameFor 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.
afterThe variable after which this new question will be placed. Use null to put the question at the top of your file.
gui_control_codeA fragment of Javascript code to generate GUI controls in the object inspector when this question is edited.
gui_control_valuesA 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_codeA fragment of R code. Use \n to separate lines.
variable_nameThe name of the new variable
variable_labelThe label of the new variable
afterThe variable after which this new variable will be placed. Use null to put the variable at the top of your file.
gui_control_codeA fragment of Javascript code to generate GUI controls in the object inspector when this variable is edited.
gui_control_valuesA 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.).
pathA string specifying the path of the file. You will need to double any back slashes. e.g. 'c:\\Users\\bob\\Cola.sav'
is_unicodeOptional. 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_nameThe name for the new question.
question_typeThe 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).
variablesAn 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);
});