Populate examples folder with examples!

[giovp]

Hi All!

Here's a brief list of examples that we need to add to the repo. We'll really use your help to populate the example folder. Here's a description of the workflow to get you started.

Set up environemnt

• git clone most recent versions of squidpy and squidpy_notebooks.
• Install latest version of squidpy with pip install -e'.[dev,test]'
• run pre-commit install in both repos
• If some packages are missing in the installation bundle, please open an issue and install them accordingly

  Pick one of the available dataset

  Remember that only the visium datasets for the image functions. Also, don't use the 4i dataset for the co_occurrence example.

• sq.datasets.imc() good for graph
• sq.datasets.seqfish() good for graph
• sq.datasets.four_i() good for graph
• sq.datasets.four_i() good for graph
• sq.datasets.visium_fluo_adata() good for graph and image
• sq.datasets.visium_hne_adata() good for graph and image
• sq.datasets.visium_fluo_adata_crop() good for graph and image (cropped)
• sq.datasets.visium_hne_adata_crop() good for graph and image (cropped)
• sq.datasets.visium_fluo_image_crop() good for image container (cropped)
• sq.datasets.visium_hne_image_crop() good for image container (cropped)
• sq.datasets.visium_hne_image() good for image container (cropped)

Pick one of the available functions in the repo

graph

• [x] sq.gr.centrality_scores and sq.pl.centrality_scores
• [x] sq.gr.nhood_enrichment and sq.pl.nhood_enrichment
• [x] sq.gr.spatial_neighbors
• [x] sq.gr.ligrec and sq.pl.ligrec
• [x] sq.gr.ripley_k and sq.pl.ripley_k

image

(also have a look at #9 for existing image examples and let Hannah know if you start working on one of these.

• [x] sq.im.ImageContainer data structure (loading, layers, etc)
• [x] sq.im.ImageContainer.crop_corner and sq.im.ImageContainer.crop_center
• [x] crop iterators? (maybe)
• [ ] sq.pl.extract
• [x] sq.im.calculate_image_features with segmentation features (I think this is already done - no, segmentation features are not yet covered)
• [x] sq.im.process with custom processing function
• [x] sq.im.segment with custom segmentation function like pre-trained keras model?

Create a new branch ex_<module>_<fun>

for example git checkout -b ex_gr_ligrec

Follow the existing examples as reference

An example consists of a short, two liners explanation of the function of interest. If the function also has a related plotting function, then that function need also to be used and briefly described. See examples for that, for instance in #13 or the beautiful ones in cellrank

Try to think like a user who has zero familiarity with python/coding, so try to be detailed regarding what the function does, and maybe some specific arguments (e.g. in sq.gr.spatial_neighbors what's the difference between radius and rings?). There is no need to "interpret biologically" the result, but the function usage needs to be clear.

You can work on a jupyter notebook for that, but the files to be pushed needs as .py file. You can conveniently go back and forth with jupytext (install it with pip).

jupytext --to py:sphinx mynotebook.ipynb # create .py file
jupytext --to notebook mynotebook.py # create .ipynb file

this makes it very easy to go back and forth!

Make sure that lines of text don't go over 120 characters (easy that this happens in text part). Also, pre-commit check will flag other potential problems for you. precommit can be painful, if you are struggling with understanding some flags, contact us directly (on MM or here or anywhere else) and we'll be happy to help.

Also, remember that the text part will be rendered with rst (not md) so checkout this cheatsheet

You can locally generate the docs to check that everything looks good: tox -e docs

Open a new PR and ask us to review it !

Thank you!

[hspitzer]

Re converting .ipynb to .py: I found that I need to specify that I want to use the sphinx format to get correct results. Otherwise the cell blocks are marked by #+ and #- which seems not to work in the docs. Using

jupytext --to py:sphinx mynotebook.ipynb

uses the valid cell block marker ###########################.

Edit: updated to use sphinx instead of percent format.

[ilibarra]

Hey Guys. Just to clarify what's the final format for the py blocks?. Default or percent (using --to py:percent)?. Just confirm and/or link to parsed example.py.

[hspitzer]

Hey Guys. Just to clarify what's the final format for the py blocks?. Default or percent (using --to py:percent)?. Just confirm and/or link to parsed example.py.

The py file needs to be in a format readable by sphinx gallery: https://sphinx-gallery.github.io/stable/syntax.html This means using either #%% or ######################### as marker for text cells. After trying out several examples, I've come to the conclusion that using the percent format is not enough, as sometimes code cells seem to be represented wrongly in the docs. Using the sphinx format, however, works. This will use lines like this ############################### to mark text cells. Sorry for the confusion, I'm also very new at this.

TL;DR: use: jupytext --to py:sphinx mynotebook.ipynb

[giovp]

closed with #46