sclab 0.1.7__py3-none-any.whl

sclab/examples/processor_steps/_pca.py

@@ -0,0 +1,124 @@
+import numpy as np
+import pandas as pd
+import plotly.express as px
+from ipywidgets import Button, Dropdown, IntText
+
+from sclab.dataset.processor import Processor
+from sclab.dataset.processor.step import ProcessorStepBase
+
+
+class PCA(ProcessorStepBase):
+    parent: Processor
+
+    def __init__(self, parent: Processor) -> None:
+        try:
+            import scanpy as sc  # noqa: F401
+        except ImportError:
+            raise ImportError("Please install scanpy: `pip install scanpy`")
+
+        bool_var_df = parent.dataset.adata.var.select_dtypes(include=bool)
+        mask_var_options = {
+            "": None,
+            **{col: col for col in bool_var_df.columns},
+        }
+        variable_controls = dict(
+            n_comps=IntText(value=30, description="N comps."),
+            mask_var=Dropdown(options=mask_var_options, description="Genes mask"),
+            **parent.make_selectbatch_drowpdown(description="Reference Batch"),
+        )
+
+        super().__init__(
+            parent=parent,
+            name="pca",
+            description="PCA",
+            fixed_params={},
+            variable_controls=variable_controls,
+        )
+
+    def make_controls(self):
+        self.plot_variance_ratio_button = Button(
+            description="Plot Variance Ratio",
+            layout={"width": "auto"},
+            button_style="info",
+            disabled=True,
+        )
+        self.plot_variance_ratio_button.on_click(self.plot_variance_ratio_callback)
+
+        self.controls_list = [
+            *self.variable_controls.values(),
+            self.run_button,
+            self.plot_variance_ratio_button,
+            self.output,
+        ]
+        return super().make_controls()
+
+    def function(
+        self,
+        n_comps: int = 30,
+        mask_var: str | None = None,
+        reference_batch: str | None = None,
+    ):
+        import scanpy as sc
+
+        adata = self.parent.dataset.adata
+        counts_layer = self.parent.dataset.counts_layer
+
+        if reference_batch:
+            obs_mask = adata.obs[self.parent.batch_key] == reference_batch
+            adata_ref = adata[obs_mask].copy()
+            if mask_var == "highly_variable":
+                sc.pp.highly_variable_genes(
+                    adata_ref, layer=f"{counts_layer}_log1p", flavor="seurat"
+                )
+                hvg_seurat = adata_ref.var["highly_variable"]
+                sc.pp.highly_variable_genes(
+                    adata_ref,
+                    layer=counts_layer,
+                    flavor="seurat_v3_paper",
+                    n_top_genes=hvg_seurat.sum(),
+                )
+                hvg_seurat_v3 = adata_ref.var["highly_variable"]
+                adata_ref.var["highly_variable"] = hvg_seurat | hvg_seurat_v3
+            sc.pp.pca(
+                adata_ref, n_comps=n_comps, mask_var=mask_var, svd_solver="arpack"
+            )
+            uns_pca = adata_ref.uns["pca"]
+            uns_pca["reference_batch"] = reference_batch
+            PCs = adata_ref.varm["PCs"]
+            X_pca: np.ndarray = adata.X.dot(PCs)
+            X_pca = X_pca - X_pca.mean(axis=0, keepdims=True)
+            adata.obsm["X_pca"] = X_pca
+            adata.uns["pca"] = uns_pca
+            adata.varm["PCs"] = PCs
+        else:
+            sc.pp.pca(adata, n_comps=n_comps, mask_var=mask_var, svd_solver="arpack")
+
+        self.plot_variance_ratio_button.disabled = False
+        self.broker.publish(
+            "dset_data_dict_change", self.parent.dataset.data_dict, "X_pca"
+        )
+
+    def plot_variance_ratio_callback(self, *args, **kwargs):
+        adata = self.parent.dataset.adata
+        ncomps = self.variable_controls["n_comps"].value
+
+        df = pd.DataFrame(
+            {k: adata.uns["pca"][k] for k in ["variance", "variance_ratio"]},
+            index=pd.Index(range(ncomps), name="component") + 1,
+        )
+
+        fig = px.scatter(df, y="variance_ratio")
+        self.broker.publish("dplt_plot_figure_request", figure=fig)
+
+    def dset_var_dataframe_change_callback(self, *args, **kwargs):
+        var_df = self.parent.dataset.adata.var
+        df = var_df.select_dtypes(include=["bool"])
+        options = {"": None, **{c: c for c in df.columns}}
+
+        control: Dropdown = self.variable_controls["mask_var"]
+        current_value = control.value
+        control.options = options
+        if current_value not in control.options:
+            control.value = None
+        else:
+            control.value = current_value

