{"name":"napari-nd2-spectral-ome-zarr","display_name":"ND2 Spectral OME-Zarr","visibility":"public","icon":"","categories":[],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-nd2-spectral-ome-zarr.get_reader","title":"Open ND2 or OME-Zarr spectral image","python_name":"napari_nd2_spectral_ome_zarr._reader:napari_get_reader","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-nd2-spectral-ome-zarr.widget","title":"ND2 Spectral OME-Zarr Exporter","python_name":"napari_nd2_spectral_ome_zarr._widget:Nd2SpectralWidget","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-nd2-spectral-ome-zarr.spectral_viewer","title":"Spectral Viewer","python_name":"napari_nd2_spectral_ome_zarr._spectral_viewer:SpectralViewerWidget","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-nd2-spectral-ome-zarr.spectral_analysis","title":"Spectral Analysis","python_name":"napari_nd2_spectral_ome_zarr._spectral_analysis:SpectralAnalysisWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"napari-nd2-spectral-ome-zarr.get_reader","filename_patterns":["*.nd2","*.zarr","*.ome.zarr"],"accepts_directories":true}],"writers":null,"widgets":[{"command":"napari-nd2-spectral-ome-zarr.widget","display_name":"ND2 Spectral Export","autogenerate":false},{"command":"napari-nd2-spectral-ome-zarr.spectral_viewer","display_name":"Spectral Viewer","autogenerate":false},{"command":"napari-nd2-spectral-ome-zarr.spectral_analysis","display_name":"Spectral Analysis","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.4","name":"napari-nd2-spectral-ome-zarr","version":"1.1.1","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"A napari plugin for Nikon ND2 spectral imaging workflows, including ND2-to-OME-Zarr conversion, OME-Zarr reading, spectral visualization, and ROI-based analysis across 400-740 nm.","description":"# napari-nd2-spectral-ome-zarr\n\nThis napari plugin supports spectral fluorescence imaging workflows for\nsolvatochromic dye analysis (e.g., Nile Red) across the visible emission\nrange (~400–740 nm). It provides ND2-to-OME-Zarr conversion, ROI-based\nspectral extraction, emission-ratio analysis, and aggregation from ROI\nto image-level and animal-level datasets.\n\n## Supported microscopy systems\n\nTested with spectral ND2 datasets generated from:\n\n- Nikon A1 spectral detector systems\n- Nikon AX spectral detector systems\n\n## Plugin Overview\n\nThe plugin is organized as 3 subplugins:\n\n1. `ND2 Spectral Export`\n- convert single files or batches from ND2 to OME-Zarr\n- load single or batch OME-Zarr datasets\n- validate image structure and dimensions such as axes order, shape, and wavelength metadata\n\n2. `Spectral Viewer`\n- visualize spectral images as truecolor using visible-wavelength hue mapping\n- provide a single-channel grayscale image for morphology review and machine-learning workflows\n- read spectral intensity versus wavelength in normalized or absolute modes\n- support ROI generation and ROI-based spectral extraction\n\n3. `Spectral Analysis`\n- collect stored ROI datasets for downstream analysis\n- compute emission-ratio metrics using a user-defined split wavelength\n- support Student's t-test and one-way or two-way ANOVA\n- support blind-group analysis using PCA, feature comparison, user-selected clustering, and p-value statistics\n\nFeatures:\n\n- Read `.nd2` files into napari\n- Read `.zarr` and `.ome.zarr` through the plugin loader widget\n- Build an estimated truecolor RGB view for spectral ranges spanning roughly 400 nm to 740 nm\n- Export the loaded ND2 spectral cube to OME-Zarr with multiscales and wavelength metadata\n- Plot ROI spectra from spectral OME-Zarr layers\n- Keep per-image ROI spectral datasets in memory during the napari session\n- Export stored ROI datasets and analysis tables to CSV\n- Run split-wavelength Nile Red ratio analysis, aggregation, and group comparison in a dedicated analysis panel\n\nThe plugin is designed around 2D spectral images and keeps `T`, `C`, `Z`, `Y`, `X` axis semantics explicit during export.\n\n## Installation\n\nInstall the plugin in a Python environment that can run napari:\n\n```bash\npip install -e .\n```\n\nThen start napari and open the plugin widgets from the Plugins menu.\n\n## Intended users\n\nThis plugin is designed for researchers working with spectral fluorescence\nmicroscopy datasets, especially solvatochromic probes such as Nile Red\nfor myelin physicochemical analysis. It supports workflows involving:\n\n- Nikon spectral ND2 datasets\n- OME-Zarr spectral cubes\n- ROI-based emission ratio measurements\n- blinded experimental grouping (PCA)\n- multi-image aggregation across animals\n\n## Dock Widgets\n\nThe plugin now exposes 3 napari dock widgets:\n\n- `ND2 Spectral Export`\n- `Spectral Viewer`\n- `Spectral Analysis`\n\nAll 3 widgets are configured to float by default instead of staying docked in the main napari window.\n\n## ND2 Spectral Export Workflow\n\n`ND2 Spectral Export` now handles:\n\n- single ND2 preview\n- batch ND2 to OME-Zarr export\n- single OME-Zarr loading\n- batch OME-Zarr loading from a parent folder\n\n### Single Zarr loading\n\nThe widget supports drag-and-drop or browsing for one `.zarr` folder.\n\nBefore opening, it shows:\n\n- dataset name\n- axes\n- full-resolution shape\n- preview shape\n- whether the dataset is spectral\n- wavelength count and wavelength range\n\nThe user can choose which views to open:\n\n- `Visible sum`\n- `Truecolor`\n- `Raw spectral`\n\nIt also supports `Use preview pyramid level` for the display layers.\n\n### Batch Zarr loading\n\nThe widget also supports scanning one parent folder recursively for `.zarr` datasets, including nested subfolders.\n\nThe batch table shows:\n\n- `open`\n- `name`\n- `relative_path`\n- `axes`\n- `shape`\n- `preview_shape`\n- `wavelengths`\n- `spectral`\n\n`relative_path` is shown as the parent folder only, for example `./659/`, instead of including the `.zarr` folder name.\n\nThe user can:\n\n- browse to a root folder\n- scan recursively for `.zarr` datasets\n- select all or clear all\n- open only the checked datasets\n\nThe chosen `Visible sum`, `Truecolor`, `Raw spectral`, and preview options are applied to all selected Zarr datasets in the batch open action.\n\n### Reader popup note\n\nIf a user opens `.zarr` files through napari's generic file-open dialog, napari may still show a `Choose reader` popup when multiple readers claim `.zarr`.\n\nThis plugin cannot reliably suppress that global napari chooser by itself.\n\nThe intended workaround is:\n\n- use the plugin's own Zarr loader in `ND2 Spectral Export`\n- open Zarr datasets from there instead of through napari's general file-open menu\n\n### Visible sum definition\n\n`Visible sum` is currently computed as the raw per-pixel mean intensity across spectral bins:\n\n- sum all channel intensities at a pixel\n- divide by the number of spectral bins\n- do not normalize\n\nSo if a pixel has 24 spectral bins, the displayed gray value is:\n\n`(bin_1 + bin_2 + ... + bin_24) / 24`\n\n## Spectral Viewer Workflow\n\n`Spectral Viewer` is where ROIs are drawn and spectral datasets are captured.\n\n### Important ROI logic\n\nROI layers are now handled per image, not globally.\n\n- Each active spectral image gets its own Shapes layer named like `image_name ROI`\n- ROI labels are displayed through a separate companion label layer\n- ROI numbering resets per image, so image 1 can have `ROI 1..N` and image 2 can also have `ROI 1..N`\n- ROIs from image 1 are not reused automatically for image 2\n\n### Recommended step-by-step use\n\n1. Select a spectral image layer.\n2. Click `Prepare ROI Layer`.\n3. Draw ROIs for that image only.\n4. Click `Plot ROI Spectrum`.\n5. The plugin stores that image's ROI spectra in memory as a dataset.\n6. Move to the next image.\n7. Click `Prepare ROI Layer` again for that image.\n8. Draw a fresh set of ROIs starting from `ROI 1`.\n\nIf you want to redraw for the current image, click `Clear Active ROI`. That clears only the active image's ROI shapes and restarts numbering from `ROI 1`.\n\n### Stored ROI datasets\n\nWhen `Plot ROI Spectrum` is used, the selected ROI spectra are stored in memory for the current napari session.\n\n- Stored datasets remain available even if the image layer is later closed\n- Stored datasets can be exported from `Spectral Viewer`\n- Stored datasets are consumed by the `Spectral Analysis` panel\n- Stored datasets do not persist across a full napari restart unless they are exported\n\n## Spectral Analysis Workflow\n\n`Spectral Analysis` is intended for multi-image and multi-animal experiments.\n\n### Metadata editing\n\nThe `Stored ROI Datasets` table lets you annotate each captured dataset with:\n\n- `animal_id`\n- `group_label`\n- `genotype`\n- `sex`\n- `age`\n- `region`\n- `batch`\n- `blind_id`\n\nThis supports experiments such as:\n\n- 10 images total\n- multiple experimental groups such as WT vs mutant, control vs treatment, or blinded cohorts\n- multiple myelin ROIs per image\n- aggregation from ROI level to image level to animal level\n\n### Dataset selection and removal\n\nAnalysis no longer uses every stored dataset automatically.\n\n- Use the `use_for_analysis` checkbox column to choose which dataset IDs are included\n- Click `Compute Spectral Analysis` to analyze only the checked datasets\n- Click `Remove Selected Datasets` to delete all checked datasets from memory\n- Click `Remove Current Row` to delete the currently selected dataset\n\nUnchecked datasets stay in memory but are ignored by the analysis.\n\n### Available analysis outputs\n\nThe panel computes:\n\n- ROI-level ratio table\n- image-level summary table\n- animal-level summary table\n\nEach table can be exported to CSV.\n\n### Ratio and statistics\n\nThe analysis panel supports:\n\n- user-defined split wavelength\n- ratio modes such as above/below split intensity ratio\n- optional normalization before ratio calculation\n- two-group comparison such as WT vs mutant or control vs treatment\n- one-way ANOVA by selected factor\n- blind PCA and clustering for unlabeled datasets\n\n### Recommended experiment flow\n\n1. Open spectral images in napari.\n2. For image 1, prepare the ROI layer and draw multiple myelin ROIs.\n3. Plot the ROI spectrum to store that image's ROI dataset.\n4. Repeat for image 2, image 3, and so on.\n5. Open `Spectral Analysis`.\n6. Enter metadata for each stored dataset.\n7. Check only the dataset IDs you want to compare.\n8. Set the wavelength split point.\n9. Compute the analysis.\n10. Export ROI, image, or animal summary CSV files as needed.\n\n## Reproducibility note\n\nThe spectral analysis tools implemented in this plugin reproduce the\nmethodology described in Teo et al. (PNAS 2021) and Teo et al. (2024).\nThe plugin itself is a new napari-based implementation designed to make\nthese workflows accessible within OME-Zarr-compatible environments.\n\n## Known Limitations\n\n- If `.zarr` files are opened through napari's generic file-open dialog, napari may still show a `Choose reader` popup when multiple readers claim `.zarr`. Use the plugin's own Zarr loader to avoid that workflow.\n- ROI datasets are stored in memory for the current napari session and should be exported if they need to survive a full application restart.\n- napari `Shapes` rendering can be sensitive in some environments. The plugin uses separate ROI label layers to reduce instability, but behavior can still depend on upstream napari and vispy rendering.\n\n\n## Citation\n\nThis plugin implements spectral analysis workflows derived from the\nNile Red myelin spectroscopy methodology described in:\n\nTeo et al., PNAS 2021\nhttps://doi.org/10.1073/pnas.2016897118\n\nTeo et al., 2024\nhttps://pmc.ncbi.nlm.nih.gov/articles/PMC11657930/\n\nIf you use this plugin in research, please cite these papers.\n","description_content_type":"text/markdown","keywords":"napari,spectral imaging,nd2,ome-zarr,myelin,nile red,fluorescence spectroscopy","home_page":null,"download_url":null,"author":null,"author_email":"Wulin Teo <wulinteo.usa2@gmail.com>","maintainer":null,"maintainer_email":null,"license":"MIT","classifier":["Framework :: napari","License :: OSI Approved :: MIT License","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11"],"requires_dist":["numpy","nd2>=0.10","dask[array]","zarr<3","numcodecs","ome-zarr","scikit-image","qtpy","matplotlib"],"requires_python":">=3.10","requires_external":null,"project_url":["Homepage, https://github.com/wulinteousa2-hash/napari-nd2-spectral-ome-zarr","Repository, https://github.com/wulinteousa2-hash/napari-nd2-spectral-ome-zarr"],"provides_extra":null,"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}