QScript DataFile
Jump to navigation
Jump to 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_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);
});
|