SpatialQuery 0.0.5__tar.gz → 0.0.6__tar.gz

{spatialquery-0.0.5/SpatialQuery.egg-info → spatialquery-0.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SpatialQuery
-Version: 0.0.5
+Version: 0.0.6
 Summary: Spatial query tools for analyzing spatial transcriptomics data
 Author-email: Shaokun An <shan12@bwh.harvard.edu>
 License-Expression: MIT
@@ -35,6 +35,10 @@ Requires-Dist: sphinx-copybutton; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
 Dynamic: license-file
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ShaokunAn/Spatial-Query/main/docs/_static/img/logo.png" alt="SpatialQuery" width="480">
+</p>
+
 # SpatialQuery
 
 SpatialQuery is a Python package for systematic spatial analysis of single-cell resolution spatial omics data. It provides a unified framework to discover, quantify, and compare recurring spatial cell type patterns — termed *motifs* — across single or multiple fields of view (FOVs).
@@ -47,6 +51,7 @@ Key capabilities include:
 
 - **Spatial motif discovery**: Identify frequent cell type patterns in local neighborhoods
 - **Motif enrichment analysis**: Statistically test whether motifs occur more than expected
+- **Motif composition**: Quantify the relative abundance of each motif cell type within motif-positive neighborhoods
 - **Differential motif analysis**: Compare spatial compositions across conditions
 - **Motif-associated differential expression**: Find DE genes linked to specific motifs
 - **Cross-cell gene-gene covariation**: Detect spatially dependent intercellular gene correlations
@@ -58,13 +63,15 @@ Key capabilities include:
 pip install SpatialQuery
 ```
 
+> **Note:** Installation typically takes ~5 minutes depending on your environment.
+
 ## Documentation
 
 Full documentation, tutorials, and API reference: **[https://spatialquery.readthedocs.io/en/latest/](https://spatialquery.readthedocs.io/en/latest/)**
 
 ## Reproducibility
 
-The following tutorials reproduce the main analyses presented in our manuscript:
+The following tutorials reproduce the main analyses presented in our manuscript. Each tutorial takes approximately 5–20 minutes to run depending on dataset size and hardware.
 
 - [Mouse organogenesis — single-FOV analysis (seqFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_1.html)
 - [Kidney disease atlas — multi-condition analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_2.html)
@@ -90,6 +97,12 @@ spm = spatial_query_multi(adatas=adatas, datasets=datasets,
 enrich_motif = spm.motif_enrichment_dist(ct="T_cell", dataset="healthy", max_dist=10, min_support=0.5)
 ```
 
+## Citation
+
+If you use SpatialQuery in your research, please cite:
+
+> An, S. et al. [SpatialQuery: scalable discovery and molecular characterization of multicellular motifs from spatial omics data](https://www.biorxiv.org/content/10.64898/2026.04.22.720136v1). *bioRxiv* (2026).
+
 ## License
 
 MIT

{spatialquery-0.0.5 → spatialquery-0.0.6}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ShaokunAn/Spatial-Query/main/docs/_static/img/logo.png" alt="SpatialQuery" width="480">
+</p>
+
 # SpatialQuery
 
 SpatialQuery is a Python package for systematic spatial analysis of single-cell resolution spatial omics data. It provides a unified framework to discover, quantify, and compare recurring spatial cell type patterns — termed *motifs* — across single or multiple fields of view (FOVs).
@@ -10,6 +14,7 @@ Key capabilities include:
 
 - **Spatial motif discovery**: Identify frequent cell type patterns in local neighborhoods
 - **Motif enrichment analysis**: Statistically test whether motifs occur more than expected
+- **Motif composition**: Quantify the relative abundance of each motif cell type within motif-positive neighborhoods
 - **Differential motif analysis**: Compare spatial compositions across conditions
 - **Motif-associated differential expression**: Find DE genes linked to specific motifs
 - **Cross-cell gene-gene covariation**: Detect spatially dependent intercellular gene correlations
@@ -21,13 +26,15 @@ Key capabilities include:
 pip install SpatialQuery
 ```
 
+> **Note:** Installation typically takes ~5 minutes depending on your environment.
+
 ## Documentation
 
 Full documentation, tutorials, and API reference: **[https://spatialquery.readthedocs.io/en/latest/](https://spatialquery.readthedocs.io/en/latest/)**
 
 ## Reproducibility
 
-The following tutorials reproduce the main analyses presented in our manuscript:
+The following tutorials reproduce the main analyses presented in our manuscript. Each tutorial takes approximately 5–20 minutes to run depending on dataset size and hardware.
 
 - [Mouse organogenesis — single-FOV analysis (seqFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_1.html)
 - [Kidney disease atlas — multi-condition analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_2.html)
@@ -53,6 +60,12 @@ spm = spatial_query_multi(adatas=adatas, datasets=datasets,
 enrich_motif = spm.motif_enrichment_dist(ct="T_cell", dataset="healthy", max_dist=10, min_support=0.5)
 ```
 
+## Citation
+
+If you use SpatialQuery in your research, please cite:
+
+> An, S. et al. [SpatialQuery: scalable discovery and molecular characterization of multicellular motifs from spatial omics data](https://www.biorxiv.org/content/10.64898/2026.04.22.720136v1). *bioRxiv* (2026).
+
 ## License
 
 MIT

{spatialquery-0.0.5 → spatialquery-0.0.6}/SpatialQuery/__init__.py

@@ -7,7 +7,8 @@ from .plotting import (
     plot_motif_grid,
     plot_motif_rand,
     plot_motif_celltype,
-    plot_all_center_motif
+    plot_all_center_motif,
+    plot_motif_composition
 )
 
 __all__ = [
@@ -22,5 +23,6 @@ __all__ = [
     'plot_motif_rand',
     'plot_motif_celltype',
     'plot_all_center_motif',
+    'plot_motif_composition',
     'interactive_motif'
 ]

{spatialquery-0.0.5 → spatialquery-0.0.6}/SpatialQuery/plotting.py

@@ -670,7 +670,88 @@ def plot_motif_enrichment_heatmap(enrich_df: pd.DataFrame,
         plt.savefig(save_path, dpi=300, bbox_inches='tight')
 
     plt.show()
-    
+
+
+def plot_motif_composition(comp_df: pd.DataFrame,
+                           motif: Optional[List[str]] = None,
+                           bins: int = 25,
+                           colors: Optional[List] = None,
+                           figsize: tuple = (6, 5),
+                           title: Optional[str] = None,
+                           save_path: Optional[str] = None):
+    """
+    Plot the distribution of each motif cell type's proportion across motif-positive center cells.
+
+    One semi-transparent histogram per motif cell type, on fixed bins over [0, 1]; the legend
+    reports the median and interquartile range (IQR) of each type's proportion.
+
+    Parameters
+    ----------
+    comp_df : pd.DataFrame
+        Output from motif_composition_dist or motif_composition_knn.
+    motif : List[str], optional
+        Motif to plot. May be omitted when comp_df holds a single motif.
+    bins : int, default=25
+        Number of equal-width bins on [0, 1].
+    colors : List, optional
+        One color per motif cell type, in sorted cell type order. Defaults to the tab10 palette.
+    figsize : tuple, default=(6, 5)
+        Figure size.
+    title : str, optional
+        Figure title. Defaults to the center cell type and the motif.
+    save_path : str, optional
+        Path to save the figure. If None, the figure will not be saved.
+
+    Returns
+    -------
+    None
+        Displays a histogram of motif cell type proportions.
+    """
+    if len(comp_df) == 0:
+        print("No motif-positive center cells to plot.")
+        return
+
+    keys = comp_df['motifs'].map(spatial_utils.canonical_motif)
+    if motif is None:
+        if keys.nunique() > 1:
+            raise ValueError("comp_df holds several motifs; specify which one to plot with motif.")
+        motif_key = keys.iloc[0]
+    else:
+        motif_key = spatial_utils.canonical_motif([motif] if isinstance(motif, str) else motif)
+    df = comp_df[keys == motif_key]
+    if len(df) == 0:
+        raise ValueError(f"Motif {list(motif_key)} is not in comp_df.")
+
+    cell_types = list(motif_key)
+    if colors is None:
+        colors = [plt.cm.tab10(i % 10) for i in range(len(cell_types))]
+    bin_edges = np.linspace(0, 1, bins + 1)
+
+    fig, ax = plt.subplots(figsize=figsize)
+    for cell_type, color in zip(cell_types, colors):
+        values = df.loc[df['cell_type'] == cell_type, 'proportion'].to_numpy(dtype=float)
+        q25, median, q75 = np.percentile(values, [25, 50, 75])
+        ax.hist(values, bins=bin_edges, color=color, alpha=0.5,
+                label=f'{cell_type}\n(median={median:.2f}, IQR={q75 - q25:.2f})')
+
+    ax.set_xlim(-0.03, 1.03)
+    ax.set_xlabel('Relative abundance among motif-associated cells', fontsize=12)
+    ax.set_ylabel('Number of motif-positive anchors', fontsize=12)
+    ax.spines[['top', 'right']].set_visible(False)
+    ax.legend(frameon=False, fontsize=10, loc='best')
+
+    if title is None:
+        centers = df['center'].unique()
+        center = f'{centers[0]} | ' if len(centers) == 1 else ''
+        title = f'{center}{" + ".join(cell_types)}'
+    ax.set_title(title, fontsize=13)
+    plt.tight_layout()
+
+    if save_path is not None:
+        plt.savefig(save_path, dpi=300, bbox_inches='tight')
+
+    plt.show()
+
 
 def plot_differential_pattern_heatmap(
     diff_motif: dict,

{spatialquery-0.0.5 → spatialquery-0.0.6}/SpatialQuery/spatial_gene_covarying.py

@@ -4395,6 +4395,7 @@ def compute_gene_gene_correlation_by_type_binary_multi_fov(
         if len(non_center_types) == 1:
             print(f"Only one non-center cell type in motif: {non_center_types}. Using compute_gene_gene_correlation_binary method.")
             result = compute_gene_gene_correlation_binary_multi_fov(
+                sq_objs=sq_objs,
                 ct=ct,
                 motif=motif,
                 dataset=dataset,

{spatialquery-0.0.5 → spatialquery-0.0.6}/SpatialQuery/spatial_query.py

@@ -157,6 +157,7 @@ class spatial_query:
                     k: int = 30,
                     min_support: float = 0.5,
                     max_dist: float = 20,
+                    if_max: bool = True,
                     ) -> pd.DataFrame:
         """
         Find frequent patterns within the KNNs of certain cell type.
@@ -171,6 +172,9 @@ class spatial_query:
             Threshold of frequency to consider a pattern as a frequent pattern.
         max_dist : float, default=20
             Maximum distance for considering a cell as a neighbor.
+        if_max : bool, default=True
+            Return only maximal patterns. Set to False to return every frequent pattern,
+            which nested motif enrichment needs to look up sub-pattern supports.
 
         Returns
         -------
@@ -190,7 +194,7 @@ class spatial_query:
             k=k,
             min_support=min_support,
             max_dist=max_dist,
-            if_max=True
+            if_max=if_max
         )
 
         return fp
@@ -200,6 +204,7 @@ class spatial_query:
                      max_dist: float = 20,
                      min_size: int = 0,
                      min_support: float = 0.5,
+                     if_max: bool = True,
                      ):
         """
         Find frequent patterns within the radius of certain cell type.
@@ -214,6 +219,9 @@ class spatial_query:
             Minimum neighborhood size for each point to consider.
         min_support : float, default=0.5
             Threshold of frequency to consider a pattern as a frequent pattern.
+        if_max : bool, default=True
+            Return only maximal patterns. Set to False to return every frequent pattern,
+            which nested motif enrichment needs to look up sub-pattern supports.
 
         Returns
         -------
@@ -233,7 +241,8 @@ class spatial_query:
             max_dist=max_dist,
             min_size=min_size,
             min_support=min_support,
-            cinds=cinds
+            cinds=cinds,
+            if_max=if_max
         )
 
         return fp
@@ -244,7 +253,8 @@ class spatial_query:
                              k: int = 30,
                              min_support: float = 0.5,
                              max_dist: float = 20,
-                             return_cellID: bool = False
+                             return_cellID: bool = False,
+                             mode: str = 'maximal'
                              ) -> pd.DataFrame:
         """
         Perform motif enrichment analysis using k-nearest neighbors (KNN).
@@ -265,6 +275,16 @@ class spatial_query:
         return_cellID : bool, default=False
             Indicate whether return cell IDs for each frequent pattern within the neighborhood of grid points.
             By defaults do not return cell ID.
+        mode : {'maximal', 'nested'}, default='maximal'
+            How the motifs to test are chosen when motifs=None. Ignored when motifs is given.
+
+            'maximal'
+                Test the maximal patterns only.
+            'nested'
+                Test the maximal patterns, then descend into the sub-patterns of any that
+                are not significant, stopping a branch as soon as it becomes significant or
+                reaches length 1. Finds cores that a maximal pattern hides when one abundant
+                cell type dilutes it. Multiple-testing correction covers everything tested.
 
         Returns
         -------
@@ -285,6 +305,27 @@ class spatial_query:
         if ct not in self.labels.unique():
             raise ValueError(f"Found no {ct} in {self.label_key}!")
 
+        if mode not in ('nested', 'maximal'):
+            raise ValueError(f"mode must be 'nested' or 'maximal', got {mode!r}")
+
+        # Nested descent only decides WHICH motifs get tested; each batch is scored by this
+        # same method, so the statistics are identical to the maximal mode's.
+        if mode == 'nested' and motifs is None:
+            fp_all = self.find_fp_knn(ct=ct, k=k, min_support=min_support,
+                                      max_dist=max_dist, if_max=False)
+            if len(fp_all) == 0:
+                return spatial_utils.apply_fdr_correction(pd.DataFrame())
+            # Cell IDs are DataFrame columns here, so they travel with the rows and need
+            # no separate merging.
+            return spatial_utils.nested_motif_descent(
+                test_motifs=lambda ms: self.motif_enrichment_knn(
+                    ct=ct, motifs=ms, k=k, min_support=min_support, max_dist=max_dist,
+                    return_cellID=return_cellID, mode='maximal'),
+                maximal_motifs=spatial_utils.find_maximal_patterns(fp_all)['itemsets'],
+                support_of={spatial_utils.canonical_motif(i): s
+                            for i, s in zip(fp_all['itemsets'], fp_all['support'])},
+            )
+
         dists, idxs = self.kd_tree.query(self.spatial_pos,
                                          k=k + 1, workers=-1
                                          )  # use k+1 to find the knn except for the points themselves
@@ -418,6 +459,7 @@ class spatial_query:
                               min_size: int = 0,
                               min_support: float = 0.5,
                               return_cellID: bool = False,
+                              mode: str = 'maximal',
                               ) -> DataFrame:
         """
         Perform motif enrichment analysis within a specified radius-based neighborhood.
@@ -438,6 +480,16 @@ class spatial_query:
         return_cellID : bool, default=False
             Indicate whether return cell IDs for each motif within the neighborhood of central cell type.
             By defaults do not return cell ID.
+        mode : {'maximal', 'nested'}, default='maximal'
+            How the motifs to test are chosen when motifs=None. Ignored when motifs is given.
+
+            'maximal'
+                Test the maximal patterns only.
+            'nested'
+                Test the maximal patterns, then descend into the sub-patterns of any that
+                are not significant, stopping a branch as soon as it becomes significant or
+                reaches length 1. Finds cores that a maximal pattern hides when one abundant
+                cell type dilutes it. Multiple-testing correction covers everything tested.
 
         Returns
         -------
@@ -458,6 +510,28 @@ class spatial_query:
         if ct not in self.labels.unique():
             raise ValueError(f"Found no {ct} in {self.label_key}!")
 
+        if mode not in ('nested', 'maximal'):
+            raise ValueError(f"mode must be 'nested' or 'maximal', got {mode!r}")
+
+        # Nested descent only decides WHICH motifs get tested; each batch is scored by this
+        # same method, so the statistics are identical to the maximal mode's.
+        if mode == 'nested' and motifs is None:
+            fp_all = self.find_fp_dist(ct=ct, max_dist=max_dist, min_size=min_size,
+                                       min_support=min_support, if_max=False)
+            if len(fp_all) == 0:
+                return spatial_utils.apply_fdr_correction(pd.DataFrame())
+            # Cell IDs are DataFrame columns here, so they travel with the rows and need
+            # no separate merging.
+            return spatial_utils.nested_motif_descent(
+                test_motifs=lambda ms: self.motif_enrichment_dist(
+                    ct=ct, motifs=ms, max_dist=max_dist, min_size=min_size,
+                    min_support=min_support, return_cellID=return_cellID,
+                    mode='maximal'),
+                maximal_motifs=spatial_utils.find_maximal_patterns(fp_all)['itemsets'],
+                support_of={spatial_utils.canonical_motif(i): s
+                            for i, s in zip(fp_all['itemsets'], fp_all['support'])},
+            )
+
         out = []
         if motifs is None:
             fp = self.find_fp_dist(ct=ct,
@@ -576,6 +650,109 @@ class spatial_query:
             out_pd = out_pd.sort_values(by='adj-pval', ignore_index=True)
             return out_pd
 
+    def motif_composition_dist(self,
+                               ct: str,
+                               motifs: Union[str, List[str], List[List[str]]],
+                               max_dist: float = 20,
+                               ) -> pd.DataFrame:
+        """
+        Compute the composition of motif cell types in the radius-based neighborhoods of center cells.
+
+        Uses the same neighborhoods as motif_enrichment_dist, but performs no enrichment test.
+        Only center cells whose neighborhood contains every cell type of the motif (motif-positive
+        centers) are kept. For each of them, the proportion of a motif cell type is its number of
+        cells divided by the total number of motif-type cells in that neighborhood.
+
+        Parameters
+        ----------
+        ct : str
+            Cell type as the center cells.
+        motifs : str or List[str] or List[List[str]]
+            Motifs to analyze, e.g. the 'motifs' column of motif_enrichment_dist output.
+        max_dist : float, default=20
+            Maximum distance for considering a cell as a neighbor.
+
+        Returns
+        -------
+        pd.DataFrame
+            Long-format table with one row per (motif-positive center cell, motif cell type):
+                - center: center cell type name
+                - motifs: sorted list of cell types in the motif
+                - cell_type: motif cell type this row describes
+                - n_cells: number of cells of cell_type in the neighborhood
+                - n_motif_cells: number of motif-type cells in the neighborhood
+                - proportion: n_cells / n_motif_cells
+        """
+        if ct not in self.labels.unique():
+            raise ValueError(f"Found no {ct} in {self.label_key}!")
+        motifs = spatial_utils.normalize_motif_list(motifs, self.labels.unique(), self.label_key)
+
+        label_encoder = LabelEncoder()
+        int_labels = label_encoder.fit_transform(np.array(self.labels))
+        cinds = np.where(self.labels == ct)[0]
+        counts = spatial_utils.anchor_neighbor_counts_dist(
+            self.kd_tree, self.spatial_pos, cinds, int_labels,
+            len(label_encoder.classes_), max_dist)
+
+        out = [spatial_utils.motif_composition_table(
+            ct, motif, counts[:, label_encoder.transform(np.array(motif))]) for motif in motifs]
+        if len(out) == 0:
+            return pd.DataFrame(columns=spatial_utils.COMPOSITION_COLUMNS)
+        return pd.concat(out, ignore_index=True)
+
+    def motif_composition_knn(self,
+                              ct: str,
+                              motifs: Union[str, List[str], List[List[str]]],
+                              k: int = 30,
+                              max_dist: float = 20,
+                              ) -> pd.DataFrame:
+        """
+        Compute the composition of motif cell types in the k-nearest-neighbor neighborhoods of center cells.
+
+        Uses the same neighborhoods as motif_enrichment_knn, but performs no enrichment test.
+        Only center cells whose neighborhood contains every cell type of the motif (motif-positive
+        centers) are kept. For each of them, the proportion of a motif cell type is its number of
+        cells divided by the total number of motif-type cells in that neighborhood.
+
+        Parameters
+        ----------
+        ct : str
+            Cell type of the center cell.
+        motifs : str or List[str] or List[List[str]]
+            Motifs to analyze, e.g. the 'motifs' column of motif_enrichment_knn output.
+        k : int, default=30
+            Number of nearest neighbors to consider.
+        max_dist : float, default=20
+            Maximum distance for neighbors.
+
+        Returns
+        -------
+        pd.DataFrame
+            Long-format table with one row per (motif-positive center cell, motif cell type):
+                - center: center cell type name
+                - motifs: sorted list of cell types in the motif
+                - cell_type: motif cell type this row describes
+                - n_cells: number of cells of cell_type in the neighborhood
+                - n_motif_cells: number of motif-type cells in the neighborhood
+                - proportion: n_cells / n_motif_cells
+        """
+        if ct not in self.labels.unique():
+            raise ValueError(f"Found no {ct} in {self.label_key}!")
+        motifs = spatial_utils.normalize_motif_list(motifs, self.labels.unique(), self.label_key)
+
+        label_encoder = LabelEncoder()
+        int_labels = label_encoder.fit_transform(np.array(self.labels))
+        cinds = np.where(self.labels == ct)[0]
+        counts = spatial_utils.anchor_neighbor_counts_knn(
+            self.kd_tree, self.spatial_pos, cinds, int_labels,
+            len(label_encoder.classes_), k, max_dist)
+
+        out = [spatial_utils.motif_composition_table(
+            ct, motif, counts[:, label_encoder.transform(np.array(motif))]) for motif in motifs]
+        if len(out) == 0:
+            return pd.DataFrame(columns=spatial_utils.COMPOSITION_COLUMNS)
+        return pd.concat(out, ignore_index=True)
+
 
     def find_patterns_grid(self,
                            max_dist: float = 20,
@@ -1404,6 +1581,42 @@ class spatial_query:
         """
         return plotting.plot_motif_enrichment_heatmap(enrich_df=enrich_df, figsize=figsize,
                                                        save_path=save_path, title=title, cmap=cmap)
+
+    def plot_motif_composition(self,
+                               comp_df: pd.DataFrame,
+                               motif: Optional[List[str]] = None,
+                               bins: int = 25,
+                               colors: Optional[List] = None,
+                               figsize: tuple = (6, 5),
+                               title: Optional[str] = None,
+                               save_path: Optional[str] = None):
+        """
+        Plot the distribution of each motif cell type's proportion across motif-positive center cells.
+
+        Parameters
+        ----------
+        comp_df : pd.DataFrame
+            Output DataFrame from motif_composition_dist or motif_composition_knn.
+        motif : List[str], optional
+            Motif to plot. May be omitted when comp_df holds a single motif.
+        bins : int, default=25
+            Number of equal-width bins on [0, 1].
+        colors : List, optional
+            One color per motif cell type, in sorted cell type order. Defaults to the tab10 palette.
+        figsize : tuple, default=(6, 5)
+            Figure size.
+        title : str, optional
+            Figure title. Defaults to the center cell type and the motif.
+        save_path : str, optional
+            Path to save the figure. If None, the figure will not be saved.
+
+        Returns
+        -------
+        None
+            Displays a histogram of motif cell type proportions, with median and IQR in the legend.
+        """
+        return plotting.plot_motif_composition(comp_df=comp_df, motif=motif, bins=bins, colors=colors,
+                                               figsize=figsize, title=title, save_path=save_path)
         
     def plot_gene_pair_heatmap(self,
                                gene_pair_df: pd.DataFrame,