FCS Express allows you to add keywords to an existing FCS File.

 

Adding keywords is useful in several scenarios, such as:

 

adding descriptors to your data files that were not saved as metadata at the time of sample acquisition (e.g. information describing the sample, the experimental group, the experimental condition,...). This is also useful when multiple files are merged together since metadata can be used as classification parameters.

adding information to your data files for loading them as a multiwell plate Heat Map plot,

adding information to your data files for creating Virtual Spectral Data.

grouping parameters so that they will be shown in a tree by the keyword group in certain parameter drop-down lists within FCS Express

 

To add extrakeywords to your data, a specific text file must be created and placed in the same folder containing the FCS files of interest.

 

When one of the following file types exists in the same folder as the relevant FCS File(s), the extra keyword(s) will be accessible after the FCS file(s) is loaded into FCS Express.

 

Use Case

File type to create

Examples

 

Annotate a single data file with one or more keywords.

 

<filename>.extrakeywords.txt

 

Example #1

In the example below a single keyword named $PatientID, with a value of 123456 is added to file Sample1.fcs.

 

Sample1.fcs.extrakeywords.txt

Sample1.fcs.extrakeywords.txt

 

 

Annotate an entire folder of data files with one or more keywords.

 

This is useful when the same keywords, with the same values, have to be added to all the FCS file in a folder.

 

 

<descriptor>.allextrakeywords.txt

 

Example #2 - Adding information about the plate size (i.e. number or rows and columns) to plate based data.

 

In the example below, two keywords, named $PlateRows and $PlateColumns with values of 8 and 12 respectively are added to all the FCS files in the folder where the "....allextrakeywords.txt" file is stored.

96well.plate.AllExtraKeywords.txt

96well.plate.AllExtraKeywords.txt

 

 

Example #3 - Adding information about how to create virtual spectra data with non-spectral data.

 

In the example below, five keywords (FCSE_SPECTRA1NAME, FCSE_SPECTRA1PARAMETERS,...) are added to all the FCS files in the folder where the "....allextrakeywords.txt" file is stored.

VirtualSpectralExample.AllExtraKeywords.txt

VirtualSpectralExample.AllExtraKeywords.txt

 

 

Annotate multiple files  with any number of custom keyword(s).

 

This is useful when the value for each keyword differs between files.

 

This method also allows the user to create the required CSV file using a spreadsheet interface.

 

 

ExtraKeywordsTable.csv

 

Example #4 - Adding keywords with different values to multiple files.

 

In the example below, three keywords named ProtocolID, Sample Type and WellID are specifically added to the files listed in the filename column. The value for each keywords can vary between files.

 

ExtraKeywordsTable.csv

ExtraKeywordsTable.csv

 

 

 

Details about each file type:

 

<filename>.extrakeywords.txt

Use this if you want to add extra-keywords to one or very few files. When extra-keywords should be added to many files, we suggest using the ExtraKeywordsTable.csv file type instead (please see below).

 

How to use this:

Add a TXT file with the name <filename>.extrakeywords.txt to the same folder as a data file with the name <filename>. The <filename> must match the name of the file to which the keyword(s) will be written.

Once the FCS file of interest is loaded into a layout, the extra-keywords contained in the TXT file will be accessible as any other standard keywords.

 

 

<descriptor>.allextrakeywords.txt

Use this when you want to add keywords that pertain to all of the files in the folder. For example, experiment name, protocol information, and plate information that is relevant across an entire series of samples.

 

How to use this:

Add a TXT file with the name <descriptor>.allextrakeywords.txt to the same folder containing your data files. The <descriptor> can be any user-defined string (e.g. it can be a word that describes the type of keywords that are being added to the data files, like "Plate").

This option will assign all keywords values within the .txt file to all files within the folder.

Once any of the FCS files in the folder are loaded into a layout, the extra-keywords contained in the TXT file will be accessible as any other standard keywords.

 

Use case examples:

Defining the number of columns and rows in Plate based data

Defining new parameters in Virtual Spectral data

 

 

ExtraKeywordsTable.csv

Use this when you want to annotate multiple files, each with different keywords and different values.

This is like using an .extrakeywords.txt file, while allowing you the ability to quickly add and edit many files and keyword values in one .csv document.

 

How to use this:

Add a CSV file with the name ExtraKeywordsTable.csv containing columns for filename and extrakeyword(s) to the same folder containing your data files.

Once any of the FCS files listed in the filename column are loaded into a layout, the corresponding extra-keywords contained in the CSV file will be accessible as any other standard keywords.

The format of the CSV file should be as follows and as seen in Figure 14.3 below:

oColumn A contains a header named filename. Additional rows in column A contain the filename of the files to add the keyword value to within the folder. The file extension (e.g. .fcs) needs to be included in the filename. (*)

oAdditional columns contain headers named with the name of the keyword you would like to add. Additional rows under each header contain the information for the keyword associated with each file in text or numeric form.

 

Use case examples:

