Improving and centralizing documentation

[rob-p]

This discussion started as an issue by @wmacnair, but was moved here to allow a more expansive discussion on the issues raised; thanks, Will!

Hi

I've been using alevin-fry and friends to do my first ever mapping of FASTQ files, and I'm really appreciating the speed of the package, and the functionality for handling spliced + unspliced reads very naturally.

However I'm finding myself frustrated by the documentation. Some observations / questions / frustrations:

• The tutorials for the alevin-fry package do not refer to various useful additional packages. The only references to alevinQC and usefulaf in the alevin-fry codebase are in the README. (I only discovered them just now, so having followed the tutorial I think I have to rerun my pipeline adding --dumpFeatures to the salmon alevin step.)
• The tutorials are currently in the form of blog posts, which makes it hard for users to know which is most relevant to them.
• I think that some of the tutorials are not up-to-date (e.g. referring to a roll-your-own loadFry function, instead of the one implemented in fishpond and / or usefulaf).
• I would find it useful to have something like a landing page, with a diagram showing all the relevant packages, their functionalities and how they interact.
• One absolutely essential task is loading the counts matrices into either sce or anndata objects, and this currently feels suboptimal. Both usefulaf and fishpond have quite a bit of other functionality, and usefulaf has a cool but non-obvious name. I wonder if something like an AlevinToSCE package which includes some of the AlevinQC functionality could be an option? [sce import package] could include: create an sce object from expected outputs; perhaps allow the sce creation function to have different options, e.g. knee / all / min bcs (I don't know how that would fit with the rest of the pipeline); allow me to view knee plots (I know that alevin-fry has the -knee option, but I will almost always want to check this myself); extract the profile of the empty droplets.

I'm a pretty experienced user of R packages for single cell analysis, trying out mapping for the first time with alevin-fry. It could well be that I've misunderstood something here, or missed some functionality, in which consider that as feedback about documentation :) I've been able to find most things, but I think finding your way around could definitely be made easier.

I appreciate that you have far too many things to do, but if / when you get around to tweaking documentation, please take these points into consideration!

Thanks for all your hard work
Will

[rob-p]

Hi @wmacnair,

Thanks again for this great feedback. I agree 💯 % that organizing, centralizing, and improving the documentation is very important. I also agree with the idea of having a landing page to organize everything. Rather than creating yet another webpage, I was thinking of repurposing the front page or top link of the read the docs for this purpose.

I also agree that an overall diagram showing how all of these things fit together would be very nice, and would help organize people's thoughts as they enter the alevin-fry ecosystem. Then, we could organize the landing page into e.g. tutorials, companion packages (organized by function etc.), other support documents, etc. I think @DongzeHE can help lead this effort!

Regarding making use of AlevinQC with alevin-fry, you should not have to re-run the salmon alevin step, as alevin-fry itself should output all of the relevant metrics needed by AlevinQC. Is there a particular issue you ran into there? This also seems like a nice topic for a tutorial / support page.

Hopefully, this discussion will act as a jumping off point for further ... discussion, about specific ways in which we can improve the documentation and "findability" of the different features / capabilities of alevin-fry.

Thanks!
Rob

[wmacnair]

Hey

These all sound like great options for implementing the suggestions.

Thanks for the tip on alevinQC - I think in the intervening hours I had got to the same conclusion myself, although with less certainty. Just need to update my entire Bioconductor to make use of the most recent version, then will try it out. Certainly easier than trying to parse .bin files myself...

I think if you just had a landing page with a "map" of the packages, a short para on what alevin-fry does, then a heading of something like "What do you want to do?" with links to tutorials + packages, that would be great. And hopefully easy to maintain :)

Happy to give feedback on any changes you're considering.

Best
Will