zmap-tools 0.2.0__tar.gz → 0.2.1__tar.gz

{zmap_tools-0.2.0 → zmap_tools-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zmap-tools
-Version: 0.2.0
+Version: 0.2.1
 Summary: API for working with ZMAP (Zebrafish Multi-Atlas Project)
 Author-email: Daniel Wagner <Daniel.Wagner@ucsf.edu>
 License: BSD 3-Clause License

{zmap_tools-0.2.0 → zmap_tools-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmap-tools"
-version = "0.2.0"
+version = "0.2.1"
 description = "API for working with ZMAP (Zebrafish Multi-Atlas Project)"
 readme = "README.md"
 requires-python = ">=3.10"

{zmap_tools-0.2.0 → zmap_tools-0.2.1}/src/zmap/predict/predict.py

@@ -962,7 +962,7 @@ def predict_labels_kNN(
         )
 
     # compact digest to validate cache
-    _mask_digest = [int(n_ref_keep), int(np.sum(np.flatnonzero(ref_keep_mask.to_numpy()) % 1048573))]
+    _mask_digest = [str(int(n_ref_keep)), str(int(np.sum(np.flatnonzero(ref_keep_mask.to_numpy()) % 1048573)))]
 
     # filtered reference arrays
     X_ref_all = adata_ref.obsm[ref_basis]
@@ -1101,7 +1101,7 @@ def predict_labels_kNN(
 
     predicted_labels = sorted_classes[np.argmax(probabilities_sorted, axis=1)]
     predicted_labels = predicted_labels.astype(object)
-    predicted_labels[~has_votes] = pd.NA
+    predicted_labels[~has_votes] = np.nan
 
     # ---------- outputs ----------
     if omit_labels:
@@ -1224,7 +1224,7 @@ def predict_labels_kNN(
         adata_query.obs[col_reject] = ~accept
 
         # Mask rejected predictions
-        adata_query.obs.loc[~accept, col_main] = pd.NA
+        adata_query.obs.loc[~accept, col_main] = np.nan
 
         n_total = len(accept)
         n_accept = int(accept.sum())
@@ -1285,7 +1285,7 @@ def predict_labels_kNN(
         rare_labels = label_counts[label_counts < min_cells_per_label].index
         if len(rare_labels) > 0:
             adata_query.obs[col_rareflag] = adata_query.obs[col_main].isin(rare_labels)
-            adata_query.obs.loc[adata_query.obs[col_rareflag], col_main] = pd.NA
+            adata_query.obs.loc[adata_query.obs[col_rareflag], col_main] = np.nan
             adata_query.uns.setdefault('zmap_labels', {}).setdefault(space, {})
             adata_query.uns['zmap_labels'][space]['Rare Labels'] = list(rare_labels)
             _zlog(f"Filtered {len(rare_labels)} rare labels: {list(rare_labels[:10])}{'...' if len(rare_labels) > 10 else ''}")
@@ -1671,8 +1671,8 @@ def predict_labels_tissue_kNN(
         )
 
     mask_digest = [
-        int(n_ref_keep),
-        int(np.sum(np.flatnonzero(ref_keep_mask.to_numpy()) % 1048573)),
+        str(int(n_ref_keep)),
+        str(int(np.sum(np.flatnonzero(ref_keep_mask.to_numpy()) % 1048573))),
     ]
 
     p_thresh_use = p_thresh
@@ -2061,6 +2061,8 @@ def summarize_knn_run(adata_query, label_key):
         ("pct_assigned", cov.get("pct_assigned")),
     ], columns=["Key", "Value"])
 
+    df["Value"] = df["Value"].astype(str)
+
     return df
 
 
@@ -2305,6 +2307,11 @@ def build_cell_annotations_table(
     df.index.name = "cell_id"
     df = df.reset_index()
 
+    # Ensure object columns are pure str (np.nan in object dtype is not h5ad-serializable in uns)
+    for col in df.columns:
+        if df[col].dtype == object:
+            df[col] = df[col].fillna("").astype(str)
+
     if save_csv:
         os.makedirs(output_dir, exist_ok=True)
         out_path = os.path.join(output_dir, f"{label_space}_cell_annotations.csv")
@@ -2573,9 +2580,11 @@ def plot_embedding_with_ondata_labels(
     figsize: tuple[float, float] = (6, 6),
     dpi: int = 200,
 
-    # ---- point/legend style ----
+    # ---- point style ----
     ref_size: float = 2,
+    ref_alpha: float = 0.3,
     test_size: float = 2,
+    test_alpha: float = 1.0,
     cmap: str = "jet",
     frameon: bool = False,
     sort_order: bool = True,
@@ -2583,6 +2592,9 @@ def plot_embedding_with_ondata_labels(
     legend_fontsize: float = 5,
     legend_fontweight: str = "normal",
 
+    # ---- label visibility ----
+    show_labels: bool = True,
+
     # ---- label styling ----
     recolor_labels_from_palette: bool = True,
     text_stroke_width: float = 1.0,
@@ -2653,15 +2665,29 @@ def plot_embedding_with_ondata_labels(
         Figure size in inches ``(width, height)``.
     dpi : int, default ``200``
         Figure resolution.
-    ref_size, test_size : float, default ``2``
-        Scatter point sizes for reference background and query cells respectively.
+    ref_size : float, default ``2``
+        Scatter point size for reference background cells.
+    ref_alpha : float, default ``0.3``
+        Opacity of reference background points. Lower values push the
+        reference further into the background.
+    test_size : float, default ``2``
+        Scatter point size for query (projected) cells.
+    test_alpha : float, default ``1.0``
+        Opacity of query overlay points.
     cmap : str, default ``"jet"``
         Colormap used for the reference background scatter.
     legend_loc : str, default ``"on data"``
         Where to place the category legend. ``"on data"`` draws labels directly
         at centroid positions; other values follow matplotlib legend conventions.
+        Ignored when ``show_labels=False`` (forced to ``"none"``).
     legend_fontsize, legend_fontweight : float and str, default ``5`` and ``"normal"``
         Font size and weight for on-data legend labels.
+    show_labels : bool, default ``True``
+        If ``True``, draw on-data text labels at category centroids with
+        ``adjustText`` repositioning and optional arrow connectors. If
+        ``False``, suppress all text labels and arrows — only the colored
+        scatter is shown, which is useful for clean figures or when the
+        number of categories is too large for readable labels.
     replace_underscores : bool, default ``True``
         Replace underscores in label strings with line breaks for cleaner
         on-data annotation.
@@ -2669,17 +2695,23 @@ def plot_embedding_with_ondata_labels(
         ``(x_expand, y_expand)`` passed to ``adjustText`` for label placement.
     match_arrow_color_to_text : bool, default ``True``
         Color annotation arrows to match their corresponding text label.
+    ref_kwargs : dict or None, default ``None``
+        Extra keyword arguments forwarded to the reference ``sc.pl.embedding``
+        call. Explicit ``ref_alpha`` takes priority over ``alpha`` in this dict.
+    test_kwargs : dict or None, default ``None``
+        Extra keyword arguments forwarded to the query ``sc.pl.embedding``
+        call. Explicit ``test_alpha`` takes priority over ``alpha`` in this dict.
     show : bool, default ``False``
         Call ``plt.show()`` after rendering.
     save : bool, default ``True``
-        Save the figure as PNG and PDF to ``./zmap/predict/``.
+        Save the figure as PNG and PDF to ``output_dir``.
     return_ax : bool, default ``False``
         Return the main ``matplotlib.axes.Axes`` object.
 
     Returns
     -------
-    matplotlib.axes.Axes or None
-        The main axes when ``return_ax=True``, otherwise ``None``.
+    tuple or None
+        ``(fig, ax_umap, ax_strip)`` when ``return_ax=True``, otherwise ``None``.
     """
     # ---- prepare test AnnData (drop NAs on requested key, cast to categorical) ----
     if filter_na:
@@ -2745,6 +2777,13 @@ def plot_embedding_with_ondata_labels(
     test_kwargs = {} if test_kwargs is None else dict(test_kwargs)
     time_strip_kwargs = {} if time_strip_kwargs is None else dict(time_strip_kwargs)
 
+    # ---- Inject alpha into kwargs (explicit params take priority) ----
+    ref_kwargs.setdefault("alpha", ref_alpha)
+    test_kwargs.setdefault("alpha", test_alpha)
+
+    # ---- Resolve legend_loc: suppress labels when show_labels=False ----
+    legend_loc_use = legend_loc if show_labels else "none"
+
     # ---- Check if we actually have a time vector ----
     has_time = (
         show_time_strip and
@@ -2793,7 +2832,7 @@ def plot_embedding_with_ondata_labels(
             basis=basis,
             sort_order=sort_order,
             size=test_size,
-            legend_loc=legend_loc,
+            legend_loc=legend_loc_use,
             legend_fontweight=legend_fontweight,
             ax=ax,
             show=False,
@@ -2802,41 +2841,42 @@ def plot_embedding_with_ondata_labels(
             **test_kwargs,
         )
 
-        # --- obtain existing on-data labels ---
-        texts = [t for t in ax.texts]
+        # --- on-data label styling (only when show_labels=True) ---
+        if show_labels:
+            texts = [t for t in ax.texts]
 
-        # --- recolor existing on-data text labels by palette ---
-        if recolor_labels_from_palette:
-            for t in texts:
-                label = t.get_text()
-                if label in palette:
-                    t.set_color(palette[label])
-
-        # --- add white border to text labels ---
-        for t in texts:
-            t.set_path_effects([pe.withStroke(linewidth=text_stroke_width, foreground='white')])
+            # --- recolor existing on-data text labels by palette ---
+            if recolor_labels_from_palette:
+                for t in texts:
+                    label = t.get_text()
+                    if label in palette:
+                        t.set_color(palette[label])
 
-        # --- replace underscores with line breaks ---
-        if replace_underscores:
+            # --- add white border to text labels ---
             for t in texts:
-                t.set_text(t.get_text().replace(linebreak_from, linebreak_to))
-
-        # --- adjust label positions with slim arrows ---
-        if len(texts) > 0:
-            adjust_text(
-                texts,
-                ax=ax,
-                expand=adjust_expand,
-                arrowprops=arrowprops,
-                min_arrow_len=min_arrow_len,
-            )
+                t.set_path_effects([pe.withStroke(linewidth=text_stroke_width, foreground='white')])
+
+            # --- replace underscores with line breaks ---
+            if replace_underscores:
+                for t in texts:
+                    t.set_text(t.get_text().replace(linebreak_from, linebreak_to))
+
+            # --- adjust label positions with slim arrows ---
+            if len(texts) > 0:
+                adjust_text(
+                    texts,
+                    ax=ax,
+                    expand=adjust_expand,
+                    arrowprops=arrowprops,
+                    min_arrow_len=min_arrow_len,
+                )
 
-        # --- match arrow color to label color ---
-        if match_arrow_color_to_text and len(texts) > 0:
-            arrows = [p for p in ax.patches if isinstance(p, FancyArrowPatch)]
-            for t, a in zip(texts, arrows[-len(texts):]):
-                a.set_color(t.get_color())
-                a.set_alpha(arrow_alpha)
+            # --- match arrow color to label color ---
+            if match_arrow_color_to_text and len(texts) > 0:
+                arrows = [p for p in ax.patches if isinstance(p, FancyArrowPatch)]
+                for t, a in zip(texts, arrows[-len(texts):]):
+                    a.set_color(t.get_color())
+                    a.set_alpha(arrow_alpha)
 
         # ---- time distribution strip on the right (rotated) ----
         if has_time and ax_strip is not None:
@@ -2920,7 +2960,6 @@ def plot_embedding_with_ondata_labels(
     return None
 
 
-
 # ================================================================
 #  6. Overlap matrix & plot
 # ================================================================
@@ -4186,8 +4225,14 @@ def plot_embedding(
     label_space: str | None = None,
     *,
     save: bool = False,
+    show_labels: bool = True,
+    ref_size: float = 2,
+    ref_alpha: float = 0.3,
+    test_size: float = 2,
+    test_alpha: float = 1.0,
+    return_ax: bool = False,
     **kwargs,
-) -> None:
+) -> tuple | None:
     """
     Re-plot the UMAP overlay with on-data labels and time strip.
 
@@ -4202,8 +4247,26 @@ def plot_embedding(
         Label namespace. When ``None``, uses the most recent run.
     save : bool, default ``False``
         Save the figure to the run's output directory.
+    show_labels : bool, default ``True``
+        If ``True``, draw on-data text labels at category centroids.
+        If ``False``, suppress all text labels and arrows.
+    ref_size : float, default ``2``
+        Scatter point size for reference background cells.
+    ref_alpha : float, default ``0.3``
+        Opacity of reference background points.
+    test_size : float, default ``2``
+        Scatter point size for query (projected) cells.
+    test_alpha : float, default ``1.0``
+        Opacity of query overlay points.
+    return_ax : bool, default ``False``
+        Return ``(fig, ax_umap, ax_strip)`` instead of ``None``.
     **kwargs
         Extra keyword arguments forwarded to ``plot_embedding_with_ondata_labels``.
+
+    Returns
+    -------
+    tuple or None
+        ``(fig, ax_umap, ax_strip)`` when ``return_ax=True``, otherwise ``None``.
     """
     label_space, config = _resolve_config(adata_query, label_space)
     space_store = adata_query.uns.get("zmap_labels", {}).get(label_space, {})
@@ -4226,13 +4289,19 @@ def plot_embedding(
     time_key = config.get("time_col", "ZMAP_time_id_predicted")
     space_dir = config.get("output_dir", os.path.join("zmap_predict", label_space))
 
-    plot_embedding_with_ondata_labels(
+    return plot_embedding_with_ondata_labels(
         adata_ref_mini,
         adata_query,
         color_key=color_key,
         time_key=time_key,
         show=True,
         save=save,
+        show_labels=show_labels,
+        ref_size=ref_size,
+        ref_alpha=ref_alpha,
+        test_size=test_size,
+        test_alpha=test_alpha,
+        return_ax=return_ax,
         output_dir=space_dir,
         **kwargs,
     )

{zmap_tools-0.2.0 → zmap_tools-0.2.1}/src/zmap_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zmap-tools
-Version: 0.2.0
+Version: 0.2.1
 Summary: API for working with ZMAP (Zebrafish Multi-Atlas Project)
 Author-email: Daniel Wagner <Daniel.Wagner@ucsf.edu>
 License: BSD 3-Clause License