User Interface

Basic usage

On start-up, you are presented with an empty interface. To load data, use the menu FileFind Measurements and select a directory containing experimental data. The directory is searched recursively for .tdms and .rtdc files which are then displayed in the measurement browser on the left. Here, you can select the measurements and plot them by clicking Analyze at the bottom of the measurement browser. The configuration tabs at the top allow you to filter the data and change the visualization in the plot area. Individual events in the plot area can be selected and are then displayed in the event area (top right). It is possible to adjust the sizes of measurement browser, configuration tabs, event area, and plotting area by dragging the borders in-between those elements. The File menu allows you to save sessions. To export data and plots, use the Export Data/Image menus.

_images/main.png

Shape-Out user interface on start-up. The measurement browser on the left is empty. The configuration tabs on the top show the plotting settings. A dummy measurement is shown in the plotting area.

Measurement browser

_images/measurement_browser.png

The measurement browser shows the measurements that are available for plotting. They are sorted according to the directory tree structure. For each measurement, the measurement index, the measurement region, the flow rate, and the number of events are shown. The buttons at the bottom of the measurement browser allow to change the selection (all, none, only specific flow rates).

The Analyze button loads the experimental data which is then visualized in the plot area. When a measurement is part of the current analysis, it is shown with a bold font weight in the measurement browser.

Plot Area

_images/plot_area.png

The plot area visualizes the current analysis. It is configured via the configuration tabs Plotting, Scatter Plot, and Contour Plot (see below).

The axes limits can directly be modified with the mouse by dragging the plot with the left mouse button (axes offset), zooming in or out with the mouse wheel, or by drawing a rectangle using the right mouse button (zoom to selection).

In addition, an individual event can be selected in a scatter plot, which is then displayed in the event area (top right).

Event Area

_images/event_area.png

The event area shows information about individual events. At the top, the measurement and the event index can be selected. The event image with the event contour (red) is shown. With the checkbox, individual events can be excluded from an analysis.

The plot below (not visible initially - drag the border between event area and plot area or scroll down to make it visible) shows the fluorescence signal over time. This plot is only available for RT-FDC data.

Configuration Tabs

_images/config_tabs.png

The configuration tabs allow to view and edit multiple aspects of the current analysis and facilitate additional analysis steps.

Information

All properties of the current analysis are shown. If properties differ between measurements within an analysis, the corresponding values are set to (multiple). To see the full panel, use the scroll bars or increase the size of the panel by dragging the edge.

A summary of all valid metadata properties can be found in the dclab documentation. The most important properties are:

event count:
Number of recorded cells. In Shape-In this number is shown on the front panel as Number of cells measured.
channel width:
Dimension of the channel. This number is not detected automatically by Shape-In, but has to be set by hand in the front panel under Channel dimension [µm].
chip region:
The position of the region of interest during the measurement. This is not detected automatically by Shape-In, but has to be set by hand in the front panel under Region of interest in the ….
flow rate:
The sum of sheath and sample flow in µl/s. Shape-In records this number when the measurement starts and shows it on the front panel under Flow Rate [µl/s].
frame rate:
Camera frame rate during the measurement. Shape-In records this information when the measurement starts and shows it in the expert tab under Camera tools and Framerate [Hz].
pixel size:
Resolution of the microscope-camera-system in [µm/pixels]. In Shape-In this number is shown in the expert tab settings under Resolution [µm/pix].
run index:
The number of the measurement within the opened project. In Shape-In this number is shown on the front panel under current/next #.

Calculate

This tab allows to compute additional features for the analysis.

Elastic modulus:
Compute the elastic modulus according to [Mokbel2017]. The new feature Young’s Modulus [kPa] (emodulus) will be available for plotting and analysis.
Fluorescence maximum crosstalk correction:
Perform a crosstalk correction for multi-color RT-FDC measurements. New features FL-1 maximum, crosstalk-corrected [a.u.] (fl1_max_ctc) will be available for plotting and analysis.

Filter

