RGLab / flowCore

Core flow cytometry infrastructure
43 stars 25 forks source link

Add full support for FCS 3.1 write.FCS #240

Open FMKerckhof opened 1 year ago

FMKerckhof commented 1 year ago

Describe the bug

More of a feature request than a bug. Currently, write.FCS only supports FCS 3.0 format. Nevertheless, FCS 3.1 has been released more than a decade ago (https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2892967/). Most modern instrument software will generate FCS 3.1 files. After performing manipulations in R, it would seem a regression to write the FCS files out to a format from 1997.

Is it very complex to add support for FCS 3.1?

FMKerckhof commented 1 year ago

I started the implementation in a fork because indeed it's only a minor change that doesn't appear to break a lot. I found that mainly the issues could lie with the $SPILLOVER tag: https://onlinelibrary.wiley.com/doi/pdf/10.1002/cyto.a.22018

As a microbial flow cytometrist my experience with compensation is very limited.

Specifically (from the paper above):

"The FCS 3.1 standard does not include a specific example of how to handle writing the spillover matrix when multiple measurement types, such as the height (H) and area (A) of a signal, are involved. The general approach is to set up a sparse spill-over matrix that isolates the different measurement types by setting some matrix elements to zero, indicating no spillover between two measurements. By specifying a value of zero for the spillover between different measurement types, the different measurement types are isolated in the matrix. Thus, the spillover for one measurement type can be properly accounted for independent of any other type using a single matrix. It is the responsibility of the FCS writer to ensure that the $SPILLOVER key-word is encoded in this way and that the matrix is well formed and invertible."

I have added a pull request (#241) addressing my current approach for FCS 3.1 support inwrite.FCSbut could use some help in implementing the checks & balances for the $SPILLOVER keyword. Are there any unit tests and/or testdata in flowCore that can be used for this development?