lavlab-pythomics 0.1.0__py3-none-any.whl

lavlab_pythomics-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: lavlab-pythomics
+Version: 0.1.0
+Summary: Feature extraction from histology label maps
+Project-URL: Documentation, https://github.com/laviolette-lab/pythomics#readme
+Project-URL: Issues, https://github.com/laviolette-lab/pythomics/issues
+Project-URL: Source, https://github.com/laviolette-lab/pythomics
+Author-email: barrettMCW <mjbarrett@mcw.edu>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: feature-extraction,histology,image-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=6.2; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Provides-Extra: visualization
+Requires-Dist: glymur; extra == 'visualization'
+Requires-Dist: matplotlib; extra == 'visualization'
+Description-Content-Type: text/markdown
+
+# Standalone pythomics feature extraction
+
+Extract per-object lumen and epithelium measurements and block-summed density maps from an integer label-map image. This folder is self-contained and does not import the repository's model/inference code.
+
+## Install
+
+From this directory, install the listed dependencies into your environment:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+Image readers are provided by scikit-image. Parquet output is deliberately not required; object-level tables are CSV, density arrays are compressed NPZ, and MAT output is optional.
+
+## CLI
+
+Run from the repository root:
+
+```bash
+python -m pythomics_standalone path/to/labels.png --output-dir output --save-mat
+```
+
+The default label values are lumen=1, epithelium=2, stroma=4, epithelial-cells=5, stromal-cells=6. Override with `--lumen-label`, `--epithelium-label`, `--stroma-label`, `--epithelial-cells-label`, and `--stromal-cells-label`. `--min-area` sets the minimum connected component size in source pixels (default 16); `--block-size HEIGHT WIDTH` sets density aggregation blocks (default 20 20).
+
+Epithelium regions include both epithelium and epithelial-cell pixels. Stroma density includes stromal-cell pixels. Connected components are labeled independently in each tissue mask. Tables contain source-pixel area, circularity (`roundness`), and for epithelium average skeleton thickness and epithelial-cell fraction. Density NPZ arrays are block sums, with edge blocks padded with zeros. The optional MAT file includes densities plus feature maps projected across every source-resolution pixel.
+
+Outputs are `<input-stem>_lumen_features.csv`, `<input-stem>_epithelium_features.csv`, and `<input-stem>_densities.npz`; with `--save-mat`, also `<input-stem>_features.mat`.

lavlab_pythomics-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pythomics/__init__.py,sha256=LXOqwZTg7-j2pXao-TDzny4v6UV4ZISeJLH8tXmSKr4,199
+pythomics/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+pythomics/cli.py,sha256=5N_R1iSM7-qks2Vyntkss7RhyJz6Ob0Vxf2zvvCsvNg,2697
+pythomics/core.py,sha256=oK-Y_MBgF6o6p1UnssJJghkt50I6Pr6wvL_7h8M2o7k,9374
+lavlab_pythomics-0.1.0.dist-info/METADATA,sha256=pXFIQlzJfQpFKtUtO31cP87ckLb-WGfA47No-xNQTYs,3240
+lavlab_pythomics-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lavlab_pythomics-0.1.0.dist-info/entry_points.txt,sha256=n-awG9x42tNICPOLkJHwKnbBHeDkLlxLkdhtyOvud58,49
+lavlab_pythomics-0.1.0.dist-info/licenses/LICENSE.txt,sha256=g-g_MSYD9bY-dMaZqJP6LzxscgMsRtIX3wERzYAYc6Q,1095
+lavlab_pythomics-0.1.0.dist-info/RECORD,,

lavlab_pythomics-0.1.0.dist-info/WHEEL

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

lavlab_pythomics-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pythomics = pythomics.cli:main

lavlab_pythomics-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present barrettMCW <mjbarrett@mcw.edu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pythomics/__init__.py

@@ -0,0 +1,5 @@
+"""Standalone feature extraction from histology label maps."""
+
+from .core import DEFAULT_LABELS, extract_features, load_label_map
+
+__all__ = ["DEFAULT_LABELS", "extract_features", "load_label_map"]

pythomics/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pythomics/cli.py

