QScript TableOutput

From Q
Jump to: navigation, search

TableOutput

Returns the output of a table's calculations. This includes the row labels, column labels, and statistics.

availableStatistics

Returns a list of statistics that this table is capable of computing. You can check if a statistic is in this list to prevent errors when setting the table's statistics property.

blue

Returns the name of the question in the blue dropdown.

blueQuestion

Returns the Question object selected in the blue dropdown.

brown

Returns the name of the item in the brown dropdown. Either 'RAW DATA', 'SUMMARY', or the name of a question (if a crosstab).

brownQuestion

Returns the Question object selected in the brown dropdown. It may also return the strings 'RAW DATA' or 'SUMMARY', when there is no crosstab.

columnIndex(label)

Returns the index of 'label' in the column labels, or -1 if the 'label' cannot be found. The first column has an index of 0. This cannot be used for one-dimensional tables, because the 'statistics' are shown in columns.
labelThe column label to look for.

columnIndices(include_nets_sums)

Returns the numeric indices of the columns in this table. Use these to iterate over all the columns in a table.
include_nets_sumsWhether to include NET/SUM columns.
Returns:An array of indices. e.g. [0, 1, 2, 3]
Example:
table.columnIndices(false).forEach(function (column) {
    ... do something for each index ...
});

columnLabels

Gets the column heading labels shown for this crosstab. This is not available for one-dimensional tables, because the statistics names are shown as columns for these.
Example:
// If common product misspellings are found, show a pop-up box to let the person know.
var column_labels = table.columnLabels;
for (var i = 0; i < column_labels.length; i++) {
    if (column_labels[i].indexOf('Coca cola') != -1)
        alert('Found "Coca cola" - please fix this in the data and use "Coca-cola" instead!');
}

columnSpans

Returns the list of labels that span the normal column labels. Each entry in the list is an object with two properties: "indices", which is a list of column indices, and "label", which is the label that spans the column. For example, if table has two column spans, one called "Sugary" that spans its first three columns, and "Sugar-free" that spans its next three columns, then columnSpans will return an array with two objects: [{ indices: [0, 1, 2], label: 'Sugary' }, { indices: [3, 4, 5], label: 'Sugar-free' }]. See rowSpans for an example showing how to use a property that is closely related to columnSpans.

decimalPlaces

Returns an object that maps from statistic names to the number of decimal places to show for that statistic.
Example:
log(table.decimalPlaces['Average']);

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])

filters

Gets the filter variables selected for the table. An empty array is returned if there are no filters selected. Note that this property is not valid for TableOutput objects that were created using calculateTable.

get(statistic)

Gets the 'statistic' values for every cell in the table. Returns a two-dimensional array, where the rows are in the first index and the columns in the second index. In one-dimensional SUMMARY tables, a two-dimensional array will still be returned, with only one column in the second dimension. Use the English names of statistics you see in the Q desktop program. If you request a text statistic, the values will be JavaScript String objects. Otherwise for numeric statistics the values will be JavaScript Number types, which are double-precision 64-bit floating point objects - the same as Q uses internally to store and compute statistics.
statisticThe name of the statistic to fetch. See `statistics`.
Example:
// Whenever a table's sample size is so small it's not worth looking at, delete the table.
var items = project.report.subItems;
for (var i = 0; i < items.length; i++)
    if (items[i].type == 'Table') {
        var output = items[i].calculateOutput();
        // If first cell's base n is less than 10...
        if (output.get('Base N')[0][0] < 10)
            // ... delete the table.
            items[i].deleteItem();
    }

numberColumns

Returns the number of columns in the table. On a one-dimensional table, this will return 1, as there is 1 column worth of cell data.

numberRows

Returns the number of rows in the table.

rowIndex(label)

Returns the index of 'label' in the row labels, or -1 if the 'label' cannot be found. The first row has an index of 0.
labelThe row label to look for.

rowIndices(include_nets_sums)

Returns the numeric indices of the rows in this table. Use these to iterate over all the rows in a table.
include_nets_sumsWhether to include NET/SUM rows.
Returns:An array of indices. e.g. [0, 1, 2, 3]
Example:
table.columnIndices(false).forEach(function (column) {
    ... do something for each index ...
});

rowLabels

Gets the row heading labels shown for this table.
Example:
// If common product misspellings are found, show a pop-up box to let the person know.
var row_labels = table.rowLabels;
for (var i = 0; i < row_labels.length; i++) {
    if (row_labels[i].indexOf('Coca cola') != -1)
        alert('Found "Coca cola" - please fix this in the data and use "Coca-cola" instead!');
}

rowSpans

Returns the list of labels that span the normal row labels. Each entry in the list is an object with two properties: "indices", which is a list of row indices, and "label", which is the label that spans the rows. For example, if table has two row spans, one called "Sugary" that spans its first three rows, and "Sugar-free" that spans its next three rows, then rowSpans will return an array with two objects: [{ indices: [0, 1, 2], label: 'Sugary' }, { indices: [3, 4, 5], label: 'Sugar-free' }].
Example:
 // Add a new Average row to every span, that averages
// the statistics of the other rows in that span.

// Get the list of spans.
var spans = table.rowSpans;

// Get the list of statistics on the table.
var statistics = table.statistics;

// Working backwards through the list of spans...
for (var i = spans.length - 1; i >= 0; i--) {
    // Get the current span.
    var span = spans[i];
    
    // Get the rows in this span.
    var rows = span.indices;
    
    // What is the last row in this span?
    var last_row = rows[rows.length - 1];
    
    // Add a new Average row.
    table.insertRowAfter(last_row, 'Average');
    
    // Remember the index of the new Average row.
    var average_row = last_row + 1;
    
    // For each other row in this span, sum its statistics.
    
    // For each column...
    for (var column = 0; column < table.numberColumns; column++) {
        // For each statistic in the table...
        for (var stat = 0; stat < statistics.length; stat++) {
            var values = table.get(statistics[stat]);
            var sum = 0;

            for (var j = 0; j < rows.length; j++) {
                var row = rows[j];
                sum += values[row][column];
            }
        
            // Store the average in the new Average row.
            values[average_row][column] = sum / rows.length;
            
            // Store the values of the Average row into the table.
            table.set(statistics[stat], values);
        }
    }
}

statisticalAssumptions

Returns a QScript StatisticalAssumptions object for the table.
Example:
alert('The overall significance level is:' + table.statisticalAssumptions.overallSignificanceLevel);

statistics

Gets the statistics shown for this table. This uses the English names of statistics you see in the Q desktop program.
Example:
var stats = output.statistics; // stats = ['%', 'n']

type

Returns "TableOutput".

weight

Get the weight variable selected for the table. If no weight is selected then null is returned. Note that this property is not valid for TableOutput objects that were created using calculateTable.