lavlab-pythomics 0.1.0__tar.gz

lavlab_pythomics-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1 @@
+../Dockerfile

lavlab_pythomics-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,38 @@
+{
+  "name": "Python 3",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "..",
+    "target": "dev",
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "python.defaultInterpreterPath": "/usr/bin/python3",
+        "autoDocstring.docstringFormat": "sphinx",
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit",
+          },
+        },
+      },
+      "extensions": [
+        "ms-toolsai.jupyter",
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker",
+        "editorconfig.editorconfig",
+        "njpwerner.autodocstring",
+        "usernamehw.errorlens",
+        "Gruntfuggly.todo-tree",
+        "eamodio.gitlens",
+        "github.vscode-github-actions",
+      ],
+    },
+  },
+  "remoteUser": "vscode",
+}

lavlab_pythomics-0.1.0/.editorconfig

@@ -0,0 +1,36 @@
+# EditorConfig — https://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_size = 4
+max_line_length = 88
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.{toml,cfg,ini}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{sh,bash,zsh}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_size = 4

lavlab_pythomics-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

lavlab_pythomics-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,31 @@
+name: Build Wheel using Hatch
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install "virtualenv==20.23.1"
+          python -m pip install --upgrade hatch
+
+      - name: Build wheel with hatch
+        run: hatch build
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel
+          path: dist/*.whl

lavlab_pythomics-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,19 @@
+name: Lint and Format with Ruff
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint-and-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build --target hatch -t shell:hatch .
+      - name: Check formatting with Ruff
+        run: docker run --rm -e HATCH_ENV=lint -v "${{ github.workspace }}:/app" shell:hatch format-check
+      - name: Run Ruff linter
+        run: docker run --rm -e HATCH_ENV=lint -v "${{ github.workspace }}:/app" shell:hatch check

lavlab_pythomics-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build Docker image (hatch stage)
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: ./Dockerfile
+          target: hatch
+          tags: shell-ci:latest
+
+      - name: Build wheel and sdist inside Docker
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}:/app" \
+            -w /app \
+            shell-ci:latest build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

lavlab_pythomics-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,37 @@
+name: Run Pytest and Codecov with Hatch
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[test]"
+
+      - name: Run pytest and generate coverage report
+        run: |
+          pytest --cov=src --cov-report=xml:coverage.xml
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: ${{ github.workspace }}/coverage.xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: laviolette-lab/taps

lavlab_pythomics-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+sdist/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Hatch
+.hatch/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.pytest_cache/
+.mypy_cache/
+
+# Documentation builds
+site/
+
+# Jupyter Notebooks
+.ipynb_checkpoints/
+<<<<<<< HEAD
+*.jp2
+outputs
+dist
+=======
+
+# Ruff
+.ruff_cache/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Secrets — never commit these
+*.pem
+*.key
+
+# Logs
+*.log
+
+# Type stubs
+.pytype/
+dmypy.json
+
+# Pre-commit
+.pre-commit-cache/
+
+# Misc
+*.bak
+*.tmp
+*.ipynb
+!visualize_outputs.ipynb
+/outputs/
+*.jp2

lavlab_pythomics-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--ignore-missing-imports]

lavlab_pythomics-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing
+
+Thank you for your interest in contributing! This document provides guidelines for working with this project.
+
+## Development Setup
+
+1. **Clone the repository:**
+
+   ```console
+   git clone https://github.com/laviolette-lab/taps.git
+   cd taps
+   ```
+
+2. **Install Hatch** (build & environment manager):
+
+   ```console
+   pip install hatch
+   ```
+
+3. **Install pre-commit hooks:**
+
+   ```console
+   pip install pre-commit
+   pre-commit install
+   ```
+
+## Common Tasks
+
+All project tasks are managed through [Hatch environments](https://hatch.pypa.io/latest/environment/):
+
+| Task                    | Command                      |
+|-------------------------|------------------------------|
+| Run tests               | `hatch run test:test`        |
+| Run tests with coverage | `hatch run test:cov`         |
+| Lint code               | `hatch run lint:check`       |
+| Format code             | `hatch run lint:format`      |
+| Auto-fix lint issues    | `hatch run lint:fix`         |
+| Run all lint checks     | `hatch run lint:all`         |
+| Type check              | `hatch run types:check`      |
+| Build docs              | `hatch run docs:build-docs`  |
+| Serve docs locally      | `hatch run docs:serve-docs`  |
+| Build wheel             | `hatch build`                |
+
+## Code Style
+
+- **Formatter & Linter:** [Ruff](https://docs.astral.sh/ruff/) handles both formatting and linting. Configuration lives in `pyproject.toml` under `[tool.ruff]`.
+- **Line length:** 88 characters (consistent with Black's default).
+- **Docstrings:** Use [Sphinx-style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) docstrings (`:param:`, `:type:`, `:return:`, `:rtype:`).
+- **Type hints:** Encouraged. The project includes a `py.typed` marker for PEP 561 compliance.
+
+## Project Architecture
+
+This project follows a **library-first** design:
+
+1. **Library modules** (`src/taps/`) contain all business logic as importable functions and classes.
+2. **CLI** (`src/taps/cli.py`) is a thin wrapper that parses arguments and delegates to library functions.
+3. **Tests** (`tests/`) import directly from the library — never from the CLI.
+
+When adding new functionality:
+
+- Write the logic as a function or class in a library module.
+- Add tests that call the function directly.
+- If CLI access is needed, add a subcommand in `cli.py` that wraps the library function.
+
+## Writing Tests
+
+- Tests live in `tests/` and use [pytest](https://docs.pytest.org/).
+- Shared fixtures belong in `tests/conftest.py`.
+- Name test files `test_<module>.py` and test functions `test_<behavior>`.
+- Aim for descriptive test names that explain what is being verified.
+
+```python
+def test_resolve_checkpoint_uses_bundled_model_by_default():
+    """Verify resolve_checkpoint falls back to the packaged model."""
+    assert resolve_checkpoint(None).name == "model_v1.pth"
+```
+
+## Submitting Changes
+
+1. **Create a branch** from `main`:
+
+   ```console
+   git checkout -b feature/my-change
+   ```
+
+2. **Make your changes** and ensure all checks pass:
+
+   ```console
+   hatch run lint:all
+   hatch run test:cov
+   hatch run types:check
+   ```
+
+3. **Commit** with a clear, descriptive message. Pre-commit hooks will run Ruff automatically.
+
+4. **Open a Pull Request** against `main`. The CI pipeline will run linting, tests, and build checks.
+
+## Docker
+
+The project includes multi-stage Docker builds:
+
+| Target   | Purpose                                    |
+|----------|--------------------------------------------|
+| `base`   | Base image with source and non-root user   |
+| `hatch`  | Runs Hatch commands (used in CI)           |
+| `dev`    | Full development environment               |
+| `prod`   | Minimal production image with only the wheel installed |
+
+```console
+# Build and run tests via Docker
+docker build --target hatch -t myapp:hatch .
+docker run --rm -e HATCH_ENV=test taps:hatch cov
+
+# Build production image
+docker build --target prod -t taps:prod .
+```
+
+## Questions?
+
+Open an issue on GitHub if you have questions or run into problems.

lavlab_pythomics-0.1.0/Dockerfile

@@ -0,0 +1,39 @@
+ARG PY_VERSION=3.12
+
+FROM python:${PY_VERSION}-slim AS base
+
+# create non-root user (primarily for devcontainer)
+RUN groupadd --gid 1000 vscode \
+    && useradd --uid 1000 --gid 1000 -m vscode
+
+WORKDIR /app
+
+# install dependencies first for better layer caching
+COPY pyproject.toml README.md LICENSE.txt ./
+COPY src/ src/
+
+RUN chown -R vscode:vscode /app
+
+FROM base AS hatch
+RUN pip3 install --no-cache-dir hatch
+ENV HATCH_ENV=default
+ENTRYPOINT ["hatch", "run"]
+
+FROM base AS dev
+COPY requirements.txt ./
+COPY tests/ tests/
+COPY docs/ docs/
+COPY mkdocs.yml ./
+RUN pip3 install --no-cache-dir hatch \
+    && hatch build \
+    && pip3 install --no-cache-dir uv \
+    && uv pip install --system --no-deps "$(python -c 'import tomllib; print(tomllib.load(open(\"pyproject.toml\", \"rb\"))[\"project\"][\"dependencies\"])')"
+USER vscode
+
+FROM base AS prod
+COPY --from=dev /app/dist/*.whl /tmp/
+RUN pip3 install --no-cache-dir /tmp/*.whl \
+    && rm -rf /tmp/*.whl
+USER vscode
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import taps" || exit 1

lavlab_pythomics-0.1.0/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.

lavlab_pythomics-0.1.0/Makefile

@@ -0,0 +1,57 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help test cov lint format fix types docs serve-docs build clean install pre-commit
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install the package in development mode with hatch
+	pip install hatch
+	hatch env create
+
+test: ## Run tests
+	hatch run test:test
+
+cov: ## Run tests with coverage report
+	hatch run test:cov
+
+lint: ## Run Ruff linter
+	hatch run lint:check
+
+format: ## Format code with Ruff
+	hatch run lint:format
+
+fix: ## Auto-fix lint issues and format
+	hatch run lint:all
+
+types: ## Run mypy type checking
+	hatch run types:check
+
+docs: ## Build documentation
+	hatch run docs:build-docs
+
+serve-docs: ## Serve documentation locally
+	hatch run docs:serve-docs
+
+build: ## Build wheel and sdist
+	hatch build
+
+clean: ## Remove build artifacts and caches
+	rm -rf dist/ build/ site/ htmlcov/
+	rm -f coverage.xml .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name '*.egg-info' -exec rm -rf {} + 2>/dev/null || true
+
+pre-commit: ## Install and run pre-commit hooks
+	pre-commit install
+	pre-commit run --all-files
+
+docker-dev: ## Build and run dev Docker image
+	docker build --target dev -t myapp:dev .
+
+docker-prod: ## Build production Docker image
+	docker build --target prod -t myapp:prod .

lavlab_pythomics-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,27 @@
+# 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/docs/api.md

@@ -0,0 +1,9 @@
+# API Reference
+
+## `taps.inference`
+
+::: taps.inference
+
+## `taps.cli`
+
+::: taps.cli