Notation¶
When coding with dclab, you should be aware of the following definitions and design principles.
Events¶
An event comprises all data recorded for the detection of one object (e.g. cell or bead) in an RT-DC measurement.
Features¶
A feature is a measurement parameter of an RT-DC measurement. For instance, the feature “index” enumerates all recorded events, the feature “deform” contains the deformation values of all events. There are scalar features, i.e. features that assign a single number to an event, and non-scalar features, such as “image” and “contour”. The following features are supported by dclab:
scalar features | description [units] |
---|---|
area_cvx | Convex area [px] |
area_msd | Measured area [px] |
area_ratio | Porosity (convex to measured area ratio) |
area_um | Area [µm²] |
aspect | Aspect ratio of bounding box |
bright_avg | Brightness average within contour [a.u.] |
bright_sd | Brightness SD within contour [a.u.] |
circ | Circularity |
deform | Deformation |
emodulus | Young’s Modulus [kPa] |
fl1_area | FL-1 area of peak [a.u.] |
fl1_dist | FL-1 distance between two first peaks [µs] |
fl1_max | FL-1 maximum [a.u.] |
fl1_max_ctc | FL-1 maximum, crosstalk-corrected [a.u.] |
fl1_npeaks | FL-1 number of peaks |
fl1_pos | FL-1 position of peak [µs] |
fl1_width | FL-1 width [µs] |
fl2_area | FL-2 area of peak [a.u.] |
fl2_dist | FL-2 distance between two first peaks [µs] |
fl2_max | FL-2 maximum [a.u.] |
fl2_max_ctc | FL-2 maximum, crosstalk-corrected [a.u.] |
fl2_npeaks | FL-2 number of peaks |
fl2_pos | FL-2 position of peak [µs] |
fl2_width | FL-2 width [µs] |
fl3_area | FL-3 area of peak [a.u.] |
fl3_dist | FL-3 distance between two first peaks [µs] |
fl3_max | FL-3 maximum [a.u.] |
fl3_max_ctc | FL-3 maximum, crosstalk-corrected [a.u.] |
fl3_npeaks | FL-3 number of peaks |
fl3_pos | FL-3 position of peak [µs] |
fl3_width | FL-3 width [µs] |
frame | Video frame number |
index | Event index |
inert_ratio_cvx | Inertia ratio of convex contour |
inert_ratio_prnc | Principal inertia ratio of raw contour |
inert_ratio_raw | Inertia ratio of raw contour |
nevents | Total number of events in the same image |
pc1 | Principal component 1 |
pc2 | Principal component 2 |
pos_x | Position along channel axis [µm] |
pos_y | Position lateral in channel [µm] |
size_x | Bounding box size x [µm] |
size_y | Bounding box size y [µm] |
tilt | Absolute tilt of raw contour |
time | Event time [s] |
userdef0 | User defined 0 |
userdef1 | User defined 1 |
userdef2 | User defined 2 |
userdef3 | User defined 3 |
userdef4 | User defined 4 |
userdef5 | User defined 5 |
userdef6 | User defined 6 |
userdef7 | User defined 7 |
userdef8 | User defined 8 |
userdef9 | User defined 9 |
volume | Volume [µm³] |
non-scalar features | description [units] |
---|---|
contour | Binary event contour image |
image | Gray scale event image |
mask | Binary region labeling the event in the image |
trace | Dictionary of fluorescence traces |
Example: deformation vs. area plot
import matplotlib.pylab as plt import dclab ds = dclab.new_dataset("data/example.rtdc") ax = plt.subplot(111) ax.plot(ds["area_um"], ds["deform"], "o", alpha=.2) ax.set_xlabel(dclab.dfn.feature_name2label["area_um"]) ax.set_ylabel(dclab.dfn.feature_name2label["deform"]) plt.show()(Source code, png, hires.png, pdf)
Example: event image plot
import matplotlib.pylab as plt import dclab ds = dclab.new_dataset("data/example_video.rtdc") ax1 = plt.subplot(211, title="image") ax2 = plt.subplot(212, title="mask") ax1.imshow(ds["image"][6], cmap="gray") ax2.imshow(ds["mask"][6])(Source code, png, hires.png, pdf)
Ancillary features¶
Not all features available in dclab are recorded online during the acquisition of the experimental dataset. Some of the features are computed offline by dclab, such as “volume” or “emodulus”. These ancillary features are computed on-the-fly and are made available seamlessly through the same interface.
Filters¶
A filter can be used to gate events using features. There are min/max filters and 2D polygon filters. The following table defines the main filtering parameters:
filtering | parsed | description [units] |
---|---|---|
enable filters | fbool |
Enable filtering |
hierarchy parent | str |
Hierarchy parent of the dataset |
limit events | fint |
Upper limit for number of filtered events |
polygon filters | fintlist |
Polygon filter indices |
remove invalid events | fbool |
Remove events with inf/nan values |
Min/max filters are also defined in the filters section:
filtering | explanation |
---|---|
area_um min | Exclude events with area [µm²] below this value |
area_um max | Exclude events with area [µm²] above this value |
aspect max | Exclude events with an aspect ratio above this value |
… | … |
Example: excluding events with large deformation
import matplotlib.pylab as plt import dclab ds = dclab.new_dataset("data/example.rtdc") ds.config["filtering"]["deform max"] = .1 ds.apply_filter() dif = ds.filter.all f, axes = plt.subplots(1, 2, sharex=True, sharey=True) axes[0].plot(ds["area_um"], ds["bright_avg"], "o", alpha=.2) axes[0].set_title("unfiltered") axes[1].plot(ds["area_um"][dif], ds["bright_avg"][dif], "o", alpha=.2) axes[1].set_title("Deformation <= 0.1") for ax in axes: ax.set_xlabel(dclab.dfn.feature_name2label["area_um"]) ax.set_ylabel(dclab.dfn.feature_name2label["bright_avg"]) plt.tight_layout() plt.show()(Source code, png, hires.png, pdf)
- Example: excluding random events
This is useful if you need to have a (sub-)dataset of a specified size. The downsampling is reproducible (the same points are excluded).
import matplotlib.pylab as plt import dclab ds = dclab.new_dataset("data/example.rtdc") ds.config["filtering"]["limit events"] = 4000 ds.apply_filter() fid = ds.filter.all ax = plt.subplot(111) ax.plot(ds["area_um"][fid], ds["deform"][fid], "o", alpha=.2) ax.set_xlabel(dclab.dfn.feature_name2label["area_um"]) ax.set_ylabel(dclab.dfn.feature_name2label["deform"]) plt.show()
(Source code, png, hires.png, pdf)
Experiment metadata¶
Every RT-DC measurement has metadata consisting of key-value-pairs. The following are supported:
experiment | parsed | description [units] |
---|---|---|
date | str |
Date of measurement (‘YYYY-MM-DD’) |
event count | fint |
Number of recorded events |
run index | fint |
Index of measurement run |
sample | str |
Measured sample or user-defined reference |
time | str |
Start time of measurement (‘HH:MM:SS’) |
fluorescence | parsed | description [units] |
---|---|---|
bit depth | fint |
Trace bit depth |
channel 1 name | str |
FL1 description |
channel 2 name | str |
FL2 description |
channel 3 name | str |
FL3 description |
channel count | fint |
Number of active channels |
channels installed | fint |
Number of available channels |
laser 1 lambda | float |
Laser 1 wavelength [nm] |
laser 1 power | float |
Laser 1 output power [%] |
laser 2 lambda | float |
Laser 2 wavelength [nm] |
laser 2 power | float |
Laser 2 output power [%] |
laser 3 lambda | float |
Laser 3 wavelength [nm] |
laser 3 power | float |
Laser 3 output power [%] |
laser count | fint |
Number of active lasers |
lasers installed | fint |
Number of available lasers |
sample rate | float |
Trace sample rate [Hz] |
samples per event | fint |
Samples per event |
signal max | float |
Upper voltage detection limit [V] |
signal min | float |
Lower voltage detection limit [V] |
trace median | fint |
Rolling median filter size for traces |
fmt_tdms | parsed | description [units] |
---|---|---|
video frame offset | fint |
Missing events at beginning of video |
imaging | parsed | description [units] |
---|---|---|
flash device | str |
Light source device type (e.g. green LED) |
flash duration | float |
Light source flash duration [µs] |
frame rate | float |
Imaging frame rate [Hz] |
pixel size | float |
Pixel size [µm] |
roi position x | float |
Image x coordinate on sensor [px] |
roi position y | float |
Image y coordinate on sensor [px] |
roi size x | fint |
Image width [px] |
roi size y | fint |
Image height [px] |
online_contour | parsed | description [units] |
---|---|---|
bin area min | fint |
Minium pixel area of binary image event |
bin kernel | fint |
Odd ellipse kernel size, binary image morphing |
bin threshold | fint |
Binary threshold for avg-bg-corrected image |
image blur | fint |
Odd sigma for Gaussian blur (21x21 kernel) |
no absdiff | fbool |
Avoid OpenCV ‘absdiff’ for avg-bg-correction |
online_filter | parsed | description [units] |
---|---|---|
area_ratio max | float |
Maximum porosity |
area_ratio min | float |
Minimum porosity |
area_ratio soft limit | fbool |
Soft limit, porosity |
area_um max | float |
Maximum area [µm²] |
area_um min | float |
Minimum area [µm²] |
area_um soft limit | fbool |
Soft limit, area [µm²] |
aspect max | float |
Maximum aspect ratio of bounding box |
aspect min | float |
Minimum aspect ratio of bounding box |
aspect soft limit | fbool |
Soft limit, aspect ratio of bbox |
deform max | float |
Maximum deformation |
deform min | float |
Minimum deformation |
deform soft limit | fbool |
Soft limit, deformation |
fl1_max max | float |
Maximum FL-1 maximum [a.u.] |
fl1_max min | float |
Minimum FL-1 maximum [a.u.] |
fl1_max soft limit | fbool |
Soft limit, FL-1 maximum |
fl2_max max | float |
Maximum FL-2 maximum [a.u.] |
fl2_max min | float |
Minimum FL-2 maximum [a.u.] |
fl2_max soft limit | fbool |
Soft limit, FL-2 maximum |
fl3_max max | float |
Maximum FL-3 maximum [a.u.] |
fl3_max min | float |
Minimum FL-3 maximum [a.u.] |
fl3_max soft limit | fbool |
Soft limit, FL-3 maximum |
size_x max | fint |
Maximum bounding box size x [µm] |
size_x min | fint |
Minimum bounding box size x [µm] |
size_x soft limit | fbool |
Soft limit, bounding box size x |
size_y max | fint |
Maximum bounding box size y [µm] |
size_y min | fint |
Minimum bounding box size y [µm] |
size_y soft limit | fbool |
Soft limit, bounding box size y |
target duration | float |
Target measurement duration [min] |
target event count | fint |
Target event count for online gating |
setup | parsed | description [units] |
---|---|---|
channel width | float |
Width of microfluidic channel [µm] |
chip region | lcstr |
Imaged chip region (channel or reservoir) |
flow rate | float |
Flow rate in channel [µL/s] |
flow rate sample | float |
Sample flow rate [µL/s] |
flow rate sheath | float |
Sheath flow rate [µL/s] |
identifier | str |
Unique setup identifier |
medium | str |
Medium used |
module composition | str |
Comma-separated list of modules used |
software version | str |
Acquisition software with version |
Example: date and time of a measurement
In [1]: import dclab In [2]: ds = dclab.new_dataset("data/example.rtdc") In [3]: ds.config["experiment"]["date"], ds.config["experiment"]["time"] Out[3]: ('2017-07-16', '19:01:36')
Analysis metadata¶
In addition to metadata, dclab also supports a user-defined analysis configuration which is usually part of a specific analysis pipeline and thus not considered to be experimental metadata.
calculation | parsed | description [units] |
---|---|---|
crosstalk fl12 | float |
Fluorescence crosstalk, channel 1 to 2 |
crosstalk fl21 | float |
Fluorescence crosstalk, channel 2 to 1 |
crosstalk fl31 | float |
Fluorescence crosstalk, channel 1 to 3 |
crosstalk fl31 | float |
Fluorescence crosstalk, channel 3 to 1 |
crosstalk fl32 | float |
Fluorescence crosstalk, channel 2 to 3 |
crosstalk fl32 | float |
Fluorescence crosstalk, channel 3 to 1 |
emodulus medium | str |
Medium used (e.g. CellCarrierB, water) |
emodulus model | lcstr |
Model for computing elastic moduli |
emodulus temperature | float |
Chip temperature [°C] |
emodulus viscosity | float |
Viscosity [Pa*s] if ‘medium’ unknown |