Why you should PluginPlay

We love the extensibility of having plugins in FlowJo. It’s our belief that no one team can build all the tools needed to analyze the full breadth of data produced through the myriad of single cell assays, so collaborating with the other bioinformatics groups in the flow community is paramount to achieving our goal of improving human health. Collaborating has frequently meant finding a way to run within FlowJo an R-script developed by a brilliant data scientist, which entails making FlowJo, R, and the operating system play nicely together. This cozy relationship must then be maintained through updates to any one of the three. We understand this can be a challenging task, especially for those of you working in more regulated environments. This is why we’ve developed the FlowJo PluginPlay Bundle, a bundle of FlowJo plugins that will manage everything related to installation for you and allow you to focus on the science.

The FlowJo PluginPlay Bundle was inspired by a user who called into FlowJo’s Technical Support needing plugin help. Lisa (name changed for privacy) was a post-doc who, though proficient with FlowJo, had limited exposure to plugins. Her PI had requested she run FlowAI to QC her data. A request from a PI is akin to a mandate from the heavens, so Lisa tried everything to make it work. When I picked up the call that afternoon, I ran through the support questions typical to plugins, “Did you download the plugins? Did you install R? Did you install the R packages?”. She had… and had also diligently worked with her IT department to install R and troubleshoot the error messages. Her IT team couldn’t figure it out so they advised her to contact us directly. We set sail on a journey into the murky waters of computer privileges and R packages, trying to sort out the R package errors. Each time we solved one, another appeared. It was as if her machine did not want to run FlowAI. After hours of back and forth to no avail, with Lisa’s patience and time starting to wane, I thought to myself, “What if there was a way to send her my fully installed R folder that she could use instead of hers. FlowJo only needs to point to a working version of R”. I asked Lisa, with her PI’s irritation growing, if she could give me a night to think and one more chance to solve her problem. She agreed and I embarked on a vision quest.

To start, I looked for a blog, a tutorial, maybe a dissertation paper, anything that would help me. But we were not so lucky. It turns out there have been few attempts to run R as an executable or standalone. Those attempts had not worked, but they gave clues as to what was needed. I encountered some success, but then realized that so much of the foundation is hard coupled to the computer’s operating system (OS), meaning what worked for Yosemite might not work on Windows 10, or even El Capitan. I came up with a solution that I thought would work for Lisa and decided to figure out how to generalize it later. I sent a stripped down, pre-configured version of R to her in the morning. It failed… but it failed in a different way, a way dependent on OS specific code. Some libraries were OS specific; some were not. The solution was to grab the non-OS specific libraries and bundle them in the R folder, then re-write just the OS dependent libraries on install. It took many tries to figure out which libraries were which, and we worked through a couple of days of “what about this version” and Lisa replying “nope, same crash”. I was beginning to feel defeated, when I opened an e-mail from Lisa with the most beautiful combination of words, “It worked!”. The skies opened and I felt victorious, and very sleep deprived.

While you won’t necessarily have the same victorious relief that Lisa and I felt, we’re hopeful that we can save you from the hours of frustration and headaches. If you would like to try the new bundle, download it from the FlowJo Exchange, making sure to pick the build that matches the OS of your computer. Once downloaded, unzip it and put the .jar file in any folder on your computer. You’ll have to tell FlowJo which folder you picked, so the single set up step is to update that preference in FlowJo: Open FlowJo, navigate to the Preferences through the heart icon in the upper right-hand corner of the workspace, then select the Diagnostics tab. At the bottom of that screen there is a check box for ‘Check for plugins’ with a choose box to show the program where you’ve put the bundle’s Jar. Use the Choose button to navigate to the folder and that’s it. You’ll need to restart FlowJo, but going forward, FlowJo will check that folder and load the plugins contained in the bundle automatically, every time you start the program. No need to touch R.

In our initial offering we’ve included FlowAI, FlowClean, FlowSOM, IndexSort, and Violin Box plots. We hope this will offer you a complete high-dimensional workflow. We expect that moving forward, we’ll be able to include more of the plugins offered on the FlowJo Exchange in this bundle or others like it. Keep in mind that many plugins have no R dependency, and can be added to your FlowJo repertoire simply by downloading, unzipping, and dropping the .jar file into the same folder as the bundle .jar file. We haven’t worked out all of the details for every system yet; apologies M1 Mac users, there’s some nuance we need to solve, but overall, PluginPlay means you really can just plug the .jar into a folder and start to play. We hope this is valuable work toward enabling you to do the amazing work for which the flow community is famous. We would be pleased to hear how your experience was using PluginPlay, and if you have any suggestions for improvement. Happy flowing!

https://www.flowjo.com/exchange/#/plugin/profile?id=51