BCR tutorial

[MKanetscheider]

Added beta-version v2 of bcr tutorial and adapted corresponding file so that I (hopefully) can visualize it with read-the-docs. I have drastically reduced the tutorial as I was very unsatisfied with the previous version. I will add soon further literature to the .bib file and adapt the glossary to make the tutorial more precise and less overwhelming, while still providing any interested user with additional information.

I would be happy for any feedback (@FFinotello @grst) to make the tutorial as good as it could possibly be!

Closes #199

• [ ] CHANGELOG.md updated
• [ ] Tests added (For bug fixes or new features)
• [ ] Tutorial updated (if necessary)

[review-notebook-app[bot]]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[MKanetscheider]

Hi, could you help me out, please? Why is here the readthedocs build failing... I don't really get the issue as there are only warnings, but no further details :/

[grst]

Warnings are treated as errors.

/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:40002: WARNING: could not find bibtex key "null.2022"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:40005: WARNING: could not find bibtex key "Suo.2023"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:60003: WARNING: could not find bibtex key "Lefranc.2003"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:60005: WARNING: could not find bibtex key "Suo.2023"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:120003: WARNING: could not find bibtex key "Zhu.2023"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:120014: WARNING: could not find bibtex key "Shi.2019"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170022: WARNING: term not in glossary: 'SHM'
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170024: WARNING: could not find bibtex key "Yaari.2015"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170026: WARNING: could not find bibtex key "Gupta.2017"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170026: WARNING: could not find bibtex key "Kepler.2014"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170028: WARNING: could not find bibtex key "Gupta.2017"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:170028: WARNING: could not find bibtex key "Yaari.2015"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:190002: WARNING: could not find bibtex key "Yaari.2015"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:190002: WARNING: could not find bibtex key "DeKosky.2013"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:190008: WARNING: could not find bibtex key "Clauset.2004"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:260004: WARNING: could not find bibtex key "Adams.2020"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:280002: WARNING: could not find bibtex key "Nutt.2015"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:320004: WARNING: could not find bibtex key "Finotello.2016"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:320004: WARNING: could not find bibtex key "Pelissier.2023"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:360002: WARNING: py:func reference target not found: scirpy.tl.hill_diversity_profile
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:380002: WARNING: could not find bibtex key "Chao.2014"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:400004: WARNING: py:func reference target not found: scirpy.tl.convert_hill_table
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:400004: WARNING: py:func reference target not found: scirpy.tl.hill_diversity_profile
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:420002: WARNING: could not find bibtex key "Jost.2010"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:530003: WARNING: could not find bibtex key "Kenneth.2017"
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:600003: WARNING: py:func reference target not found: scirpy.pl.logoplot_cdr3_motif
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:600003: WARNING: py:func reference target not found: scirpy.pl.logoplot_cdr3_motif
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:600006: WARNING: py:func reference target not found: scirpy.pl.logoplot_cdr3_motif
/home/docs/checkouts/readthedocs.org/user_builds/scirpy/checkouts/542/docs/tutorials/tutorial_5k_bcr.ipynb:640005: WARNING: py:func reference target not found: scirpy.tl.mutational_load

this means you are referring to citation keys and functions that don't exist.

[MKanetscheider]

Thanks a lot that makes sense...I will add the other citations and will for now exclude those references new functions as they are still in their own PR, but used in the notebook... 🥹

[MKanetscheider]

If the read the Docs build is succesfull we are able to investigate the tutorial on the website interface, right?

[grst]

If the read the Docs build is succesfull we are able to investigate the tutorial on the website interface, right?

yes

[MKanetscheider]

Hi, I adapted also the glossary a little bit to include some more information regarding B cells and B cell clustering, which is in my opinion important to know/clarify, but does confuse if included into the markdown text of the tutorial. I would have some questions that might need some discussion:

• is it possible to include the .h5mu file that I used to load the 5k B-cells for the tutorial somewhere into github? It is a rather large file (~2 600 000KB) so directly importing it into GitHub shouldn't work as far as I'm aware. Is there an alternative solution, because I think it's important that any user can experiment a bit with this toy dataset. Is there a way to implement the test data similar to the one you used for the TCR tutorial, i.e. load it with its own function call? If this is desired I would be happy to give it a try, but maybe you need to offer me some guidance as I'm not sure how "easy" this is for me :/
• this is somewhat of an overlap with the prior point, but should I upload the notebook, which contains the code to obtain this subsetted (down to 5k B cells) stephenson dataset, somewhere into Scirpy?
• lastly I want to report some kind of bug/issue that I recognized during my work in Scirpy and has to do with scirpy.tl.define_clonotype cluster (but likely also with scirpy.tl.define_clonotype, although this was not tested). Scirpy considers any string inside v_call (same problem with j_call) as a unique V-gene assignment, and this is perfectly fine for working with Cell Ranger annotation. However, if we are working with re-annotated data, which is done with IgBlastn or IMGT/Highv-quest this is not true any more. First, the annotation contains alleles, which are depicted like this IGHV3-33*001. The problem is that if another cell would have IGHV3-33*002 these two cells would always be separated by Scirpy (if v_gene = True), because Scirpy thinks that those are totally different genes, although they only differ in their alleles, even if everything else even the junction sequence can be quite similar. Another issue with using IgBlastn or IMGT/Highv-quest re-annotation is that they often leave multiple possible gene assignments into the v_call column if they are all similar likely. What I did so far with my datasets was that I manually manipulated the v_call and j_call column prior to loading the datatset into an AnnData object so that they only contain the first v/j_call and without the allele information.

My idea here would be to adapt the clonotype cluster function so that it automatically ignores multiple v_call's/j_call's i.e. only considers the first one and also ignores the allele information for clustering, but doesn't manipulate the call itself. Immcantation has a own parameter on how to work with multiple calls for a gene (see "parameter first= FALSE": https://scoper.readthedocs.io/en/stable/topics/hierarchicalClones/). Actually I encountered this problem already some time ago and discussed it with @felixpetschko but eventually we both forgot about it until now. Either way, I think it's good if @grst can also have a look on this problem and help with a solution, because if I remeber correctly it's not that trivial to "fix" this. Maybe there is some elegant workaround available?