ueler-viewer 0.5.0__tar.gz

ueler_viewer-0.5.0/LICENSE.txt

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, Yu-Le Wu, Hartmann Lab,
+German Cancer Research Center (DKFZ), Heidelberg, Germany.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ueler_viewer-0.5.0/MANIFEST.in

@@ -0,0 +1,38 @@
+# Controls the sdist only; the wheel is driven by [tool.setuptools] in
+# pyproject.toml. An sdist is a build input, so it must carry everything needed
+# to rebuild the wheel — and nothing else.
+
+include LICENSE.txt
+include README.md
+include pyproject.toml
+
+# Packaged runtime assets (also declared as package-data for the wheel).
+recursive-include ueler/viewer/images *
+
+# Development scaffolding that is not needed to build or run the package.
+prune tests
+prune tests_tmp
+prune dev_note
+prune doc
+prune docs
+prune script
+prune tools
+prune site
+prune env
+prune .binder
+prune .github
+prune .claude
+prune .specify
+prune specs
+prune graphify-out
+prune ueler/graphify-out
+
+exclude Makefile
+exclude mkdocs.yml
+exclude CLAUDE.md
+exclude sitecustomize.py
+exclude usercustomize.py
+
+global-exclude *.py[cod]
+global-exclude __pycache__/*
+global-exclude .DS_Store

ueler_viewer-0.5.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: ueler-viewer
+Version: 0.5.0
+Summary: Unified Exploratory Linked Viewer for spatial proteomics and multiplexed imaging
+Author: Yu-Le Wu (Hartmann Lab, DKFZ)
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/HartmannLab/UELer
+Project-URL: Documentation, https://hartmannlab.github.io/UELer/
+Project-URL: Repository, https://github.com/HartmannLab/UELer
+Project-URL: Issues, https://github.com/HartmannLab/UELer/issues
+Project-URL: Changelog, https://github.com/HartmannLab/UELer/blob/main/doc/log.md
+Keywords: spatial proteomics,multiplexed imaging,image viewer,jupyter,MIBI,IMC,bioimage analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Framework :: Jupyter
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: scikit-image>=0.19
+Requires-Dist: dask
+Requires-Dist: dask-image
+Requires-Dist: ipydatagrid
+Requires-Dist: bqplot
+Requires-Dist: seaborn
+Requires-Dist: seaborn-image
+Requires-Dist: opencv-python-headless
+Requires-Dist: watchfiles
+Requires-Dist: jupyter-scatter
+Requires-Dist: ipywidgets>=8.1
+Requires-Dist: anywidget>=0.9
+Requires-Dist: numpy
+Requires-Dist: pandas>=2.0
+Requires-Dist: ipykernel
+Requires-Dist: ipympl
+Requires-Dist: anndata>=0.10
+Requires-Dist: tifffile
+Requires-Dist: fsspec[http]
+Requires-Dist: requests
+Requires-Dist: bokeh>=3.0
+Requires-Dist: jupyter_bokeh>=4.0
+Provides-Extra: ark
+Requires-Dist: ark-analysis==0.7.0; extra == "ark"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mike>=2.1; extra == "docs"
+Dynamic: license-file
+
+# UELer
+Unified Exploratory Linked Viewer: a Jupyter-based framework for interactive exploration of multiplexed imaging datasets.
+
+## Try it on Binder
+You can try UELer without installation by launching it on [Binder](https://mybinder.org/v2/gh/HartmannLab/UELer/main?urlpath=%2Fdoc%2Ftree%2Fscript%2Frun_ueler_binder.ipynb):
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/HartmannLab/UELer/main?urlpath=%2Fdoc%2Ftree%2Fscript%2Frun_ueler_binder.ipynb)
+
+## Installation
+
+### Option A — install with pip (recommended)
+
+**The install name is `ueler-viewer`; the import name is `ueler`.**
+
+The **stable** release is on PyPI:
+
+```shell
+pip install ueler-viewer
+```
+
+This pulls in every runtime dependency. Two optional extras are available:
+
+```shell
+pip install "ueler-viewer[ark]"     # adds ark-analysis (pinned) for ark-based workflows
+pip install "ueler-viewer[docs]"    # adds the mkdocs toolchain for building the docs
+```
+
+Requires Python 3.10, 3.11, or 3.12. Then, in Python:
+
+```python
+import ueler
+```
+
+#### Pre-releases (TestPyPI)
+
+Every release also goes to **TestPyPI**, and pre-releases (`alpha`, `beta`, `rc`) go there *only* — so use this if you want a preview of a version that is not out yet. Keep the command on one line: `--extra-index-url` is required, because TestPyPI does not mirror UELer's runtime dependencies, and `--pre` is what lets pip pick a pre-release at all.
+
+```shell
+pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ueler-viewer
+```
+
+Extras work the same way — `"ueler-viewer[ark]"`, `"ueler-viewer[docs]"` — and appending `==0.6.0rc1` pins one specific preview. Full details, including how to get back to the stable channel: [the installation page](https://hartmannlab.github.io/UELer/installation/).
+
+#### If the install fails
+
+- **`No matching distribution found for scikit-image>=0.19`** (or for any other dependency) — specific to the TestPyPI command: the resolver is only seeing TestPyPI, which hosts an empty `scikit-image` project. Keep the command on **one line**: the `--extra-index-url https://pypi.org/simple/` part is what lets the dependencies come from real PyPI, and it is easy to lose when a multi-line command is pasted.
+- **Installing with `uv`** — uv's default `--index-strategy first-index` stops at the first index that lists a package at all, so it never falls back to PyPI for the dependencies. It needs an extra flag:
+
+  ```shell
+  uv pip install --prerelease=allow --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match ueler-viewer
+  ```
+- **You installed an earlier release under the old `ueler` distribution name** — run `pip uninstall ueler` first. Both distributions install the same `ueler/` package, and pip does not know they are the same project, so having both leaves two installs fighting over the same files.
+
+### Option B — install from source (for development)
+
+Use this if you want to modify UELer or track the `develop` branch.
+
+1. Create a compatible environment from the `env/environment.yml` file in this repository:
+
+   ```shell
+   micromamba env create --name ark-analysis-ueler --file environment.yml
+   ```
+2. Clone the repository and activate the environment:
+
+   ```shell
+   git clone https://github.com/HartmannLab/UELer.git
+   micromamba activate ark-analysis-ueler
+   ```
+3. Install in editable mode from the cloned directory:
+
+   ```shell
+   cd UELer
+   pip install -e .
+   ```
+
+### Upgrade UELer
+If you installed the stable release from PyPI:
+```shell
+pip install --upgrade ueler-viewer
+```
+If you installed a pre-release from TestPyPI:
+```shell
+pip install --upgrade --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ueler-viewer
+```
+Coming from a release installed as `ueler` rather than `ueler-viewer`? Run `pip uninstall ueler` first — see [If the install fails](#if-the-install-fails).
+If you installed from source, pull the latest commits in your UELer directory. Re-run the install only when the dependencies changed — an editable install picks up code changes on its own:
+```shell
+git pull
+pip install -e .   # only needed if env/environment.yml or pyproject.toml changed
+```
+
+## Getting started
+1. Open your favorite editor that supports Jupyter notebook.
+2. Open the starter notebook `script/run_ueler.ipynb`. If you installed with pip rather than cloning, download it from [the repository](https://github.com/HartmannLab/UELer/blob/main/script/run_ueler.ipynb).
+3. Select the kernel for an ark-analysis compatible conda/micromamba env.
+4. Change the lines according to the instructions in the notebook: when configuring the `/script/run_ueler.ipynb`, ensure that you specify the following directory paths:
+  - **`base_folder`**: The directory containing the FOV (Field of View) folders with image data (e.g., `.../image_data`).
+  - **`masks_folder`** (optional): The directory containing the segmentation `.tif` files for cell segmentation (e.g., `.../segmentation/cellpose_output`).
+  - **`annotations_folder`** (optional): The directory containing annotation files for marking regions of interest (e.g., `.../annotations`).
+  - **`cell_table_path`** (optional): The path to the file containing the cell table data (e.g., `.../segmentation/cell_table/cell_table_size_normalized.csv`).
+Make sure these paths are correctly set in the notebook for the viewer to access the data correctly.
+
+5. Run the code and you will see the viewer displayed.
+
+### Streaming from the BioImage Archive (BIA)
+You can explore a public BioImage Archive study (an `S-BIAD*` accession) without downloading the
+whole dataset first:
+```python
+from ueler.runner import run_viewer_bia
+
+viewer = run_viewer_bia(
+    "S-BIAD2557",                      # accession id (or a direct HTTPS base URL)
+    descriptor={                        # optional; auto-detection is attempted if omitted
+        "mode": "folder",
+        "base": "Files/spatial_murine_iCCAvsHCC/image_data",
+        "mask_dir": "Files/spatial_murine_iCCAvsHCC/segmentation/cleaned_mask",
+        "mask_glob": "{fov}_*.tiff",
+    },
+)
+```
+Because BIA studies have no standard folder layout, a small JSON **descriptor** (a dict or a path
+to a `.json` file) maps the study files onto FOVs / channels / masks; when omitted, UELer attempts
+to auto-detect the folder-per-FOV, OME-TIFF-per-FOV, or zip-container layouts. The descriptor is
+flexible enough for the variation seen across real studies:
+- **Masks** accept either a single `mask_dir`/`mask_glob`, or a `masks` list of sources — each with
+  an optional `name` (renames masks named `<fov>.tiff` to a clean label) or `per_fov: true` (masks
+  stored in a per-FOV subfolder `<dir>/<fov>/*.tiff`). `annotations` uses the same shape.
+- **Zipped FOVs**: set `"fov_container": "zip"` when each FOV is a `<FOV>.zip` of channel TIFFs —
+  UELer reads a single channel straight out of the remote zip via an HTTP byte-range request rather
+  than downloading the whole archive.
+
+Pyramidal OME-TIFFs and single zip members are streamed via HTTP byte-range requests; other files
+(e.g. single-resolution MIBI TIFFs) are downloaded once into a local cache. A per-study
+**workspace** at `~/.ueler/bia/<accession>/` (override with `local_dir=`) holds your persistent
+`.UELer` work (ROIs, checkpoints, palettes) plus a disposable `cache/` of downloaded images.
+
+Examples for three real studies — `S-BIAD2557` (single-dir masks), `S-BIAD2864` (two named mask
+folders), and `S-BIAD2708` (zipped FOVs + per-FOV masks) — are in `script/run_ueler_BIA.ipynb`.
+
+## User interface
+![GUI_preview](https://raw.githubusercontent.com/HartmannLab/UELer/main/doc/GUI_preview.png)
+The GUI can be split into four main regions (wide plugins toggle the optional footer automatically):
+- left: overall settings (channel, annotation, and mask accordions)
+- middle: main viewer with overlay controls and image navigation
+- right: plugin tools (Mask Painter, ROI Manager, palette editors, statistics panels)
+- bottom (optional): wide plugin tabs (e.g., horizontal heatmap or gallery extensions)
+
+For more details, see the [user guide](https://hartmannlab.github.io/UELer/latest/tutorials/user-interface).
+
+## New Update  
+### **UELer v0.5.0 Summary**
+
+The `0.5.0` line turns UELer from a repository you clone into a package you install. This is the first release published to PyPI.
+
+**Installation and licensing**
+
+- **`pip install ueler-viewer` — you still `import ueler`.** PyPI prohibits the name `ueler`, so the distribution is `ueler-viewer`, like `scikit-image`/`skimage` or `opencv-python`/`cv2`. Nothing in your code changes. **Stable releases come from PyPI; alphas, betas and release candidates are only on TestPyPI** — see the [installation guide](https://hartmannlab.github.io/UELer/latest/installation). If you hold an editable install of the old `ueler` distribution, `pip uninstall ueler` first: pip treats the two as unrelated projects even though both own the `ueler/` package.
+- **Relicensed from GPL-3.0-only to BSD 3-Clause.** UELer is imported into other people's pipelines, which is where copyleft bites hardest — under the GPL, distributing a pipeline that imported `ueler` pulled that pipeline into the GPL too. BSD-3 matches the surrounding stack (scikit-image, dask, bokeh, anndata, napari). Existing users only gain permissions.
+- **Supported Python: 3.10, 3.11 and 3.12**, and `pandas>=2.0` is now a declared dependency rather than arriving through seaborn and anndata.
+- **Breaking: `import ueler` no longer claims the top-level names `viewer`, `constants`, `data_loader` and `image_utils`.** The pre-0.2 compatibility hook is removed, along with the `ensure_aliases=` argument of `run_viewer()` / `run_viewer_bia()`. The canonical paths (`ueler.constants`, `ueler.viewer.*`, …) are unchanged.
+
+**New in the viewer**
+
+- **Line and polygon ROIs, in the ROI manager.** Click a chain of points onto the canvas — left-click adds a vertex, left-drag moves one, right-click deletes the nearest, `ctrl+z`/`ctrl+y` undo and redo, `enter` finishes — with a live length or perimeter readout in px and µm. Shapes are ordinary ROI rows, so tags, thumbnails, filtering, CSV import/export and batch export all apply; exporting a shape exports its bounding box. Older ROI CSVs load unchanged.
+- **Cells selected in the image now reach the plots.** A **Follow main viewer** checkbox (*Linked plugins* tab, off by default) in the Scatter plot, Histogram and Heatmap mirrors the image's live selection into the plot, across several FOVs in map mode. It is the counterpart of the **Main viewer** checkbox, which pushes the other way.
+- **A handful of selected cells is now visible in the histogram.** Five cells out of 80 000 drew a bar 0.006 % of the plot height. When the selection's peak falls below 5 % of the tallest bar, the bins holding selected cells are tinted over their full height, with the proportional overlay still drawn on top. **Mark faint selections** turns it off.
+- **The interactive scatter is the default everywhere, VS Code included.** The static-Matplotlib fallback for VS Code worked around a webview bug that no longer happens, and cost every VS Code user their linked brushing. `UELER_SCATTER_BACKEND=static` remains as an opt-out.
+
+**Fixed**
+
+- **Locating a single cell works in the channel grid view.** Go-To, a gallery tile, a scatter or heatmap point, and centring on a saved ROI all did nothing at all in grid mode — no error, no movement.
+- **Painting a cell table no longer crashes on pandas extension dtypes.** The Mask Painter raised `TypeError: Cannot interpret '<StringDtype…>' as a data type` whenever the identifier column was categorical or nullable — which AnnData `obs` columns routinely are.
+- **The scatter matrix follows the standard SPLOM convention:** a row shares its y-axis, a column shares its x-axis. The previous layout was the transpose.
+- **A finished shape stays on screen**, instead of vanishing until the ROI was saved and loaded back, and **`Save shape` now finishes the drawing for you**.
+
+**Removed**
+
+- **The `Chart (heatmap)` plugin.** A near-duplicate of the Scatter plot reading its axes from the cluster × marker matrix, offering nothing Scatter plot or Heatmap does not. The real **Heatmap**, **Scatter plot** and **Histogram** are untouched — the plugin once labelled *Chart* is today's **Scatter plot**, not the removed one.
+
+**Worth knowing**
+
+- **`ENABLE_MAP_MODE` must be set before `import ueler`.** The flag is read at module import time, so setting it later has no effect — even before `run_viewer()`.
+- **The pixel size defaults to 390 nm — the MIBI pixel pitch — for every dataset**, and it drives the scale bar in the viewer and in every batch-exported image. Set it from your acquisition metadata (1000 nm for IMC), or to `0` to omit the scale bar entirely. The new [display settings](https://hartmannlab.github.io/UELer/latest/tutorials/display-settings) page covers this and the 99.9th-percentile contrast default.
+- **The [documentation site](https://hartmannlab.github.io/UELer/latest/) was audited against the code**, and a checker now runs on every docs deploy so install commands, the Python range, extras, repo paths, environment variables and UI labels cannot drift from the software again. Two new developer pages cover [plugin development](https://hartmannlab.github.io/UELer/latest/develop-notes/plugin-development) and [mask rendering & coloring](https://hartmannlab.github.io/UELer/latest/develop-notes/mask-rendering).
+- **Behind the scenes:** CI runs the suite on Python 3.10–3.12 and installs the built wheel outside the repository, a skipped test counts as a failure, and a pushed tag routes itself — pre-releases to TestPyPI, stable only after a matching release candidate is confirmed to ship identical code. Publishing uses PyPI Trusted Publishing; no API token exists in the repository.
+
+_Earlier changes (v0.4.4 and before) are in the [update log](https://github.com/HartmannLab/UELer/blob/main/doc/log.md)._
+
+## License
+UELer is released under the **BSD 3-Clause License** — see
+[LICENSE.txt](https://github.com/HartmannLab/UELer/blob/main/LICENSE.txt).
+
+You are free to use, modify and redistribute UELer, including in commercial and closed-source
+work, provided you keep the copyright notice and do not use the authors' names to endorse a
+derived product. This is the same license as `scikit-image`, `dask`, `bokeh`, `anndata` and
+`napari`, so UELer imposes no constraints your existing scientific Python stack does not.
+
+If you use UELer in published work, a citation is appreciated but not required.
+
+## Issues and contact
+Bug reports and feature requests: [GitHub Issues](https://github.com/HartmannLab/UELer/issues).
+Maintained by Yu-Le Wu, Hartmann Lab, DKFZ Heidelberg.

ueler_viewer-0.5.0/README.md

@@ -0,0 +1,201 @@
+# UELer
+Unified Exploratory Linked Viewer: a Jupyter-based framework for interactive exploration of multiplexed imaging datasets.
+
+## Try it on Binder
+You can try UELer without installation by launching it on [Binder](https://mybinder.org/v2/gh/HartmannLab/UELer/main?urlpath=%2Fdoc%2Ftree%2Fscript%2Frun_ueler_binder.ipynb):
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/HartmannLab/UELer/main?urlpath=%2Fdoc%2Ftree%2Fscript%2Frun_ueler_binder.ipynb)
+
+## Installation
+
+### Option A — install with pip (recommended)
+
+**The install name is `ueler-viewer`; the import name is `ueler`.**
+
+The **stable** release is on PyPI:
+
+```shell
+pip install ueler-viewer
+```
+
+This pulls in every runtime dependency. Two optional extras are available:
+
+```shell
+pip install "ueler-viewer[ark]"     # adds ark-analysis (pinned) for ark-based workflows
+pip install "ueler-viewer[docs]"    # adds the mkdocs toolchain for building the docs
+```
+
+Requires Python 3.10, 3.11, or 3.12. Then, in Python:
+
+```python
+import ueler
+```
+
+#### Pre-releases (TestPyPI)
+
+Every release also goes to **TestPyPI**, and pre-releases (`alpha`, `beta`, `rc`) go there *only* — so use this if you want a preview of a version that is not out yet. Keep the command on one line: `--extra-index-url` is required, because TestPyPI does not mirror UELer's runtime dependencies, and `--pre` is what lets pip pick a pre-release at all.
+
+```shell
+pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ueler-viewer
+```
+
+Extras work the same way — `"ueler-viewer[ark]"`, `"ueler-viewer[docs]"` — and appending `==0.6.0rc1` pins one specific preview. Full details, including how to get back to the stable channel: [the installation page](https://hartmannlab.github.io/UELer/installation/).
+
+#### If the install fails
+
+- **`No matching distribution found for scikit-image>=0.19`** (or for any other dependency) — specific to the TestPyPI command: the resolver is only seeing TestPyPI, which hosts an empty `scikit-image` project. Keep the command on **one line**: the `--extra-index-url https://pypi.org/simple/` part is what lets the dependencies come from real PyPI, and it is easy to lose when a multi-line command is pasted.
+- **Installing with `uv`** — uv's default `--index-strategy first-index` stops at the first index that lists a package at all, so it never falls back to PyPI for the dependencies. It needs an extra flag:
+
+  ```shell
+  uv pip install --prerelease=allow --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match ueler-viewer
+  ```
+- **You installed an earlier release under the old `ueler` distribution name** — run `pip uninstall ueler` first. Both distributions install the same `ueler/` package, and pip does not know they are the same project, so having both leaves two installs fighting over the same files.
+
+### Option B — install from source (for development)
+
+Use this if you want to modify UELer or track the `develop` branch.
+
+1. Create a compatible environment from the `env/environment.yml` file in this repository:
+
+   ```shell
+   micromamba env create --name ark-analysis-ueler --file environment.yml
+   ```
+2. Clone the repository and activate the environment:
+
+   ```shell
+   git clone https://github.com/HartmannLab/UELer.git
+   micromamba activate ark-analysis-ueler
+   ```
+3. Install in editable mode from the cloned directory:
+
+   ```shell
+   cd UELer
+   pip install -e .
+   ```
+
+### Upgrade UELer
+If you installed the stable release from PyPI:
+```shell
+pip install --upgrade ueler-viewer
+```
+If you installed a pre-release from TestPyPI:
+```shell
+pip install --upgrade --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ueler-viewer
+```
+Coming from a release installed as `ueler` rather than `ueler-viewer`? Run `pip uninstall ueler` first — see [If the install fails](#if-the-install-fails).
+If you installed from source, pull the latest commits in your UELer directory. Re-run the install only when the dependencies changed — an editable install picks up code changes on its own:
+```shell
+git pull
+pip install -e .   # only needed if env/environment.yml or pyproject.toml changed
+```
+
+## Getting started
+1. Open your favorite editor that supports Jupyter notebook.
+2. Open the starter notebook `script/run_ueler.ipynb`. If you installed with pip rather than cloning, download it from [the repository](https://github.com/HartmannLab/UELer/blob/main/script/run_ueler.ipynb).
+3. Select the kernel for an ark-analysis compatible conda/micromamba env.
+4. Change the lines according to the instructions in the notebook: when configuring the `/script/run_ueler.ipynb`, ensure that you specify the following directory paths:
+  - **`base_folder`**: The directory containing the FOV (Field of View) folders with image data (e.g., `.../image_data`).
+  - **`masks_folder`** (optional): The directory containing the segmentation `.tif` files for cell segmentation (e.g., `.../segmentation/cellpose_output`).
+  - **`annotations_folder`** (optional): The directory containing annotation files for marking regions of interest (e.g., `.../annotations`).
+  - **`cell_table_path`** (optional): The path to the file containing the cell table data (e.g., `.../segmentation/cell_table/cell_table_size_normalized.csv`).
+Make sure these paths are correctly set in the notebook for the viewer to access the data correctly.
+
+5. Run the code and you will see the viewer displayed.
+
+### Streaming from the BioImage Archive (BIA)
+You can explore a public BioImage Archive study (an `S-BIAD*` accession) without downloading the
+whole dataset first:
+```python
+from ueler.runner import run_viewer_bia
+
+viewer = run_viewer_bia(
+    "S-BIAD2557",                      # accession id (or a direct HTTPS base URL)
+    descriptor={                        # optional; auto-detection is attempted if omitted
+        "mode": "folder",
+        "base": "Files/spatial_murine_iCCAvsHCC/image_data",
+        "mask_dir": "Files/spatial_murine_iCCAvsHCC/segmentation/cleaned_mask",
+        "mask_glob": "{fov}_*.tiff",
+    },
+)
+```
+Because BIA studies have no standard folder layout, a small JSON **descriptor** (a dict or a path
+to a `.json` file) maps the study files onto FOVs / channels / masks; when omitted, UELer attempts
+to auto-detect the folder-per-FOV, OME-TIFF-per-FOV, or zip-container layouts. The descriptor is
+flexible enough for the variation seen across real studies:
+- **Masks** accept either a single `mask_dir`/`mask_glob`, or a `masks` list of sources — each with
+  an optional `name` (renames masks named `<fov>.tiff` to a clean label) or `per_fov: true` (masks
+  stored in a per-FOV subfolder `<dir>/<fov>/*.tiff`). `annotations` uses the same shape.
+- **Zipped FOVs**: set `"fov_container": "zip"` when each FOV is a `<FOV>.zip` of channel TIFFs —
+  UELer reads a single channel straight out of the remote zip via an HTTP byte-range request rather
+  than downloading the whole archive.
+
+Pyramidal OME-TIFFs and single zip members are streamed via HTTP byte-range requests; other files
+(e.g. single-resolution MIBI TIFFs) are downloaded once into a local cache. A per-study
+**workspace** at `~/.ueler/bia/<accession>/` (override with `local_dir=`) holds your persistent
+`.UELer` work (ROIs, checkpoints, palettes) plus a disposable `cache/` of downloaded images.
+
+Examples for three real studies — `S-BIAD2557` (single-dir masks), `S-BIAD2864` (two named mask
+folders), and `S-BIAD2708` (zipped FOVs + per-FOV masks) — are in `script/run_ueler_BIA.ipynb`.
+
+## User interface
+![GUI_preview](https://raw.githubusercontent.com/HartmannLab/UELer/main/doc/GUI_preview.png)
+The GUI can be split into four main regions (wide plugins toggle the optional footer automatically):
+- left: overall settings (channel, annotation, and mask accordions)
+- middle: main viewer with overlay controls and image navigation
+- right: plugin tools (Mask Painter, ROI Manager, palette editors, statistics panels)
+- bottom (optional): wide plugin tabs (e.g., horizontal heatmap or gallery extensions)
+
+For more details, see the [user guide](https://hartmannlab.github.io/UELer/latest/tutorials/user-interface).
+
+## New Update  
+### **UELer v0.5.0 Summary**
+
+The `0.5.0` line turns UELer from a repository you clone into a package you install. This is the first release published to PyPI.
+
+**Installation and licensing**
+
+- **`pip install ueler-viewer` — you still `import ueler`.** PyPI prohibits the name `ueler`, so the distribution is `ueler-viewer`, like `scikit-image`/`skimage` or `opencv-python`/`cv2`. Nothing in your code changes. **Stable releases come from PyPI; alphas, betas and release candidates are only on TestPyPI** — see the [installation guide](https://hartmannlab.github.io/UELer/latest/installation). If you hold an editable install of the old `ueler` distribution, `pip uninstall ueler` first: pip treats the two as unrelated projects even though both own the `ueler/` package.
+- **Relicensed from GPL-3.0-only to BSD 3-Clause.** UELer is imported into other people's pipelines, which is where copyleft bites hardest — under the GPL, distributing a pipeline that imported `ueler` pulled that pipeline into the GPL too. BSD-3 matches the surrounding stack (scikit-image, dask, bokeh, anndata, napari). Existing users only gain permissions.
+- **Supported Python: 3.10, 3.11 and 3.12**, and `pandas>=2.0` is now a declared dependency rather than arriving through seaborn and anndata.
+- **Breaking: `import ueler` no longer claims the top-level names `viewer`, `constants`, `data_loader` and `image_utils`.** The pre-0.2 compatibility hook is removed, along with the `ensure_aliases=` argument of `run_viewer()` / `run_viewer_bia()`. The canonical paths (`ueler.constants`, `ueler.viewer.*`, …) are unchanged.
+
+**New in the viewer**
+
+- **Line and polygon ROIs, in the ROI manager.** Click a chain of points onto the canvas — left-click adds a vertex, left-drag moves one, right-click deletes the nearest, `ctrl+z`/`ctrl+y` undo and redo, `enter` finishes — with a live length or perimeter readout in px and µm. Shapes are ordinary ROI rows, so tags, thumbnails, filtering, CSV import/export and batch export all apply; exporting a shape exports its bounding box. Older ROI CSVs load unchanged.
+- **Cells selected in the image now reach the plots.** A **Follow main viewer** checkbox (*Linked plugins* tab, off by default) in the Scatter plot, Histogram and Heatmap mirrors the image's live selection into the plot, across several FOVs in map mode. It is the counterpart of the **Main viewer** checkbox, which pushes the other way.
+- **A handful of selected cells is now visible in the histogram.** Five cells out of 80 000 drew a bar 0.006 % of the plot height. When the selection's peak falls below 5 % of the tallest bar, the bins holding selected cells are tinted over their full height, with the proportional overlay still drawn on top. **Mark faint selections** turns it off.
+- **The interactive scatter is the default everywhere, VS Code included.** The static-Matplotlib fallback for VS Code worked around a webview bug that no longer happens, and cost every VS Code user their linked brushing. `UELER_SCATTER_BACKEND=static` remains as an opt-out.
+
+**Fixed**
+
+- **Locating a single cell works in the channel grid view.** Go-To, a gallery tile, a scatter or heatmap point, and centring on a saved ROI all did nothing at all in grid mode — no error, no movement.
+- **Painting a cell table no longer crashes on pandas extension dtypes.** The Mask Painter raised `TypeError: Cannot interpret '<StringDtype…>' as a data type` whenever the identifier column was categorical or nullable — which AnnData `obs` columns routinely are.
+- **The scatter matrix follows the standard SPLOM convention:** a row shares its y-axis, a column shares its x-axis. The previous layout was the transpose.
+- **A finished shape stays on screen**, instead of vanishing until the ROI was saved and loaded back, and **`Save shape` now finishes the drawing for you**.
+
+**Removed**
+
+- **The `Chart (heatmap)` plugin.** A near-duplicate of the Scatter plot reading its axes from the cluster × marker matrix, offering nothing Scatter plot or Heatmap does not. The real **Heatmap**, **Scatter plot** and **Histogram** are untouched — the plugin once labelled *Chart* is today's **Scatter plot**, not the removed one.
+
+**Worth knowing**
+
+- **`ENABLE_MAP_MODE` must be set before `import ueler`.** The flag is read at module import time, so setting it later has no effect — even before `run_viewer()`.
+- **The pixel size defaults to 390 nm — the MIBI pixel pitch — for every dataset**, and it drives the scale bar in the viewer and in every batch-exported image. Set it from your acquisition metadata (1000 nm for IMC), or to `0` to omit the scale bar entirely. The new [display settings](https://hartmannlab.github.io/UELer/latest/tutorials/display-settings) page covers this and the 99.9th-percentile contrast default.
+- **The [documentation site](https://hartmannlab.github.io/UELer/latest/) was audited against the code**, and a checker now runs on every docs deploy so install commands, the Python range, extras, repo paths, environment variables and UI labels cannot drift from the software again. Two new developer pages cover [plugin development](https://hartmannlab.github.io/UELer/latest/develop-notes/plugin-development) and [mask rendering & coloring](https://hartmannlab.github.io/UELer/latest/develop-notes/mask-rendering).
+- **Behind the scenes:** CI runs the suite on Python 3.10–3.12 and installs the built wheel outside the repository, a skipped test counts as a failure, and a pushed tag routes itself — pre-releases to TestPyPI, stable only after a matching release candidate is confirmed to ship identical code. Publishing uses PyPI Trusted Publishing; no API token exists in the repository.
+
+_Earlier changes (v0.4.4 and before) are in the [update log](https://github.com/HartmannLab/UELer/blob/main/doc/log.md)._
+
+## License
+UELer is released under the **BSD 3-Clause License** — see
+[LICENSE.txt](https://github.com/HartmannLab/UELer/blob/main/LICENSE.txt).
+
+You are free to use, modify and redistribute UELer, including in commercial and closed-source
+work, provided you keep the copyright notice and do not use the authors' names to endorse a
+derived product. This is the same license as `scikit-image`, `dask`, `bokeh`, `anndata` and
+`napari`, so UELer imposes no constraints your existing scientific Python stack does not.
+
+If you use UELer in published work, a citation is appreciated but not required.
+
+## Issues and contact
+Bug reports and feature requests: [GitHub Issues](https://github.com/HartmannLab/UELer/issues).
+Maintained by Yu-Le Wu, Hartmann Lab, DKFZ Heidelberg.

ueler_viewer-0.5.0/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# The *distribution* name only — what `pip install` asks for. The import name is
+# `ueler` and is unaffected: it comes from the package directory, not from here.
+# `ueler` is administratively prohibited on PyPI (most likely as typo-squat
+# protection for the live `euler` project), so the distribution ships under
+# `ueler-viewer` on both indexes. See dev_note/issue_tracking/issue79_dist_name_rename.md.
+name = "ueler-viewer"
+version = "0.5.0"
+description = "Unified Exploratory Linked Viewer for spatial proteomics and multiplexed imaging"
+readme = "README.md"
+requires-python = ">=3.10,<3.13"
+license = "BSD-3-Clause"
+license-files = ["LICENSE.txt"]
+authors = [
+    { name = "Yu-Le Wu (Hartmann Lab, DKFZ)" }
+]
+keywords = [
+    "spatial proteomics",
+    "multiplexed imaging",
+    "image viewer",
+    "jupyter",
+    "MIBI",
+    "IMC",
+    "bioimage analysis",
+]
+# No "License ::" classifier here on purpose: PEP 639 forbids combining one with
+# the `license` SPDX expression above, and setuptools warns if both are present.
+# No "Topic :: Scientific/Engineering :: Image Processing" either: UELer displays
+# and links images, it does not offer filtering, segmentation or registration, so
+# Visualization + Bio-Informatics is the honest pair.
+# The Python classifiers must stay in step with `requires-python`.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Framework :: Jupyter",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "scikit-image>=0.19",
+    "dask",
+    "dask-image",
+    "ipydatagrid",
+    "bqplot",
+    "seaborn",
+    "seaborn-image",
+    "opencv-python-headless",
+    "watchfiles",
+    "jupyter-scatter",
+    "ipywidgets>=8.1",
+    "anywidget>=0.9",
+    "numpy",
+    # Declared explicitly although seaborn/anndata would drag it in anyway: the
+    # viewer imports pandas directly in ~14 modules, and leaving it transitive is
+    # what let pip resolve a different major version per Python minor (pandas 3
+    # needs >=3.11, so the CI 3.12 leg got the new string dtype and 3.10/3.11 did
+    # not). The floor is conservative rather than measured -- the suite is only
+    # exercised against 2.3 and, via `future.infer_string`, pandas-3 semantics.
+    "pandas>=2.0",
+    "ipykernel",
+    "ipympl",
+    "anndata>=0.10",
+    "tifffile",
+    "fsspec[http]",
+    "requests",
+    "bokeh>=3.0",
+    "jupyter_bokeh>=4.0",
+]
+
+[project.optional-dependencies]
+ark = ["ark-analysis==0.7.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mike>=2.1",
+]
+
+# These become the "Project links" sidebar on the PyPI page. Absolute URLs only —
+# a release is browsed outside the repository, so nothing repo-relative works here.
+[project.urls]
+Homepage = "https://github.com/HartmannLab/UELer"
+Documentation = "https://hartmannlab.github.io/UELer/"
+Repository = "https://github.com/HartmannLab/UELer"
+Issues = "https://github.com/HartmannLab/UELer/issues"
+Changelog = "https://github.com/HartmannLab/UELer/blob/main/doc/log.md"
+
+[tool.setuptools.packages.find]
+include = ["ueler", "ueler.*"]
+exclude = ["tests", "tests.*", "dev_note", "script"]
+
+[tool.setuptools.package-data]
+"ueler.viewer" = ["images/*"]

ueler_viewer-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+