The Problem
Suppose that you have created a detailed model for one of your analysis applications, and you want to analyze a data file that was run on a different instrument. The new data file has the same markers that your model was built upon, but the parameter names are a little different. What happens when you read the data file into your model?
Nothing!
Some of the Parameter Profile plots show that the parameters are inactive. The label for the parameter is dimmed when the parameter is not found in the data file, and no events appear in the plot.
Does this mean that you can’t analyze this data file with the model you worked so hard to create? Absolutely not. You just have some remapping to do, to tell GemStone which parameters in the file match up with the parameters in the model.
Two Approaches
There are two ways to approach this: one that modifies the model to match the new parameters, and one that modifies GemStone’s parameter database so that it can automatically remap the parameters for you. Modifying the model is quick and easy. The limitation with that approach is that you need to maintain a separate model for each of the naming variants that your data files use. Modifying the parameter database requires a little more effort, but it has the advantage of not requiring any changes to the model. We’ll look at both techniques in this how to section.
Option 1: Remapping the Model Parameters
The first approach is to remap the parameters in the model to the appropriate parameters in the new data file. Here’s how that is done.
First, open the GemStone Model Document that you want to use. Then open the new data file that has different parameter names than those used in the model.
Now, show the Cell Type editors by clicking the Cell Type shrink tool.
Next, click the label of the first Parameter Profile plot that you want to remap. For example, in the illustration above we would choose the CD19_CD19 plot label. This activates that plot and shows its properties in the Parameter Profile Properties panel.
On the right edge of the Parameter Profile Properties editor is a toolbar. Click the button at the top of the toolbar, with the tooltip “Match to Database Parameter”.
A list of parameters found in the data file appears. Choose the parameter in the list that you want to map to the model parameter. Using our example, we would choose PE-Cy55-A_CD19.
As soon as we make the selection, GemStone fills the CD19 Parameter Profile with events from the data file and reactivates the parameter.
This process is repeated for each inactive parameter in the model. If the model has more than one Cell Type, you will need to repeat the process for each.
Saving the Changes to a New Model
Once the model has been remapped for the new parameter names, it should be saved as a new model so that it can be used again with data files with this format for file names. The original model remains unchanged so that it works with the parameter names in the original data files.
Option 2: Using the Parameter Database
The second approach is to make use of the Parameter Database to map the new file’s parameters to existing parameters in the database that the model was designed for. Here’s how that is done.
Once again, start by opening the GemStone Model Document that you want to use. Then open the new data file that has different parameter names than those used in the model.
As before, you will see some of the labels on the Parameter Profiles are dimmed, indicating that the parameters do not exist in the new data file.
Open the Parameter Database
Click the Parameter Database button on the main toolbar. The Edit Parameter Database dialog is displayed.
The “Live” column shows a value of “On” for the parameters that are found in the current FCS file. A value of “Off” means that the parameter is in the database, but not found in the current FCS file. Our job is to tell the database how to match the parameters in this new file with parameters that are already in the database.
Matching the Parameters
This technique requires us to edit the names of the “Live” parameters to match existing parameters. For example, in the dialog shown above, we see a parameter named “PE-Cy55-A_CD19”. Our model and the parameter database already know about a parameter named “CD19_CD19”. So, we need to edit the name of the Live parameter to match “CD19_CD19”
Click on the label of a Live parameter that you want to edit. In our example, we’ll start with “PE-Cy55-A_CD19”. Edit the name to match the existing parameter, in this case “CD19_CD19”. Then, press the Tab key to finish the edit.
As soon as you press Tab, GemStone realizes that the name you typed matches a name it already has in the Parameter Database. It presents a “Merge” confirmation dialog, with a message similar to the one shown here:
Choosing “Yes” means that the program will merge the two parameter names into one entry in the database. It will treat the names as aliases for the same parameter, and our model will be able to work with either data file. Choosing “No” will allow us to choose a different name, in case we made the change by accident.
In this case, we want to choose “Yes”. After we click “Yes”, the entry we just edited is flagged to be deleted from the parameter database.
So if this entry is going to be deleted, how will the program keep track of the alias we just created? Let’s take a look.
Scroll down in the list and you will eventually find another entry labeled “CD19_CD19” that has “Live” set to “Off”. Double-click this entry to display the Edit Properties dialog.
Click the Edit All Conditions button to display the Edit All Parameter Conditions dialog.
We see there are two entries in the condition list: one for “CD19_CD19” as a short name, and another that has “PE-Cy55-A” for the short name and “CD19” for the long name. GemStone will consider parameters with these keyword values as equivalent. Note that you can manually create new conditions or remove existing conditions with this dialog. See Edit Parameter Conditions for details.
Click OK to close the dialog, and once again to close the Edit Properties dialog.
Finishing Edits
Repeat this editing process for each of the parameters in the new data file until you have mapped each one to an existing entry in the parameter database. Take care to match the names with the names used by your model exactly.
When you finish your edits, click OK to close the Edit Parameter Database dialog. As soon as you close the dialog, the parameters in the model that had been inactive should activate and display events.
Summary
We have looked at two methods for telling GemStone how to map parameters in a new data file to the parameters in an existing model. In the first case, we modified the model to use the parameters in the new file. This was very quick, but required us to create a second copy of the model to handle both of the file naming styles.
In the second approach, we used the Parameter Database to let GemStone map the parameters to the same database entry. We edited the new parameter names in the database to match existing parameters, and merged the parameters together. This created aliases for the parameter by defining “conditions”. The advantage to this approach is that one model can now work with files that have different parameter names.
See also: