QScript Table
Jump to navigation
Jump to search
Table
A table or crosstab. Assign Question objects to primary and (optionally) secondary. Can also show raw data.
applyTemplate(template_file)
Updates the appearance of a plot using a template file. Template files are created manually from within Q.
| template_file | The path to a Q template 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. If you change a table to a plot then the Table object you used to have will stop working. Instead use the object returned by this method. |
| Returns: | The (perhaps new) Plot object. |
| Example: | var plot = table.applyTemplate('Snake.QTemplate');
|
calculateOutput()
Calculates the table/crosstab and returns a TableOutput object, which you can interrogate for its row labels, column labels, and statistical values.
| Example: | // Change the name of the table to include the category which has the lowest (most significant) p-value.
// Calculate the statistics.
var output = table.calculateOutput();
// Get the array of p-values.
var pvalues = output.get('p');
// Keep track of which row contains the lowest p-value.
var lowest_p;
var lowest_row;
for (var row = 0; row < output.numberRows; row++)
for (var column = 0; column < output.numberColumns; column++) {
var p = pvalues[row][column];
if (row == 0 && column == 0) {
lowest_p = p;
lowest_row = row;
} else {
if (p < lowest_p) {
lowest_p = p;
lowest_row = row;
}
}
}
// Now 'lowest_row' holds the number of the row with the lowest p value.
// Lets extract its label from the output.
var lowest_row_label = output.rowLabels[lowest_row];
// Change the name of the table to include the lowest row information.
table.name = table.name + ' (Most significant: ' + lowest_row_label + ', p = ' + lowest_p + ')';
|
cellStatistics
Gets/sets the statistics shown in cells for this table. Unknown statistics, or those not valid for this table/crosstab, will be ignored. Use the English names of statistics you see in the Q desktop program.
| Example: | table.cellStatistics = ['%', 'n']
|
changeDecimalPlacesBy(delta)
Increases or decreases the number of decimal places shown in the table or plot. This is equivalent to pressing the buttons in the toolbar to increase or decrease the number of decimal places shown.
| delta | The change in the number of decimal places shown. |
| Example: | table.changeDecimalPlacesBy(3);
|
columnStatistics
Gets/sets the statistics shown at the bottom of each row. Unknown statistics, or those not valid for this table/crosstab, will be ignored. Use the English names of statistics you see in the Q desktop program.
| Example: | table.columnStatistics = ['Column n']
|
deleteItem()
Deletes a table, plot or sub-group.
dependants(recursive)
Returns an array containing the variables, questions, tables, R items, or other items that are used when calculating this object. A Table object will return an array containing the questions it is a crosstab for, and any variables used as filters or weights. An ROutput object will return other ROutput objects used in its calculations. A JavaScript Variable object will return the variables referenced in its formula, etc.
| recursive | Optional. If true then it will return all the objects that are normally returned, as well as all objects that those objects depend on, and so on. |
| Returns: | Returns an array containing Question objects, Variable objects and AnalysisItem objects. |
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,
});
|
filters
Get/sets the list of Variable objects to apply as filters for this analysis item. This only includes filters added to the object in Q. To get filters added in Displayr, see 'groupedFilters'
| Example: | t.filters = [data_file.getVariableByName('awarenessCoke')];
|
| Example: | t.filters = [];
|
getDecimalPlaceFor(statistic)
Gets the number of decimal places shown in the table or plot for the specified statistic.
| statistic | The statistic name in English. |
| Example: | getDecimalPlacesFor("Average");
|
group
Get the ReportGroup object that contains this table/plot/group, or null if the sub item of an item.
groupedFilters
Get/sets the list of Variable objects to apply as filters for this analysis item. This only includes filters added to the object in Displayr. To get filters added in Q, see 'filters'
| Example: | t.groupedFilters = [data_file.getVariableByName('awarenessCoke')];
|
| Example: | t.groupedFilters = [];
|
guid
Get the internal identifier for this object, which is unique for all objects in the Report.
height
Gets/sets the height of the item 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;
|
left
Gets/sets the left position (i.e. X position) of the item in pixels
name
Get/set the name for this object, as it appears in the Report.
primary
Gets/sets the main Question object to plot/tabulate.
referenceName
Get/set the reference name for this object, that is used to reference this object in the source code of other objects.
rowStatistics
Gets/sets the statistics shown to the right of each row. Unknown statistics, or those not valid for this table/crosstab, will be ignored. Use the English names of statistics you see in the Q desktop program.
| Example: | table.rowStatistics = ['Row Population']
|
rules
Provides an object you can use to add or remove Rules from a table or plot.
| Example: | table.rules.add(f);
|
secondary
setDecimalPlaceFor(statistic, place)
Sets the number of decimal places shown in the table or plot for the specified statistic.
| statistic | The statistic name in English. |
| place | The number of decimal places, which has to be an integer from 0 to 13. |
| Example: | setDecimalPlaceFor("Average", 1);
|
showCaption
Gets/sets whether to show the caption for this item. This setting is only useful in Displayr and where a caption is available.
| Example: | plot.showCaption = true
|
showPercentSign
Gets/sets whether to show the percent sign next to percentages in the table or plot. Changing this property is equivalent to toggling the percent sign button in the toolbar.
| Example: | table.showPercentSign = false; // percent signs will not be shown next to percentages in table.
|
size
Gets/sets the size (in mm) for this item, presented as an array containing two elements: width and height.
| Example: | item.size = [100, 100];
|
subItems
Returns an array of the items under this object. Check their type to find out if they are tables, plots or sub-groups.
switchTo(item_type)
Switch the current item to a new type e.g. chart to table. NB: only transitions from Tables, Charts and Visualizations are supported
| item_type | The name of the item to switch to. This should match 'Table' or the title of its wiki page |
tableJavaScript
No longer supported.
top
Gets/sets the top position (i.e. Y position) of the item in pixels
translations
Gets the Translations object for this item, allowing you to override the names used for (for example) statistics, NET, SUM, etc.
| Example: | log(item.translations.get('Column n'));
|
type
Returns "Table".
weight
Gets/sets the Variable object to be used as a weight for this table/plot. Assign null to remove any weight previously applied.
| Example: | t.weight = project.dataFiles[0].getVariableByName('weight');
|
| Example: | t.weight = null;
|
width
Gets/sets the width of the item in pixels