@@ -0,0 +1,88 @@
+"""Command-line interface for standalone pythomics."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from .core import DEFAULT_LABELS, extract_features, load_label_map, save_outputs
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Calculate lumen and epithelium features from an integer label map."
+    )
+    parser.add_argument(
+        "label_map", type=Path, help="Input 2-D integer label map image"
+    )
+    parser.add_argument(
+        "-o", "--output-dir", type=Path, default=Path("pythomics-output")
+    )
+    parser.add_argument(
+        "--min-area",
+        type=int,
+        default=16,
+        help="Minimum connected-region area in pixels",
+    )
+    parser.add_argument(
+        "--block-size", type=int, nargs=2, metavar=("HEIGHT", "WIDTH"), default=(20, 20)
+    )
+    parser.add_argument(
+        "--save-mat",
+        action="store_true",
+        help="Also write a full-resolution feature-map MAT file",
+    )
+    parser.add_argument(
+        "--log-level", choices=("DEBUG", "INFO", "WARNING", "ERROR"), default="INFO"
+    )
+    for name, default in DEFAULT_LABELS.items():
+        parser.add_argument(
+            f"--{name.replace('_', '-')}-label",
+            type=int,
+            default=default,
+            help=f"Label value for {name}",
+        )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=getattr(logging, args.log_level), format="%(levelname)s: %(message)s"
+    )
+    if args.min_area < 0 or min(args.block_size) <= 0:
+        build_parser().error(
+            "--min-area must be non-negative and --block-size values must be positive"
+        )
+    if not args.label_map.is_file():
+        build_parser().error(f"label map does not exist: {args.label_map}")
+
+    labels = {name: getattr(args, f"{name}_label") for name in DEFAULT_LABELS}
+    if len(set(labels.values())) != len(labels):
+        build_parser().error("label values must be distinct")
+
+    label_map = load_label_map(args.label_map)
+    densities, lumen, epithelium = extract_features(
+        label_map,
+        labels=labels,
+        min_area=args.min_area,
+        block_size=tuple(args.block_size),
+    )
+    save_outputs(
+        label_map,
+        densities,
+        lumen,
+        epithelium,
+        args.output_dir,
+        args.label_map.stem,
+        save_mat=args.save_mat,
+        labels=labels,
+        block_size=tuple(args.block_size),
+    )
+    logging.info("Wrote outputs to %s", args.output_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pythomics/core.py

@@ -0,0 +1,253 @@
+"""Feature calculations for integer-valued histology label maps."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import scipy.io
+import scipy.ndimage
+import skimage.io
+import skimage.measure
+import skimage.morphology
+
+DEFAULT_LABELS = {
+    "lumen": 1,
+    "epithelium": 2,
+    "stroma": 4,
+    "epithelial_cells": 5,
+    "stromal_cells": 6,
+}
+
+
+def load_label_map(path: str | Path) -> np.ndarray:
+    """Read a 2-D label map; RGB representations are accepted only if channels match."""
+    image = np.asarray(skimage.io.imread(str(path)))
+    if image.ndim == 3:
+        if image.shape[-1] not in (3, 4) or not np.all(
+            image[..., :3] == image[..., :1]
+        ):
+            raise ValueError(
+                "Expected a single-channel integer label map, not a color image"
+            )
+        image = image[..., 0]
+    if image.ndim != 2:
+        raise ValueError(f"Expected a 2-D label map, got shape {image.shape}")
+    if not np.issubdtype(image.dtype, np.integer):
+        raise ValueError(f"Expected integer label values, got dtype {image.dtype}")
+    return image
+
+
+def summify(image: np.ndarray, block_size: tuple[int, int] = (20, 20)) -> np.ndarray:
+    """Sum image pixels in padded, non-overlapping blocks."""
+    arr = np.asarray(image, dtype=np.float32)
+    if arr.ndim != 2:
+        raise ValueError("summify expects a 2-D image")
+    if not arr.size:
+        return np.empty((0, 0), dtype=np.float32)
+    bh, bw = block_size
+    if bh <= 0 or bw <= 0:
+        raise ValueError("block_size values must be positive")
+    pad_h, pad_w = (-arr.shape[0]) % bh, (-arr.shape[1]) % bw
+    arr = np.pad(arr, ((0, pad_h), (0, pad_w)), mode="constant")
+    return skimage.measure.block_reduce(arr, block_size=block_size, func=np.sum).astype(
+        np.float32
+    )
+
+
+def calculate_tortuosity(area: float, perimeter: float) -> float:
+    """Return circularity (1 for an ideal circle).
+
+    skimage's pixel-based perimeter underestimates small objects, which can push
+    the raw ratio above 1, so the result is clipped to [0, 1].
+    """
+    if area <= 0 or perimeter <= 0:
+        return 0.0
+    return float(min(1.0, 4 * np.pi * area / perimeter**2))
+
+
+def average_thickness(region_mask: np.ndarray) -> float:
+    area = int(np.sum(region_mask))
+    if area == 0:
+        return 0.0
+    length = int(np.sum(skimage.morphology.skeletonize(region_mask)))
+    return float(area / length) if length else 0.0
+
+
+def _empty(columns: list[str]) -> pd.DataFrame:
+    return pd.DataFrame(columns=columns)
+
+
+def calculate_lumen_features(
+    labeled_lumen: np.ndarray, min_area: int = 16
+) -> pd.DataFrame:
+    columns = ["label", "area", "roundness"]
+    if not np.any(labeled_lumen):
+        return _empty(columns)
+    props = skimage.measure.regionprops_table(
+        labeled_lumen, properties=("label", "area", "perimeter")
+    )
+    frame = pd.DataFrame(props)
+    frame["roundness"] = [
+        calculate_tortuosity(a, p)
+        for a, p in zip(frame.area, frame.perimeter, strict=False)
+    ]
+    frame = frame.loc[frame.area >= min_area, columns]
+    return frame.reset_index(drop=True)
+
+
+def calculate_epithelium_features(
+    labeled_epithelium: np.ndarray, epithelial_cells: np.ndarray, min_area: int = 16
+) -> pd.DataFrame:
+    columns = ["label", "area", "roundness", "average_thickness", "cell_fraction"]
+    if not np.any(labeled_epithelium):
+        return _empty(columns)
+    props = skimage.measure.regionprops_table(
+        labeled_epithelium,
+        intensity_image=epithelial_cells.astype(np.uint8),
+        properties=("label", "area", "perimeter"),
+        extra_properties=[average_thickness],
+    )
+    frame = pd.DataFrame(props)
+    frame["roundness"] = [
+        calculate_tortuosity(a, p)
+        for a, p in zip(frame.area, frame.perimeter, strict=False)
+    ]
+    cell_counts = np.bincount(
+        labeled_epithelium.ravel(), weights=epithelial_cells.astype(np.uint8).ravel()
+    )
+    counts = cell_counts[frame.label.to_numpy(dtype=np.int64)]
+    frame["cell_fraction"] = np.divide(
+        counts,
+        frame.area,
+        out=np.zeros_like(counts, dtype=float),
+        where=frame.area.to_numpy() > 0,
+    )
+    frame = frame.loc[frame.area >= min_area, columns]
+    return frame.reset_index(drop=True)
+
+
+def extract_features(
+    label_map: np.ndarray,
+    labels: Mapping[str, int] | None = None,
+    min_area: int = 16,
+    block_size: tuple[int, int] = (20, 20),
+) -> tuple[dict[str, np.ndarray], pd.DataFrame, pd.DataFrame]:
+    """Calculate density maps and per-object lumen/epithelium measurements.
+
+    Epithelium includes both ``epithelium`` and ``epithelial_cells`` labels;
+    stromal cells are included in the stroma density. All feature areas and
+    thresholds are in source-map pixels.
+    """
+    palette = np.asarray(label_map)
+    if palette.ndim != 2 or not np.issubdtype(palette.dtype, np.integer):
+        raise ValueError("label_map must be a 2-D integer array")
+    label_values = dict(DEFAULT_LABELS)
+    if labels:
+        unknown = set(labels) - set(label_values)
+        if unknown:
+            raise ValueError(f"Unknown label names: {', '.join(sorted(unknown))}")
+        label_values.update(labels)
+    if len(set(label_values.values())) != len(label_values):
+        raise ValueError("label values must be distinct")
+    lumen = palette == label_values["lumen"]
+    epithelial_cells = palette == label_values["epithelial_cells"]
+    epithelium = (palette == label_values["epithelium"]) | epithelial_cells
+    stroma = (palette == label_values["stroma"]) | (
+        palette == label_values["stromal_cells"]
+    )
+
+    densities = {
+        "lumen_density": summify(lumen, block_size),
+        "stroma_density": summify(stroma, block_size),
+        "epithelium_density": summify(epithelium, block_size),
+        "epithelial_cells_density": summify(epithelial_cells, block_size),
+    }
+    labeled_lumen = scipy.ndimage.label(lumen)[0]
+    labeled_epithelium = scipy.ndimage.label(epithelium)[0]
+    lumen_features = calculate_lumen_features(labeled_lumen, min_area)
+    epithelium_features = calculate_epithelium_features(
+        labeled_epithelium, epithelial_cells, min_area
+    )
+    logging.info(
+        "Found %d lumens and %d epithelial regions",
+        len(lumen_features),
+        len(epithelium_features),
+    )
+    return densities, lumen_features, epithelium_features
+
+
+def _paint_features(
+    labeled: np.ndarray, features: pd.DataFrame, column: str
+) -> np.ndarray:
+    if column not in features.columns:
+        raise ValueError(f"Feature column {column!r} not found")
+    max_label = int(labeled.max()) if labeled.size else 0
+    lookup = np.zeros(max_label + 1, dtype=np.float32)
+    if not features.empty:
+        ids = features["label"].to_numpy(dtype=np.int64)
+        values = features[column].to_numpy(dtype=np.float32)
+        valid = (ids > 0) & (ids <= max_label)
+        values = np.nan_to_num(values, nan=0.0)
+        lookup[ids[valid]] = values[valid]
+    return lookup[labeled]
+
+
+def save_outputs(
+    label_map: np.ndarray,
+    densities: Mapping[str, np.ndarray],
+    lumen_features: pd.DataFrame,
+    epithelium_features: pd.DataFrame,
+    output_dir: str | Path,
+    stem: str,
+    save_mat: bool = False,
+    labels: Mapping[str, int] | None = None,
+    block_size: tuple[int, int] = (20, 20),
+) -> None:
+    """Write per-object CSV tables, density arrays, and optionally a MAT feature map."""
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+    lumen_features.to_csv(output / f"{stem}_lumen_features.csv", index=False)
+    epithelium_features.to_csv(output / f"{stem}_epithelium_features.csv", index=False)
+    np.savez_compressed(output / f"{stem}_densities.npz", **densities)
+    if not save_mat:
+        return
+
+    values = dict(DEFAULT_LABELS)
+    if labels:
+        values.update(labels)
+    lumen = label_map == values["lumen"]
+    epithelial_cells = label_map == values["epithelial_cells"]
+    epithelium = (label_map == values["epithelium"]) | epithelial_cells
+    labeled_lumen = scipy.ndimage.label(lumen)[0]
+    labeled_epithelium = scipy.ndimage.label(epithelium)[0]
+    maps = {
+        **{
+            key: summify(mask, block_size)
+            for key, mask in {
+                "lumen_density": lumen,
+                "stroma_density": (label_map == values["stroma"])
+                | (label_map == values["stromal_cells"]),
+                "epithelium_density": epithelium,
+                "epithelial_cells_density": epithelial_cells,
+            }.items()
+        },
+        "lumen_roundness": _paint_features(labeled_lumen, lumen_features, "roundness"),
+        "lumen_area": _paint_features(labeled_lumen, lumen_features, "area"),
+        "epithelium_roundness": _paint_features(
+            labeled_epithelium, epithelium_features, "roundness"
+        ),
+        "epithelium_area": _paint_features(
+            labeled_epithelium, epithelium_features, "area"
+        ),
+        "epithelium_thickness": _paint_features(
+            labeled_epithelium, epithelium_features, "average_thickness"
+        ),
+        "cell_fraction": _paint_features(
+            labeled_epithelium, epithelium_features, "cell_fraction"
+        ),
+    }
+    scipy.io.savemat(output / f"{stem}_features.mat", maps)