gates drawn in flowjo that intersect the chart edge behave differently in flowkit

[hbhargava7]

Describe the bug
If you draw a rectangle gate that intersects the chart edge in FlowJo, the count in FlowJo includes all events at least as extreme as the chart edge. But flowkit uses a literal upper bound on the gate, which may or may not capture all of the off-chart points (I incorrectly assumed that flowjo scales the chart to the most extreme points, which is not always the case).

(note: my usage of flowkit involves drawing gates in FlowJo and then analyzing the data in Python with flowkit. This issue is fairly specific to this paradigm.)

related to #265 which deals with chat edge points.

here is an example of some (nasty) data in Flowjo 10.10.1 with lots of points off the chart edge (these are from a BD FACSymphony A1). There are two rectangle gates for mCherry+ and mCherry-.

Flowjo and flowkit disagree on the counts for the mCherry+ gate:

import flowkit as fk

wsp = fk.Workspace('demo.wsp', find_fcs_files_from_wsp=True)
wsp.analyze_samples()

gating_results = wsp.get_analysis_report()

gating_df = gating_results[['sample', 'gate_name', 'count']]
gating_df = gating_df[gating_df['gate_name'] == 'mCherry+']

FlowKit Counts Output:

 sample gate_name  count
1      A1  mCherry+     47
4      A2  mCherry+     63
7      A3  mCherry+     72
10     A4  mCherry+    209
13     A5  mCherry+    261
16     A6  mCherry+    194
19     A7  mCherry+      7
22     A8  mCherry+     10
25     A9  mCherry+     14

yet the flowjo output is super different, all higher (table editor -> counts for gate)

Sample:	Live/mCherry+ | Count
 A1: 	        242
 A2: 	390
 A3: 	445
 A4: 	371
 A5: 	421
 A6: 	343
 A7: 	7.00
 A8: 	9.00
 A9: 	10.0

The culprit is that FlowJo seems to use a "greater than or equal to" approach when the gate goes off the visible chart edge whereas flowkit uses actual numerical point values.

if I extend the y-bound on the chart in flowjo, we see that the points have discrete values above the previous chart bound (and above the gate)

the issue gets fixed if you expand the gate in Flowjo to include those points.

btw I"m not 100% sure how to read the gate dims but

gate = wsp.get_gating_strategy(wsp.get_sample_ids()[0]).get_gate('mCherry+')

for dim in gate.dimensions:
    print("%s: %s, %s" % (dim.id, dim.min, dim.max))

PE-Texas Red-A: 0.48163841808221497, 1.0056497175206365
FITC-A: 0.24012158054866745, 1.010638297878885

if these dims are indexed to the chart edge, maybe flowkit should treat values >1 as indicating a gate bound of greater than or equal to the value.

Desktop (please complete the following information):

• OS: macOS Tahoe 26.5
• Python version 3.11.15
• FlowKit version 1.2.3

data and code to replicate:

SHARED flowkit issue demo.zip

[whitews]

Hi Hersh,

I believe the discrepancies you are seeing are related to FlowJo binning data. You can find more detailed explanations in these previous issues:

#113
#254 (comment)
#120 (comment)

Another issue that further complicates this is that the display ranges in FlowJo's plotting are tied to the transform parameters. As you found, this makes it nearly impossible to set a gate boundary above the plot boundary to include these points. FlowJo includes them because that are in the last bin.

The best approach to solve this is what you have done to change the transform such that the plot boundary is well above the intended gate boundary. A set of range gates or a Quadrant gate would also likely avoid this issue since they don't have outside gate boundaries.

Hope this helps and happy to discuss further,
Scott

[hbhargava7]

@whitews yeah reading more about flowjo bins this definitely makes sense.

as a user it's key to watch out for this issue. probably some kind of warning flag would be a good feature (flowkit count vs flowjo mismatch). though if there's not a way to programmatically get the flowjo gate counts it prob won't be straightforward. "gate intersects chart edge" warning could also be an option.

as always thanks for all your great work on this tool!

[whitews]

Glad I could help and agree that FlowJo users should watch out for this issue. I believe the combo of binning and the plot boundaries being tied to transform parameters is why FlowJo displays the aggressive red warning message about events on the chart edges.

For your idea about some kind of warning that FlowKit could issue, I'll think some more about how this could be done. The first step would be to prove we can reliably determine where the plot edges were in FlowJo given a channel's transform parameters. I would assume this would be near 1.0 in the transformed space, but the "biex" transform FlowJo defaults to scales from 0 to 4096 (not 0 to 1). If I were to implement this it would probably be in the analyze_samples method. Again, I'll have to think more about the best way to do this.