BCR tutorial (#542)

* Added beta-version v2 of bcr tutorial and adapted corresponding file accordingly; tested to add two citations into .bib file

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fixed issues with citation, leading to a fail of build-the-docs

* Added missing citations and removed references to in-work functions

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fixed an issue with one citation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Updated glossary to match new BCR functionalities and offer the user easy-access literature

* Reference to new glossary entries

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fixed faulty citation

* Update tutorial

* update tutorial

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update notebook

* Update tutorial

* Discussion regarding bimodality of dataset

* Remove sections that will be added in separate PR

* Improve wording

* Update CHANGELOG

* Add BCR tutorial to CI

* Fix glossary link

* Glossary updates

* Update references to preprocessing tools

* Fix function reference

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Gregor Sturm <[email protected]>
Co-authored-by: Gregor Sturm <[email protected]>

.github/workflows/test-tutorials.yaml

@@ -23,6 +23,7 @@ jobs:
         tutorial:
           - tutorial_3k_tcr.ipynb
           - tutorial_io.ipynb
+          - tutorial_5k_bcr.ipynb
         os:
           - ubuntu-latest
         python:

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning][].
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
+## [Unreleased]
+
+### Documentation
+
+-   Add a tutorial for BCR analysis with Scirpy ([#542](https://github.com/scverse/scirpy/pull/542)).
+
 ## v0.19.0
 
 ### Additions

docs/glossary.rst

@@ -49,6 +49,16 @@ Glossary
         :term:`CDR3<CDR>` nucleotide sequences, but might recognize the same antigen
         because they have the same or similar CDR3 amino acid sequence.
 
+        This is especially relevant for BCR, because clonally related cell are likely to differ due to
+        :term:`somatic hypermutation <SHM>`. It is important to understand that there is currently no best practice or
+        go-to approach on how to define clonotype cluster for BCR, as it remains an active research
+        field (:cite:`Yaari.2015`). There exist many different approaches such as maximum-likelihood (:cite:`Ralph.2016`),
+        hierarchical clustering (:cite:`Gupta.2017`), spectral clustering (:cite:`Nouri.2018`), natural language
+        processing (:cite:`Lindenbaum.2021`) and network based approaches (:cite:`BashfordRogers.2013`). A recent
+        comparison study indicates that computationally more sophisticated clonal inference approaches do not
+        outperform simplistic, computational cheaper ones (:cite:`Balashova.2024`). That said, there is still a
+        need for more in-depth comparison studies to confirm these results.
+
         See also: :func:`scirpy.tl.define_clonotype_clusters`.
 
     Private clonotype
@@ -190,7 +200,7 @@ Glossary
         Immune receptor.
 
     BCR
-        B-cell receptor. A BCR consiste of two Immunoglobulin (IG) heavy chains and
+        B-cell receptor. A BCR consists of two Immunoglobulin (IG) heavy chains and
         two IG light chains. The two light chains contain a variable region, which is
         responsible for antigen recognition.
 
@@ -201,12 +211,24 @@ Glossary
            under the `CC BY-4.0 <https://creativecommons.org/licenses/by/4.0/deed.en>`__ license,
            obtained from `wikimedia commons <https://commons.wikimedia.org/w/index.php?curid=49935883>`__
 
+    SHM
+        Common abbreviation for "Somatic hypermutation". This process is unique to BCR and occurs as part
+        of affinity maturation upon antigen encounter. This process further increases the diversity of the
+        variable domain of the BCR and selects for cells with higher affinity. SHM introduces around one point mutation per 1000
+        base pairs (:cite:`Kleinstein.2003`) and is able to introduce (although rare) deletions and/or insertions (:cite:`Wilson.1998`).
+        Furthermore, SHM is not a stochastic process, but biased in multiple ways (e.g. intrinsic hot-spot motifs (reviewed in :cite:`Schramm.2018`))
+
     Dual IR
         :term:`IRs<IR>` with more than one pair of :term:`VJ<V(D)J>` and
         :term:`VDJ<V(D)J>` sequences. While this was
         previously thought to be impossible due to the mechanism of allelic exclusion
-        (:cite:`Brady2010-gh`), there is an increasing amound of evidence for a *bona fide*
-        dual-IR population (:cite:`Schuldt2019`, :cite:`Ji2010-bn`, :cite:`Vettermann2010`).
+        (:cite:`Brady2010-gh`), there is an increasing amount of evidence for a *bona fide*
+        dual-IR population (:cite:`Schuldt2019`, :cite:`Shi.2019`, :cite:`RobertaPelanda.2014`,
+        :cite:`Ji2010-bn`, :cite:`Vettermann2010`).
+
+        Recent evidence suggest that also B cells with three or more productively rearranged
+        H and/or L chains exist (:cite:`Zhu.2023`), which indicates how much of B cell development
+        is still unclear.
 
         For more information on how *Scirpy* handles dual IRs, see the
         page about our :ref:`IR model<receptor-model>`.
@@ -239,8 +261,12 @@ Glossary
     Alellically included B-cells
         A B cell with two pairs of :term:`IG` chains. See :term:`Dual IR`.
 
+    Isotypically included B-cells
+        Similar to :term:`Alellically included B-cells`, but expresses both IGL and
+        IGK and thus rearrangements are not on alleles of the same gene (= isotypic inclusion).
+
     Clonotype modularity
-        The clonotype modularity measures how densly connected the transcriptomics
+        The clonotype modularity measures how densely connected the transcriptomics
         neighborhood graph underlying the cells in a clonotype is. Clonotypes with
         a high modularity consist of cells that are transcriptionally more similar
         than that of a clonotype with a low modularity.