rectanglepy 0.1.3__tar.gz → 0.1.7__tar.gz

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.3
+current_version = 0.1.7
 tag = True
 commit = True
 

rectanglepy-0.1.7/.github/workflows/release_testpypi.yaml

@@ -0,0 +1,44 @@
+name: Manual Upload to TestPyPI
+
+on:
+    workflow_dispatch:
+
+jobs:
+    package:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+            - name: Set up Python 3.10
+              uses: actions/setup-python@v2
+              with:
+                  python-version: "3.10"
+            - name: Install build dependencies
+              run: python -m pip install --upgrade pip wheel twine build
+            - name: Build package
+              run: python -m build
+            - name: Check package
+              run: twine check --strict dist/*.whl
+
+    release:
+        name: Release
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v3
+
+            - name: Set up Python 3.10
+              uses: actions/setup-python@v4
+              with:
+                  python-version: "3.10"
+
+            - name: Install hatch
+              run: pip install hatch
+
+            - name: Install twine
+              run: pip install twine
+
+            - name: Build project for distribution
+              run: hatch build
+
+            - name: Publish a Python distribution to  test PyPI
+              run: twine upload --repository testpypi dist/* -u __token__ -p ${{ secrets.TESTPYPI_API_TOKEN }}

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/CHANGELOG.md

@@ -10,6 +10,19 @@ and this project adheres to [Semantic Versioning][].
 
 ## [Unreleased]
 
+## [0.1.7] - 2024-07-25
+
+### Fixed
+
+-   Fixed bug in the consensus method.
+
+## [0.1.6] - 2024-05-07
+
+### Added
+
+-   Added consenus method to Rectangle
+-   RectangleSignatureResult now contains list of marker genes per cell type / cluster
+
 ## [0.1.0] - 2024-04-25
 
 ### Added

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rectanglepy
-Version: 0.1.3
+Version: 0.1.7
 Summary: Hierarchical deconvolution of bulk  transcriptomics
 Project-URL: Documentation, https://rectanglepy.readthedocs.io/
 Project-URL: Source, https://github.com/ComputationalBiomedicineGroup/Rectangle
@@ -31,6 +31,7 @@ License: MIT License
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: loguru
+Requires-Dist: numpy<2.0.0,>=1.0.0
 Requires-Dist: pydeseq2==0.4.1
 Requires-Dist: quadprog==0.1.11
 Provides-Extra: dev

rectanglepy-0.1.7/docs/api.md

@@ -0,0 +1,17 @@
+# API
+
+## Rectangle
+
+```{eval-rst}
+.. currentmodule:: rectanglepy
+
+.. autosummary::
+    :toctree: generated
+
+    rectanglepy.rectangle
+    rectanglepy.rectangle_consens
+    rectanglepy.pp.build_rectangle_signatures
+    rectanglepy.tl.deconvolution
+    rectanglepy.pp.RectangleSignatureResult
+    rectanglepy.ConsensusResult
+```

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/docs/notebooks/example.ipynb

@@ -157,6 +157,11 @@
     "collapsed": false
    }
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "To deconvolute the bulk data in a single step, use the rectangle function. This function returns a tuple of the estimated cell type proportions and the signature result."
+  },
   {
    "cell_type": "code",
    "outputs": [],
@@ -195,28 +200,21 @@
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "signature_result is a [`RectangleSignatureResult`](../generated/rectanglepy.pp.RectangleSignatureResult.rst) object. Results of estimations vary slightly from machine to machine (due to difference in theunderlying linear algebra packages)"
-   ],
+   "source": "signature_result is a [`RectangleSignatureResult`](../generated/rectanglepy.pp.RectangleSignatureResult.rst) object. ",
    "metadata": {
     "collapsed": false
    }
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "## Even sampling and consensus"
-   ],
+   "source": "## Running Rectangle in Consensus mode",
    "metadata": {
     "collapsed": false
    }
   },
   {
    "cell_type": "markdown",
-   "source": [
-    "We recommend even subsampling of the sc data.\n",
-    "You can use the `sample_size` parameter to sample a fixed number of cells per cell type,  and run the consensus multiple times to get a more robust result."
-   ],
+   "source": "For some scRNA-seq datatasets it may be beneficial to run rectangle in consensus mode. In this function we run the rectangle algorithm multiple times (`consensus_runs`), where on each iteration we sample  `sample_size` cells of each cell type. The final cell type proportions are the median of the proportions estimated in each run.",
    "metadata": {
     "collapsed": false
    }
@@ -224,14 +222,17 @@
   {
    "cell_type": "code",
    "outputs": [],
-   "source": [
-    "estimations, signature_result = rectangle.rectangle(sc_adata, bulks, consensus_runs=5, sample_size=1500)"
-   ],
+   "source": "estimations, signature_result, consensus_result = rectangle.rectangle_consens(sc_adata, bulks, consensus_runs=5, sample_size=1500)",
    "metadata": {
     "collapsed": false
    },
    "execution_count": null
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "signature_result holds the signature result([`RectangleSignatureResult`](../generated/rectanglepy.pp.RectangleSignatureResult.rst)) for the most recent consensus run, while consensus_result is a [`ConsensusResult`](../generated/rectanglepy.ConsensusResult.rst) object that holds the results of all the runs."
+  },
   {
    "cell_type": "markdown",
    "source": [

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["hatchling"]
 
 [project]
 name = "rectanglepy"
-version = "0.1.3"
+version = "0.1.7"
 description = "Hierarchical deconvolution of bulk  transcriptomics"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,7 @@ dependencies = [
     "pydeseq2==0.4.1",
     "quadprog==0.1.11",
     "loguru",
+    "numpy>=1.0.0,<2.0.0",
 ]
 
 [project.optional-dependencies]

rectanglepy-0.1.7/src/rectanglepy/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import version
+
+from . import pp, tl
+from .rectangle import ConsensusResult, load_tutorial_data, rectangle, rectangle_consens
+
+__all__ = ["pp", "tl", "load_tutorial_data", "rectangle", "rectangle_consens", "ConsensusResult"]
+
+__version__ = version("rectanglepy")

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/src/rectanglepy/pp/create_signature.py

@@ -155,7 +155,7 @@ def _run_deseq2(countsig: pd.DataFrame, n_cpus: int = None) -> dict[str | int, p
 
 def _de_analysis(
     pseudo_count_sig, sc_data, annotations, p, lfc, optimize_cutoffs: bool, n_cpus: int = None, genes=None
-) -> tuple[Series, dict[str, int] :, DataFrame | None]:
+) -> tuple[Series, dict[str, [str]] :, DataFrame | None]:
     logger.info("Starting DE analysis")
     deseq_results = _run_deseq2(pseudo_count_sig, n_cpus)
     optimization_results = None
@@ -185,15 +185,15 @@ def _get_marker_genes(deseq_results, logfc, p, pseudo_count_sig):
     optimal_condition_matrix = condition_number_matrices[optimal_condition_index]
 
     markers = optimal_condition_matrix.index
-    marker_genes_per_cell_type = _count_marker_genes_per_cell_type(de_analysis_adjusted, optimal_condition_number)
+    marker_genes_per_cell_type = _get_marker_genes_per_cell_type(de_analysis_adjusted, optimal_condition_number)
     return markers, marker_genes_per_cell_type
 
 
-def _count_marker_genes_per_cell_type(de_analysis_adjusted, optimal_condition_number: int) -> dict[str, int]:
+def _get_marker_genes_per_cell_type(de_analysis_adjusted, optimal_condition_number: int) -> dict[str, [str]]:
     marker_genes_per_cell_type = {}
     for annotation, result in de_analysis_adjusted.items():
-        marker_genes_per_cell_type[annotation] = min(len(result), optimal_condition_number)
-    logger.info(f"Number of marker genes per cell type: {str(marker_genes_per_cell_type)}")
+        number_of_genes = min(len(result), optimal_condition_number)
+        marker_genes_per_cell_type[annotation] = list(result.index[0:number_of_genes])
     return marker_genes_per_cell_type
 
 
@@ -245,6 +245,7 @@ def build_rectangle_signatures(
     subsample: bool = False,
     sample_size: int = 1500,
     n_cpus: int = None,
+    run: int = 0,
 ) -> RectangleSignatureResult:
     r"""Builds rectangle signatures based on single-cell  count data and annotations.
 
@@ -272,6 +273,8 @@ def build_rectangle_signatures(
         The log fold change threshold for the DE analysis (only used if optimize_cutoffs is False).
     n_cpus
         The number of cpus to use for the DE analysis. Defaults to the number of cpus available.
+    run
+        The consensus run number for the analysis. Defaults to 0.
 
     Returns
     -------
@@ -286,7 +289,7 @@ def build_rectangle_signatures(
 
     annotations = adata.obs[cell_type_col]
     if subsample:
-        annotations = _even(annotations, sample_size)
+        annotations = _even(annotations, sample_size, run)
         adata = adata[annotations.index]
 
     if layer is not None:
@@ -323,7 +326,9 @@ def build_rectangle_signatures(
         )
 
     clustered_biasfact = _create_bias_factors(clustered_signature, sc_counts, clustered_annotations)
-    clustered_genes = _de_analysis(clustered_signature, sc_counts, clustered_annotations, p, lfc, False)[0]
+    clustered_genes, clustered_marker_genes_per_cell_type, _ = _de_analysis(
+        clustered_signature, sc_counts, clustered_annotations, p, lfc, False
+    )
     clustered_signature = _convert_to_cpm(clustered_signature)
     return RectangleSignatureResult(
         signature_genes=marker_genes,
@@ -335,6 +340,7 @@ def build_rectangle_signatures(
         clustered_signature_genes=clustered_genes,
         clustered_bias_factors=clustered_biasfact,
         cluster_assignments=assignments,
+        marker_genes_per_cluster=clustered_marker_genes_per_cell_type,
     )
 
 
@@ -445,7 +451,8 @@ def _reduce_to_common_genes(bulks: pd.DataFrame, sc_data: pd.DataFrame):
     return bulks, sc_data
 
 
-def _even(annotations: pd.Series, number: int) -> pd.Series:
+def _even(annotations: pd.Series, number: int, run=0) -> pd.Series:
+    np.random.seed(run)
     assert number > 0, "Number of cells must be greater than 0"
     annotation_counts = annotations.value_counts()
     selected_cells = []

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/src/rectanglepy/pp/rectangle_signature.py

@@ -29,16 +29,18 @@ class RectangleSignatureResult:
         signature_genes: pd.Series,
         bias_factors: pd.Series,
         pseudobulk_sig_cpm: pd.DataFrame,
-        marker_genes_per_cell_type: dict[str, int],
+        marker_genes_per_cell_type: dict[str, [str]],
         optimization_result: pd.DataFrame = None,
         clustered_pseudobulk_sig_cpm: pd.DataFrame = None,
         clustered_bias_factors: pd.Series = None,
+        marker_genes_per_cluster: dict[str, [str]] = None,
         clustered_signature_genes: pd.Series = None,
         cluster_assignments: list[int or str] = None,
     ):
         self.signature_genes = signature_genes
         self.bias_factors = bias_factors
         self.pseudobulk_sig_cpm = pseudobulk_sig_cpm
+        self.marker_genes_per_cluster = marker_genes_per_cluster
         self.marker_genes_per_cell_type = marker_genes_per_cell_type
         self.optimization_result = optimization_result
         self.clustered_pseudobulk_sig_cpm = clustered_pseudobulk_sig_cpm
@@ -46,21 +48,6 @@ class RectangleSignatureResult:
         self.clustered_signature_genes = clustered_signature_genes
         self.assignments = cluster_assignments
 
-    def cell_types_with_low_number_of_marker_genes(self) -> list[str]:
-        """Returns the cell types with less than threshold marker genes.
-
-        Returns
-        -------
-        list[str]: The cell types with less than threshold marker genes.
-
-        """
-        low_annotation_threshold = 30
-        return [
-            cell_type
-            for cell_type, count in self.marker_genes_per_cell_type.items()
-            if count < low_annotation_threshold
-        ]
-
     def get_signature_matrix(self, include_mrna_bias=True) -> pd.DataFrame:
         """Calculates the signature matrix by multiplying the pseudobulk_sig_cpm DataFrame subset by signature_genes and the bias_factors Series.
 

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/src/rectanglepy/rectangle.py

@@ -8,22 +8,38 @@ from .pp import RectangleSignatureResult, build_rectangle_signatures
 from .tl import deconvolution
 
 
-def rectangle(
+class ConsensusResult:
+    """A class used to represent the consensus result of the rectangle_consens function.
+
+    Parameters
+    ----------
+    estimations
+        A list of DataFrame objects representing the estimations from each consensus run.
+    rectangle_signature_results
+        A list of RectangleSignatureResult objects representing the rectangle signature results from each consensus run.
+    """
+
+    def __init__(self, estimations: list[DataFrame], rectangle_signature_results: list[RectangleSignatureResult]):
+        self.estimations = estimations
+        self.rectangle_signature_results = rectangle_signature_results
+
+
+def rectangle_consens(
     adata: AnnData,
     bulks: DataFrame,
     cell_type_col: str = "cell_type",
     *,
     layer: str = None,
     raw: bool = False,
-    subsample: bool = False,
+    subsample: bool = True,
     sample_size: int = 1500,
-    consensus_runs: int = 1,
+    consensus_runs: int = 5,
     correct_mrna_bias: bool = True,
     optimize_cutoffs=True,
     p=0.015,
     lfc=1.5,
     n_cpus: int = None,
-) -> tuple[DataFrame, RectangleSignatureResult]:
+) -> tuple[DataFrame, RectangleSignatureResult, ConsensusResult]:
     r"""All in one deconvolution method. Creates signatures and deconvolutes the bulk data. Has options for subsampling and consensus runs.
 
     Parameters
@@ -39,26 +55,27 @@ def rectangle(
     raw
         A flag indicating whether to use the raw Anndata data. Defaults to False.
     subsample : bool
-        A flag indicating whether to balance the single-cell data. Defaults to False.
+        A flag indicating whether to balance the single-cell data.
     sample_size : int
-        The number of cells to balance the single-cell data to. Defaults to 1500. If cell number is less than this number it takes the original number of cells.
+        The number of cells to balance the single-cell data to. If cell number is less than this number it takes the original number of cells.
     consensus_runs : int
-        The number of consensus runs to perform. Defaults to 1 for a singular deconvolution run. Consensus runs are performed by subsampling the single-cell data and running the analysis multiple times. The results are then aggregated.
+        The number of consensus runs to perform. Consensus runs are performed by subsampling the single-cell data and running the analysis multiple times. The results are then aggregated.
     optimize_cutoffs
-        Indicates whether to optimize the p-value and log fold change cutoffs using gridsearch. Defaults to True.
+        Indicates whether to optimize the p-value and log fold change cutoffs using gridsearch.
     p
         The p-value threshold for the DE analysis (only used if optimize_cutoffs is False).
     lfc
         The log fold change threshold for the DE analysis (only used if optimize_cutoffs is False).
     n_cpus
-        The number of cpus to use for the DE analysis. Defaults to the number of cpus available.
+        The number of cpus to use for the DE analysis. None value takes all cpus available.
     correct_mrna_bias : bool
         A flag indicating whether to correct for mRNA bias. Defaults to True.
 
     Returns
     -------
-    DataFrame : The estimated cell fractions.
-    RectangleSignatureResult : The result of the rectangle signature analysis.
+    DataFrame : The estimated cell fractions consens.
+    RectangleSignatureResult : The result of the last consensus run.
+    ConsensusResult : Estimations and rectangle signature results for each consensus run.
     """
     assert isinstance(adata, AnnData), "adata must be an AnnData object"
     assert isinstance(bulks, DataFrame), "bulks must be a DataFrame"
@@ -74,10 +91,11 @@ def rectangle(
         subsample = True
 
     estimations = []
+    rectangle_signature_results = []
     most_recent_signatures = None
 
-    for _i in range(consensus_runs):
-        logger.info(f"Running consensus run {_i + 1} of {consensus_runs}")
+    for i in range(consensus_runs):
+        logger.info(f"Running consensus run {i + 1} of {consensus_runs}")
         signatures = build_rectangle_signatures(
             adata,
             cell_type_col,
@@ -90,12 +108,76 @@ def rectangle(
             n_cpus=n_cpus,
             subsample=subsample,
             sample_size=sample_size,
+            run=i,
         )
+        rectangle_signature_results.append(signatures)
+        most_recent_signatures = signatures
         cell_fractions = deconvolution(signatures, bulks, correct_mrna_bias, n_cpus)
         estimations.append(cell_fractions)
-        most_recent_signatures = signatures
 
-    return pd.concat(estimations).groupby(level=0).median(), most_recent_signatures
+    consensus_results = ConsensusResult(estimations, rectangle_signature_results)
+    return pd.concat(estimations).groupby(level=0).median(), most_recent_signatures, consensus_results
+
+
+def rectangle(
+    adata: AnnData,
+    bulks: DataFrame,
+    cell_type_col: str = "cell_type",
+    *,
+    layer: str = None,
+    raw: bool = False,
+    correct_mrna_bias: bool = True,
+    optimize_cutoffs=True,
+    p=0.015,
+    lfc=1.5,
+    n_cpus: int = None,
+) -> tuple[DataFrame, RectangleSignatureResult]:
+    r"""All in one deconvolution method. Creates signatures and deconvolutes the bulk data. Has options for subsampling and consensus runs.
+
+    Parameters
+    ----------
+    adata
+        The single-cell count data as a DataFrame. DataFrame must have the genes as index and cell identifier as columns. Each entry should be in raw counts.
+    bulks
+        The bulk data as a DataFrame. DataFrame must have the bulk identifier as index and the genes as columns. Each entry should be in transcripts per million (TPM).
+    cell_type_col
+        The annotations corresponding to the single-cell count data. Series data should have the cell identifier as index and the annotations as values.
+    layer
+        The Anndata layer to use for the single-cell data.
+    raw
+        A flag indicating whether to use the raw Anndata data.
+    optimize_cutoffs
+        Indicates whether to optimize the p-value and log fold change cutoffs using gridsearch.
+    p
+        The p-value threshold for the DE analysis (only used if optimize_cutoffs is False).
+    lfc
+        The log fold change threshold for the DE analysis (only used if optimize_cutoffs is False).
+    n_cpus
+        The number of cpus to use for the DE analysis. None value takes all cpus available.
+    correct_mrna_bias : bool
+        A flag indicating whether to correct for mRNA bias. Defaults to True.
+
+    Returns
+    -------
+    DataFrame : The estimated cell fractions.
+    RectangleSignatureResult : The result of the rectangle signature analysis.
+    """
+    estimations, signatures, _ = rectangle_consens(
+        adata,
+        bulks,
+        cell_type_col,
+        layer=layer,
+        raw=raw,
+        subsample=False,
+        sample_size=-1,
+        consensus_runs=1,
+        correct_mrna_bias=correct_mrna_bias,
+        optimize_cutoffs=optimize_cutoffs,
+        p=p,
+        lfc=lfc,
+        n_cpus=n_cpus,
+    )
+    return estimations, signatures
 
 
 def load_tutorial_data() -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/src/rectanglepy/tl/deconvolution.py

@@ -257,7 +257,14 @@ def _deconvolute(signatures: RectangleSignatureResult, bulk: pd.Series, correct_
     averaged_start_fractions = (start_fractions + union_direct_fraction) / 2
 
     final_fractions = []
-    cell_types_with_low_number_of_marker_genes = signatures.cell_types_with_low_number_of_marker_genes()
+
+    low_number_threshold = 30
+    cell_types_with_low_number_of_marker_genes = [
+        cell_type
+        for cell_type, num_marker_genes in signatures.marker_genes_per_cell_type.items()
+        if len(num_marker_genes) < low_number_threshold
+    ]
+
     for cell_type in list(averaged_start_fractions.index):
         if cell_type in cell_types_with_low_number_of_marker_genes:
             final_fractions.append(recursive_fractions[cell_type])

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/tests/test_pp.py

@@ -146,7 +146,7 @@ def test_build_rectangle_signatures(small_data):
     adata = AnnData(sc_counts.T, obs=annotations.to_frame(name="cell_type"))
     results = build_rectangle_signatures(adata, "cell_type", bulks=bulk.T, p=0.5, lfc=0.1, optimize_cutoffs=False)
     assert results.assignments is None  # not enough cells to cluster
-    assert 10 < len(results.signature_genes) < 100
+    assert 10 < len(results.signature_genes) < 400
 
 
 def test_generate_pseudo_bulks(small_data):

{rectanglepy-0.1.3 → rectanglepy-0.1.7}/tests/test_rectangle.py

@@ -2,6 +2,7 @@ import pandas as pd
 from anndata import AnnData
 
 import rectanglepy.rectangle
+from rectanglepy import ConsensusResult
 from rectanglepy.pp import RectangleSignatureResult
 
 
@@ -24,11 +25,21 @@ def test_rectangle():
 
 def test_rectangle_consensus():
     sc_data, annotations, bulks = rectanglepy.load_tutorial_data()
+    sc_data = sc_data.iloc[:, :500]
     sc_data_adata = AnnData(sc_data, obs=annotations.to_frame(name="cell_type"))
 
-    result = rectanglepy.rectangle(
-        sc_data_adata, bulks, optimize_cutoffs=False, p=0.5, lfc=0.0, consensus_runs=2, sample_size=50
+    result = rectanglepy.rectangle_consens(
+        sc_data_adata, bulks, optimize_cutoffs=False, p=0.5, lfc=0.0, consensus_runs=3, sample_size=50
     )
 
     assert isinstance(result[0], pd.DataFrame)
     assert isinstance(result[1], RectangleSignatureResult)
+    assert isinstance(result[2], ConsensusResult)
+
+    # all bias factors should differ, else there is a problem with the random sampling
+    consensus_results = result[2]
+    signature_results = consensus_results.rectangle_signature_results
+    bias_factors = [result.bias_factors for result in signature_results]
+    assert bias_factors[0]["Monocytes"] != bias_factors[1]["Monocytes"]
+    assert bias_factors[0]["Monocytes"] != bias_factors[2]["Monocytes"]
+    assert bias_factors[1]["Monocytes"] != bias_factors[2]["Monocytes"]

rectanglepy-0.1.3/docs/api.md

@@ -1,15 +0,0 @@
-# API
-
-## Rectangle
-
-```{eval-rst}
-.. currentmodule:: rectanglepy
-
-.. autosummary::
-    :toctree: generated
-
-    rectangle
-    pp.build_rectangle_signatures
-    pp.RectangleSignatureResult
-    tl.deconvolution
-```

rectanglepy-0.1.3/src/rectanglepy/__init__.py

@@ -1,8 +0,0 @@
-from importlib.metadata import version
-
-from . import pp, tl
-from .rectangle import load_tutorial_data, rectangle
-
-__all__ = ["pp", "tl", "load_tutorial_data", "rectangle"]
-
-__version__ = version("rectanglepy")