Enable 3D visualizations with CytoDataFrame (#186)

* trame-based display

* add 3d image example data for testing

* 3d framing

* visual adjustments

* docs, tests, notebook example

* linting

* Update poetry.lock

* [pre-commit.ci lite] apply automatic fixes

* updates for test coverage

* [pre-commit.ci lite] apply automatic fixes

* remove unused zarr test data

* address coderabbit review suggestions

* [pre-commit.ci lite] apply automatic fixes

* address coderabbit review suggestions

* [pre-commit.ci lite] apply automatic fixes

* address copilot review suggestions

* [pre-commit.ci lite] apply automatic fixes

* updates from copilot review

* [pre-commit.ci lite] apply automatic fixes

* readd pytest-cov

* [pre-commit.ci lite] apply automatic fixes

* address coderabbit review suggestions

* address issues with pyproject file

* Update pyproject.toml

* update lockfile

* [pre-commit.ci lite] apply automatic fixes

* fix installs and code cov

* [pre-commit.ci lite] apply automatic fixes

* override opts

* fix yaml issue

* Update cytodataframe_at_a_glance.ipynb

* Update cytodataframe_at_a_glance.py

Co-Authored-By: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

* remove col specificity for 3d example

Co-Authored-By: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

* docstring for build_3d_image_html_stub

Co-Authored-By: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

* updates from review

Co-Authored-By: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

* [pre-commit.ci lite] apply automatic fixes

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Jenna Tomkinson <107513215+jenna-tomkinson@users.noreply.github.com>

Author: 3 people

.github/workflows/run-tests.yml

@@ -2,7 +2,7 @@
 # used for running tests
 name: tests
 
-on:
+"on":
   push:
     branches: [main]
   pull_request:
@@ -28,7 +28,7 @@ jobs:
         run: |
           poetry version 99.0.0
       - name: Install environment
-        run: poetry install --no-interaction --no-ansi
+        run: poetry install --with dev --no-interaction --no-ansi
       # run pre-commit
       - uses: pre-commit/action@v3.0.1
         id: pre_commit
@@ -57,15 +57,17 @@ jobs:
         run: |
           poetry version 99.0.0
       - name: Install environment
-        run: poetry install --no-interaction --no-ansi
+        run: poetry install --with dev --no-interaction --no-ansi
       - name: Run pytest (non-3.13)
         if: ${{ matrix.python_version != '3.13' }}
         # run all tests
-        run: poetry run pytest
+        run: poetry run pytest -o addopts=
       - name: Run pytest (py 3.13)
         if: ${{ matrix.python_version == '3.13' }}
         # run all tests except integration tests with cosmicqc
-        run: poetry run pytest --ignore=tests/test_project_integration.py
+        run: |
+          poetry run pytest -o addopts= \
+            --ignore=tests/test_project_integration.py
       - name: Reset version to 0.0.0
         run: |
           poetry version 0.0.0

.pre-commit-config.yaml

@@ -31,7 +31,8 @@ repos:
               .*\.lock |
               .*\.json |
               .*\.ipynb |
-              .*\.cppipe
+              .*\.cppipe |
+              tests/data/CP_tutorial_3D_noise_nuclei_segmentation/output/MyExpt_Experiment\.csv
           )$
 -   repo: https://github.com/executablebooks/mdformat
     rev: 0.7.18
@@ -53,25 +54,26 @@ repos:
     hooks:
     -   id: actionlint
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.14.14"
+    rev: "v0.15.0"
     hooks:
     -   id: ruff-format
     -   id: ruff-check
 -   repo: https://github.com/software-gardening/almanack
-    rev: v0.1.13
+    rev: v0.1.15
     hooks:
     -   id: almanack-check
 -   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
     rev: v0.6.0
     hooks:
     -   id: pre-commit-update
-        args: ["--keep", "mdformat", "--keep", "pre-commit-update", "--keep", "cffconvert"]
+        args: ["--keep", "mdformat", "--keep", "pre-commit-update", "--keep", "cffconvert",
+          "--keep", "pyproject-fmt"]
 -   repo: local
     hooks:
     -   id: code-cov-gen
         name: Generate code coverage
         language: system
-        entry: poetry run coverage run -m pytest
+        entry: poetry run coverage run -m pytest -o addopts=
         pass_filenames: false
         always_run: true
 -   repo: https://github.com/Weird-Sheep-Labs/coverage-pre-commit

