features on 1.5.1: leiden + gating on scatter

Author: quentinblampey

docs/api/tools.md

@@ -2,14 +2,18 @@
     options:
       show_root_heading: true
 
-::: scyan.tools.palette_level
+::: scyan.tools.leiden
     options:
       show_root_heading: true
 
 ::: scyan.tools.subcluster
     options:
       show_root_heading: true
 
+::: scyan.tools.palette_level
+    options:
+      show_root_heading: true
+
 ::: scyan.tools.cell_type_ratios
     options:
       show_root_heading: true
@@ -25,3 +29,13 @@
         - __init__
         - select
         - save_selection
+        - extract_adata
+  
+::: scyan.tools.PolygonGatingScatter
+    options:
+      show_root_heading: true
+      members:
+        - __init__
+        - select
+        - save_selection
+        - extract_adata

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "scyan"
-version = "1.5.0"
+version = "1.5.1"
 description = "Single-cell Cytometry Annotation Network"
 documentation = "https://mics-lab.github.io/scyan/"
 homepage = "https://mics-lab.github.io/scyan/"
@@ -14,11 +14,9 @@ classifiers = [
   "Operating System :: POSIX :: Linux",
   "Operating System :: Microsoft :: Windows",
   "Programming Language :: Python :: 3",
-  "Topic :: Scientific/Engineering"
-]
-packages = [
-    { include = "scyan" },
+  "Topic :: Scientific/Engineering",
 ]
+packages = [{ include = "scyan" }]
 
 [tool.poetry.dependencies]
 python = ">=3.8,<3.11"
@@ -32,25 +30,35 @@ FlowUtils = "^1.0.0"
 fcsparser = "^0.2.4"
 fcswrite = "^0.6.2"
 
-wandb = {version =  "0.13.7", optional = true}
-hydra-core = {version = "^1.2.0", optional = true}
-hydra-colorlog = {version = "^1.2.0", optional = true}
-hydra-optuna-sweeper = {version = "^1.2.0", optional = true}
+wandb = { version = "0.13.7", optional = true }
+hydra-core = { version = "^1.2.0", optional = true }
+hydra-colorlog = { version = "^1.2.0", optional = true }
+hydra-optuna-sweeper = { version = "^1.2.0", optional = true }
 
-pytest = {version = "^7.1.2", optional = true}
-ipykernel = {version = "^6.15.0", optional = true}
-ipywidgets = {version = "^7.7.1", optional = true}
-isort = {version = "^5.10.1", optional = true}
-black = {version = "^22.6.0", optional = true}
-mkdocs-material = {version = "^8.5.0", optional = true}
-mkdocstrings = {version = "^0.19.0", optional = true}
-mkdocstrings-python = {version = "^0.7.1", optional = true}
-mkdocs-jupyter = {version = "^0.21.0", optional = true}
+pytest = { version = "^7.1.2", optional = true }
+ipykernel = { version = "^6.15.0", optional = true }
+ipywidgets = { version = "^7.7.1", optional = true }
+isort = { version = "^5.10.1", optional = true }
+black = { version = "^22.6.0", optional = true }
+mkdocs-material = { version = "^8.5.0", optional = true }
+mkdocstrings = { version = "^0.19.0", optional = true }
+mkdocstrings-python = { version = "^0.7.1", optional = true }
+mkdocs-jupyter = { version = "^0.21.0", optional = true }
 
-leidenalg = {version = "^0.8.10", optional = true}
+leidenalg = { version = "^0.8.10", optional = true }
 
 [tool.poetry.extras]
-dev = ["pytest", "ipykernel", "ipywidgets", "isort", "black", "mkdocs-material", "mkdocstrings", "mkdocstrings-python", "mkdocs-jupyter"]
+dev = [
+  "pytest",
+  "ipykernel",
+  "ipywidgets",
+  "isort",
+  "black",
+  "mkdocs-material",
+  "mkdocstrings",
+  "mkdocstrings-python",
+  "mkdocs-jupyter",
+]
 hydra = ["wandb", "hydra-core", "hydra-colorlog", "hydra-optuna-sweeper"]
 discovery = ["leidenalg"]
 
