Dataset Editor Dialog
In the Figure Composer application, the Property Editor panels for the five supported data presentation nodes (trace, raster, heatmap, bar, scatter) each include a small section labelled Data. Here you'll find a text field for changing the identifier of the data set associated with the presentation node, along with three pushbuttons. The Load button lets you load the data set from a source file that Figure Composer recognizes, while the Export button lets you save the current data set to a file. The Edit button raises a modeless tool dialog -- the Dataset Editor -- by which you can view and modify the actual data set. A screenshot of this dialog is displayed below. The dialog title includes the title of the presentation node container for the data set edited (if the node lacks a title, the node type is used instead -- as in the screenshot). Along the top are controls for changing the data set's identifier, format, and any additional parameters associated with the data set (varies with the format). The format combo box lists all dataset formats that can be rendered by the presentation node. It is enabled only if the presentation node supports more than one data format. In the bottom-right corner of the dialog are three pushbuttons:
Update: This button is enabled only once you've made some changes to the data set within the dialog. When you click the button, the data presentation node is updated with the new data set. Observe that the figure on display is updated accordingly. The dialog remains up, and the button is once again disabled until you make further changes to the data.
Start Over: If you've made some changes to the data set and have not yet pressed Update, click this button to restore the data set to its state on the last "update". This may be helpful if you've made a mistake modifying the the data and would like to start from scratch.
Cancel: Press this button to discard any changes you've made since the last "update" and hide the dialog. Clicking the dialog's "close" button has the same effect.
New in 4.7.0: Modeless behavior
The Dataset Editor Dialog was significantly revamped in version 4.7.0. The preview canvas was removed to make it more compact, and it now behaves appropriately when resized. But, most importantly, it was converted from a modal blocking dialog to a modeless tool dialog.
This means that you can keep the dialog up while you do other work on the figure in the main application window. For example, you might need to edit the data for several different traces in the figure in sequence. As you select each trace, the dialog is automatically reloaded to display the data set for that trace. If you've made some changes to the data set that was previously displayed and forgot to Update it, the data set is automatically updated prior to loading the new data set. The only time changes are discarded is when you explicitly close the dialog via the "close" button or Cancel.
If the dialog is raised and you select a graphic object that is not a data presentation node, the dialog is automatically hidden, but it will reappear when you select another presentation node. However, if you explicitly close the dialog with the "close" or Cancel button, it will not reappear until you explicitly request it -- by pressing the Edit button in the Property Editor for the selected trace, raster, heatmap, bar or scatter plot.
The data set's underlying raw data is presented in one of two alternative views, a tabular view and a text view. The pushbutton in the bottom-left corner lets you switch between the two views. Prior to version 3.1.3, only the text view (not shown) was available. It is quite simple to use. The data is presented in text form, one datum tuple per text line, in a simple editable text pane. Individual data in a tuple are separated by space characters, and each datum is parsed as a floating-point number (NaN is a legal value). The length of each tuple varies with the data set format; see Loading Data for a brief summary of the supported data set formats. To edit the data in the text view, simply enter the data, cut/copy portions of the text, and paste in text from an external application. Once you've made a change, you must confirm the changes by pressing the Apply button. The current contents of the text pane are parsed and the data set's raw data is replaced accordingly; if parsing fails, an error dialog will explain what went wrong. Press the Revert button to restore the contents of the text pane to reflect the current valid state of the raw data.
The text view may be convenient for creating or editing small data sets, but it is unsuitable for large ones. The tabular view was introduced in Figure Composer v3.1.2 (and improved in v3.1.3) to address deficiencies in the text view -- particularly its very inefficient use of system memory. [In fact, the text view is now disabled when the data size reaches ~50000 elements, or ~250000 characters when converted to text form. In older versions of Figure Composer, attempting to load a 600x600 xyzimg data set into the text view would exhaust system memory!] Once you get the hang of it, you will find that you can do everything in the tabular view that you could do in the text view, and perhaps with greater ease. You can cut, copy, delete, and paste entire rows, entire columns, or blocks of data selected in the table. You can still paste in data copied from an external application. Under the hood, the clipboard text is parsed into floating-point data, which is then pasted into the data table. If parsing fails, no action is taken, and you'll hear a "beep" out of the computer. Two versions of the paste operation are supported, the standard "replace paste" (in which the current selection is replaced) and an "insert paste" (the clipboard data is inserted before the first row or column of the current selection). All of the actions are available via keyboard shortcuts (when the keyboard focus is on the table) or by pressing one of the buttons in the horizontal toolbar along the top edge of the data table.
The exact action taken when you copy, cut, or paste depends upon the data set format, the "shape" of the current selection, and -- for paste operations -- the shape of the clipboard data chunk. Consider pasting into a non-raster-type data set (raw data matrix is rectangular). If the current selection spans the table column-wise but not row-wise, the clipboard data replaces the selected rows (or is inserted before the first selected row in the case of an "insert paste") and is truncated or padded column-wise (with NaN) to match the number of columns in the data set. The number of rows added is the number of rows in the clipboard data chunk. However, if the selection spans the table row-wise but not column-wise, then the clipboard data replaces the selected columns (or is inserted before the first selected column) and is truncated or padded row-wise to match the number of rows in the dataset. The number of columns added is the number of columns in the clipboard data -- unless that would violate the breadth restrictions of the data set format (e.g., a ptset can only have 2-6 columns), in which case the clipboard data must also be truncated or padded column-wise. Finally, if the current selection is a block spanning neither the table's width nor height, then the clipboard data replaces the selected block, truncated or padded both row-wise and column-wise to match the dimensions of the selected block (in the case of an "insert paste", all clipboard data rows are inserted before the first selected row, truncated or padded column-wise).
When the displayed data set format is raster1d, additional restrictions apply. Each row in the data table represents a single raster, each of which will typically have a different length. Thus, it does not make sense to cut/copy/paste a selection which does not span the table; the operations are disabled in this situation -- unless the selection involves a single row (raster).
In addition to the cut, copy and paste operations, you can append or insert new rows or columns into the data set. Again, adding a column makes little sense for a raster, since there is no notion of a "column" across multiple rasters (meaning spike train rasters, NOT video rasters). However, if a single raster is currently selected, the append/insert column operations are enabled, letting you append or insert a single sample (initialized to NaN) into the selected raster.
Selecting a range of rows or columns is easy in the tabular view. For full-column selection, simply mouse-down on a cell in the table's column header and drag the mouse left or right. The corresponding columns in the table are automatically selected. If you drag the mouse past either end of the header, the table will automatically scroll in that direction so that you can extend the selection beyond the visible viewport. Alternatively, you can click on a cell n1 in the column header to select the corresponding column, use the horizontal scroll bar to bring a different portion of the table into view, then click on another cell n2 in the header with the Shift key depressed to extend the full-column selection to include all columns between n1 and n2 inclusive. Analogous mouse gestures on the table's row header mediate full-row selection. Finally, clicking on the cell labelled "N:M" in the upper-left corner of the scroll pane will clear the current selection entirely and reset the scroll bars so that the cell (1,1) is visible.
The above description is short on details and does not explore all the different ways in which you can alter the raw data array. We strongly recommend "test-driving" the data table: just experiment with all of the different operations until you understand the effects of each action. Once you have learned how to use it, you'll find that the tabular view is a much more powerful editing tool than the text view.