CITATION.cff

@@ -168,3 +168,39 @@ references:
       JUMP (cpg0000-jump-pilot) was used to help demonstrate CytoDataFrame performance
       with large data. See here for more information:
       https://github.com/broadinstitute/cellpainting-gallery
+  - type: article
+    authors:
+      - family-names: Blin
+        given-names: Guillaume
+      - family-names: Sadurska
+        given-names: Dominika
+      - family-names: Portero Migueles
+        given-names: Rafael
+      - family-names: Chen
+        given-names: Ni
+      - family-names: Watson
+        given-names: James A.
+      - family-names: Lowell
+        given-names: Sally
+    title: "Nessys: A new set of tools for the automated detection of nuclei within intact tissues and dense 3D cultures"
+    journal: PLoS Biology
+    volume: "17"
+    issue: "8"
+    pages: e3000388
+    year: 2019
+    doi: "10.1371/journal.pbio.3000388"
+    url: "https://doi.org/10.1371/journal.pbio.3000388"
+    notes: >
+      This work used the file "6001240_labels.zarr" from the DISCEPTS imaging
+      dataset, available through the Image Data Resource (IDR) under accession
+      number idr0062.
+  - type: data
+    title: "3D Noise Nuclei Segmentation Tutorial"
+    authors:
+      - name: "CellProfiler Tutorials Team"
+    url: "https://tutorials.cellprofiler.org/#3d-noise-nuclei-segmentation"
+    publisher:
+      name: "CellProfiler Organization"
+    notes: >
+      This work uses data that were slightly modified from the
+      CellProfiler 3D Noise Nuclei Segmentation tutorial.

README.md

@@ -22,6 +22,13 @@ With CytoDataFrame you can:
 - View image objects alongside their feature data using a Pandas DataFrame-like interface.
 - Highlight image objects using mask or outline files to understand their segmentation.
 - Adjust image displays on-the-fly using interactive slider widgets.
+- Automatically detect 3D image volumes and render interactive [trame](https://github.com/Kitware/trame) views in notebooks when 3D dependencies are installed (with graceful fallback otherwise).
+
+For 3D notebook display behavior:
+
+- 3D-aware rendering is enabled by default (`display_options={"auto_trame_for_3d": True}`).
+- Disable automatic trame switching with `display_options={"auto_trame_for_3d": False}`.
+- Force trame layout regardless of auto-detection with `display_options={"view": "trame"}`.
 
 📓 ___Want to see CytoDataFrame in action?___ Check out our [example notebook](docs/src/examples/cytodataframe_at_a_glance.ipynb) for a quick tour of its key features.
 

docs/src/contributing.md

@@ -53,6 +53,9 @@ You can run pytest on your work using the following example:
 % poetry run pytest
 ```
 
+Pytest output includes a terminal coverage summary to help track current
+coverage and uncovered lines.
+
 ## Making changes to this repository
 
 We welcome anyone to use [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) (requires a GitHub login) or create [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (to directly make changes within this repository) to modify content found within this repository.

docs/src/examples/cytodataframe_at_a_glance.ipynb

@@ -5,9 +5,9 @@
 #       extension: .py
 #       format_name: light
 #       format_version: '1.5'
-#       jupytext_version: 1.18.1
+#       jupytext_version: 1.17.3
 #   kernelspec:
-#     display_name: Python 3 (ipykernel)
+#     display_name: cytodataframe-shAZamSV-py3.12
 #     language: python
 #     name: python3
 # ---
@@ -338,3 +338,19 @@
 
 # read OME Parquet file into the CytoDataFrame
 CytoDataFrame(data="example.ome.parquet")
+
+# +
+# %%time
+# 3D example dataset, showing how
+# CytoDataFrame can be used with 3D data for visualization.
+cp_3d_path = "../../../tests/data/CP_tutorial_3D_noise_nuclei_segmentation"
+
+# send the data to CytoDataFrame
+# note: because we have 3d input images, CytoDataFrame will automatically process
+# using the 3D display options for interactive visualization.
+cdf = CytoDataFrame(
+    data=pathlib.Path(cp_3d_path) / "output/MyExpt_RealsizeNuclei.csv",
+    data_context_dir=str(pathlib.Path(cp_3d_path) / "input"),
+)
+
+cdf[["ImageNumber", "ObjectNumber", "FileName_Nuclei"]][:3]