sclab/examples/processor_steps/_preprocess.py

@@ -0,0 +1,186 @@
+import numpy as np
+from ipywidgets import Checkbox, Dropdown
+from tqdm.auto import tqdm
+
+from sclab.dataset.processor import Processor
+from sclab.dataset.processor.step import ProcessorStepBase
+
+
+class Preprocess(ProcessorStepBase):
+    parent: Processor
+
+    def __init__(self, parent: Processor) -> None:
+        try:
+            import scanpy as sc  # noqa: F401
+        except ImportError:
+            raise ImportError("Please install scanpy: `pip install scanpy`")
+
+        cat_metadata = parent.dataset._metadata.select_dtypes(
+            include=["object", "category"]
+        )
+        cat_options = {"": None, **{c: c for c in cat_metadata.columns}}
+
+        variable_controls = dict(
+            layer=Dropdown(
+                options=tuple(parent.dataset.adata.layers.keys()),
+                value="counts",
+                description="Layer",
+            ),
+            group_by=Dropdown(
+                options=cat_options,
+                value=None,
+                description="GroupBy",
+            ),
+            regress_total_counts=Checkbox(description="Regr. out total counts"),
+            regress_n_genes=Checkbox(description="Regr. out n genes"),
+            normalize_total=Checkbox(value=True, description="Normalize total"),
+            log1p=Checkbox(value=True, description="Log1p"),
+            scale=Checkbox(value=True, description="Scale"),
+        )
+
+        def filter_layers(change: dict):
+            new_options: tuple[str] = change["new"]
+            if any(s.endswith("log1p") for s in new_options):
+                new_options = tuple(
+                    filter(lambda y: not y.endswith("log1p"), new_options)
+                )
+                variable_controls["layer"].options = new_options
+
+        variable_controls["layer"].observe(filter_layers, "options", "change")
+
+        super().__init__(
+            parent=parent,
+            name="preprocess",
+            description="Preprocess",
+            fixed_params={},
+            variable_controls=variable_controls,
+        )
+
+    def function(
+        self,
+        layer: str | None = None,
+        group_by: str | None = None,
+        regress_total_counts: bool = False,
+        regress_n_genes: bool = False,
+        normalize_total: bool = False,
+        log1p: bool = True,
+        scale: bool = True,
+    ):
+        import scanpy as sc
+
+        self.output.clear_output(wait=True)
+        with self.output:
+            pbar = tqdm(total=100, bar_format="{percentage:3.0f}%|{bar}|")
+
+        dataset = self.parent.dataset
+        adata = dataset.adata
+        if layer is None:
+            layer = dataset.counts_layer
+
+        if f"{layer}_log1p" not in adata.layers:
+            adata.layers[f"{layer}_log1p"] = sc.pp.log1p(adata.layers[layer].copy())
+        pbar.update(10)
+
+        if layer != "X":
+            adata.X = adata.layers[layer].copy()
+        start_n_cells_i, start_n_genes = adata.shape
+
+        sc.pp.calculate_qc_metrics(
+            adata,
+            percent_top=None,
+            log1p=False,
+            inplace=True,
+        )
+        sc.pp.filter_cells(adata, min_genes=5)
+        sc.pp.filter_genes(adata, min_cells=5)
+        pbar.update(10)
+
+        sc.pp.calculate_qc_metrics(
+            adata,
+            percent_top=None,
+            log1p=False,
+            inplace=True,
+        )
+        pbar.update(10)
+
+        sc.pp.highly_variable_genes(
+            adata,
+            layer=f"{layer}_log1p",
+            flavor="seurat",
+            batch_key=group_by,
+        )
+        hvg_seurat = adata.var["highly_variable"]
+        sc.pp.highly_variable_genes(
+            adata,
+            layer=layer,
+            flavor="seurat_v3_paper",
+            batch_key=group_by,
+            n_top_genes=hvg_seurat.sum(),
+        )
+        hvg_seurat_v3 = adata.var["highly_variable"]
+
+        adata.var["highly_variable"] = hvg_seurat | hvg_seurat_v3
+        adata.var["highly_variable_seurat"] = hvg_seurat
+        adata.var["highly_variable_seurat_v3"] = hvg_seurat_v3
+        pbar.update(10)
+        pbar.update(10)
+
+        new_layer = layer
+        if normalize_total:
+            new_layer += "_normt"
+            sc.pp.normalize_total(adata, target_sum=1e4)
+            adata.layers[new_layer] = adata.X.copy()
+
+        pbar.update(10)
+        pbar.update(10)
+
+        if log1p:
+            new_layer += "_log1p"
+            adata.uns.pop("log1p", None)
+            sc.pp.log1p(adata)
+            adata.layers[new_layer] = adata.X.copy()
+        pbar.update(10)
+
+        vars_to_regress = []
+        if regress_n_genes:
+            vars_to_regress.append("n_genes_by_counts")
+
+        if regress_total_counts and log1p:
+            adata.obs["log1p_total_counts"] = np.log1p(adata.obs["total_counts"])
+            vars_to_regress.append("log1p_total_counts")
+        elif regress_total_counts:
+            vars_to_regress.append("total_counts")
+
+        if vars_to_regress:
+            new_layer += "_regr"
+            sc.pp.regress_out(adata, keys=vars_to_regress, n_jobs=1)
+            adata.layers[new_layer] = adata.X.copy()
+        pbar.update(10)
+
+        if scale:
+            new_layer += "_scale"
+            sc.pp.scale(adata, zero_center=False)
+            adata.layers[new_layer] = adata.X.copy()
+
+        pbar.update(10)
+
+        self.broker.publish("dset_metadata_change", dataset.metadata)
+        self.broker.publish("dset_data_dict_change", dataset.data_dict, "metadata")
+        self.broker.publish("dset_anndata_layers_change", dataset.adata.layers.keys())
+        self.broker.publish(
+            "ctrl_value_change_request",
+            data_key="metadata",
+            selected_axes_1="n_genes_by_counts",
+            selected_axes_2="total_counts",
+        )
+        self.broker.publish("dset_var_dataframe_change", dataset.adata.var)
+
+        end_n_cells_i, end_n_genes = adata.shape
+        if start_n_cells_i != end_n_cells_i:
+            self.broker.publish("dset_total_rows_change", dataset.metadata)
+        if start_n_genes != end_n_genes:
+            self.broker.publish("dset_total_vars_change", adata.var)
+
+        adata.X = adata.X.astype(np.float32)
+
+        pbar.close()

