Every Element within the ZENBU-Reports system has a core set of attributes and functions which allows them to interact with each other and with the system in general. These are the title and frame, a common set of widgets and control subpanels, the datasources, the triggers and then the specific visualization of how it is displayed on the page. To configure each element the page editor must bring up the configuration panel of the element.
Frame, Title bar and Widgets
Each element has a containing structure which allows it to be placed on a page and nested within the page-layout system of rows,columns, and tabs. This frame can have a border style and either a fixed width/height or be allowed to auto size. When placed inside a layout structure each element can be either left/right justified if in a column, or top/bottom justified if inside a row.
The titlebar of the frame contains the title and widgets to allow users to interact with additional functionalities. For some elements it might be desired to hide the title bar to create a cleaner looking page. When editing a page the title bar is always displayed to allow the editor to interact with the configuration panel and to drag the element around the page for the desired layout.
The search widget brings up a search panel which allows for searching within the data content of the element. Depending on the element type, it might show only those matching the search or highlight the matches. The search is performed on all metadata associated with the data content of the element. In the example below, we are showing the search panel on a TableElement. The SearchElement is the same interface, except it is an Element always visible on the page, instead of a panel which needs to be brought forward by clicking on the search widget.
The filter widget brings up a filter panel to apply numerical filters to the signal/weight based columns of the data. Users can add or remove signal datatypes to be filtered and set the min and/or max values. The slider not only displays a graphical representation of the filter range, but users can click and drag the bar to set the range. Hovering over the bar also displays the corresponding value for that position.
The columns widget brings up the column / datatypes interface. This allows for reordering the columns, selecting which data columns are to be displayed and to rename the column if desired. This interface affects how the data is displayed within the Element and how the data is displayed in the hover info panel. A column/datatype is defined in the input data files. Column/datatypes can be metadata, chromosome positions, or numerical signals and weights.
The columns are auto-populated based on the datatypes defined from the input file databases as defined in the Datasources configuration of the Element. Selecting the checkbox next to a column will display that data in the element and within the "hover info" if activated. A yellow background on a column indicates that it is numerical signal/weight data and can be numerically filtered with a FilterElement or with filter subpanel. Clicking on a column will bring up the detail information on that column. Within the column detail panel you can
- see the original dataype as inputed from the file (in the example it is Chr_cpm)
- see the class of the datatype. In this case it is a "signal" class
- rename the column. Here it is renamed to "Chromatin cpm"
- change the column order: enter a new column position and press <enter>. a negative value will move the column to the end of active columns. You can only reorder active columns. The deactivated columns are always in alphabetical order.
- highlight color: allows for different background colors on cells in certain Elements like the TableElement when a data row is selected.
- column user modifiable: enabling this allows users of the page to access the column details, and hide or show these additional columns.
The download widget brings up the download interface panel. This allows for export of the data from the element. The interface is very simple and allows the user to choose between exporting all column-datatypes or only those defined as visible. After clicking the download button the user will be presented with a file selector panel to choose the file location.
The gear icon brings up the configuration panel. This is only available when editing a page. The configuration panel has common sections for the Title/Frame, Datasource, and Triggers, but the visualization section is different depending on the class of Element that is being configured.
Every element in the ZENBU Reports system uses the same internal data structures for managing the data objects of the element. These are the same data objects as used within the ZENBU Genome Browser and uses the same ZENBU data upload and web-service query system. For ZENBU Reports the server side data management system was expanded with additional data types and queries, in particular the OSCtable format was expanded to include edge files which can be used in the CytoscapeElement, the CircosPlotElement or any other element where complex dependent relationship queries are needed.
When first configuring an element, the datasource interface is expanded to show all the controls. The datasource for an element can either be shared from another element or it can queried from the uploaded in the ZENBU system. To connect to an uploaded datasource, the user will need to search the system for the appropriate previously uploaded data files. The collaboration filter can help refine the search by only searching within a specific collaboration. Type in some keywords either from the uploaded file name or in the description you entered when uploading the file. In the example below I searched for "hic lnrana ref genes" and found two versions I have uploaded. If you forgot how you named your files, you can also push the show my uploads to show all of the files you have personally uploaded into your account. After you find the file(s) you want to use, click the checkbox next to it. If you want to merge multiple files with the same data columns, you can select multiple files from the interface (for example multiple BAM files).
After the configuration is applied, the datasource interface is compacted to just show the type of data that is being loaded. If the datasources need to be updated or changed, clicking the edit button will expose the full interface.
Triggers allow for cascaded behavior within a page and between elements. One can think of a trigger like a reaction to something. For example if a user clicks on something to select it, that user event trigger can then be cascaded to do something like apply a filter and cause another element on the page to reload. In addition to user triggers there are also system triggers, for example a trigger can happen after an element finishes loading.
For example on the ZENBU Reports page FANTOM6_HiC_comparative_analysis The table at the top of the page lists all reference lncRNA genes in the study. Triggers have been setup so that when a user selects a lncRNA gene, it will trigger filtered-focus-loads on 4 different Heatmap Elements on the page by sending the selection as the focus-filter and then performing a load.
each trigger has 4 primary parts
- on : this is what causes the trigger. The available user event trigger options here are: select, select-location, hyperlink, and filter_change. The system trigger options are reset, preload, load, and postprocess.
- trigger target : this is the element on the page which will receive the triggered event. Every element on a ZENBU Reports page has its own unique ID. This ID can be seen at the top of the configuration panel of each element on the page.
- action : this is the action that the receiving element is supposed to do once it receives the trigger. The options are: select, select_location, search_filter, set_focus, focus_load, set_filter_features, set_load_filter, reset, load, postprocess.
- send : this defines what extra data is to be sent along with the trigger. depending on the action selected, this will change or might not be shown.
The configuration of the visualization is different for each element type. Please see the documentation for each element type for full details on how to configure the visualization.
For example the TableElement has only a few visualization configuration option, while a HeatMapElement has a much more complex visualization configuration section.