Visualization Control: FilterDataTableControl

  1. Overview
  2. Example
  3. Loading
  4. Data Format
  5. Configuration Options
  6. Methods
  7. Events
  8. Data Policy

Overview

The FilterDataTableControl is a Visualization that acts as a control over other visualizations. It is rendered within the browser using HTML. This visualization offers the ability to select some criteria to filter the DataTable used by the controlled visualizations. Any visualization may be registered with this control, and it fully supports "select" event propagation.

By default the FilterDataTableControl offers a set of simple controls over "string", "number" and "boolean" columns (I refer to these as FilterColumnControls).

The FilterDataTableControl does not provide the ability to filter "date", "datetime" or "timeofday" columns. However it exposes an interface to allow developers to register their own custom FilterColumnControls. You can read our documentation for Customizing Filter Column Controls.

By: Hector Rovira for the Institute for Systems Biology (ISB)
This work was made possible by funding from "The Systems Approach to Immunity and Inflammation Contract" (HHSN272200700038C) from the National Institute of Allergy and Infectious Diseases (NIAID)

Filter Data Table Control Lifecycle

When new filter criteria is selected:
  1. A filtered DataTable is created
  2. The original DataTable is read and every row is evaluated against all active FilterColumnControls
  3. Each row that passes the filter criteria is copied over to the filtered DataTable depending on one of these options
    • All Must Pass - this rule ensures that a row must pass the criteria for all active FilterColumnControls
    • At Least One Must Pass - this rule ensures that a row must pass the criteria for at least one of the active FilterColumnControls
  4. Selection mappings are maintained between the original and filtered DataTables (to support select event propagation with non-controlled visualizations)
  5. Finally, the filtered DataTable is propagated to the registered visualizations

Default Column Filter Controls

Data Type Control Type Visualization Filter Criteria
string Multiple Select Drop-Down Compiles a list of distinct values in the controlled column and visualizes it as a multiple select box The value from the controlled column must match one of the selected values
number Single Select Drop-Down
and Input Text Field		 Displays a selection of simple mathematical comparison operators (Greater Than, Less Than, Equals, etc) and an input text field to capture the value to compare against The value from the controlled column must pass the criteria expressed by the operation in the control
boolean Radio Buttons Offers a true or false choice for the controlled column The value from the controlled column must match the selected choice

Example

Table A: Unfiltered

Table B: Filtered

Table C: Filtered

Line Chart: Filtered

 
<html>
<head>
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">
    google.load("prototype", "1.6.0.2");
    google.load("scriptaculous", "1.8.1");
    google.load("visualization", "1", {packages:["table", "linechart"]});
</script>
<script type="text/javascript" src="http://systemsbiology-visualizations.googlecode.com/svn/trunk/src/main/js/load.js"></script>
<script type="text/javascript">
    systemsbiology.load("visualization", "1.0", {packages:["filterDataTableControl"]});
</script>

<script type="text/javascript">
    function drawVisualizations() {
        var data = new google.visualization.DataTable();
        data.addColumn("string", "Name");
        data.addColumn("number", "Height");
        data.addColumn("number", "Age");
        data.addColumn("boolean", "Girl?");
        data.addRows(4);
        data.setCell(0, 0, "Hector");
        data.setCell(0, 1, 67);
        data.setCell(0, 2, 33);
        data.setCell(0, 3, false);
        data.setCell(1, 0, "Isola");
        data.setCell(1, 1, 30);
        data.setCell(1, 2, 3);
        data.setCell(1, 3, true);
        data.setCell(2, 0, "Mindy");
        data.setCell(2, 1, 64);
        data.setCell(2, 2, 33);
        data.setCell(2, 3, true);
        data.setCell(3, 0, "Jacek");
        data.setCell(3, 1, 25);
        data.setCell(3, 2, 1);
        data.setCell(3, 3, false);

        var tableA = new google.visualization.Table($("table_a_container"));
        var tableB = new google.visualization.Table($("table_b_container"));
        var tableC = new google.visualization.Table($("table_c_container"));
        var linechart = new google.visualization.LineChart($("line_chart_container"));
        var filterControl = new org.systemsbiology.visualization.FilterDataTableControl($("containerFilterControl"));
        filterControl.draw(data, {
            controlledVisualizations: [
            {visualization: tableB, options: {showRowNumber:true}},
            {visualization: tableC, options: {showRowNumber:false, sort: "disable"}},
            {visualization: linechart, options: {width: 400, height: 240, legend: "bottom", title: "Family Stats"}}
                    ],
            columnIndexesToFilter: [0,1,3],
            columnFilterControlConfigByColumnIndex: {
                column_3: { labelForTrue:"Girl", labelForFalse:"Boy"}
            }
            simpleOperatorLabels: {
                gt: "Greater Than",
                ge: "Greater Or Equal To",
                eq: "Equals",
                ne: "Does Not Equal",
                lt: "Less Than",
                le: "Less Than Or Equal To"
            }
        });

        tableA.draw(data,{showRowNumber:false});

        // add listeners
        google.visualization.events.addListener(tableA, "select", function() {
            filterControl.setSelection(tableA.getSelection());
        });
        google.visualization.events.addListener(filterControl, "select", function() {
            tableA.setSelection(filterControl.getSelection());
        });
        google.visualization.events.addListener(tableB, "select", function() {
            tableC.setSelection(tableB.getSelection());
        });
        google.visualization.events.addListener(tableC, "select", function() {
            tableB.setSelection(tableC.getSelection());
        });
    }

    google.setOnLoadCallback(drawVisualizations);