sclab/examples/processor_steps/_qc.py

@@ -0,0 +1,93 @@
+from ipywidgets import Dropdown, IntText
+
+from sclab.dataset.processor import Processor
+from sclab.dataset.processor.step import ProcessorStepBase
+
+
+class QC(ProcessorStepBase):
+    parent: Processor
+
+    def __init__(self, parent: Processor) -> None:
+        try:
+            import scanpy as sc  # noqa: F401
+        except ImportError:
+            raise ImportError("Please install scanpy: `pip install scanpy`")
+
+        variable_controls = dict(
+            layer=Dropdown(
+                options=tuple(parent.dataset.adata.layers.keys()),
+                value="counts",
+                description="Layer",
+            ),
+            min_genes=IntText(value=5, description="Min. Genes"),
+            min_cells=IntText(value=0, description="Min. Cells"),
+            max_rank=IntText(value=0, description="Max. Rank"),
+        )
+
+        def filter_layers(change: dict):
+            new_options: tuple[str] = change["new"]
+            if any(s.endswith("log1p") for s in new_options):
+                new_options = tuple(
+                    filter(lambda y: not y.endswith("log1p"), new_options)
+                )
+                variable_controls["layer"].options = new_options
+
+        variable_controls["layer"].observe(filter_layers, "options", "change")
+
+        super().__init__(
+            parent=parent,
+            name="qc",
+            description="QC",
+            fixed_params={},
+            variable_controls=variable_controls,
+        )
+
+    def compute_qc_metrics(
+        self,
+        layer: str | None = None,
+        min_genes: int = 5,
+        min_cells: int = 5,
+    ):
+        import scanpy as sc
+
+        if layer is None:
+            layer = self.parent.dataset.counts_layer
+
+        dataset = self.parent.dataset
+        adata = dataset.adata
+
+        adata.layers["qc_tmp_current_X"] = adata.X
+        adata.X = adata.layers[layer].copy()
+        sc.pp.calculate_qc_metrics(adata, percent_top=None, log1p=False, inplace=True)
+
+        sc.pp.filter_cells(adata, min_genes=min_genes)
+        sc.pp.filter_genes(adata, min_cells=min_cells)
+        sc.pp.calculate_qc_metrics(adata, percent_top=None, log1p=False, inplace=True)
+        adata.obs["barcode_rank"] = adata.obs["total_counts"].rank(ascending=False)
+
+        # Restore original X
+        adata.X = adata.layers.pop("qc_tmp_current_X")
+
+    def function(
+        self,
+        layer: str | None = None,
+        min_genes: int = 5,
+        min_cells: int = 5,
+        max_rank: int = 0,
+    ):
+        self.compute_qc_metrics(layer, min_genes, min_cells)
+
+        if max_rank > 0:
+            series = self.parent.dataset.adata.obs["barcode_rank"]
+            index = series.loc[series < max_rank].index
+            self.parent.dataset.filter_rows(index)
+
+        self.broker.publish("dset_metadata_change", self.parent.dataset.metadata)
+        self.broker.publish(
+            "ctrl_value_change_request",
+            data_key="metadata",
+            selected_axes_1="barcode_rank",
+            selected_axes_2="total_counts",
+            log_axes_2=True,
+        )
+        self.broker.publish("dset_var_dataframe_change", self.parent.dataset.adata.var)

