sclab 0.1.7__tar.gz → 0.2.2__tar.gz

sclab-0.2.2/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025 Argenis Arriojas
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{sclab-0.1.7 → sclab-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: sclab
-Version: 0.1.7
+Version: 0.2.2
 Summary: sclab
 Author-email: Argenis Arriojas <ArriojasMaldonado001@umb.edu>
 Requires-Python: >=3.10,<3.13
@@ -10,23 +10,28 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE
 Requires-Dist: anndata
 Requires-Dist: anywidget
 Requires-Dist: ipywidgets
 Requires-Dist: itables
 Requires-Dist: numpy<2.2
 Requires-Dist: pandas
-Requires-Dist: plotly
-Requires-Dist: scanpy
+Requires-Dist: plotly<6.0
+Requires-Dist: requests>=2.32.3
 Requires-Dist: scikit-learn
-Requires-Dist: scikit-misc
 Requires-Dist: svgpathtools
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: jupyterlab>=4.3.6 ; extra == "jupyter"
+Requires-Dist: scanpy[leiden, skmisc]>=1.10 ; extra == "scanpy"
 Requires-Dist: pytest>=8.3.4 ; extra == "test"
 Project-URL: Bug Tracker, https://github.com/umbibio/sclab/issues
 Project-URL: Changelog, https://github.com/umbibio/sclab/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/umbibio/sclab/docs
 Project-URL: Homepage, https://github.com/umbibio/sclab
 Project-URL: Repository, https://github.com/umbibio/sclab.git
+Provides-Extra: jupyter
+Provides-Extra: scanpy
 Provides-Extra: test
 
 # SCLab
@@ -53,23 +58,29 @@ pip install sclab
 Open a Jupyter Notebook and run the following:
 
 ```python
+from IPython.display import display
 from sclab import SCLabDashboard
+from sclab.examples.processor_steps import QC, Preprocess, PCA, Neighbors, UMAP, Cluster
 import scanpy as sc
-from IPython.display import display
 
 # Load your data
 adata = sc.read_10x_h5("your_data.h5")
 
 # Create dashboard
 dashboard = SCLabDashboard(adata, name="My Analysis")
+# Add desired processing steps to the interface
+dashboard.pr.add_steps({"Processing": [QC, Preprocess, PCA, Neighbors, UMAP, Cluster]})
 
 # Display dashboard
 display(dashboard)
 
 # The dashboard provides easy access to components:
-dashboard.ds  # Dataset (wrapper for AnnData)
-dashboard.pl  # Plotter
-dashboard.pr  # Processor
+# dashboard.ds  # Dataset (wrapper for AnnData)
+# dashboard.pl  # Plotter
+# dashboard.pr  # Processor
+
+# the resulting AnnData object is found within the dataset object:
+# dashboard.ds.adata
 ```
 
 ## Components
@@ -129,10 +140,10 @@ This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICE
 If you use SCLab in your research, please cite:
 
 ```bibtex
-@software{sclab2024,
+@software{sclab2025,
   author = {Arriojas, Argenis},
   title = {SCLab: Interactive Single-Cell Analysis Toolkit},
-  year = {2024},
+  year = {2025},
   publisher = {GitHub},
   url = {https://github.com/umbibio/sclab}
 }

{sclab-0.1.7 → sclab-0.2.2}/README.md

@@ -22,23 +22,29 @@ pip install sclab
 Open a Jupyter Notebook and run the following:
 
 ```python
+from IPython.display import display
 from sclab import SCLabDashboard
+from sclab.examples.processor_steps import QC, Preprocess, PCA, Neighbors, UMAP, Cluster
 import scanpy as sc
-from IPython.display import display
 
 # Load your data
 adata = sc.read_10x_h5("your_data.h5")
 
 # Create dashboard
 dashboard = SCLabDashboard(adata, name="My Analysis")
+# Add desired processing steps to the interface
+dashboard.pr.add_steps({"Processing": [QC, Preprocess, PCA, Neighbors, UMAP, Cluster]})
 
 # Display dashboard
 display(dashboard)
 
 # The dashboard provides easy access to components:
-dashboard.ds  # Dataset (wrapper for AnnData)
-dashboard.pl  # Plotter
-dashboard.pr  # Processor
+# dashboard.ds  # Dataset (wrapper for AnnData)
+# dashboard.pl  # Plotter
+# dashboard.pr  # Processor
+
+# the resulting AnnData object is found within the dataset object:
+# dashboard.ds.adata
 ```
 
 ## Components
@@ -98,10 +104,10 @@ This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICE
 If you use SCLab in your research, please cite:
 
 ```bibtex
-@software{sclab2024,
+@software{sclab2025,
   author = {Arriojas, Argenis},
   title = {SCLab: Interactive Single-Cell Analysis Toolkit},
-  year = {2024},
+  year = {2025},
   publisher = {GitHub},
   url = {https://github.com/umbibio/sclab}
 }

{sclab-0.1.7 → sclab-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sclab"
-version = "0.1.7"
+version = "0.2.2"
 description = "sclab"
 readme = "README.md"
 authors = [
@@ -21,11 +21,11 @@ dependencies = [
     "itables",
     "numpy<2.2",
     "pandas",
-    "plotly",
-    "scanpy",
+    "plotly<6.0",
+    "requests>=2.32.3",
     "scikit-learn",
-    "scikit-misc",
     "svgpathtools",
+    "tqdm>=4.67.1",
 ]
 
 [project.urls]
@@ -37,6 +37,8 @@ dependencies = [
 
 [project.optional-dependencies]
 test = ["pytest>=8.3.4"]
+scanpy = ["scanpy[leiden,skmisc]>=1.10"]
+jupyter = ["jupyterlab>=4.3.6"]
 
 [build-system]
 requires = ["flit_core>=3.2,<4"]
@@ -53,4 +55,9 @@ dev = [
     "ruff>=0.9.4",
     "nox>=2024.1.29",
     "pytest>=8.3.4",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.3",
+    "mkdocs-jupyter>=0.25.1",
+    "scanpy[leiden]>=1.10.4",
+    "jupyterlab>=4.3.6",
 ]

{sclab-0.1.7 → sclab-0.2.2}/src/sclab/__init__.py

@@ -1,7 +1,9 @@
+from . import methods
 from ._sclab import SCLabDashboard
 
 __all__ = [
+    "methods",
     "SCLabDashboard",
 ]
 
-__version__ = "0.1.7"
+__version__ = "0.2.2"

sclab-0.2.2/src/sclab/_io.py

@@ -0,0 +1,109 @@
+from io import BytesIO
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests
+from anndata import AnnData, read_h5ad
+from tqdm.auto import tqdm
+
+
+def read_adata(path: str | Path, var_names: str = "gene_ids") -> AnnData:
+    from .scanpy.readwrite import read_10x_h5, read_10x_mtx
+
+    path = Path(path)
+
+    match path.suffix:
+        case ".h5":
+            adata = read_10x_h5(path)
+        case ".h5ad":
+            adata = read_h5ad(path)
+        case "":
+            assert path.is_dir()
+            adata = read_10x_mtx(path)
+        case _:
+            raise ValueError(
+                "Input file must be a 10x h5, h5ad or a folder of 10x mtx files"
+            )
+
+    if var_names in adata.var:
+        adata.var = adata.var.set_index(var_names)
+
+    return adata
+
+
+def load_adata_from_url(
+    url: str,
+    var_names: str = "gene_ids",
+    progress: bool = True,
+) -> AnnData:
+    """
+    Load an AnnData object from a URL to an .h5ad file.
+
+    Parameters:
+    -----------
+    url : str
+        URL to the .h5ad file
+    var_names : str
+        Name of the variable column in the .h5ad file
+    progress : bool
+        Whether to show a progress bar
+
+    Returns:
+    --------
+    anndata.AnnData
+        Loaded AnnData object
+    """
+    from .scanpy.readwrite import read_10x_h5
+
+    assert is_valid_url(url), "URL is not valid"
+    url_path = Path(urlparse(url).path)
+
+    if url_path.suffix == ".h5":
+        try:
+            import scanpy as sc
+        except ImportError:
+            raise ImportError("Please install scanpy: `pip install scanpy`")
+
+    file_content = fetch_file(url, progress=progress)
+    match url_path.suffix:
+        case ".h5":
+            adata = read_10x_h5(file_content)
+        case ".h5ad":
+            adata = read_h5ad(file_content)
+        case _:
+            raise ValueError("Input file must be a 10x h5 or h5ad file")
+
+    if var_names in adata.var:
+        adata.var = adata.var.set_index(var_names)
+
+    return adata
+
+
+def fetch_file(url: str, progress: bool = True) -> BytesIO:
+    response = requests.get(url, stream=True)
+    response.raise_for_status()
+
+    total_size_in_bytes = int(response.headers.get("content-length", 0))
+    block_size = 1024  # 1 Kibibyte
+
+    if progress:
+        progress_bar = tqdm(total=total_size_in_bytes, unit="iB", unit_scale=True)
+
+    result = BytesIO()
+    for data in response.iter_content(block_size):
+        result.write(data)
+        if progress:
+            progress_bar.update(len(data))
+
+    if progress:
+        progress_bar.close()
+
+    return result
+
+
+def is_valid_url(url: str) -> bool:
+    if not isinstance(url, str):
+        return False
+
+    result = urlparse(url)
+    return all([result.scheme, result.netloc])

sclab-0.2.2/src/sclab/_methods_registry.py

@@ -0,0 +1,65 @@
+from typing import Callable, Type
+
+
+# full class definition is in .dataset/processor/step/_processor_step_base.py
+class ProcessorStepBase:
+    name: str
+    description: str
+
+
+methods_registry: dict[str, list[ProcessorStepBase]] = {}
+
+
+def register_sclab_method(
+    category: str,
+    name: str | None = None,
+    description: str | None = None,
+    order: int | None = None,
+) -> Callable:
+    """
+    Decorator to register a class as a sclab method.
+
+    Args:
+        category: The category to register the method under (e.g., "Processing")
+        name: Optional display name for the method. If None, uses the class name.
+        description: Optional description of the method.
+        order: Optional ordering within the category. Lower numbers appear first.
+
+    Returns:
+        Decorated class
+    """
+
+    def decorator(cls: Type[ProcessorStepBase]) -> Type[ProcessorStepBase]:
+        if name:
+            cls.name = name
+
+        if description:
+            cls.description = description
+
+        if order is not None:
+            cls.order = order
+
+        # Initialize the category in the registry if it doesn't exist
+        if category not in methods_registry:
+            methods_registry[category] = []
+
+        methods_list = methods_registry[category]
+
+        # Add the class to the registry
+        methods_list.append(cls)
+
+        # Sort the methods by order
+        methods_registry[category] = sorted(methods_list, key=lambda x: x.order)
+
+        return cls
+
+    return decorator
+
+
+def get_sclab_methods():
+    methods = {}
+
+    for category, methods_list in methods_registry.items():
+        methods[category] = sorted(methods_list, key=lambda x: x.order)
+
+    return methods

sclab-0.2.2/src/sclab/_sclab.py

@@ -0,0 +1,288 @@
+import inspect
+from io import BytesIO
+from pathlib import Path
+
+from anndata import AnnData
+from IPython.display import display
+from ipywidgets.widgets import (
+    Button,
+    FileUpload,
+    GridBox,
+    HBox,
+    Label,
+    Layout,
+    Output,
+    Tab,
+    Text,
+    ToggleButtons,
+    VBox,
+)
+
+from ._io import is_valid_url, load_adata_from_url, read_adata
+from .dataset import SCLabDataset
+from .dataset.plotter import Plotter
+from .dataset.processor import Processor
+from .event import EventBroker
+
+
+class SCLabDashboard(GridBox):
+    broker: EventBroker
+    dataset: SCLabDataset
+    plotter: Plotter
+    processor: Processor
+    main_content: Tab
+
+    def __init__(
+        self,
+        adata_or_filepath_or_url: AnnData | str | None = None,
+        name: str = "SCLab Dashboard",
+        counts_layer: str = "counts",
+        batch_key: str | None = None,
+        copy: bool = False,
+    ):
+        if adata_or_filepath_or_url is None:
+            adata = None
+
+        elif isinstance(adata_or_filepath_or_url, AnnData):
+            adata = adata_or_filepath_or_url
+
+        elif is_valid_url(adata_or_filepath_or_url):
+            url = adata_or_filepath_or_url
+            adata = load_adata_from_url(url)
+
+        elif isinstance(adata_or_filepath_or_url, str):
+            filepath = adata_or_filepath_or_url
+            adata = read_adata(filepath)
+
+        self.name = name
+        self.counts_layer = counts_layer
+        self.batch_key = batch_key
+
+        self.broker = EventBroker()
+
+        self.dataset = None
+        self.plotter = None
+        self.processor = None
+        self.main_content = None
+
+        self.data_loader_layout = Layout(
+            width="100%",
+            height="500px",
+            grid_template_columns="auto",
+            grid_template_areas=""" "data_loader" """,
+            border="0px solid black",
+        )
+
+        self.dashboard_layout = Layout(
+            width="100%",
+            height="100%",
+            grid_template_columns="350px auto",
+            grid_template_areas=""" "processor plotter" """,
+            border="0px solid black",
+        )
+
+        self.data_loader = DataLoader(self)
+
+        GridBox.__init__(self)
+        if adata is not None:
+            self._load(adata, copy=copy)
+        else:
+            self.children = (self.data_loader,)
+            self.layout = self.data_loader_layout
+
+    def _load(self, adata: AnnData, copy: bool = False):
+        self.dataset = SCLabDataset(
+            adata,
+            name=self.name,
+            counts_layer=self.counts_layer,
+            copy=copy,
+            broker=self.broker,
+        )
+        self.plotter = Plotter(self.dataset)
+        self.processor = Processor(
+            self.dataset,
+            self.plotter,
+            batch_key=self.batch_key,
+        )
+
+        self.main_content = Tab(
+            children=[
+                self.plotter,
+                self.processor.results_panel,
+                self.dataset.obs_table,
+                self.dataset.var_table,
+                self.broker.logs_tab,
+            ],
+            titles=[
+                "Main graph",
+                "Results",
+                "Observations",
+                "Genes",
+                "Logs",
+            ],
+        )
+
+        self.children = (
+            self.processor.main_accordion,
+            self.main_content,
+        )
+        self.layout = self.dashboard_layout
+
+    @property
+    def ds(self):
+        return self.dataset
+
+    @property
+    def pr(self):
+        return self.processor
+
+    @property
+    def pl(self):
+        return self.plotter
+
+
+class DataLoader(VBox):
+    dashboard: SCLabDashboard
+    adata: AnnData
+
+    upload: FileUpload
+    upload_info: Output
+    upload_row: HBox
+    upload_row_label: Label
+
+    url: Text
+    load_button: Button
+    url_row: HBox
+    url_row_label: Label
+
+    defined_adatas_dict: dict[str, AnnData]
+    defined_adatas: ToggleButtons
+    defined_adatas_row: HBox
+    defined_adatas_label: Label
+
+    progress_output: Output
+    continue_button: Button
+
+    def __init__(self, dashboard: SCLabDashboard):
+        self.dashboard = dashboard
+
+        self.upload_row_label = Label("Load from file:", layout=Layout(width="120px"))
+        self.upload = FileUpload(layout=Layout(width="200px"))
+        self.upload_info = Output(layout=Layout(width="95%"))
+        self.upload_row = HBox(
+            [self.upload_row_label, self.upload, self.upload_info],
+            layout=Layout(width="100%"),
+        )
+        self.upload.observe(self.on_upload, "value")
+
+        self.url_row_label = Label("Load from URL:", layout=Layout(width="120px"))
+        self.url = Text(placeholder="https://...", layout=Layout(width="100%"))
+        self.load_button = Button(description="Load", layout=Layout(width="200px"))
+        self.url_row = HBox(
+            [self.url_row_label, self.url, self.load_button],
+            layout=Layout(width="100%"),
+        )
+        self.load_button.on_click(self.on_load_url)
+
+        user_f_locals = inspect.stack()[2].frame.f_locals
+        self.defined_adatas_dict = {}
+        for name, variable_type in [(k, type(v)) for k, v in user_f_locals.items()]:
+            if variable_type is AnnData:
+                self.defined_adatas_dict[name] = user_f_locals[name]
+
+        self.defined_adatas_label = Label(
+            "Defined datasets:", layout=Layout(width="120px")
+        )
+        self.defined_adatas = ToggleButtons(
+            options=list(self.defined_adatas_dict.keys()),
+            value=None,
+            layout=Layout(width="100%"),
+        )
+        self.defined_adatas_row = HBox(
+            [self.defined_adatas_label, self.defined_adatas],
+            layout=Layout(width="100%"),
+        )
+        self.defined_adatas.observe(self.on_defined_adatas_toggle, "value")
+
+        self.progress_output = Output(layout=Layout(width="95%"))
+        self.continue_button = Button(
+            description="Continue", layout=Layout(width="100%"), button_style="success"
+        )
+        self.continue_button.on_click(self.on_continue)
+
+        VBox.__init__(
+            self,
+            [
+                self.url_row,
+                self.upload_row,
+                self.defined_adatas_row,
+                self.progress_output,
+            ],
+            layout=Layout(width="100%"),
+        )
+
+    def on_defined_adatas_toggle(self, *args, **kwargs):
+        adata = self.defined_adatas_dict[self.defined_adatas.value]
+
+        self.progress_output.clear_output()
+        with self.progress_output:
+            print(f"Loaded {adata.shape[0]} observations and {adata.shape[1]} genes\n")
+            print(adata)
+            display(self.continue_button)
+
+        self.adata = adata
+
+    def on_upload(self, *args, **kwargs):
+        from .scanpy.readwrite import read_10x_h5, read_h5ad
+
+        files = self.upload.value
+        if len(files) == 0:
+            return
+
+        file = files[0]
+
+        self.upload_info.clear_output()
+        with self.upload_info:
+            for k, v in file.items():
+                if k == "content":
+                    continue
+                print(f"{k}: {v}")
+
+        filename = file["name"]
+        contents = BytesIO(file["content"].tobytes())
+        var_names = "gene_ids"
+
+        path = Path(filename)
+
+        match path.suffix:
+            case ".h5":
+                adata = read_10x_h5(contents)
+            case ".h5ad":
+                adata = read_h5ad(contents)
+            case _:
+                self.upload_info.clear_output()
+                with self.upload_info:
+                    print(f"`{filename}` is not valid")
+                    print("Please upload a 10x h5 or h5ad file")
+                return
+
+        if var_names in adata.var:
+            adata.var = adata.var.set_index(var_names)
+
+        with self.progress_output:
+            print(f"Loaded {adata.shape[0]} observations and {adata.shape[1]} genes\n")
+            print(adata)
+            display(self.continue_button)
+
+        self.adata = adata
+
+    def on_load_url(self, *args, **kwargs):
+        self.progress_output.clear_output()
+        with self.progress_output:
+            self.adata = load_adata_from_url(self.url.value)
+            display(self.continue_button)
+
+    def on_continue(self, *args, **kwargs):
+        self.dashboard._load(self.adata)
+        self.adata = None
+        self.defined_adatas_dict = {}