Embedded Files
The Data File page is used to preview and load single-molecule photon-counting data file and associated files such as TCSPC calibration files.
When previewing a file, only a small fraction of the file is loaded and analyzed in order to determine the number of channels and read associated information (such as macrotime clock period, channel name, etc.). Previewing files is useful when the data comprises multiple channels of unknown types, or the channel types might be different from the previously loaded file. While the user will in general not know how many photons are available in each channel by a simple preview, enough information will in general be read to be able to specify which channel to use as Donor and Acceptor (or Monitor, if applicable). Once this selection is done, the file can be loaded in memory.
Loading a file entails different steps and actual operations, depending on the file type.
The difference between these two actions are detailed in the following sections.
1. Supported data files
Several file formats are supported, as indicated in the File Type pull-down list shown below the File Path control:
.sm: us-ALEX or standard CW smFRET data file (originally developed by Dr. Ted Laurence).
.spc: ns-ALEX or TCSPC smFRET, or polarization anistropy data file (generated by the Becker & Hickl SPCM software).
.dat: multispot smFRET data file (in use in the Weiss Lab).
.hdf5: photon-HDF5 data file, designed to contain different type of photon-counting data (see Ref. 4 for details).
.pts: simple photon time stamp data file generated by simulation software.
Note that this list is not actionable by the user (it is an indicator, not a control) and simply reflects the nature of the file last previewed or loaded in memory.
2. Previewing a file
Previewing a file is useful if the data it contains is of an unknown nature (for instance, if the file format doesn't natively provide enough information to interpret its data unambiguously, as is the case of the majority of file formats except for photon-PDF5).
To preview a file without loading it, first make sure that the Preview File Information checkbox (below the File Path control) is checked.
Since a number of file formats containing different types of data are supported, it is necessary to provide some guidance as to which type of data (or measurement) will be previewed. This is performed with the Measurement Type pull-down list located above the File Path control:
The Measurement Type follows (in part) the list of measurement types supported in the photon-HDF5 format. Some measurement types of the photon-HDF5 format are not currently supported (for instance, there is no support for 3-color us-ALEX measurements), but some others are added for clarity. For instance:
smFRET (CW) indicates a smFRET data file with no alternation or nanotimes.
smFRET (TCPSC) indicates a smFRET data file with no alternation but with nanotimes.
Time-Resolved Polarization indicates a measurement without spectral information, but two orthogonal polarizations.
The main effect of specifying the Measurement Type before previewing the file is to limit the type of accessible files in the next step. Specifically, the following File Types are available for the different Measurement Types:
The final step in previewing a file is to update the File Path control, by either dragging a file into it or by pressing the Browse button (in the red box in the Figure below):
Once this is done, basic information about the file is updated on the front panel:
Photons in File: indicates how many photons the file contains, based on the known file size and data structure.
Macrotime Clock (ns): clock period used to convert photon timestamps from clock unit to real time.
Channel Names: list of distinct channels stored in the file with their names (or numbers if no name was stored in the file).
Notice that the Macrotime Clock (ns) parameter is a control (white background), i.e. a parameter which can be modified by the user, by contrast to the Photons in File indicator (gray background, not modifiable by the user).
Notice also that the title bar still shows the path and name of the previously loaded file. This is because the data from this previous file is still in memory, while the data from the new file hasn't been loaded yet (it has just been previewed). In fact, at this stage, it is possible to cancel the preview (and the modifications it may have generated in the Data File page, by pressing the Restore Data File Information button (green curved arrow to the right of the File Path control).
In general, the file preview will not allow the software to specify which spectral definition to associate with each channel, or which channel to select, therefore this information will be left unchanged from that of the previous file. In the specific case illustrated above, the previewed file was the first file looked at after starting the software, therefore there is no selected channel, and their Channel Definitions are all identical to the default one (Donor)
In order to specify which definition to use and which channel to select before the file is loaded, the user needs to define the nature of each channel by selecting one of the following possibilities for the Channel Definitions:
It is only necessary to specify the nature of the channels which will be loaded during the next step. Those need to be specified by checking the corresponding Selected checkbox:
In the example above, Ch 1 was defined as the Donor channel (and selected), while Ch 2 was defined as the Acceptor channel (and selected).
Notice that at this point, the number of photons loaded for each channel is zero (Photons array to the right), because it could not be read out from a mere preview of the .sm file. This would have been different with a photon-HDF5 file, where this information is easier to obtain.
Finally, note that the two checkboxes Ignore Parameter Definitions from File and Ignore Channel Definitions from File have no effect during a preview. Their use will be described in the next section.
3. Loading a file
Before loading a file, the user can specify whether all photons should be read (default: yes, indicated by the value -1 in Photons to Read (-1: All)) and whether some photons need to be skipped (default: no, indicated by the value 0 in Photons to Skip). The combination of both parameters allows for instance to look at a file by windows comprised of fixed number of photons.
When the user enters non-default values for both controls, they appear white on black (as shown below), in order to grab the user's attention, in case these settings were used for a previous file but have become unnecessary for the new file:
For photon-HDF5 files, an alternative way to define a partial read is available: right-clicking on either of the two controls above gives access to a Switch to Fraction option, which allows defining which fraction of the photons to skip and which fraction of photons to read:
To return to a definition in terms of photon numbers, use the right-click option Switch to Photons.
These options apply to each file load individually. For instance, in the case of a multispot file, the fractions correspond to the photons belonging to the spot under consideration.
Additionally, it is also possible to check for large gaps between successive photon timestamps by imposing a maximum gap (Max Gap in ms), and ask those gaps to be removed by checking the Remove Time Trace Gaps over: checkbox.
To load the file, press the Load File button (red box below) or use the Ctrl-O shortcut of the File menu.
Notice how, in the Figure above, the title bar now displays the file path of the file just loaded, and how the Photons array now shows the number of photons read in each channel.
Since a new file has been successfully loaded, the Restore Data File Information button is not visible anymore, and the right-most LED of the Task Completion Indicator at the bottom right of the window has lit up. In fact, since the file is not an ALEX measurement file, its single excitation period is by definition Donor-excitation, and therefore the second LED is also lit up, indicating that all information is available to proceed with data analysis.
Ignoring File Parameters
All file formats will contain timestamp resolution information which can be translated into a Macrotime Clock (ns) parameter. This parameter can be changed by the user after the file is loaded, but it might be more convenient to set it once and for all and ignore that information from subsequent files. Checking the Ignore Parameter Definitions from File will serve that purpose (in addition to ignoring other parameters such as TCSPC parameters in the relevant cases).
The photon-HDF5 file format allows specifying the type of each channel (or pixel). If the user wants to override the file definitions, it is possible to do so after loading the file, but, as before, it might be preferable to specify the channel-definition relations once and for all, and ignore that information from subsequent files. Checking the Ignore Channel Definitions from File will serve that purpose.
4. Difference between file types
The example above used a smFRET (CW) data file to illustrate basic concepts.
The interface behaves slightly differently for other file types.
For instance, previewing a smFRET ns-ALEX (.spc) file will change the page appearance to:
There is clearly more information, related to the nanotime definitions (SPC parameters) as well as to the optional calibration file for the time-to-amplitude converters (TAC).
Similarly, previewing a multispot file may result in the following appearance:
Here, two new parameters have appeared, as well as a new checkbox:
Words/Photon
Channels
Ignore .dat header
and the Channel Names, Channel Definitions, Selected and Photons arrays are now too large to be displayed in there entirety withing the page, resulting in the apparition of a scrollbar next to the Channel Names array. The scrollbar allows accessing the other 8 channels in the arrays and specifying their type and selection checkbox.
The Ignore .dat header checkbox skips some header information specifying the encoding and other parameters for the data and is here mostly for debugging purposes. The two other controls are populated by the values found in the file header, but can be overwritten if needed.
5. Notes
a. While it possible to select two different channels to be of the same type, such a choice will trigger a warning in the form of a beep sound and a Duplicate Channel Types! message in the bottom left message box. The only reason to perform such a choice is for scripting purposes (see the corresponding manual page).
b. The Task Completion Indicators (bottom right of the page) light up after different phases of the analysis have been completed. When no data file has been loaded, they are all off, but as soon as a data file has been loaded (not just previewed), the File Loaded indicator lights up:
In the specific case of multispot data, where loading also defines the emission periods, the Emission Windows Defined indicator also lights up:
These indicators therefore can serve as a useful reminder of the analysis stage for the loaded file (in addition to the information provided by the Notebook).
You have opened the Notebook already (Ctrl-N), haven't you?
Page updated
Report abuse