Merge pull request #53 from HiDiHlabs/restructure

Restructure codebase

Author: niklasmueboe

.pre-commit-config.yaml

@@ -21,3 +21,16 @@ repos:
       - id: ruff
       # Formatter
       - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - "numpy"
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        exclude_types: ["jupyter", "svg"]
+        additional_dependencies:
+          - tomli

README.md

@@ -37,8 +37,8 @@ In a first step, we define a number of parameters for the analysis:
 import pandas as pd
 import ovrlpy
 
-# define ovrlpy analysis parameters:
-n_expected_celltypes = 20
+# define ovrlpy analysis parameters
+n_components = 20
 
 # load the data
 coordinate_df = pd.read_csv('path/to/coordinate_file.csv')
@@ -51,53 +51,46 @@ you can then fit an ovrlpy model to the data and create a signal integrity map:
 
 ```python
 # fit the ovrlpy model to the data
-signal_integrity, signal_strength, visualizer = ovrlpy.run(
-    coordinate_df, n_expected_celltypes=n_expected_celltypes
+dataset = ovrlpy.Ovrlp(
+    coordinate_df,
+    n_components=n_components,
+    n_workers=4,  # number of threads to use for processing
 )
+
+dataset.analyse()
 ```
 
-returns a signal integrity map, a signal map and a visualizer object that can be used to visualize the data:
+after fitting we can visualize the data ...
 
 ```python
-visualizer.plot_fit()
+fig = ovrlpy.plot_pseudocells(dataset)
 ```
 ![plot_fit output](docs/resources/plot_fit.png)
 
 
-and visualize the signal integrity map:
+... and the signal integrity map
 
 ```python
-fig, ax = ovrlpy.plot_signal_integrity(signal_integrity, signal_strength, signal_threshold=4)
+fig = ovrlpy.plot_signal_integrity(dataset, signal_threshold=4)
 ```
 
 ![plot_signal_integrity output](docs/resources/xenium_integrity_with_highlights.svg)
 
 Ovrlpy can also identify individual overlap events in the data:
 
 ```python
-doublet_df = ovrlpy.detect_doublets(
-    signal_integrity, signal_strength, minimum_signal_strength=3, integrity_sigma=2
-)
-
-doublet_df.head()
+doublets = dataset.detect_doublets(min_signal=4, integrity_sigma=1)
 ```
 
-And use the visualizer to show a 3D visualization of the overlaps in the tissue:
+And plot a multi-view visualization of the overlaps in the tissue:
 
 ```python
 # Which doublet do you want to visualize?
-n_doublet_case = 0
+doublet_to_show = 0
 
-x, y = doublet_df.loc[doublet_case, ["x", "y"]]
+x, y = doublets["x", "y"].row(doublet_to_show)
 
-ovrlpy.plot_region_of_interest(
-    x,
-    y,
-    coordinate_df,
-    visualizer,
-    signal_integrity,
-    signal_strength,
-)
+fig = ovrlpy.plot_region_of_interest(dataset, x, y, window_size=window_size)
 ```
 
 ![plot_region_of_interest output](docs/resources/plot_roi.png)

docs/source/conf.py

