Keyword Search and Replace

Keyword Search and Replace is a tool that allows users to fix/change event annotations supplied by FCS files. This can be done in the graphical user interface or with the help of scripts. The changes are made to the FlowJo Workspace and the FCS data is NOT ALTERED in this process.

Use the GUI below to change one string at a time. If you need more complicated jobs, skip to the Scripts section further down.

The dialog constructs a Search and replace command when you choose elements from the menus. For example,

"When keyword $DATE contains 01/26/2006 replace keyword value with Thursday."

The Choose drop down menu offers a list of all the keywords in the Workspace.
The Contains menu offers Equals, Contains, Starts with, Ends with.
After Contains, type in the text you want to replace, or...
Auto-Enter value: If you selected a keyword from the first list, this menu will display currently available values.
Replace keyword value with – this menu has two options, Replace Search String and Replace Keyword Value with.

Replace Search String will run the job on parts of keyword values.
Example: "When keyword "anyKeyword" contains A Replace search string with b
will turn “$CYT=FACSCAlibur” to “$CYT=FbCSCblibur”

Replace Keyword Value will run the job on whole keyword values.
Example: "When keyword "anyKeyword" contains 8 Replace keyword value with bob
will turn “$P3S=CD8” to “$P3S=bob”

Scripts

You can combine a series of operations like the above, and put them in a text file so FlowJo will batch-search-and-replace. This section will discuss the syntax of this file with some examples.

There are 6 commands in the current implementation:

1. Search and replace
2. Search and define
3. Copy KW value
4. Merge KW value
5. Complex Join Operations
6. Concatenate KW

1. Search and replace

Separate the brackets by typing the tab key

For each job, the syntax should be:
Search <{key, blank}>tab<{equals,contains,starts,ends}>tab<SValue>tab<{Replace search},{Replace keyword}>tab<Rvalue>
For each sample, see if the keyword <key> (or, if blank, any keyword) has a string <SValue> according to the search operator. If so, then replace either just the search string or the entire keyword value with <RValue>

Example:
Search $P3S equals FITC Replace Keyword Fluorescein
If a sample keyword $P3S equals FITC (exactly), then the keyword value is replaced with
"Fluorescein".
Search contains 44 Replace search 45
If any keyword contains the string "44", then the "44" is replaced with "45" irrespective of
where it occurs.

2. Search and define

Define <key1>tab<{equals,contains,starts,ends}>tab<Value1>tab<Key2>tab<Value2>
For each sample, see if the keyword <key1> has a string <Value1> according to the search
operator (as above). If so, then set the value of keyword <Key2> to be <Value2>

3. Copy Keyword Value

Copy <Key1>tab<Key2>
For each sample, copy the value of keyword <key1> into the keyword <key2>

4. Merge KW Value
Merge <Key1>tab<Key2>
For each sample, copy the value of keyword <key1> into the keyword <key2>, but only if the keyword <key2> does not already have a value in it. (I.e., Copy if blank destination).

5. Complex Join Operations

This is a multiline command that begins with Join and ends with EndJoin. In between, it
has any number of Match criteria followed by any number of Define criteria. It looks for samples that match certain criteria; for those samples, the defines are executed.

Format:
Join
Match <Key1>tab<Value11>tab<Value12> ... <Value1M> Match <Key2>tab<Value21>tab<Value22> ... <Value2M> ...
Match <KeyN>tab<ValueN1>tab<ValueN2> ... <ValueNM> Define <DKey1>tab<DValue11>tab<DValue12> ... <DValue1M> ...
Define <DKeyJ>tab<DValueJ1>tab<DValueJ2> ... <DValueJM> EndJoin

For each sample, see if there is a matching set of keyword value pairs from the keywords
{key1...KeyN} and value pairs as listed. If the Match Keywords all match the values from a
single column of values (for example, for a given sample, Key1 value is Value12, Key2 value
is Value22, ... KeyN value is ValueN2), the the Define commands are execute for column 2.
Therefore, DKey1 is assigned DValue12, ... DKeyJ is assigned DValueJ2.

This function is essentially a "join" command for joining databases.
The Match values are used to match a sample up with a set of criteria; then the Define
commands are executed for that criterion.

Example:
Join
Match $P3S CD4 CD8 CD12
Match $P4S CD8 CD14 CD45
Define Panel Stain1 Stain2 Stain3
EndJoin

In this Join command, if a sample has $P3S of CD4 and $P4S of CD8, then the keyword Panel is set to "Stain1". If it has $P3S of CD8 and $P4S of CD14, then the keyword Panel is set to "Stain2", and so forth.

In Complex Join Operations, between Join and EndJoin, after the Match criteria, you can also specify

Conditional <keyx>tab<value1x> .... <valuemx>tab<CKey>tab<{contains, equals, starts, ends}> <CValue>

amongst the Define commands.

This command will do the same as the Define, but ONLY for those samples which also have the keyword <CKey> with the value <CValue> according to the operator criteria. This lets you edit the keywords for a subset of the samples specified by the match criteria.

6. Concatenate KW

Concatenate <DKey>tab<{Skey, "text"}>tab<{Skey, "text"}> ...

Creates a concatenation of all of the values and puts it into DKey. Each value can be either a keyword (take the value of the keyword) or text (enclosed in double quotes).

Example:
Concatenate DB_PatientVisit DB_SampleID ": " DB_TimePoint

When you construct your script, blank lines are ignored. Lines beginning with "//" are ignored (they can be used as comment lines)

Save your script as a plain text file. Select the Load and Execute Changes button at the bottom of the Replace Keyword Values dialog above. Point to the file you just saved. FlowJo will read the file and execute the commands, changing the Keyword values in the Workspace according to your script.