Query regarding Compensation

[jainaditi0204]

Hi Scott,
I hope you’re doing well!
I have a small query regarding compensation, and the way it is stored in Sample files modified and exported via FlowKit, and I’ll delineate it below:

When I try to load a FCS file (which has a compensation matrix in it), and try to print out the compensation matrix using sample.compensation, it gives the output as None.
I, then added the matrix using sample.apply_compensation(sample.metadata[‘spill’], and it adds the information perfectly to the sample. But when I’m exporting the modified file containing the matrix, and reading it again, and trying to print the compensation matrix, it again shows None.
Also, when I try to extract it using the same method as above, it throws a key error for the keyword ‘spill’. It’s a bit confusing, and I have tried different settings for ‘source’ while exporting the sample, and in all of them, the matrix is getting lost.
I am curious to hear your thoughts on it.
Thank you!

Best,
Aditi

[whitews]

Hi Aditi,

The Sample class does not assume the user wants to use a built-in spillover matrix. One issue is that the spill keyword is not a reserved keyword in the FCS specification, the reserved keyword is actually spillover. Unfortunately, most cytometers use spill, which adds to the confusion. Your use of apply_compensation(sample.metadata['spill']) is the correct way to explicitly apply the file's spillover matrix.

When exporting the file, the same behavior will apply....no spill will be applied by default. If you want to export the compensated events from the first loaded sample where you explicitly applied the compensation, you would use the source keyword like: sample.export("some_filename.fcs", source='comp'). The resulting output file then doesn't need to have the spill matrix as its events will already be compensated. Thus, re-importing that exported file as a new Sample will have the raw events already compensated.

Regarding what metadata is included in the export, only the minimum required keywords are included in the exported FCS file by default. If you want to include all the metadata you can use the argument include_metadata=True in the export call. All key-value pairs in the sample.metadata dictionary will then be included (this is also a way to add new keywords if you want).

As an example, say you want to export a new FCS file with uncompensated events AND you want to include the spill keyword, you could do something like:

sample = fk.Sample("original_sample.fcs")
sample.export("new_sample.fcs", source='raw', include_metadata=True)

On a separate but related note, there is also the difference between 'orig' and 'raw' to consider when exporting FCS files. The original events are the values exactly as stored in the original FCS file. This means that the channel gain has not been applied. Channel gain should be applied for proper processing and for this reason, the original events are not stored in the Sample instance by default. If you want to retain them in the instance, you can load the sample as in the example below. The example then shows exporting the file with those original events (which will correctly include the original channel gain metadata). The use case for doing this is unclear though, as you are essentially exporting the same file as you loaded.

sample = fk.Sample("original_sample.fcs", cache_original_events=True)
sample.export("new_sample.fcs", source='orig', include_metadata=True)

Hope this helps,
Scott

[jainaditi0204]

Hi Scott,
Thank you for your reply.
Your suggestions were very helpful, and they cleared a lot of my doubts! :)
I also think, that maybe adding this information (about compensation, and metadata during FCS file export) in the notes might be useful!

Again, I highly appreciate your time and consideration!

Best,
Aditi