dsa-helpers 0.8.dev1__tar.gz → 0.9__tar.gz

dsa_helpers-0.9/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3.12"
+  jobs:
+    pre_build:
+      - sphinx-apidoc -o docs/source dsa_helpers/
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

{dsa_helpers-0.8.dev1/dsa_helpers.egg-info → dsa_helpers-0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dsa_helpers
-Version: 0.8.dev1
+Version: 0.9
 Summary: Utility functions for working with the DSA girder client.
 Author-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
 Maintainer-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
@@ -19,11 +19,10 @@ Requires-Dist: pandas
 Requires-Dist: pymongo
 Requires-Dist: pillow
 Requires-Dist: dash
-Requires-Dist: dash_bootstrap_components
+Requires-Dist: dash-bootstrap-components
 Requires-Dist: shapely
 Requires-Dist: geopandas
 Requires-Dist: transformers[torch]
-Requires-Dist: torch
 Requires-Dist: datasets
 Requires-Dist: torchvision
 Requires-Dist: large-image
@@ -37,6 +36,9 @@ This library was tested using Python version 3.11.8 and uses the dependencies de
 
 This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
 
+## Extra dependencies
+If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
+
 ## Instructions for Development
 1. Install requirements for building and distributing package:
 ```

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/README.md

@@ -7,6 +7,9 @@ This library was tested using Python version 3.11.8 and uses the dependencies de
 
 This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
 
+## Extra dependencies
+If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
+
 ## Instructions for Development
 1. Install requirements for building and distributing package:
 ```

dsa_helpers-0.9/docs/requirements.txt

@@ -0,0 +1,16 @@
+girder-client
+numpy
+setuptools
+opencv-python
+pandas
+pymongo
+pillow
+dash
+dash-bootstrap-components
+shapely
+geopandas
+transformers[torch]
+datasets
+torchvision
+large-image
+sphinx_rtd_theme

dsa_helpers-0.9/docs/source/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "DSA Helpers"
+copyright = "2024, Juan Carlos Vizcarra"
+author = "Juan Carlos Vizcarra"
+release = "00.00.01"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

dsa_helpers-0.9/docs/source/index.rst

@@ -0,0 +1,18 @@
+.. DSA Helpers documentation master file, created by
+   sphinx-quickstart on Fri Dec  6 12:07:31 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+DSA Helpers documentation
+=========================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules

dsa_helpers-0.9/dsa_helpers/__init__.py

@@ -0,0 +1,23 @@
+# Shadow imports.
+from .imread import imread
+from .imwrite import imwrite
+
+# Make modules available.
+from . import girder_utils
+from . import dash
+from . import ml
+from . import mongo_utils
+from . import tiling
+from . import utils
+from . import tile_utils
+
+# Modules that should be available.
+__all__ = [
+    "girder_utils",
+    "dash",
+    "ml",
+    "mongo_utils",
+    "tiling",
+    "utils",
+    "tile_utils",
+]

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/dash/header.py

@@ -15,13 +15,8 @@ def get_header(
     Args:
         dsa_api_url (str): The URL of the DSA API.
         title (str, optional): The title of the application. Defaults to "App".
-        config (dict, optional): The configuration of the component. Defaults to None.
-            If None the default configuration is:
-            {
-                "backgroundColor": "#012169",
-                "titleColor": "#d9d9d6",
-                "fontColor": "#f2a900",
-            }
+        config (dict, optional): The configuration of the component.
+            Defaults to None which uses default settings.
 
     Returns:
         html.Div: The header component.
@@ -38,7 +33,8 @@ def get_header(
             dbc.ModalBody(
                 [
                     html.Div(
-                        "Login or email", style={"margin": 5, "fontWeight": "bold"}
+                        "Login or email",
+                        style={"margin": 5, "fontWeight": "bold"},
                     ),
                     dbc.Input(
                         id=f"{store_id}=login",
@@ -48,7 +44,11 @@ def get_header(
                     ),
                     html.Div(
                         "Password",
-                        style={"margin": 5, "marginTop": 15, "fontWeight": "bold"},
+                        style={
+                            "margin": 5,
+                            "marginTop": 15,
+                            "fontWeight": "bold",
+                        },
                     ),
                     dbc.Input(
                         id=f"{store_id}=password",
@@ -60,7 +60,11 @@ def get_header(
                         "Login failed.",
                         hidden=True,
                         id=f"{store_id}=login-failed",
-                        style={"color": "red", "fontWeight": "bold", "margin": 10},
+                        style={
+                            "color": "red",
+                            "fontWeight": "bold",
+                            "margin": 10,
+                        },
                     ),
                 ],
             ),

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/girder_utils.py

@@ -6,6 +6,7 @@ import pandas as pd
 from pathlib import Path
 import cv2 as cv
 from copy import deepcopy
+from geopandas import GeoDataFrame
 
 
 def get_item_large_image_metadata(gc: GirderClient, item_id: str) -> dict:
@@ -87,19 +88,19 @@ def get_region(
     height: int,
     mag: float | None = None,
 ) -> np.ndarray:
-    """Get a region of the image for an item. Note that the output image might
-    not be in the shape (width, height) if left + width or top + height exceeds
-    the image size. The outpuzerositem id.
+    """Get image region from DSA. Note that the output image might not
+    be in the shape (width, height) if left + width or top + height
+    exceeds the image size.
+
+    Args:
+        gc (girder_client.GirderClient): The authenticated girder client.
+        item_id (str): The item id.
         left (int): The left coordinate.
         top (int): The top coordinate.
         width (int): The width of the region.
         height (int): The height of the region.
-        mag (float, optional): The magnification. Defaults to None which returns
-            the image at scan magnification. Using a mag lower than the scan
-            magnification will result in an ouptut image smaller than the
-            width and height. Similarly, using a mag higher than the scan
-            magnification will result in an output image larger than the width
-            and height.
+        mag (float, optional): The magnification. Defaults to None which
+            returns the image at the scan magnification.
 
     Returns:
         np.ndarray: The region of the image.
@@ -257,17 +258,16 @@ def _rotate_point_list(point_list, rotation, center=(0, 0)):
     return point_list_rotated
 
 
-def get_rectangle_element_coords(element):
+def get_rectangle_element_coords(element: dict) -> np.ndarray:
     """Get the corner coordinate from a rectangle HistomicsUI element, can handle rotated elements.
     Adapted from: https://github.com/DigitalSlideArchive/HistomicsTK/blob/master/histomicstk/annotations_and_masks/annotation_and_mask_utils.py
-    INPUTS
-    ------
-    element : dict
-        rectangle element, in HistomicsUI format
-    RETURN
-    ------
-    corner_coords : array
-        array of shape [4, 2] for the four corners of the rectangle in (x, y) format
+
+    Args:
+        element (dict): rectangle element from HistomicsUI annotation.
+
+    Returns:
+    corner_coords (np.ndarray): 4x2 array of corner coordinates of rectangle.
+
     """
     # element is a dict so prevent referencing
     element = deepcopy(element)
@@ -400,7 +400,9 @@ def get_roi_with_yolo_labels_from_single_doc(
         if element.get("group") == roi_element_group:
             # Append the ROI element, there can't more than one.
             if roi_element is not None:
-                raise ValueError("Multiple ROI elements found in the document.")
+                raise ValueError(
+                    "Multiple ROI elements found in the document."
+                )
 
             roi_element = element
         elif element.get("group") in group_map:
@@ -459,7 +461,9 @@ def get_roi_with_yolo_labels_from_single_doc(
     for element in box_elements:
         if element.get("group") in group_map:
             if element.get("type") != "rectangle":
-                print(f"Skipping element: {element.get('type')} not supported.")
+                print(
+                    f"Skipping element: {element.get('type')} not supported."
+                )
                 continue
 
             group_id = group_map[element.get("group")]
@@ -487,3 +491,88 @@ def get_roi_with_yolo_labels_from_single_doc(
 
     # Return the ROI image and labels data.
     return img, labels_data.strip()
+
+
+def post_annotations_from_gdf(
+    gc: GirderClient,
+    item_id: str,
+    doc_name: str,
+    gdf: GeoDataFrame,
+    idx_config: dict,
+    tolerance: float = 0.5,
+    max_points: int = 1000,
+) -> dict:
+    """Post annotations from a GeoDataFrame to the DSA.
+
+    Args:
+        gc (girder_client.GirderClient): The authenticated girder client.
+        item_id (str): The item id to post the annotations.
+        doc_name (str): The name of the document.
+        gdf (GeoDataFrame): The GeoDataFrame with the polygons.
+        idx_config (dict): For each label in the GeoDataFrame, the configuration
+            for the DSA annotation. Include "label", "fillColor", "lineColor", and
+            "group".
+        tolerance (float, optional): The tolerance to simplify the polygons.
+            Defaults to 0.5.
+        max_points (int, optional): If polygon has more than max_points,
+            simplify the polygon. Defaults to 1000.
+
+    Returns:
+        dict: The response from the DSA.
+
+    """
+    elements = []
+
+    # Process the dataframe.
+    for _, row in gdf.iterrows():
+        # Flatten multipolygon to list of polygons.
+        list_of_polygons = list(
+            row["geometry"].geoms
+        )  # assuming multipolygons
+        label = row["label"]
+
+        for poly in list_of_polygons:
+            exterior_poly = list(poly.exterior.coords)
+            interior_polys = [
+                list(interior.coords) for interior in poly.interiors
+            ]
+
+            if len(exterior_poly) > max_points:
+                poly = poly.simplify(tolerance, preserve_topology=True)
+                exterior_poly = list(poly.exterior.coords)
+
+            points = [
+                [int(xy[0]) * 2, int(xy[1]) * 2, 0] for xy in exterior_poly
+            ]
+
+            holes = []
+
+            for interior_poly in interior_polys:
+                hole = [
+                    [int(xy[0]) * 2, int(xy[1]) * 2, 0] for xy in interior_poly
+                ]
+                holes.append(hole)
+
+            element = {
+                "points": points,
+                "fillColor": idx_config[label]["fillColor"],
+                "lineColor": idx_config[label]["lineColor"],
+                "type": "polyline",
+                "lineWidth": 2,
+                "closed": True,
+                "label": {"value": idx_config[label]["label"]},
+                "group": idx_config[label]["group"],
+            }
+
+            if len(holes):
+                element["holes"] = holes
+
+            elements.append(element)
+
+    response = gc.post(
+        "/annotation",
+        parameters={"itemId": item_id},
+        json={"name": doc_name, "description": "", "elements": elements},
+    )
+
+    return response

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/__init__.py

@@ -2,7 +2,6 @@
 from . import (
     object_detection,
     datasets,
-    metrics,
     transforms,
     segformer_semantic_segmentation,
     tiling,

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/datasets/__init__.py

@@ -1,3 +1,3 @@
 from .SegFormerSegmentationDataset import SegFormerSegmentationDataset
 
-__all__ = ["SegFormerSegmentationDataset", "utils"]
+__all__ = ["utils"]

dsa_helpers-0.9/dsa_helpers/ml/metrics.py

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+"""Metric functions.
+
+This module contains functions used to evaluate the performance of 
+machine learning models.
+
+"""
+import torch
+from torch import nn
+import numpy as np
+
+
+def binary_dice_coefficient(eval_pred: tuple[np.ndarray, np.ndarray]) -> dict:
+    """Calculate the dice coefficient for binary masks. Developed for use
+    in compute_metrics parameters of transformers Trainer class, for
+    SegFormer senantic segmentation model of two classes.
+
+    Args:
+        eval_pred (tuple[np.ndarray, np.ndarray]): A tuple containing the
+            predicted and true masks.
+
+    Returns:
+        dict: A dictionary containing the dice coefficient.
+
+    """
+    with torch.no_grad():
+        logits, labels = eval_pred
+
+        # Convert to tensors.
+        logits = torch.from_numpy(logits).cpu()
+
+        # Resize the logits to be the same shape as the labels.
+        logits = nn.functional.interpolate(
+            logits,
+            size=labels.shape[-2:],
+            mode="bilinear",
+            align_corners=False,
+        ).argmax(dim=1)
+
+        preds = logits.detach().numpy()
+
+        # Convert the masks to binary.
+        preds = preds > 0
+        labels = labels > 0
+
+        # Calculate dice.
+        intersection = np.sum(preds * labels)
+        union = np.sum(preds) + np.sum(labels)
+
+        if union == 0:
+            dice = 1.0  # Both masks are empty
+        else:
+            dice = 2.0 * intersection / union
+
+        return {"dice_coefficient": dice}
+
+
+def mean_iou(eval_pred: tuple[np.ndarray, np.ndarray]) -> dict:
+    """Compute the mean intersection over union (IoU) for semantic
+    segmentation. Also returns the IoU for each class.
+
+    Args:
+        eval_pred (tuple[numpy.ndarray, numpy.ndarray]): Tuple of
+            logits and labels.
+
+    Returns:
+        dict: Dictionary of metrics.
+
+    """
+    with torch.no_grad():
+        logits, labels = eval_pred
+
+        # Convert logits to tensor.
+        logits_tensor = torch.from_numpy(logits).cpu()
+        labels_tensor = torch.from_numpy(labels).cpu()
+
+        # From logits get the number of classes in the dataset.
+        num_classes = logits.shape[1]
+
+        # Scale the logits back to the shape of the labels.
+        logits_tensor = nn.functional.interpolate(
+            logits_tensor,
+            size=labels.shape[-2:],
+            mode="bilinear",
+            align_corners=False,
+        )
+
+        # Turn the logits to predictions.
+        pred = logits_tensor.argmax(dim=1)
+
+        # Calculate the IoU for each class.
+        ious = []
+
+        metrics = {}
+
+        for cls in range(num_classes):
+            pred_mask = pred == cls
+            labels_mask = labels_tensor == cls
+
+            intersection = (
+                torch.logical_and(pred_mask, labels_mask).sum().item()
+            )
+            union = torch.logical_or(pred_mask, labels_mask).sum().item()
+
+            if union == 0:
+                iou = float("nan")  # or 1.0
+            else:
+                iou = intersection / union
+
+            metrics[f"label {cls} IoU"] = iou
+
+            ious.append(iou)
+
+        mean_iou = np.nanmean(ious)  # Use NumPy for NaN handling
+        metrics["mean_iou"] = mean_iou
+
+        return metrics

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/object_detection/__init__.py

@@ -2,4 +2,4 @@
 from .get_pearce_roi_images import get_pearce_roi_images
 from .tile_image import tile_image
 
-__all__ = ["utils", "get_pearce_roi_images", "tile_image"]
+__all__ = ["utils"]

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/segformer_semantic_segmentation/__init__.py

@@ -1,3 +1,3 @@
 from .inference import inference
 
-__all__ = ["inference"]
+__all__ = []

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/segformer_semantic_segmentation/inference.py

@@ -10,7 +10,7 @@ import torch
 import torch.nn as nn
 
 from ... import imread
-from ...image_utils import tile_image
+from ...tiling import tile_image
 
 
 def inference(
@@ -115,7 +115,9 @@ def inference(
     predicted_mask = predicted_mask[:h, :w]
 
     # Extract the contours of the mask.
-    contours = cv.findContours(predicted_mask, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE)[0]
+    contours = cv.findContours(
+        predicted_mask, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE
+    )[0]
 
     # Return the mask.
     return predicted_mask, contours

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/tiling/__init__.py

@@ -2,4 +2,4 @@ from .semantic_seg_tile_wsi_with_dsa_annotations import (
     semantic_seg_tile_wsi_with_dsa_annotations,
 )
 
-__all__ = ["semantic_seg_tile_wsi_with_dsa_annotations"]
+__all__ = []

{dsa_helpers-0.8.dev1 → dsa_helpers-0.9}/dsa_helpers/ml/tiling/semantic_seg_tile_wsi_with_dsa_annotations.py

@@ -82,7 +82,7 @@ def _process_tile(
     imwrite(img_fp, tile_img)
     imwrite(mask_dir / fn, tile_mask, grayscale=True)
 
-    return str(img_fp)
+    return str(img_fp), x, y
 
 
 def semantic_seg_tile_wsi_with_dsa_annotations(
@@ -112,7 +112,8 @@ def semantic_seg_tile_wsi_with_dsa_annotations(
         nproc (int, optional): number of processes to use for tiling.
 
     Returns:
-        list[str]: list of file paths to the created tile images.
+        list[str]: A list of tuples: (tile file path, x, y coordinates
+            of tile).
 
     """
     # Format annotation documents for drawing on tile masks.
@@ -216,9 +217,9 @@ def semantic_seg_tile_wsi_with_dsa_annotations(
             for xy in xys
         ]
 
-        fps = []
+        tile_info = []
 
         for job in tqdm(jobs, desc="Tiling..."):
-            fps.append(job.get())
+            tile_info.append(job.get())
 
-        return fps
+        return tile_info

dsa_helpers-0.9/dsa_helpers/tile_utils.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""Tile functions.
+
+This module contains functions used when working tiles.
+
+"""
+from geopandas import GeoDataFrame
+from .utils import mask_to_shapely
+
+
+def merge_tile_masks(tile_list: list, buffer: int = 1) -> GeoDataFrame:
+    """
+    Merge the tile masks into a single mask for a large image.
+
+    Args:
+        tile_list (list): List of three-lenght tuples containing:
+            (1) fp or array for mask, (2) x-coordinate for tile, (3)
+            y-coordinate for tile.
+        buffer (int): Buffer to apply to the polygons before dissolving.
+
+    Returns:
+        GeoDataFrame: GeoDataFrame with the merged mask.
+
+    """
+    polygons_and_labels = []
+
+    # Process each tile.
+    for tile_info in tile_list:
+        tile, x, y = tile_info
+
+        # Process the mask by converting it to polygons.
+        polygons_and_labels.extend(
+            mask_to_shapely(tile, x_offset=x, y_offset=y)
+        )
+
+    # Convert polygons and labels into a GeoDataFrame.
+    gdf = GeoDataFrame(polygons_and_labels, columns=["geometry", "label"])
+
+    # Apply a buffer to make edges touch.
+    gdf["geometry"] = gdf["geometry"].buffer(buffer)
+
+    # Dissolve the dataframe by the label.
+    gdf = gdf.dissolve(by="label", as_index=False)
+
+    # Remove the buffer.
+    gdf["geometry"] = gdf["geometry"].buffer(-buffer)
+
+    return gdf