QScript ReportGroup
Jump to navigation
Jump to search
ReportGroup
A group in the project's Report tree, or the root of the report tree itself. Obtain the root of the report tree using project.report. Use these to add tables and plots.
appendCalculationGrid()
Creates a new CalculationGrid object in the report tree.
| Returns: | The new CalculationGrid object. |
| Example: | var mat = project.report.appendCalculationGrid();
|
appendControl(type)
Creates a new control
| type | Type of control. Valid values are "Combobox", "Listbox", "Textbox", and "Date". |
| Returns: | The new control |
| Example: | var parent = project.report.appendGroup();
parent.name = "Parent";
var control = parent.appendControl("Combobox");
|
appendFolder()
Creates a new Displayr folder. In general you should assign its name immediately after creating it.
| Example: | var folder = project.report.appendFolder();
|
appendGroup()
Creates a new sub-group. In general you should assign its name immediately after creating it.
| Returns: | The new ReportGroup object. |
| Example: | var parent = project.report.appendGroup();
parent.name = "Parent";
var child = parent.appendGroup();
child.name = "Child";
|
appendImage(image_path)
Creates a new image in the report tree.
| image_path | The path to an image file. This must be a BMP, GIF, EXIG, JPG, PNG or TIFF file. If this is a relative path then it is relative to the running script's directory. If you are running the script on Displayr then this should be the ID returned by /API/Upload after you uploaded a template file. |
| Returns: | The new Image object. |
| Example: | project.report.appendImage("Q Blue Logo.png");
|
appendPage(master_slide_name)
Creates a new Displayr page. In general you should assign its name immediately after creating it.
| master_slide_name | The name of the master slide for the new page. Options provided for backwards compatibility are: Item, ItemAndText, TwoItems, TitleOnly, Blank |
| Example: | var page = project.report.appendPage('Title');
|
appendPlot(plot_type, questions)
Creates a new plot.
| plot_type | A string containing the name of the type of plot you want. e.g. 'Bar/column/line plot'. See the names that appear when you hover your mouse over the plot options in Q. |
| questions | An array of Question objects that will be used as the inputs for the new plot. |
| Returns: | The new Plot object. |
| Example: | project.report.appendPlot("Bar/column/line plot", [project.dataFiles[0].getQuestionByName("Age")]);
|
appendPlotAutomatic(questions)
Creates a new plot to show the questions passed in. The plot type used is whatever is judged best for the combination of questions passed in. If no plot is able to use the provided questions then a table may be created instead.
| questions | An array of Question objects. |
| Returns: | A Plot object or a Table object. |
| Example: | var q1 = project.dataFiles[0].getQuestionByName("Q1");
var q2 = project.dataFiles[0].getQuestionByName("Q2");
project.report.appendPlotAutomatic([q1, q2]);
|
appendR(code)
Creates a new ROutput object in the report tree.
| code | R source code. |
| Returns: | The new ROutput object. |
| Example: | var mat = project.report.appendR("matrix(1:12, 3, 4)");
log(mat.data);
|
appendStandardR(library_title, parameters)
Creates a new standard R item from a wiki page in the report.
| library_title | The title of a wiki page containing the standard R item |
| parameters | A Json dictionary of control names and their desired pre-filled value |
| Returns: | The created R item |
| Example: | // creates a bar chart and adds the selected var as input.
var selected = project.report.selectedVariables()[0];
var item = project.report.subItems[0].appendStandardR("Visualization - Bar Chart", {"formX": selected.guid});
|
appendTable()
Creates a new table. You must assign questions to the table before it will be useful.
| Returns: | The new Table object. |
| Example: | var t = project.report.appendTable();
t.primary = project.dataFiles[0].getQuestionByName("Gender");
|
appendText()
Creates a new text item in the report tree.
| Returns: | The new Text object. |
| Example: | var text = project.report.appendText();
log(text.htmlFragment);
|
appendVisualization(library_title, parameters)
Creates a new standard R item or built in chart from a wiki page in the report.
| library_title | The title of a wiki page containing the visualization |
| parameters | For R Items: A Json dictionary of control names and their desired pre-filled value, For Ngviz: A Json serialized element tree of settings, For everything else: Ignored |
| Returns: | The created visualization |
| Example: | // creates a bar chart and adds the selected var as input.
var selected = project.report.selectedVariables()[0];
var item = project.report.subItems[0].appendVisualization("Visualization - Bar Chart", {"formX": selected.guid});
|
copyAfter(item, after)
Copies a table, plot or sub-group from its current position, to just after after.
| item | The item to be copied. |
| after | The child of this group after which it should be added. null will cause it to be copied to the top of its group. |
| Returns: | The new item. |
deleteItem()
Deletes a table, plot or sub-group.
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])
|
exportToExcel(filename, options)
Exports an item or group to Excel. This method is currently only available in desktop Q.
| filename | The name of the exported file. |
| options | An optional dictionary of options to pass to the function. These map to the settings in the Table Options dialog when exporting in Q using the fast Excel export option: table_style: The name of an Excel-based table style to use for the export. See the dropdown in the Q Excel export dialog for names - remove the spaces when used here. notes: Text that appears as a comment in the first cell of every sheet. hyperlink: A link applied if the project is uploaded as a Dashboard. ignore_net_and_sum: Excludes the NET and SUM columns or rows from the exported table. export_tables_as: When exporting multiple tables, how they should be laid out: - OneWorksheetPerTable: each table is placed on a new worksheet. - OneWorksheetPerPage: tables in the same group are placed on the same worksheet. - OneWorksheet: all tables are placed on a single worksheet. how_count: For multiple tables on the same worksheet, how they should be spaced: - BetweenTops: use a fixed number of rows between the tops of tables. - FromBottomOfOneToTopOfNext: leave a number of rows between the bottom of one table and the top of the next. num_rows_between_tables: The number of rows used by how_count include_table_of_contents: Whether to include a table of contents perform_statistical_test_of_independence: Whether to perform a statistical test of independence for the entire table (NB: this is in addition to the tests automatically shown on tables). repeat_headings: Whether to repeat headings for each table. show_significance_arrows: Whether to include significance arrows (when shown in table). table_names_sequential: Whether to name tables sequentially (e.g. Table 1, Table 2, etc.). show_column_comparisons_in_separate_row: Whether to show column comparisons in a separate row. |
| Example: | project.report.exportToExcel('output.xlsx');
|
| Example: | project.report.exportToExcel('output.xlsx', {
table_style: 'TableStyleLight1',
notes: 'Notes',
include_table_of_contents: true,
});
|
group
Get the ReportGroup object that contains this table/plot/group, or null if the sub item of an item.
guid
Get the internal identifier for this object, which is unique for all objects in the Report.
height
Gets the height of the page in pixels
Gets/sets whether this item is hidden from exported views in Displayr. If an item is hidden from exported views, then when you share or export the project, the item will not appear in the shared page or exported document. This is typically used if you are using Calculations for intermediate steps in calculating values, and these steps would be irrelevant or confusing for the person viewing the page.
| Example: | routput1.hiddenFromExportedViews = true;
|
moveAfter(item, after)
Moves a table, plot or sub-group from its current position, to just after after.
| item | The item to be moved. |
| after | The child of this group after which it should be added. null will cause it to move to the top of its group. |
name
Get/set the name for this object, as it appears in the Report.
parentGroup(fallback_to_root)
Returns the parent group of this group.
| fallback_to_root | If current group is a root: FALSE returns NULL, TRUE returns current group |
| Returns: | The ReportGroup object. |
| Example: | var group;
if (project.currentPage()) {
var parent = project.currentPage().parentGroup();
group = parent.appendGroup();
parent.moveAfter(group, project.currentPage());
} else
group = project.report.appendGroup();
|
referenceName
Get/set the reference name for this object, that is used to reference this object in the source code of other objects.
selectedDataSets()
Returns the DataFile objects that are selected in Q/Displayr. Q: If the Variables and Questions or Data tab is being viewed, then that data set will be returned. On the Tables tab, the data sets used by the selected analyses wil be returned. Displayr: As selected in the Data tree (else the Report tree).
| Returns: | An array of DataFile objects. |
selectedItems()
Returns all normal analysis items (tables, plots, etc., but not their groups) that are selected, or implicitly selected because a parent group is selected.
| Returns: | An array of tables, plots, etc. (but not groups) in report tree order. |
| Example: | project.report.selectedItems().forEach(function (item) {
item.showPercentSign = false;
});
|
selectedQuestions()
Returns the Question objects that are selected in Q/Displayr. If the Variables and Questions tab is being viewed, the distinct questions representing the selected rows are returned. On the Data tab, the distinct questions of the selected columns are returned. On the Tables tab, the distinct questions in the dropdowns of the selected items are returned.
| Returns: | An array of Question objects. |
selectedRaw()
Returns all items selected by the user underneath this, including itself. It will not implicitly include any items underneath selected items (for that see selectedItems()).
| Returns: | An array of items, which may include groups, in report tree order. |
| Example: | project.report.selectedRaw().forEach(function (item) {
log(item.name + ' is selected');
});
|
| Example: | // Tests whether a specific item (itemToTest) is selected.
if (project.report.selectedRaw().filter(function (s) {
return s.equals(itemToTest);
}).length) {
log(itemToTest.name + ' is selected');
}
|
selectedVariables()
Returns the Variable objects that are selected in Q/Displayr. Q: If the Variables and Questions or Data tab is being viewed, then that data set will be returned. On the Tables tab, the distinct variables of the questions in the dropdowns of the selected items are returned. Displayr: As selected in the Data tree.
| Returns: | An array of Variable objects. |
setSelectedRaw(items)
Set the items to be selected after the script has finished running. Note that this function can only be called from the root of the report tree, i.e., project.report.
| items | An array of items, which may include groups. |
| Example: | project.report.setSelectedRaw([project.report.subItems[1]]); // select 2nd item in report tree
|
subItems
Returns an array of the items under this object. Check their type to find out if they are tables, plots or sub-groups.
type
Returns "ReportGroup".
width
Gets the width of the page in pixels