{"name":"napari-cilia-assistant","display_name":"Cilia Assistant","visibility":"public","icon":"","categories":["Utilities"],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-cilia-assistant.make_widget","title":"Open Cilia Assistant","python_name":"napari_cilia_assistant._widget:CiliaAssistantWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":null,"writers":null,"widgets":[{"command":"napari-cilia-assistant.make_widget","display_name":"Cilia Assistant","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.4","name":"napari-cilia-assistant","version":"1.1.0","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"A napari plugin for measuring ciliary beat frequency from high-speed microscopy videos.","description":"# napari-cilia-assistant\n\n`napari-cilia-assistant` is a napari plugin for exploratory ciliary motion analysis from high-speed AVI microscopy videos.\n\nThe plugin supports ROI-based ciliary beat frequency (CBF) measurement, kymograph review, spatial CBF heatmaps, motion activity maps, and experimental optical-flow descriptors.\n\n[Watch the demo video](docs/ui.mp4)\n\n## Install\n\nInstall conda-forge first:  \nhttps://conda-forge.org/download/\n\nThen open a terminal and run:\n\n```bash\nconda create -n cilia-assistant python=3.11 -y\nconda activate cilia-assistant\nconda install -c conda-forge napari pyqt git -y\ngit clone https://github.com/wulinteousa2-hash/napari-cilia-assistant.git\ncd napari-cilia-assistant\npip install -e .\nnapari\n```\n\nIn napari, open:\n\n```text\nPlugins > Cilia Assistant\n```\n\n## What It Does\n\n- Opens one AVI video through the napari widget.\n- Reads video metadata such as FPS, frame count, size, codec, and duration.\n- Loads AVI data as a grayscale `T, Y, X` image stack.\n- Lets the user draw/edit a rectangular ROI over active cilia.\n- Supports optional background ROI subtraction.\n- Measures ROI mean-intensity change over time.\n- Estimates CBF using FFT, Welch PSD, or periodogram analysis.\n- Provides a peak-interval CBF check.\n- Creates a kymograph layer from the selected ROI.\n- Generates spatial CBF heatmaps.\n- Generates motion activity maps to help locate moving regions.\n- Provides experimental optical-flow maps for apparent motion direction, magnitude, curl, and deformation.\n- Exports the last ROI signal and frequency spectrum as CSV files.\n- Copies or saves the current measurement graph.\n\n## User Interface Overview\n\nThe widget uses a five-step workflow:\n\n1. **Input**  \n   Load an AVI file, inspect metadata, and confirm FPS.\n\n2. **Region of Interest**  \n   Draw or edit the cilia ROI. Optionally define a background ROI.\n\n3. **Analysis**  \n   Choose one of the analysis tabs:\n\n   - **ROI Frequency**  \n     Standard CBF measurement from a selected ROI. This is the main workflow for quantitative reporting.\n\n   - **CBF Heatmap**  \n     Generates a spatial map of dominant frequency across the selected ROI or whole frame.\n\n   - **Motion Activity**  \n     Shows where the video changes over time. This is useful for finding active cilia, drift, debris, or non-ciliary motion.\n\n   - **Advanced Flow**  \n     Experimental optical-flow analysis for apparent motion magnitude, direction, curl, and deformation.\n\n4. **Results / Graphs**  \n   Review the intensity trace, frequency spectrum, peak result, heatmap, activity map, or flow-map summary.\n\n5. **Export & Log**  \n   Export results and copy the analysis log.\n\n## Basic ROI Frequency Workflow\n\n1. Open napari.\n2. Open `Plugins > Cilia Assistant`.\n3. Click **Open AVI**.\n4. Confirm the FPS. Correct it manually if the AVI metadata are wrong.\n5. Click **Create / Edit ROI Rectangle**.\n6. Move/resize the ROI over visibly beating cilia.\n7. Optional: create a background ROI if there is shared illumination or focus drift.\n8. Go to **Step 3 > ROI Frequency**.\n9. Choose the frequency method:\n   - `FFT` for simple dominant-frequency analysis.\n   - `Welch` for noisier traces.\n   - `Periodogram` as another spectrum-based check.\n10. Set the expected CBF search range, for example `3-25 Hz`.\n11. Click **Analyze Selected ROI**.\n12. Review the trace, frequency peak, peak-interval result, and kymograph.\n13. Export CSV files if the result is usable.\n\n## Output\n\n- **Frequency CBF:** dominant frequency in the selected search range.\n- **Peak-interval CBF:** independent check based on repeated peaks in the ROI signal.\n- **Kymograph:** visual audit of periodic motion in the ROI.\n- **CBF heatmap:** spatial map of estimated dominant frequency.\n- **Peak-strength map:** map showing relative frequency-peak strength.\n- **Motion activity map:** temporal motion/activity map.\n- **Optical-flow maps:** exploratory apparent motion descriptors.\n- **CSV export:** raw ROI time-intensity signal and frequency spectrum.\n- **Graph export:** copy or save the current measurement graph.\n\n## Good Measurement Practice\n\n- Use videos with known FPS.\n- Correct the FPS manually if AVI metadata are wrong.\n- Keep temperature, medium, and timing consistent across samples.\n- Place the ROI on active cilia, not static tissue, debris, or whole-frame motion.\n- Use motion activity maps to identify candidate moving regions before final ROI measurement.\n- Use CBF heatmaps as exploratory spatial screening, not as a replacement for careful ROI review.\n- Use multiple ROIs/videos and biological replicates for group comparisons.\n- Treat whole-frame frequency and optical-flow results as exploratory only.\n- Always review the raw video, ROI placement, graph, and kymograph before interpreting the number.\n\n## Limitations\n\nThis plugin measures ciliary motion from intensity changes in AVI microscopy videos. The standard ROI workflow estimates beat frequency, not full ciliary waveform or clinical diagnostic beat pattern.\n\nA sample can have a normal CBF but abnormal waveform or poor flow generation. CBF heatmaps, motion activity maps, and optical-flow maps are useful exploratory tools, but they do not replace expert review of the raw video.\n\nThe **Advanced Flow** tab is experimental. Flow magnitude, direction, curl, and deformation should be interpreted as image-motion descriptors, not diagnostic classifications.\n\n\n## Acknowledgements\n\nDuring development, I reviewed publicly available open-source cilia motion-analysis resources, including the `cilia-metrics` repository:\n\nhttps://github.com/quinngroup/cilia-metrics\n\nThe repository was useful for understanding existing computational approaches to ciliary motion analysis, especially spatial CBF mapping and frequency-domain analysis. This helped guide the addition of CBF heatmaps, Welch/PSD options, and motion-map style outputs in `napari-cilia-assistant`.\n\n`napari-cilia-assistant` is independently implemented as a napari-based interactive workflow for AVI loading, ROI-based CBF measurement, kymograph review, spatial screening, and exportable analysis logs.\n\n## References\n\n1. Chilvers MA, O'Callaghan C. Analysis of ciliary beat pattern and beat frequency using digital high speed imaging: comparison with the photomultiplier and photodiode methods. *Thorax*. 2000;55:314-317. doi:10.1136/thorax.55.4.314\n\n2. Jackson CL, Bottier M. Methods for the assessment of human airway ciliary function. *European Respiratory Journal*. 2022;60:2102300. doi:10.1183/13993003.02300-2021\n\n3. Francis R. A Simple Method for Imaging and Quantifying Respiratory Cilia Motility in Mouse Models. *Methods and Protocols*. 2025;8:113. doi:10.3390/mps8050113\n","description_content_type":"text/markdown","keywords":null,"home_page":null,"download_url":null,"author":"Wulin Teo","author_email":null,"maintainer":null,"maintainer_email":null,"license":"MIT","classifier":["Framework :: napari","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","License :: OSI Approved :: MIT License","Operating System :: OS Independent","Intended Audience :: Science/Research","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["napari","numpy","scipy","opencv-python","qtpy","magicgui","matplotlib"],"requires_python":">=3.10","requires_external":null,"project_url":["Homepage, https://github.com/wulinteousa2-hash/napari-cilia-assistant","Repository, https://github.com/wulinteousa2-hash/napari-cilia-assistant","Issues, https://github.com/wulinteousa2-hash/napari-cilia-assistant/issues"],"provides_extra":null,"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}