Documentation feedback

[Nick-Eagles]

Hello,

First of all, thanks for developing this extraordinary ecosystem of analysis tools for spatial data. While Giotto suite is clearly a powerful set of tools, I found certain aspects of the documentation hard to navigate for a beginner, and I worry that the steep learning curve may detract from the usability of the software.

The first specific concern I had was that the multi-scale capabilities demonstrated in the preprint did not have an obvious location in the documentation. For example, how can one store segmented cells and Visium HD bins, both associated with expression, on the same spatial area? Can expression then be aggregated across spatial units (summing expression across large, uniform bins)? Since this was a particularly impressive feature of Giotto, I spent some time looking into this. My first instinct was to look at the Spatial Manipulation tutorials, which did not seem to show this functionality. I then hoped I could just search by function (i.e. here), and arrived upon createSpatialGrid.

This brought me to my second concern: the function documentation is often not descriptive enough to convey purpose or customization options to a beginner. It's not obvious what it means to "create a spatial grid" and parameters like name, method, and minimum_padding have descriptions that mostly repeat the parameter name without additional explanation. Other various functions I explored had a similar problem, like spatFeatPlot2D's parameters gimage, feats, show_network, edge_alpha, etc. In the latter case, I recognize and appreciate the thorough vignettes like this which do a good job walking through visualization functions, but descriptive function documentation goes a long way in making functions usable on user-specific data, particularly for beginners like me who don't know which vignette to search.

A final recommendation I have is providing more thorough descriptions for very common parameters like feat_type and spat_unit. Adding links here to vignettes describing core Giotto concepts would go a long way (and the use of @inheritParams here might make changes less repetitive).

I hope these come across as helpful suggestions, and recognize that an extraordinary amount of effort has already been put in to document such a wide range of useful functionality that Giotto provides. Thanks!

Best,
-Nick

[lcolladotor]

Thanks Nick for sharing this! ^^

And thanks Giotto team for making and maintaining it! Kudos to you 💯

[RubD]

Thanks @Nick-Eagles and @lcolladotor ! This is amazing and we really appreciate your feedback. As you probably know documentation is probably as important as the actual code and you might have already noticed that @jiajic and @josschavezf - together with many others - have been adding a lot of tutorials and examples lately.

Your input will certainly help us to learn where some of our major holes are and how we can prioritize our efforts with the (sometimes) limited time we have. Feel free to keep adding additional suggestions for improvements as you encounter them.