@@ -52,15 +52,20 @@
 
 nitpicky = True
 nitpick_ignore = [
+    ("py:class", "numpy.typing.DTypeLike"),
+    ("py:class", "polars.DataFrame"),
+    ("py:class", "polars.DataType"),
+    ("py:class", "umap.UMAP"),
     ("py:class", "optional"),
 ]
 
 intersphinx_mapping = dict(
+    anndata=("https://anndata.readthedocs.io/en/stable/", None),
     matplotlib=("https://matplotlib.org/stable/", None),
     numpy=("https://numpy.org/doc/stable/", None),
     pandas=("https://pandas.pydata.org/pandas-docs/stable/", None),
+    polars=("https://docs.pola.rs/api/python/stable/", None),
     python=("https://docs.python.org/3", None),
-    scanpy=("https://scanpy.readthedocs.io/en/stable/", None),
     scipy=("https://docs.scipy.org/doc/scipy/", None),
     sklearn=("https://scikit-learn.org/stable/", None),
     umap=("https://umap-learn.readthedocs.io/page/", None),

docs/source/tutorials/vizgen_liver.ipynb

@@ -17,16 +17,16 @@ Functions to read the data in the correct format are available for common file f
    import ovrlpy
 
    # Define analysis parameters for ovrlpy
-   kde_bandwidth = 2  # The smoothness of the kernel density estimation (KDE)
-   n_expected_celltypes = 20  # Number of expected cell types in the data
+   kde_bandwidth = 2.5  # smoothness of the kernel density estimation (KDE)
+   n_components = 20  # number of principal components, depends on the data complexity
 
    # Load your spatial transcriptomics data from a CSV file
    coordinate_df = pd.read_csv('path/to/coordinate_file.csv')
 
 
 In this step, we load the dataset and configure the model parameters, such as
 `kde_bandwidth` (to control smoothness) and
-`n_expected_celltypes` (to set the expected number of cell types).
+`n_components` (to set the number of prinicpal components that will be used).
 
 2. Fit the ovrlpy Model
 _______________________
@@ -36,17 +36,13 @@ Fit the **ovrlpy** model to generate the signal integrity map.
 .. code-block:: python
 
    # Fit the ovrlpy model to the spatial data
-   integrity, signal, visualizer = ovrlpy.run(
-       df=coordinate_df,
+   dataset = ovrlpy.Ovrlp(
+       coordinate_df,
        KDE_bandwidth=kde_bandwidth,
-       n_expected_celltypes=n_expected_celltypes
+       n_components=n_components,
+       n_workers=4,  # number of threads to use for processing
    )
-
-This function generates:
-
-- **integrity**: The signal integrity map.
-- **signal**: The signal map representing the strength of spatial expression signals.
-- **visualizer**: A visualizer object that helps to plot and explore the results.
+   dataset.analyse()
 
 3. Visualize the Model Fit
 __________________________
@@ -55,8 +51,7 @@ Once the model is fitted, you can visualize how well it matches your spatial dat
 
 .. code-block:: python
 
-   # Use the visualizer object to plot the fitted signal map
-   visualizer.plot_fit()
+   fig = ovrlpy.plot_pseudocells(dataset)
 
 This plot gives you a visual representation of the models fit to the spatial transcriptomics data.
 
@@ -67,8 +62,7 @@ Now, plot the signal integrity map using a threshold to highlight areas with str
 
 .. code-block:: python
 
-   # Plot the signal integrity map with a signal threshold
-   fig, ax = ovrlpy.plot_signal_integrity(integrity, signal, signal_threshold=4.0)
+   fig = ovrlpy.plot_signal_integrity(dataset, signal_threshold=4)
 
 
 5. Detect and Visualize Overlaps (Doublets)
@@ -79,39 +73,29 @@ Identify overlapping signals (doublets) in the tissue and visualize them.
 .. code-block:: python
 
    # Detect doublet events (overlapping signals) in the dataset
-   doublet_df = ovrlpy.detect_doublets(
-       integrity,
-       signal,
-       signal_cutoff=4,  # Threshold for signal strength
-       integrity_sigma=1  # Controls the coherence of the signals
+   doublets = dataset.detect_doublets(
+       min_signal=4,  # threshold for signal strength
+       integrity_sigma=1,  # controls the coherence of the signals
    )
 
-   # Display the detected doublets
-   doublet_df.head()
+   doublets.head()
 
 6. 3D Visualization of a Doublet Event
 ______________________________________
 
-Visualize a specific overlap event (doublet) in 3D to see how it looks in the tissue.
+Visualize a specific overlap event (doublet) to see how it looks in the tissue.
 
 .. code-block:: python
 
-   # Parameters for 3D visualization
+   # Parameters for the visualization
    window_size = 60  # Size of the visualization window around the doublet
    doublet_to_show = 0  # Index of the doublet to visualize
 
-   # Get the coordinates of the doublet event
-   x, y = doublet_df.loc[doublet_to_show, ["x", "y"]]
+   # Coordinates of the doublet event
+   x, y = doublets["x", "y"].row(doublet_to_show)
 
    # Plot the doublet event with 3D visualization
-   _ = ovrlpy.plot_region_of_interest(
-      x, y,
-      coordinate_df,
-      visualizer,
-      signal_integrity,
-      signal_strength,
-      window_size=window_size,
-   )
+   fig = ovrlpy.plot_region_of_interest(dataset, x, y, window_size=window_size)
 
-This visualization shows a 3D representation of the spatial overlap event, giving more
-insight into the structure and coherence of the signals.
+This visualization shows a top/bottom/side representation of the spatial overlap event,
+giving more insight into the structure and coherence of the signals.

docs/source/tutorials/xenium_brain.ipynb

@@ -1,18 +1,17 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from . import io
-from ._ovrlp import (
-    Visualizer,
-    compute_VSI,
-    detect_doublets,
-    get_pseudocell_locations,
+from ._ovrlp import Ovrlp
+from ._plotting import (
+    SCALEBAR_PARAMS,
+    plot_pseudocells,
     plot_region_of_interest,
     plot_signal_integrity,
-    pre_process_coordinates,
-    run,
-    sample_expression_at_xy,
+    plot_tissue,
+    plot_umap,
 )
-from ._utils import SCALEBAR_PARAMS, UMAP_2D_PARAMS, UMAP_RGB_PARAMS
+from ._subslicing import process_coordinates
+from ._utils import UMAP_2D_PARAMS, UMAP_RGB_PARAMS
 
 try:
     __version__ = version("ovrlpy")
@@ -24,15 +23,13 @@
 
 __all__ = [
     "io",
-    "compute_VSI",
-    "detect_doublets",
-    "sample_expression_at_xy",
-    "get_pseudocell_locations",
+    "Ovrlp",
+    "plot_pseudocells",
     "plot_region_of_interest",
     "plot_signal_integrity",
-    "pre_process_coordinates",
-    "Visualizer",
-    "run",
+    "plot_tissue",
+    "plot_umap",
+    "process_coordinates",
     "SCALEBAR_PARAMS",
     "UMAP_2D_PARAMS",
     "UMAP_RGB_PARAMS",