In this tab, you can filter your data by excluding values beyond certain limits. Select the enable filters check box on the right and hit the Apply/Reset button to apply/reset the settings. The Box Filters limit the range of parameters; the Polygon Filters allow freely defining a gate by a polygon in the current plot. The filters are applied to all measurements of the analysis, independent of the plot shown currently. For a quick guide to exclude invalid events, see Excluding invalid events.

  • Box Filters:

    Box filters allow to set minium and maximum values for each feature (e.g. Area [µm]) of a measurement. Minimum and maximum values for box filters are set to 0.0 by default. As long as they are equal, the filter is not applied. On the left of the table the minimum value is set, on the right the maximum. For a list containing short descriptions of all features, please see the dclab documentation. The most important box feature filters are:

    Range area_ratio:

    Limit the porosity, the relative difference between convex hull area and cell area. A value of “1”, means that the convex hull and is equal to event contour. Values smaller than “1” are not possible, because the convex hull cannot be smaller than the contour.

    Range area_um:

    Limit the cell area in [µm²].

    Range aspect:

    Limits the aspect ratio of the bounding box, the ratio of height and length of the bounding box around the contour of the event.

    Range deform:

    Limits the deformation.

    Range post x:

    Limit the position along channel axis [µm].

    Range post y:

    Limit the position lateral in channel [µm].

    Range time:

    Limits the event time [s].

    Range x-size:

    Limit the bounding box size along the channel axis [µm].

    Range x-size:

    Limit the bounding box size perpendicular to the channel axis [µm].

  • Polygon Filters:

    Polygon filters are two-dimensional filters that can be used to specify non-rectangular regions of interest. To create a polygon filter, select the desired measurement (used as a plot template) in the dropdown menu and click New. A new window pops up. Clicking on the plot will generate the points of the polygon filter. When you are done, press Enter on the keyboard and close the window. The new polygon filter is then shown in the list. Polygon filters can be applied to all measurements or only to individual measurements. You can see which polygon filters are set for which measurement by selecting each measurement in the dropdown list. In addition, polygon filters can be duplicated, inverted, exported and imported.

  • Filter Hierarchy:

    Filter hierarchies allow to create a virtual measurement from an existing measurement. All events that are filtered in the original measurement will not show up in its hierarchy child, allowing to perform additional filter operations on hierarchy children. This comes in handy e.g. when different subpopulations in a study need to be distinguished without the noise (e.g. debris) in the original data. Children in hierarchies always update their data according to the filtered event data from their parent, i.e. when the filters of the parent measurement change, the hierarchy child changes as well.

Statistics

Show statistics of the current analysis. Please note that more comprehensive functionalities are available via the menus Export DataComputed statistics (*.tsv) and BatchStatistical summary.

Analyze

Regression analysis:
Perform a regression analysis according to (general) linear mixed effects models. For more information, please see Comparing datasets with LMM as well as the references [Herbig2017] and [Herbig2018]. If you are using this feature in a scientific publication, please consider citing [Herbig2018].

Plotting tabs

Plotting:
Change the plotted axes and modify the displayed axis ranges. In addition, several plotting parameters can be modified, including the number of plots, the types of plots shown and the types of isoelasticity lines shown.
Scatter plot:
Modify the parameters of the scatter plots.
Contour plot:

Enable or disable contour plots, modify contour plot parameters, and select the title and color for each scatter plot.

New in version 0.9.2: Contour lines can now be plotted at KDE data quantiles (percentiles/100) instead of at fractions of the overall KDE using the contour level mode option. A contour line at a 0.95 quantile contains 5% of all data points.

Expert Mode

The expert mode is available via the menu PreferencesExpert mode. The following options are enabled in expert mode:

  • Export data in the .rtdc file format. Using .rtdc files instead of .tdms files speeds up the analysis in Shape-Out significantly. However, exporting .tdms files to .rtdc files might be accompanied by data loss (most likely some metadata keys are not converted and included in the resulting .rtdc files). Make sure to keep the original .tdms datasets. You might have to re-generate the .rtdc files to be compatible with future versions of Shape-Out.

  • Several features are made available for data analysis:

    • Convex area [px] (area_cvx)
    • Measured area [px] (area_msd)
    • Video frame number (frame)
    • Principal inertia ratio of raw contour (inert_ratio_prnc)
    • Absolute tilt of raw contour (tilt)

    See the dclab documentation for a full list of available features.