QScript Functions to Generate Outputs
The functions below are designed to assist the QScript communicate to the user of the regarding changes that have been made by the QScript. The main ways of reporting on changes are to use logs, which will be shown in the box that appears at the completion of the QScript, and to add groups of tables for the questions that have been changed.
To make these functions available when writing a QScript or Rule see JavaScript Reference.
generateGroupOfSummaryTables(group_name, question_array)
This function generates a new group in the report tree with the name specified by group_name that contains a summary table for each question in the question_array. It returns the new group object.
generateSubgroupOfSummaryTables(group_name, within_group, question_array)
This function generates a new group in the input group within_group with the name specified by group_name that contains a summary table for each question in the question_array. It returns the new group object. generateSubgroupOfSummaryTables
generateGroupOfSummaryPlots(group_name, question_array)
This function generates a new group in the report tree with the name specified by group_name that contains a summary plot for each question in the question_array. It returns the new group object.
logQuestionList(message, question_array)
This function creates a new log entry that begins with the input message and then a list of the names of the questions in question_array, where each is given a new line. Logs are displayed once the script has finished running.
simpleHTMLReport(paragraphs, title, group, set_focus, web_mode)
Generates a Text item in the report group group with the elements of paragraphs as content, and the specified title. paragraphs should be an array of strings. Each string will be added as a separate line. If you want this new report to be selected in the Report tree at the conclusion of the script supply set_focus as true.
conditionallyEmptyLog(message)
If the Q version is such that we can avoid displaying blank logs then do nothing, otherwise log the message.
makeWordList(words)
Takes an array of variable names (strings) as input and returns a formatted string of the names in a comma separated list.
insertGroupAtHoverButtonIfUsed
Given a QScript ReportGroup, i.e. a page or folder in the Displayr Report Tree, this function will move the provided group to the current position of the Page Hover Button in Displayr, or do nothing if the calling script was not executed via that button.
layoutOutputsOnPage
Given an array of outputs and a page/ReportGroup in Displayr, this function adds the outputs to the page in a grid ensuring there are no overlaps between any of the outputs and the page title, if one is present.
distributeOutputsHorizontally
This is a helper function for layoutOutputsOnPage, it converts arrays of output positions from being left-justified to horizontally-centred, returning and array of modified left positions that can be assigned to the outputs to horizontally centre them on the page (i.e. so that the left and right margins of the page are equal).
createReport
Adds a new report QScript ReportGroup containing crosstabs for a given set of primary and secondary variable sets. The first argument outputs should be an array of objects which are pairs {primary, secondary}, where primary is always a QScript Question object, and secondary can be a question object, or "SUMMARY" or "RAW DATA". The second argument, names should be an array of the names of pages which go with each of the outputs. The argument statistics should be an array containing strings that correspond to the names of the statistics which should be added to the pages. There are additional arguments weight, filters, and as_plot for supplying an optional weight variable to apply to all tables, an optional array of filter variables to apply to all tables, and a true/false value controlling whether to create small multiples bar charts instead of tables for each output, respectively.
addCrosstab
This is a helper function for createReport that adds a page to a provided QScript ReportGroup containing a crosstab (QScript Table) for a given set of primary and secondary variable sets. The first argument parent is the QScript ReportGroup to append the new page to. The second argument, variable_sets, is a single element from the outputs argument documented above for createReport. The third argument should be the string to use for the page name. The remaining arguments are the same as for createReport. The function returns parent with the new page added.
createGroupAtHoverOrBelowCurrentGroup
Creates a new report group at the position of the page hover button, if it was used to execute the script, or below the current page in the Report Tree. The single argument page_name should be a string specifying the name to assign the created group. The function returns the created QScript ReportGroup.
Source Code
/*----------------------------------------------------------------------------------------------------------*/
/*--- ---*/
/*--- enums ---*/
/*--- ---*/
/*----------------------------------------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------------------------------------*/
var InvalidVariableSet;
(function (InvalidVariableSet) {
InvalidVariableSet["ALL_MISSING"] = "ALL_MISSING";
InvalidVariableSet["HIDDEN"] = "HIDDEN";
InvalidVariableSet["BROKEN"] = "Broken";
InvalidVariableSet["BANNER"] = "BANNER"; // A banner variable set - they are always user-created so we skip them entirely
})(InvalidVariableSet || (InvalidVariableSet = {}));
var VariableSetType;
(function (VariableSetType) {
VariableSetType[VariableSetType["ID"] = 1] = "ID";
VariableSetType[VariableSetType["STIMULUS_ID"] = 2] = "STIMULUS_ID";
VariableSetType[VariableSetType["SURVEY_START"] = 3] = "SURVEY_START";
VariableSetType[VariableSetType["SURVEY_END"] = 4] = "SURVEY_END";
VariableSetType[VariableSetType["SURVEY_DURATION"] = 5] = "SURVEY_DURATION";
VariableSetType[VariableSetType["DATE_TIME"] = 6] = "DATE_TIME";
VariableSetType[VariableSetType["DEMOGRAPHICS"] = 7] = "DEMOGRAPHICS";
VariableSetType[VariableSetType["FIRMOGRAPHICS"] = 8] = "FIRMOGRAPHICS";
VariableSetType[VariableSetType["AMOUNTS"] = 9] = "AMOUNTS";
VariableSetType[VariableSetType["CONSTANT_SUM"] = 10] = "CONSTANT_SUM";
VariableSetType[VariableSetType["RATING_SCALE"] = 11] = "RATING_SCALE";
VariableSetType[VariableSetType["RANKINGS"] = 12] = "RANKINGS";
VariableSetType[VariableSetType["OPEN_ENDED"] = 13] = "OPEN_ENDED";
VariableSetType[VariableSetType["OTHER_SPECIFY"] = 14] = "OTHER_SPECIFY";
VariableSetType[VariableSetType["BRAND_ASSOCIATIONS"] = 15] = "BRAND_ASSOCIATIONS";
VariableSetType[VariableSetType["LIKELIHOOD_TO_RECOMMEND"] = 16] = "LIKELIHOOD_TO_RECOMMEND";
VariableSetType[VariableSetType["WEIGHT"] = 17] = "WEIGHT";
VariableSetType[VariableSetType["DATA_QUALITY"] = 18] = "DATA_QUALITY";
/** Given code of 99 so don't need to revise when adding new levels.
* Please update the prompt accordingly. */
VariableSetType[VariableSetType["INVALID"] = 98] = "INVALID";
VariableSetType[VariableSetType["OTHER"] = 99] = "OTHER";
})(VariableSetType || (VariableSetType = {}));
var LabelType;
(function (LabelType) {
LabelType[LabelType["DK"] = 1] = "DK";
LabelType[LabelType["Refused"] = 2] = "Refused";
LabelType[LabelType["NA"] = 3] = "NA";
LabelType[LabelType["Missing"] = 4] = "Missing";
LabelType[LabelType["SurveyStatus"] = 5] = "SurveyStatus";
LabelType[LabelType["Numeric"] = 6] = "Numeric";
LabelType[LabelType["NumericWithPrefixOrSuffix"] = 7] = "NumericWithPrefixOrSuffix";
LabelType[LabelType["QuantityInWords"] = 8] = "QuantityInWords";
LabelType[LabelType["NumericDelimited"] = 9] = "NumericDelimited";
LabelType[LabelType["Intensity"] = 10] = "Intensity";
LabelType[LabelType["IntensityDelimited"] = 11] = "IntensityDelimited";
LabelType[LabelType["OtherOptionsDelimited"] = 12] = "OtherOptionsDelimited";
LabelType[LabelType["DateTime"] = 13] = "DateTime";
LabelType[LabelType["Geography"] = 14] = "Geography";
LabelType[LabelType["Brand"] = 15] = "Brand";
LabelType[LabelType["Person"] = 16] = "Person";
LabelType[LabelType["Entity"] = 17] = "Entity";
LabelType[LabelType["Property"] = 18] = "Property";
LabelType[LabelType["BinaryResponse"] = 19] = "BinaryResponse";
LabelType[LabelType["Other"] = 99] = "Other";
})(LabelType || (LabelType = {}));
const MISSING_DATA_LABEL_TYPES = [LabelType.DK, LabelType.NA, LabelType.Refused, LabelType.Missing];
const ORDINALITY = Object.freeze({
ASCENDING: 1,
DESCENDING: -1,
NONE: 0,
});
// Identifies all the possible crosstabs that can be created from the data.
function isCrosstableWithText(vs) {
return ["Nominal", "Ordinal", "Date/Time", "Binary - Multi", "Binary - Multi (Compact)"].includes(vs.variableSetStructure);
}
function isMultipleVariableSet(vs) {
return ["Text - Multi", "Nominal - Multi", "Ordinal - Multi", "Binary - Multi", "Binary - Multi (Compact)", "Numeric - Multi", "Experiment", "Ranking", "Binary - Grid", "Numeric - Grid"].includes(vs.variableSetStructure);
}
function isNominalOrOrdinalMulti(vs) {
return ["Nominal - Multi", "Ordinal - Multi"].includes(vs.variableSetStructure);
}
function isOrdinal(vs) {
return ["Ordinal", "Ordinal - Multi"].includes(vs.variableSetStructure);
}
function isOrdinalScale(vs) {
return ["Ordinal", "Ordinal - Multi", "Date/Time"].includes(vs.variableSetStructure);
}
function is2D(vs) {
return ["Binary - Grid", "Numeric - Grid", "Nominal - Multi", "Ordinal - Multi"].includes(vs.variableSetStructure);
}
function isRanking(vs) {
return vs.variableSetStructure === "Ranking";
}
const CATEGORICAL_TYPES = ['Categorical', 'Ordered Categorical']; // only these two "categorical" types carry value-attributes
function isCategoricalType(variable_type) {
return CATEGORICAL_TYPES.includes(variable_type);
}