flowjo_fasinh_trans exported into FlowJo workspace uses incorrect value for width basis

[alexheubeck]

Hi all,

I'm using the flowjo_fasinh_trans function to transform Aurora data in this method:

chnls <- colnames(gs)
fluorchnls <- chnls[9:34]
trans.obj <- flowjo_fasinh_trans(t=4194304, m = 3, a = 0, length=1)
transList <- transformerList(fluorchnls, trans.obj)
gs <- transform(gs,transList)

Then, after applying the gating template, I use gatingset_to_flowjo:

outFile <- paste(Output, 'FlowJo Export', ".wsp", sep="")
gatingset_to_flowjo(gs, outFile)

When I open the FlowJo workspace, the scaling on the fluor channels looks like this:

It looks like FlowJo is using the 't' value as the width basis rather than the 'm' value. When I change 't' to something else (like 100,000), the width basis is changed to the same value.

Do I have something set up wrong, or is this a bug? Thanks!

[mikejiang]

Width Basis used to be only used in biexp, and I believe bringing it to fasinh is pretty recent thing by flowJo. So when we implemented flowjo_to_gatingset and gatingset_to_flowjo, width basis (or W) didn't exist thus isn't actually handled right now. Here is from the legacy wsp file

<transforms:fasinh transforms:length="256"  transforms:maxRange="12000"  transforms:T="12000"  transforms:A="0.6989700043"  transforms:M="4.079181246" >

As shown, there is no W parameter .

and here is our fasinh in R

flowjo_fasinh(m , t, a , length)

m  numeric the full width of the transformed display in asymptotic decades
t  numeric the maximum value of input data
a  numeric Additional negative range to be included in the display in asymptotic decades
length  numeric the maximum value of transformed data

So, in your flowjo_fasinh_trans(t=4194304, m = 3, a = 0, length=1), there is no definition for width basis definition, m here is full decades, has nothing to do with width basis. The value you see (-4.19e6) in flowjo is actually correct, which is the -t , the default behavior of flowjo fasinh if you don't manually change its value.

[alexheubeck]

Thanks Mike, that makes sense. The way I have been using it, m corresponds to the width value in FlowJo. For example, I found that setting m = 3 gives the same visual result as setting the width basis to -1000. And it actually matches the axis of the slider in FlowJo:

I think the width value that FlowJo uses equals -10^`m'.

Edit: Is FlowJo trying to display the cofactor for the arcsinh transform with that value? Only other thing I can think of

[jacobpwagner]

With the current versions of the packages there's actually an issue with transformations added by flowjo_fasinh_trans not being exported correctly. For example (based on @alexheubeck 's code):

library(flowCore)
library(flowWorkspace)
library(CytoML)

fcs <- list.files(system.file("extdata", package = "flowWorkspaceData"), pattern="CytoTrol", full.names = TRUE)
cs <- load_cytoset_from_fcs(fcs)

comps <- lapply(cs, function(cf) spillover(cf)$SPILL)
gs <- GatingSet(cs)
gs <- compensate(gs, comps)

chnls <- colnames(gs)
fluorchnls <- chnls[5:11]

trans.obj <- flowjo_fasinh_trans(t=4194303, m=3, a=0, length=1)
transList <- transformerList(fluorchnls, trans.obj)

gs <- transform(gs, transList)

# gatingset_to_flowjo will error out if there are no gates,
# which is a separate issue
rg <- rectangleGate(filterId="dummy_gate", "B710-A"=c(0.1, Inf))
gs_pop_add(gs, rg, parent = "root")
recompute(gs)

outFile <- tempfile()
gatingset_to_flowjo(gs, outFile)

If you examine the XML in outFile, the transformations are linear:

  <Transformations>                                                                                                                                                                                                                                    
    <transforms:linear transforms:minRange="0" transforms:maxRange="262143" gain="1">                                                                                                                                                                   
     <data-type:parameter data-type:name="FSC-A" />                                                                                                                                                                                                     
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="0" transforms:maxRange="262143" gain="1">                                                                                                                                                                   
     <data-type:parameter data-type:name="FSC-H" />                                                                                                                                                                                                     
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="0" transforms:maxRange="262143" gain="1">                                                                                                                                                                   
     <data-type:parameter data-type:name="FSC-W" />                                                                                                                                                                                                     
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="0" transforms:maxRange="262143" gain="1">                                                                                                                                                                   
     <data-type:parameter data-type:name="SSC-A" />                                                                                                                                                                                                     
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-B710-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-R660-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-R780-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-V450-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-V545-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-G560-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="-0.00192" transforms:maxRange="0.59866" gain="1">                                                                                                                                                           
     <data-type:parameter data-type:name="Comp-G780-A" />                                                                                                                                                                                               
    </transforms:linear>                                                                                                                                                                                                                                
    <transforms:linear transforms:minRange="0.4" transforms:maxRange="26012.80078" gain="0.01">                                                                                                                                                         
     <data-type:parameter data-type:name="Time" />                                                                                                                                                                                                      
    </transforms:linear>                                                                                                                                                                                                                                
   </Transformations> 

You can also see that there is no type attribute with value "fasinh":

> gh_get_transformations(gs[[1]])
$`B710-A`
function(x){ #copied fom c++ code
    length * ((asinh(x * sinh(m * log(10)) / t) + a * log(10)) / ((m + a) * log(10)))
  }
<bytecode: 0x5587c34050f0>
<environment: 0x5587c8cb1298>

$`R660-A`
function(x){ #copied fom c++ code
    length * ((asinh(x * sinh(m * log(10)) / t) + a * log(10)) / ((m + a) * log(10)))
  }
<bytecode: 0x5587c34050f0>
<environment: 0x5587c8cb1298>
...

This is due to flowJo_fasinh not being a recognized name here: https://github.com/RGLab/flowWorkspace/blob/879af942b16b10861b31e7585773820261d719dd/R/parse_transformer.R#L9-L15

We also just need to add a case to construct the cytolib::fasinhTrans here: https://github.com/RGLab/flowWorkspace/blob/879af942b16b10861b31e7585773820261d719dd/src/R_GatingHierarchy.cpp#L146-L195

I have the fix pretty much ready and am just testing it out. I just wanted to document the issue/rationale.

[jacobpwagner]

@alexheubeck. Before I close this, can you verify that this is working correctly after that commit?: https://github.com/RGLab/flowWorkspace/commit/c4498b1bbc8d7854403320c5b8c0300fbb969df1.

[alexheubeck]

It is working correctly now, thanks!

[jacobpwagner]

Good to hear. I'll go ahead and close this then.