</script>
<style type="text/css">
    div#container {
        margin: 0 auto;
        padding: 2px;
        background: #FFF
    }

    div#containerFilterControl {
        border: 1px solid gray;
    }

    table#visualizationsContainer {
        padding: 3px;
        margin: 1em auto;
        width: 90%;
        border: 1px solid gray;
    }

    h2 {
        font: lighter 150% "Trebuchet MS", Arial sans-serif;
        color: #9E4A24
    }
</style>
</head>
<body>
<div id="container">
    <div id="containerFilterControl">
    </div>

    <table id="visualizationsContainer" border="0" cellpadding="0" cellspacing="10">
        <tr>
            <td width="50%" align="center">
                <h2><span>Table A: Unfiltered</span></h2>

                <div id="table_a_container">
                </div>
            </td>
            <td width="50%" align="center">
                <h2><span>Table B: Filtered</span></h2>

                <div id="table_b_container">
                </div>
            </td>
        </tr>
        <tr>
            <td width="50%" align="center">
                <h2><span>Table C: Filtered</span></h2>

                <div id="table_c_container">
                </div>
            </td>
            <td width="50%" align="center">
                <h2><span>Line Chart: Filtered</span></h2>

                <div id="line_chart_container">
                </div>
            </td>
        </tr>
    </table>
</div>
</body>
</html>

Loading

The systemsbiology.load package name is "filterDataTableControl" 

<script type="text/javascript" src="http://systemsbiology-visualizations.googlecode.com/svn/trunk/src/main/js/load.js"></script>
<script type="text/javascript">
    systemsbiology.load("visualization", "1.0", {packages:["filterDataTableControl"]});
</script>

The visualization control's class name is org.systemsbiology.visualization.FilterDataTableControl 

var filterControl = new org.systemsbiology.visualization.FilterDataTableControl(container);

Data Format

This visualization supports all data formats.

Configuration Options

Name Type Default Description
columnIndexesToFilter Array all columns An array of column indexes corresponding to the original DataTable, indicating the columns that should be filtered. For example: 
columnIndexesToFilter: [0,1,3]
columnFilterControlConfigByColumnIndex Array empty Filter configuration options that can override the visualization of each column's filter. For example: 
columnFilterControlConfigByColumnIndex: {
    column_3: { labelForTrue:"Girl", labelForFalse:"Boy"}
}
controlledEvent string "filtered-select" A label for the event to be published to the controlled visualizations
controlledVisualizations Array empty A list of visualizations and their options. For example: 
controlledVisualizations: [
    {visualization: table2, options: {showRowNumber:true}},
    {visualization: linechart5, options: {legend: "bottom", title: "Family Stats"}}
]
hideFilterContainerOnOpen boolean false Configures the start view of the control. Collapsed if set to true.
labelForAnd string "All Must Pass" Label to show in the control for the "AND" case
labelForOr string "At Least One Must Pass" Label to show in the control for the "OR" case
labelForTitle string "Filters" Title Label open and closes the control
simpleOperatorLabels Object simple labels Labels for the operators in the numeric filter select box. For example: 
simpleOperatorLabels: {
    gt: "Greater Than", ge: "Greater Or Equal To",
    eq: "Equals", ne: "Does Not Equal",
    lt: "Less Than", le: "Less Than Or Equal To"
}

Configuration Options for Default FilterColumnControls

All FilterColumnControls receive an options Object on the draw method, containing these properties:
  • assignedColumnIndex: column index assigned to the control
  • inheritedOptions: options passed to the FilterDataTableControl
These tables show the configuration for each of the default FilterColumnControls provided:

SelectDistinctValuesStringFilterColumnControl

Name Type Default Description
assignedColumnIndex number none Assigned by the FilterDataTableControl during draw method

SimpleOperatorNumberFilterColumnControl

Name Type Default Description
assignedColumnIndex number none Assigned by the FilterDataTableControl during draw method
simpleOperatorLabels Object simple labels Labels for the operators in the numeric filter select box. For example: 
simpleOperatorLabels: {
    gt: "Greater Than", ge: "Greater Or Equal To",
    eq: "Equals", ne: "Does Not Equal",
    lt: "Less Than", le: "Less Than Or Equal To"
}

SimpleChoiceBooleanFilterColumnControl

Name Type Default Description
assignedColumnIndex number none Assigned by the FilterDataTableControl during draw method
columnFilterControlConfigByColumnIndex Object simple true/false labels Accessed from the columnFilterControlConfigByColumnIndex option by assignedColumnIndex.
Provides labels for the radio buttons. For example: 
columnFilterControlConfigByColumnIndex: {
    column_3: { labelForTrue: "Girl", labelForFalse: "Boy" }
}

Methods

Method Return Type Description
draw(data, options) none Draws the control and its controlled visualizations
applyFilter() none Called from the visualization to apply the newly selected filters. Can be called by another object that is modifying the data.
resetFilter() none Propagates to its controlled visualizations the original DataTable without any filters.
getSelection() Array of selection elements Selection elements are all row elements of the original DataTable, mapped from the filtered DataTable. Can return more than one selected row.
setSelection(selection) none Treats every selection entry as a row selection. Supports selection of mutiple rows. Maps the selection to the filteredData and publishes a "filtered-select" event to the controlled visualizations.

Events

Name Description Properties
select Standard select event None
filtered-select Published to controlled visualizations upon receipt of an external select event. None

Note on Event Propagation:

    This control extends org.systemsbiology.visualization.MappedSelectEventPropagation, receiving the following functionality:
  • Listens to controlled visualization "select" events (if any), maps them to original DataTable selections, and publishes its own "select" event
  • On a call to "setSelection", this control will map the given selection object to filtered DataTable selections, and publish a "filtered-select" event to any controlled visualizations that implement "setSelection"

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.