Terminology: 'raw' 'orig'

[MarkLeakos]

Just learning about mass cytometry and have some questions regrarding the terminology:
At https://flowkit.readthedocs.io/en/latest/sample.html in the Sample Class under 'export' -> parameters -> source, it is written: "source – ‘orig’, ‘raw’, ‘comp’, ‘xform’ for whether the original (no gain applied), raw (orig + gain), compensated (raw + comp), or transformed (comp + xform) events are used for exporting."

This confuses me a bit, do .fcs files generally include the gain so that one can derive both the 'orig' and the 'raw' data as defined above?
Chatgpt had this to say:

---

"Typically, a .fcs file contains the original ("orig") data that comes straight out of the flow cytometer. This data represents the fluorescence intensity and scatter properties of each individual particle (usually a cell) as measured by the cytometer's detectors.

When the term "raw" is used, it generally refers to this original, unprocessed data. However, in the context of the function you've mentioned, it seems they're using "raw" to represent the data after a gain has been applied. Gain is a multiplication factor used to increase or decrease the signal strength from a detector in the cytometer, so in this case, "raw" would represent the original data after this multiplication has taken place.

So to directly answer your question, a .fcs file typically contains what the function documentation refers to as "orig" data. Any other modifications to the data (like applying a gain, which they refer to as "raw", or performing compensation or transformations) typically occur during the analysis process, after the data has been loaded from the .fcs file into an analysis software or script."

---

Thanks to anyone who can clarify this for me.

[whitews]

Hi Mark,

I agree the terms 'orig' and 'raw' aren't ideal. Early in FlowKit's development, only 'raw', 'comp', and 'xform' were available as options. At that time, I wrestled with what term to use for the 'raw' events with gain applied. I didn't want to use a variant of 'original' since these events are not technically in their original form as stored in the FCS file, so I chose 'raw'.

Later, there was a question regarding discrepancies in event values between FlowKit and other libraries like the R package flowCore (see discussion in issue #19). The option was then added to allow retrieval of the original non-processed events. This created 2 issues, the memory storage of yet another array of event data and further confusion between 'orig' and 'raw'.

To address these issues, a later version (I think v0.8) added the default behavior of not storing the original events but allowing an override with the cache_original_events argument to the Sample class to store them. The thinking there was to prevent users from mistakenly using the original events since the gain really should be applied for any analysis.

So that's the back story. The question of what terms should be used for these 2 sets of event data is admittedly unclear. I'd be open to changing them if a strong case can be made for better terms, though it would have to be convincing as it would result in a breaking change to the current API.

Hope this helps clarify some of the confusion and welcome further discussion / feedback,
Scott