Adding parse_wsp docstring to ReadTheDocs

[matthewn6]

Just a comment that it would be useful to include some details from parse_wsp's docstring somewhere in the ReadTheDocs documentation. I have been searching for why a sample that had a unique gate, but was in multiple groups, was giving me an error. This is described perfectly in the docstring -

If you add a sample to 2 groups,
# then try to make a gate in one of the groups, the sample will have the
# same gate tree in the other group as well. So, it doesn't seem possible
# for a sample to have multiple gating strategies in the same workspace..

Maybe a good place to put it would be in the Workspace class documentation, as a Limitations section - this would help illuminate current discrepancies between FlowJo and FlowKit, and possibly strategies to navigate around them. What do you think?

[whitews]

Hi Matthew,

Yes, there are probably a lot of useful comments in the codebase that could be extracted as documentation content. All the classes, modules, and functions in ReadTheDocs are automatically created, so these would have to live somewhere else in a dedicated RST file (like the tutorials). Options that come to mind are:

1. a FAQ page
2. a dedicated doc page on FlowJo compatibility

I've had an open issue to create a FAQ (#53) for a while, but never started it. This option would be good in that anything can be added to it and it's easy to link to from the main README on GitHub. TBH though, I'm not sold on the FAQ concept because the topics aren't easily browsable and whenever I've come across one I feel like it has a "don't bother me" vibe.

Adding a dedicated page for FJ related stuff isn't a bad idea. I suspect the majority of FlowKit users are using the library because it supports reading FJ wsp files. There's certainly a lot of info to add related to the topic...it's quite complex as you probably know from reading the comments in the code.

Which option do you think is best?

Also, I'm curious if you are using the parse_wsp function directly or just found it when looking for info?

Regards,
Scott

[matthewn6]

Hey Scott,

I found FlowKit while searching for a package I could extract data points from FlowJo into python for downstream analysis that doesn't rely on FlowJo's limited set - maybe there are others who found it for the same reason.

I think it may actually be worth just adding the details in the Workspace tutorial, since you've already included lots of comments about converting from FlowJo there. Are Workspaces only for users converting from FlowJo wsp files, or do users who bring raw FCS files also use Workspaces?

I found the parse_wsp function while I was debugging and I realized the workspace wasn't importing unique gates for my sample.

Best,
Matthew