Troubleshooting
Solutions to common problems and error messages.
Installation Issues
Python Version Errors
Error: Python 3.8 or higher is required
Solution:
```bash # Check Python version python –version
# Install Python 3.9+ # On Mac with Homebrew: brew install python@3.9
Dependency Installation Failures
Error: Could not install napari
Solutions:
Use virtual environment:
```bash python -m venv napari-env source napari-env/bin/activate # Mac/Linux # or napari-envScriptsactivate # Windows
pip install napari cellpose scikit-image ```
Update pip:
`bash
pip install --upgrade pip
pip install napari
`
Use conda instead:
`bash
conda create -n napari-chr python=3.9
conda activate napari-chr
conda install -c conda-forge napari
`
CUDA/GPU Issues
Error: CUDA out of memory
Solutions:
Reduce image size:
Resize images to smaller dimensions before processing.
Use CPU mode:
In the code, disable GPU:
`python
model = Cellpose(gpu=False)
`
Close other GPU applications:
Free up GPU memory by closing other programs.
Process one image at a time:
Avoid batch processing large images.
Qt/GUI Issues
Error: No module named 'PyQt5'
Solution:
`bash
pip install PyQt5
# or
pip install PySide2
`
Error: Could not initialize Qt application
Solution on macOS:
Image Loading Problems
No Images Found
Error: No images found in folder
Diagnosis:
Channel identifiers don’t match filenames
Images are in subdirectories
Wrong folder selected
Solutions:
Check filenames:
`bash
ls /path/to/images/
# Verify files contain your identifier strings
`
Update identifiers:
Match the actual strings in your filenames:
`
If files are: sample_DAPI.tif, sample_GFP.tif, sample_RFP.tif
Use identifiers: DAPI, GFP, RFP
`
Check folder structure:
Images should be in the folder you selected, not in subdirectories.
File Format Not Supported
Error: Cannot read file format
Supported Formats:
TIFF (.tif, .tiff) - recommended
PNG (.png)
JPEG (.jpg, .jpeg)
Solution:
Convert images to TIFF:
`python
from PIL import Image
img = Image.open('image.jpg')
img.save('image.tif')
`
Incorrect Number of Channels
Problem: Only 1 or 2 channels loaded
Solutions:
Verify all files exist:
`bash
ls -1 /path/to/images/*435* # DAPI
ls -1 /path/to/images/*525* # Channel 1
ls -1 /path/to/images/*679* # Channel 2
`
Check identifier case sensitivity:
Use identifiers that match exactly (case-sensitive on Linux/Mac).
Enable “Skip Segmentation”:
If DAPI is missing and not needed.
Segmentation Problems
Segmentation Failed
Error: Segmentation could not complete
Causes & Solutions:
Poor Image Quality:
Low contrast
Out of focus
Overexposed
Solution: Adjust image acquisition settings or skip segmentation.
Model File Missing:
Error: Cellpose model not found
Solution:
Verify model path in code or use default model:
`python
model = Cellpose(gpu=True, model_type='cyto') # Use built-in model
`
Too Many/Few Chromosomes Detected
Problem: 100+ chromosomes detected (should be ~46)
Causes:
Threshold too low
Debris in image
Over-segmentation
Solutions:
Adjust Cellpose parameters (in code):
`python
model.eval(..., flow_threshold=0.6) # Increase from default 0.4
`
Use manual corrections:
Remove extra objects with the Remove tool.
Pre-process images:
Clean up debris before analysis.
Problem: Very few chromosomes detected (<10)
Causes:
Threshold too high
Poor DAPI signal
Chromosomes clumped together
Solutions:
Lower threshold in code
Improve DAPI staining
Use manual merge tool for clumped chromosomes
Segmentation is Very Slow
Typical Times:
With GPU: 5-15 seconds
Without GPU: 30-60 seconds
If Slower:
Enable GPU:
`bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
`
Reduce image size:
Resize to 1024x1024 or smaller.
Check GPU is being used:
Console should show: Using GPU for segmentation
Spot Detection Issues
No Spots Detected
Problem: Zero spots found in one or both channels
Solutions:
Lower threshold:
Move slider to 20-30 (more sensitive).
Check image quality:
Verify signal is present by looking at the raw image.
Verify correct channel loaded:
Check that the fluorescence channel is displayed.
Increase sensitivity in code (advanced):
Modify detection parameters for more sensitive detection.
Too Many False Positives
Problem: Hundreds of spots, many are noise
Solutions:
Increase threshold:
Move slider to 60-70 (more specific).
Improve image quality:
Better background subtraction
Reduce imaging noise
Optimize exposure time
Use manual deletion:
Remove false positives with the spot deletion tool.
Filter by size (in code):
`python
# Only keep spots of certain size
spots = filter_by_size(spots, min_size=3, max_size=50)
`
Spots Don’t Match Visual Inspection
Problem: Detected spots don’t align with visible signals
Causes:
Wrong channel being analyzed
Coordinate system mismatch
Detection on wrong image plane (z-stack)
Solutions:
Verify channel order:
Toggle layers to confirm which is which.
Check z-plane:
If using z-stacks, ensure analyzing the correct plane.
Manual verification:
Use spot deletion to remove incorrect detections.
Intensity Measurement Problems
Negative or Zero Intensities
Problem: CSV shows 0 or negative intensity values
Causes:
Background subtraction too aggressive
Spots outside image bounds
Empty spot regions
Solutions:
Check background subtraction:
Disable or reduce background subtraction.
Verify spot coordinates:
Ensure spots are within image boundaries.
Inspect raw data:
Look at intensity values before processing.
Unrealistic Intensity Values
Problem: Intensities seem too high or too low
Checks:
Verify image bit-depth:
`python
import tifffile
img = tifffile.imread('image.tif')
print(f"Data type: {img.dtype}")
print(f"Max value: {img.max()}")
`
Check for saturation:
High values may indicate saturated pixels.
Normalize if needed:
Convert to consistent scale across images.
Missing Intensity Data
Problem: CSV file has no data or few rows
Solutions:
Verify “Find Common” was run:
Must run before intensity calculation.
Check spot detection:
Ensure spots were detected in both channels.
Look for error messages:
Console may show why measurement failed.
Batch Processing Problems
Batch Processing Stops Unexpectedly
Problem: Processing halts mid-batch
Causes & Solutions:
Memory Exhaustion:
Reduce batch size
Close other applications
Add swap space
File Permission Errors:
```bash # Check permissions ls -la /path/to/images/
# Fix permissions chmod -R 755 /path/to/images/ ```
Corrupted Image File:
Identify problematic file from last console message
Remove or fix the file
Resume batch processing
Some Folders Skipped
Problem: Not all folders were processed
Check:
Console output for error messages
Folder structure - each folder should have all 3 channels
File permissions - ensure read/write access
Solution:
Process skipped folders individually to see specific errors.
Inconsistent Results Across Batch
Problem: Wide variation in spot counts or intensities
Possible Causes:
Variable image quality
Inconsistent imaging parameters
Sample-to-sample biological variation
Solutions:
Quality control:
Identify outliers and inspect manually.
Normalize parameters:
Adjust thresholds per subset if needed.
Document variability:
May be real biological variation.
Performance Issues
Application is Slow or Unresponsive
General Solutions:
Close other applications
Restart the application
Reduce image size
Enable GPU acceleration
Process in smaller batches
High Memory Usage
Problem: System runs out of RAM
Solutions:
Process fewer images at once
Reduce image resolution
Close unnecessary layers in Napari
Increase system swap space
Use 64-bit Python
Application Crashes
Problem: Unexpected crashes or freezes
Debugging Steps:
Check console for error messages
Update all dependencies:
`bash
pip install --upgrade napari cellpose scikit-image
`
Try with minimal test case:
Process one small image to isolate the problem.
Check system resources:
`bash
# Monitor memory and CPU
top # Linux/Mac
# or Task Manager on Windows
`
Data and File Issues
CSV File Empty or Malformed
Problem: Results CSV is empty or doesn’t open
Solutions:
Check file exists:
`bash
ls -lh /path/to/results.csv
`
Verify analysis completed:
Check console for “Intensity calculation complete” message.
Try alternative CSV reader:
If Excel fails, try:
`python
import pandas as pd
df = pd.read_csv('results.csv')
print(df.head())
`
Can’t Find Output Files
Problem: Don’t know where results were saved
Solution:
Check console output - it shows the save location:
`
Saved results to: /path/to/folder/folder_name_intensity.csv
`
Or search for files:
`bash
find /path/to/images -name "*intensity.csv"
`
Unable to Save Corrections
Problem: “Save” button doesn’t work or corrections not saved
Solutions:
Check write permissions:
`bash
ls -ld /path/to/folder/
# Should show: drwxr-xr-x (writeable)
`
Verify disk space:
`bash
df -h
`
Try saving to different location
Error Messages Reference
Common Error Messages and Solutions
ValueError: shapes not aligned
Cause: Image dimensions mismatch
Solution: Verify all channels are same size
FileNotFoundError: Model file not found
Cause: Cellpose model path incorrect
Solution: Update model path or use default model
RuntimeError: CUDA error
Cause: GPU memory issue
Solution: Use CPU mode or reduce image size
PermissionError: Access denied
Cause: No write permissions
Solution: Check folder permissions
MemoryError: Unable to allocate array
Cause: Insufficient RAM
Solution: Reduce image size or add more RAM
Getting Additional Help
Before Contacting Support
Please gather:
Error message (full text from console)
System information (OS, Python version)
Steps to reproduce the problem
Sample images (if possible)
Console output (copy/paste or screenshot)
Contact Information
Email: sagarm2@nih.gov Subject line: “Napari Chromosome Analysis - [Your Issue]” Affiliation: HITIF/LRBGE/CCR/NCI
Include in Email:
Brief problem description
Error messages
What you’ve tried
System details
Community Resources
Napari Documentation: https://napari.org/
Cellpose Documentation: https://cellpose.readthedocs.io/
GitHub Issues: Report bugs on the repository
Next Steps
Basic Workflow - Review basic workflow
Advanced Features - Advanced troubleshooting options
API Documentation - API documentation for programmatic solutions