@@ -65,7 +73,7 @@ python_files = "test_*.py"
 filterwarnings = [
   "ignore::DeprecationWarning",
   "ignore::UserWarning",
-  "ignore:::.*anndata*"
+  "ignore:::.*anndata*",
 ]
 
 [tool.black]
@@ -88,4 +96,4 @@ exclude = '''
 
 [tool.isort]
 profile = "black"
-skip_glob = ["*/__init__.py"]
+skip_glob = ["*/__init__.py"]

scyan/plot/density.py

@@ -27,7 +27,7 @@ def kde(
     """Plot Kernel-Density-Estimation for each provided population and for multiple markers.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         population: One population, or a list of population to be analyzed, or `None`. If not `None`, the population name(s) has to be in `adata.obs[key]`.
         markers: List of markers to plot. If `None`, the list is chosen automatically.
         key: Key to look for populations in `adata.obs`. By default, uses the model predictions.
@@ -97,7 +97,7 @@ def log_prob_threshold(adata: AnnData, show: bool = True):
         To use this function, you first need to fit a `scyan.Scyan` model and use the `model.predict()` method.
 
     Args:
-        adata: The `anndata` object used during the model training.
+        adata: The `AnnData` object used during the model training.
         show: Whether or not to display the figure.
     """
     assert (

scyan/plot/dot.py

@@ -27,7 +27,7 @@ def scatter(
     One scatter plot is displayed for each pair of markers.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         population: One population, or a list of population to be colored, or `None`. If not `None`, the population name(s) has to be in `adata.obs[key]`.
         markers: List of markers to plot. If `None`, the list is chosen automatically.
         n_markers: Number of markers to choose automatically if `markers is None`.
@@ -79,7 +79,7 @@ def umap(
         If you trained your UMAP with [scyan.tools.umap][] on a subset of cells, it will only display the desired subset of cells.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         color: Marker(s) or `obs` name(s) to color. It can be either just one string, or a list (it will plot one UMAP per element in the list).
         vmax: `scanpy.pl.umap` vmax argument.
         vmin: `scanpy.pl.umap` vmin argument.

scyan/preprocess.py

@@ -18,7 +18,7 @@ def auto_logicle_transform(
     We recommend it for flow cytometry or spectral flow cytometry data.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         q: See logicle article. Defaults to 0.05.
         m: See logicle article. Defaults to 4.5.
     """
@@ -73,7 +73,7 @@ def asinh_transform(adata: AnnData, translation: float = 0, cofactor: float = 5)
     """Asinh transformation for cell-expressions: $asinh((x - translation)/cofactor)$.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         translation: Constant substracted to the marker expression before division by the cofactor.
         cofactor: Scaling factor before computing the asinh.
     """
@@ -93,7 +93,7 @@ def inverse_transform(
         If you scaled your data, the complete inverse consists in running [scyan.preprocess.unscale][] first, and then this function.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         obsm: Name of the anndata obsm to consider. If `None`, use `adata.X`.
         obsm_names: Names of the ordered markers from obsm. It is required if obsm is not `None`, if there are less markers than in `adata.X`, and if the transformation to reverse is `logicle`. Usually, it corresponds to `model.var_names`.
         transformation: Name of the transformation to inverse: one of `['logicle', 'asinh', None]`. By default, it chooses automatically depending on which transformation was previously run.
@@ -148,7 +148,7 @@ def scale(adata: AnnData, max_value: float = 10, center: Optional[bool] = None)
     """Tranforms the data such as (i) `std=1`, and (ii) either `0` is sent to `-1` (for CyTOF data) or `means=0` (for flow or spectral flow data); except if `center` is set (which overwrites the default behavior).
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         max_value: Clip to this value after scaling.
         center: If `None`, data is only centered for spectral or flow cytometry data (recommended), else, it is centered or not according to the value given.
     """
@@ -175,7 +175,7 @@ def unscale(
     """Reverse standardisation. It requires to have run [scyan.preprocess.scale][] before.
 
     Args:
-        adata: An `anndata` object.
+        adata: An `AnnData` object.
         obsm: Name of the adata obsm to consider. If `None`, use `adata.X`.
         obsm_names: Names of the ordered markers from obsm. It is required if obsm is not `None`, and if there are less markers than in `adata.X`. Usually, it corresponds to `model.var_names`.
 

scyan/tools/__init__.py

@@ -1,4 +1,4 @@
-from .representation import umap, subcluster
+from .representation import umap, subcluster, leiden
 from .biomarkers import cell_type_ratios, mean_intensities
-from .gating import PolygonGatingUMAP
+from .gating import PolygonGatingUMAP, PolygonGatingScatter
 from .colors import palette_level

scyan/tools/gating.py

@@ -10,17 +10,17 @@
 
 
 class _SelectFromCollection:
-    """From https://matplotlib.org/stable/gallery/widgets/polygon_selector_demo.html"""
+    """Updated from https://matplotlib.org/stable/gallery/widgets/polygon_selector_demo.html"""
 
-    def __init__(self, ax, collection, alpha_other=0.3):
+    def __init__(self, ax, collection, xy: np.ndarray, alpha_other: float = 0.3):
         from matplotlib.widgets import PolygonSelector
 
         self.canvas = ax.figure.canvas
         self.collection = collection
+        self.xy = xy
         self.alpha_other = alpha_other
 
-        self.xys = collection.get_offsets()
-        self.n_obs = len(self.xys)
+        self.n_obs = len(self.xy)
 
         self.fc = collection.get_facecolors()
         self.fc = np.tile(self.fc, (self.n_obs, 1))
@@ -32,41 +32,37 @@ def onselect(self, verts):
         from matplotlib.path import Path
 
         path = Path(verts)
-        self.ind = np.nonzero(path.contains_points(self.xys))[0]
+        self.ind = np.nonzero(path.contains_points(self.xy))[0]
         self.fc[:, -1] = self.alpha_other
         self.fc[self.ind, -1] = 1
         self.collection.set_facecolors(self.fc)
         self.canvas.draw_idle()
 
     def disconnect(self):
         self.poly.disconnect_events()
-        # TODO: understand why it crashes
-        # self.fc[:, -1] = 1
-        # self.collection.set_facecolors(self.fc)
-        # self.canvas.draw_idle()
 
 
 class PolygonGatingUMAP:
     """Class used to select cells on a UMAP using polygons.
 
     !!! note
 
-        We recommend using it on Jupyter Notebooks. To be able to select the cells, you should first run `%matplotlib tk` on a blank jupyter cell. After the selection, you can run `%matplotlib inline` to retrieve the default behavior.
+        If used on a Jupyter Notebook, you should first run `%matplotlib tk`. After the selection, you can run `%matplotlib inline` to retrieve the default behavior.
 
     ```py
-    # Usage example (to be run on a jupyter notebook) (`%matplotlib tk` is required for the cell selection)
+    # Usage example (`%matplotlib tk` is required for the cell selection on jupyter notebooks)
     >>> %matplotlib tk
     >>> selector = scyan.tools.PolygonGatingUMAP(adata)
     >>> selector.select()         # select the cells
-    >>> selector.save_selection() # save the selected cells in adata.obs
-    >>> %matplotlib inline        # to retrieve the default behavior
+
+    >>> sub_adata = selector.extract_adata() # on a notebook, this has to be on a new jupyter cell
     ```
     """
 
     def __init__(self, adata: AnnData) -> None:
         """
         Args:
-            adata: An `anndata` object.
+            adata: An `AnnData` object.
         """
         self.adata = adata
         self.has_umap = _has_umap(adata)
@@ -88,7 +84,7 @@ def select(self, s: float = 0.05) -> None:
             s=s,
         )
 
-        self.selector = _SelectFromCollection(ax, pts)
+        self.selector = _SelectFromCollection(ax, pts, self.x_umap[self.has_umap])
 
         log.info(
             f"Enclose cells within a polygon. Helper:\n    - Click on the plot to add a polygon vertex\n    - Press the 'esc' key to start a new polygon\n    - Try holding the 'ctrl' key to move a single vertex\n    - Once the polygon is finished and overlaid in red, you can close the window"
@@ -112,3 +108,95 @@ def save_selection(self, key_added: str = "scyan_selected"):
         log.info(
             f"Selected {len(self.selector.ind)} cells and saved the selection in adata.obs['{key_added}']"
         )
+
+    def extract_adata(self) -> AnnData:
+        """Returns an anndata objects whose cells where inside the polygon"""
+        log.info(f"Selected {len(self.selector.ind)} cells")
+        self.selector.disconnect()
+
+        return self.adata[np.where(self.has_umap)[0][self.selector.ind]]
+
+
+class PolygonGatingScatter:
+    """Class used to select cells on a scatterplot using polygons.
+
+    !!! note
+
+        If used on a Jupyter Notebook, you should first run `%matplotlib tk` on a blank jupyter cell. After the selection, you can run `%matplotlib inline` to retrieve the default behavior.
+
+    ```py
+    # Usage example (`%matplotlib tk` is required for the cell selection on jupyter notebooks)
+    >>> %matplotlib tk
+    >>> selector = scyan.tools.PolygonGatingScatter(adata)
+    >>> selector.select()         # select the cells
+
+    >>> sub_adata = selector.extract_adata() # on a notebook, this has to be on a new jupyter cell
+    ```
+    """
+
+    def __init__(self, adata: AnnData) -> None:
+        """
+        Args:
+            adata: An `AnnData` object.
+        """
+        self.adata = adata
+
+    def select(
+        self, x: str, y: str, s: float = 0.05, max_cells_display: int = 100_000
+    ) -> None:
+        """Open a scatter plot on which you can draw a polygon to select cells.
+
+        Args:
+            x: Column name of adata.obs used for the x-axis
+            y: Column name of adata.obs used for the y-axis
+            s: Size of the cells on the plot.
+        """
+        _, ax = plt.subplots()
+
+        indices = np.arange(self.adata.n_obs)
+        if max_cells_display is not None and max_cells_display < self.adata.n_obs:
+            indices = np.random.choice(
+                np.arange(self.adata.n_obs), size=max_cells_display, replace=False
+            )
+
+        x = self.adata.obs_vector(x)
+        y = self.adata.obs_vector(y)
+        xy = np.stack([x, y], axis=1)
+
+        pts = ax.scatter(
+            xy[indices, 0],
+            xy[indices, 1],
+            marker=".",
+            rasterized=True,
+            s=s,
+        )
+
+        self.selector = _SelectFromCollection(ax, pts, xy)
+
+        log.info(
+            f"Enclose cells within a polygon. Helper:\n    - Click on the plot to add a polygon vertex\n    - Press the 'esc' key to start a new polygon\n    - Try holding the 'ctrl' key to move a single vertex\n    - Once the polygon is finished and overlaid in red, you can close the window"
+        )
+        plt.show()
+
+    def save_selection(self, key_added: str = "scyan_selected"):
+        """Save the selected cells in `adata.obs[key_added]`.
+
+        Args:
+            key_added: Column name used to save the selected cells in `adata.obs`.
+        """
+        self.adata.obs[key_added] = "unselected"
+        col_index = self.adata.obs.columns.get_loc(key_added)
+        self.adata.obs.iloc[self.selector.ind, col_index] = "selected"
+        self.adata.obs[key_added] = self.adata.obs[key_added].astype("category")
+
+        self.selector.disconnect()
+        log.info(
+            f"Selected {len(self.selector.ind)} cells and saved the selection in adata.obs['{key_added}']"
+        )
+
+    def extract_adata(self) -> AnnData:
+        """Returns an anndata objects whose cells where inside the polygon"""
+        log.info(f"Selected {len(self.selector.ind)} cells")
+        self.selector.disconnect()
+
+        return self.adata[self.selector.ind]