Assigning a Well ID to each Plate based file

 

(*) TIP: A template for creating an ExtraKeywordsTable.csv file with the filename column automatically populated can be downloaded here.

 

 

Figure 14.3  ExtraKeywordsTable.csv

Figure 14.3  ExtraKeywordsTable.csv

 

Note: If you add extra keywords to a data file already in use within a layout you can utilize the Refresh icon on the Data tab to reload the data.

 

 

 

Examples of common uses of Extra Keywords:

 

1. Plate Based Data- defining the number of columns and rows

File type: <descriptor>.allextrakeywords.txt

When loading data as a multiwell plate Heat Map, the size of the plate must be specified in an extra keywords file residing in the same directory folder as your data file(s). An example of this file is shown below in Figure 14.4. The keywords file must contain the keywords $PlateRows and $PlateColumns. In a typical 96 well plate, that file would contain the following text:

         $PlateRows=8

         $PlateColumns=12

Extra keyword .txt files for 6-, 12-, 24-, 48-, 96- and 384- well plates can be downloaded on the De Novo Software website.

 

Figure 14.4 96well.plate.AllExtraKeywords.txt

Figure 14.4 96well.plate.AllExtraKeywords.txt

 

 

 

2. Plate Based Data- assigning a Well ID to each FCS file.

File type: ExtraKeywordsTable.csv

In order to control the well which a file will be associated with, a WellID ($WellID) keyword must be assigned to each FCS File.

oNote: If you recorded the data on a plate-sampling instrument, your FCS File may already contain this $WellID keyword and you do not need to create an ExtraKeywordsTable.csv file.

You will need to create a file called ExtraKeywordsTable.csv in Excel and save it in the same folder that contains your associated FCS Files. An example of this file is shown below in Figure 14.5.

oCell A1 contains the header filename.

oThe rows of Column A contain the filenames of the associated FCS Files exactly as they are named. The file extension (i.e. .fcs) needs to be included in the file name.

oOne of the other cells in row 1 contains the header WellID.

oThe rows of the WellID column contain the Well ID you want to assign (A1, A2, A3, etc.) to the file in the same row.

oYou may also define the number of columns and rows in your plate here instead of using the file <descriptor>.allextrakeywords.txt

oYou may include other columns for other keywords.

 

Figure 14.5 ExtraKeywordsTable.csv

Figure 14.5 ExtraKeywordsTable.csv

 

 

 

3. Virtual Spectral Data:

File type: <descriptor>.allextrakeywords.txt

 

Note: Please also see the chapter on Pipeline Steps for virtual Spectra Merging including options to automatically create the necessary extra keywords files. The options below allow for manual creation of the necessary file, but De Novo Software recommends the pipeline steps version for ease of use.

 

FCS Express allows you to visualize any .FCS data files as a "Virtual Spectral" data file via the addition of special keywords to the data set. A virtual spectra parameter may be created by indicating the original parameter channels to use in a spectral plot (i.e. FL1, FL2, FL3, FL4, etc). After the virtual spectra parameter is defined for a data file, all of the standard Spectrum Plot functionality in FCS Express for further exploration and analysis  of the data set.

The <descriptor>.allextrakeywords.txt file needs to be saved in the same folder as the associated FCS files.

Download and Unzip Example Virtual Spectral Data extra keywords file (shown below in Figure 14.6)

 

Figure 14.6 VirtualSpectralExample.AllExtraKeywords.txt

Figure 14.6 VirtualSpectralExample.AllExtraKeywords.txt

 

 

Keywords needed for adding a new spectral parameter:

 

Keyword

Explanation

Example

FCSE_SPECTRA1NAME=

Required: Indicates the name of the new spectral parameter.

FCSE_SPECTRA1NAME=FL

FCSE_SPECTRA1PARAMETERS=

Required:Indicates which of the original parameters to use to create a new virtual spectral parameter. Parameter names must match your user preferences for Keyword To Use as Parameter Name

FCSE_SPECTRA1PARAMETERS=FL1-H,FL2-H,FL3-H

FCSE_SPECTRA1LABELS=

Required:Indicates the labels to be used for each channel in Spectrum Plots.

FCSE_SPECTRA1LABELS=One,Two,Three

 

Optional keywords for removing unneeded parameters:

Keyword

Explanation

Example

FCSE_COLUMNTODELETE_STRICT=

Comma separated exact list of parameters to delete after the import process. An error will be given if a parameter is not found for deletion. Parameter names must match your user preferences for Keyword To Use as Parameter Name

FCSE_COLUMNTODELETE_STRICT=FL1-H,FL2

FCSE_COLUMNTODELETE=

Comma separated list of parameters to delete after the import process. Any parameters not found will be ignored. Parameter names must match your user preferences for Keyword To Use as Parameter Name

FCSE_COLUMNTODELETE=FL1-H,FL2-H

 

Please also see the chapter on Pipeline Steps for virtual Spectra Merging including options to automatically create the necessary extra keywords files.