sclab/examples/processor_steps/_umap.py

@@ -0,0 +1,48 @@
+import numpy as np
+from ipywidgets import Checkbox, IntText
+
+from sclab.dataset.processor import Processor
+from sclab.dataset.processor.step import ProcessorStepBase
+
+
+class UMAP(ProcessorStepBase):
+    parent: Processor
+
+    def __init__(self, parent: Processor) -> None:
+        try:
+            import scanpy as sc  # noqa: F401
+        except ImportError:
+            raise ImportError("Please install scanpy: `pip install scanpy`")
+
+        variable_controls = dict(
+            n_components=IntText(value=2, description="N comp."),
+            zero_center=Checkbox(value=False, description="Zero center"),
+        )
+
+        super().__init__(
+            parent=parent,
+            name="umap",
+            description="UMAP",
+            fixed_params={},
+            variable_controls=variable_controls,
+        )
+
+    def function(
+        self,
+        n_components: int = 2,
+        zero_center: bool = True,
+    ):
+        import scanpy as sc
+
+        dataset = self.parent.dataset
+        adata = self.parent.dataset.adata
+
+        sc.tl.umap(adata, n_components=n_components)
+        X: np.ndarray = adata.obsm.pop("X_umap")
+        if zero_center:
+            X = X - X.mean(axis=0, keepdims=True)
+
+        key = f"X_{n_components}Dumap"
+        adata.obsm[key] = X
+
+        self.broker.publish("dset_data_dict_change", dataset.data_dict, key)

sclab-0.1.7.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: sclab
+Version: 0.1.7
+Summary: sclab
+Author-email: Argenis Arriojas <ArriojasMaldonado001@umb.edu>
+Requires-Python: >=3.10,<3.13
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: scikit-learn
+Requires-Dist: scikit-misc
+Requires-Dist: svgpathtools
+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: test
+
+# SCLab
+
+SCLab is an interactive single-cell analysis toolkit that provides a seamless interface for analyzing and visualizing single-cell RNA sequencing data. Built on top of popular tools like scanpy and AnnData, SCLab offers an event-driven architecture for real-time updates and interactive visualizations.
+
+## Features
+
+- **Interactive Data Analysis**: Built-in dashboard with real-time updates
+- **Quality Control**: Comprehensive QC metrics and filtering capabilities
+- **Preprocessing**: Normalization, log transformation, and scaling with progress tracking
+- **Dimensionality Reduction**: PCA with batch effect correction support
+- **Visualization**: Interactive plots and tables using plotly and itables
+- **Event System**: Robust event-driven architecture for real-time updates
+
+## Installation
+
+```bash
+pip install sclab
+```
+
+## Quick Start
+
+Open a Jupyter Notebook and run the following:
+
+```python
+from sclab import SCLabDashboard
+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")
+
+# Display dashboard
+display(dashboard)
+
+# The dashboard provides easy access to components:
+dashboard.ds  # Dataset (wrapper for AnnData)
+dashboard.pl  # Plotter
+dashboard.pr  # Processor
+```
+
+## Components
+
+### SCLabDashboard
+
+The main interface that integrates all components with a tabbed layout:
+- Main graph for visualizations
+- Observations table
+- Genes table
+- Event logs
+
+### Dataset
+
+Handles data management with:
+- AnnData integration
+- Interactive tables
+- Row selection and filtering
+- Metadata handling
+
+### Processor
+
+Handles data processing steps. It is configurable with custom steps implementing the `ProcessorStepBase` interface. This package provides multiple examples of steps:
+
+- QC
+- Preprocessing
+- PCA
+- Nearest Neighbors
+- UMAP
+- Clustering
+
+### Plotter
+
+Provides interactive visualizations with:
+- Real-time updates
+- Customizable plots
+- Batch effect visualization
+- Export capabilities
+
+## Requirements
+
+- Python ≥ 3.12
+- anndata ≥ 0.11.3
+- scanpy ≥ 1.10.4
+- Other dependencies listed in pyproject.toml
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use SCLab in your research, please cite:
+
+```bibtex
+@software{sclab2024,
+  author = {Arriojas, Argenis},
+  title = {SCLab: Interactive Single-Cell Analysis Toolkit},
+  year = {2024},
+  publisher = {GitHub},
+  url = {https://github.com/umbibio/sclab}
+}
+

sclab-0.1.7.dist-info/RECORD

@@ -0,0 +1,30 @@
+sclab/__init__.py,sha256=0RUdbuZt9XoQgNmLnMCR4-LYIXnwXUgNyuLEL1Gu9Ms,95
+sclab/_io.py,sha256=mVazSViXfKpfY1iUNZXgQc1hutu6MXTaGZXF4rcqKLE,875
+sclab/_sclab.py,sha256=Eln0nWlnFpnDabW94UK8qOdxIys9FWSyqsm8lvlnk4A,2156
+sclab/dataset/__init__.py,sha256=f9PoXIMAPnC3Var1ODr3mXkotW6u6NRPQvlgcWYXk54,143
+sclab/dataset/_dataset.py,sha256=51E8iwiUFxFBvka8EsCuZrc-nfNxHcB4iEAy_Ja5qPg,14409
+sclab/dataset/_exceptions.py,sha256=g8RJL8PiRmD4--PkOs5CZth_qeaduvieMlKJNkrUIYA,45
+sclab/dataset/plotter/__init__.py,sha256=pdWhAywnoc1_nnIcD-qNW0U364-yo4k5DwP79y9NVgA,129
+sclab/dataset/plotter/_controls.py,sha256=NBDdtY1wQbIEvE_WToigR5bEEoi3z30_67T_dLSOSIo,20295
+sclab/dataset/plotter/_plotter.py,sha256=EXwk6KSM7FOyLLJ8HCgIB_2m730t0kHsVKWfQOxL6kA,37023
+sclab/dataset/plotter/_utils.py,sha256=ANm_R9PJd33-QJtZzqXCN5pJ_XrJ7AA4AvSHaDRbOMA,11595
+sclab/dataset/processor/__init__.py,sha256=v8Qbusb6h8oSndv9q-12vzHrz5BDF3N2LCkQG9KC19I,104
+sclab/dataset/processor/_processor.py,sha256=bvDdjcZDD7ighP-wvmebh4Tuc_-HyFT9KP8bFOB4POY,40811
+sclab/dataset/processor/step/__init__.py,sha256=j8j4oU9NMdWHn6kVjft7Klm6xme8M6wzebxJj_zNehg,179
+sclab/dataset/processor/step/_basic_processor_step.py,sha256=7NKC4W-I_EU3QBPi5BL9-NwAF_h6_oWl1l_kEk6gSAg,3640
+sclab/dataset/processor/step/_processor_step_base.py,sha256=Yk8nCDu4atk-txJcEEC6kravzP6FDBjcrdh6kNyZjdM,3909
+sclab/event/__init__.py,sha256=unkfpmoxitPVZvWcc9YhkUwcXODdcd9cw_toVXVIDMU,126
+sclab/event/_broker.py,sha256=W4GgoBhJS1LxGQv8TYFg71o5jUQPO8BDLrKzahDUyEM,7121
+sclab/event/_client.py,sha256=Kx7pza-CzLySR0JBBneiZQAjtllUnjWKNKSfw3K2ZQE,2362
+sclab/event/_utils.py,sha256=LehiFhn7dopNEaTFERJhs6fiVgXCBvseRxWTSWc6u-k,456
+sclab/examples/__init__.py,sha256=uSu4DMfF2K7xlZbLC_CmANyS3D56khGLMSVt6x9XXiI,68
+sclab/examples/processor_steps/__init__.py,sha256=tm2YWKIkBPcBoHp4VS78tLyQX44Y7zUj2dgzFH058DA,279
+sclab/examples/processor_steps/_cluster.py,sha256=fXI8J_ae8ZXjckmCff3WfwSa9HTdQmEDYQ3vTilmV9k,1124
+sclab/examples/processor_steps/_neighbors.py,sha256=-FxRBi5Uaywrn2fXnlgmwtQrTefPPdnfOuI6RhKw314,2210
+sclab/examples/processor_steps/_pca.py,sha256=XKEau9MtHr0LBDFTc9Y3QUQRv5fvNyKT8KeFujepypc,4589
+sclab/examples/processor_steps/_preprocess.py,sha256=ftuWt9asef_a5OU195UazfI34MjA82nE1LWTPjhXPPY,6340
+sclab/examples/processor_steps/_qc.py,sha256=VPiyY7o7YM8v6hetjxrSfnrn_fJhuC5EzeMi1bSUsw0,3242
+sclab/examples/processor_steps/_umap.py,sha256=Geyme_biIHxGE7zD8dsECUfQy31ff-w1BrAN55BW5Ug,1406
+sclab-0.1.7.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+sclab-0.1.7.dist-info/METADATA,sha256=UTX_EmyQXRn0F2r69fnTKwju9H3PnMExTN08LuTfCkI,3767
+sclab-0.1.7.dist-info/RECORD,,

sclab-0.1.7.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.10.1
+Root-Is-Purelib: true
+Tag: py3-none-any