microlive 1.0.13__py3-none-any.whl → 1.0.14__py3-none-any.whl

microlive/__init__.py

@@ -23,7 +23,7 @@ Authors:
     Nathan L. Nowling, Brian Munsky, Ning Zhao
 """
 
-__version__ = "1.0.13"
+__version__ = "1.0.14"
 __author__ = "Luis U. Aguilera, William S. Raymond, Rhiannon M. Sears, Nathan L. Nowling, Brian Munsky, Ning Zhao"
 
 # Package name (for backward compatibility)

microlive/microscopy.py

@@ -1423,6 +1423,13 @@ class Intensity():
         optimize_spot_size: Search for optimal spot size (5-11 px). Slower. Defaults to False.
         allow_subpixel_repositioning: Search ±2px for better center. Defaults to False.
         fast_gaussian_fit: Use moment-based (fast) vs full Gaussian fit. Defaults to True.
+        snr_method: Method for calculating signal-to-noise ratio. Options:
+            - 'peak' (default): Uses the maximum pixel value in the spot region as signal.
+              This is the standard definition of SNR: (max_spot - mean_bg) / std_bg.
+              Recommended for most applications.
+            - 'disk_doughnut': Uses mean disk intensity as signal instead of peak value.
+              Calculates SNR as: (mean_disk - mean_bg) / std_bg.
+              More robust when data is very noisy or spots are dim.
     
     Attributes:
         number_spots: Number of spots to measure.
@@ -1431,7 +1438,7 @@ class Intensity():
     
     def __init__(self, original_image, spot_size=5, array_spot_location_z_y_x=None, 
                  use_max_projection=False, optimize_spot_size=False, allow_subpixel_repositioning=False,
-                 fast_gaussian_fit=True):
+                 fast_gaussian_fit=True, snr_method='peak'):
         self.original_image = original_image
         if array_spot_location_z_y_x is None:
             self.array_spot_location_z_y_x = np.array([[0, 0, 0]])
@@ -1449,6 +1456,7 @@ class Intensity():
         self.optimize_spot_size = optimize_spot_size
         self.allow_subpixel_repositioning = allow_subpixel_repositioning
         self.fast_gaussian_fit = fast_gaussian_fit
+        self.snr_method = snr_method
 
     def two_dimensional_gaussian(self, xy, amplitude, x0, y0, sigma_x, sigma_y, offset):
         """Evaluate 2D Gaussian at given coordinates."""
@@ -1551,11 +1559,23 @@ class Intensity():
     def calculate_intensity(self):
         """Calculate intensity metrics for all spots across all channels.
         
+        The signal-to-noise ratio (SNR) calculation method is controlled by the
+        `snr_method` parameter set during class initialization:
+        
+        - **'peak'** (default): Uses the maximum pixel value in the spot region 
+          as the signal. This is the standard definition of SNR commonly used 
+          in microscopy: SNR = (max_spot - mean_background) / std_background.
+          
+        - **'disk_doughnut'**: Uses the mean disk intensity as signal instead 
+          of the peak value. This method is more robust for very noisy data 
+          or dim spots where the maximum value may be unreliable due to noise.
+          SNR = (mean_disk - mean_background) / std_background.
+        
         Returns:
             tuple: 8-element tuple of arrays, each with shape [N_spots, N_channels]:
                 - intensities: Background-subtracted intensity (disk - doughnut mean).
                 - intensities_std: Standard deviation within disk region.
-                - intensities_snr: Signal-to-noise ratio (disk-bg) / std(bg).
+                - intensities_snr: Signal-to-noise ratio (calculation depends on snr_method).
                 - intensities_background_mean: Mean background from doughnut.
                 - intensities_background_std: Std of background from doughnut.
                 - psfs_amplitude: PSF peak amplitude from Gaussian fit (or NaN).
@@ -1577,11 +1597,31 @@ class Intensity():
             donut_values = tem_img[~np.isnan(tem_img)].astype('uint16')
             return donut_values
 
-        def signal_to_noise_ratio(values_disk, values_donut):
-            mean_disk = np.mean(values_disk.astype(float))
+        def signal_to_noise_ratio(values_disk, values_donut, snr_method='peak'):
+            """Calculate signal-to-noise ratio for a spot.
+            
+            Args:
+                values_disk: Pixel values in the spot disk region.
+                values_donut: Pixel values in the background doughnut region.
+                snr_method: 'peak' uses max pixel value as signal (standard),
+                           'disk_doughnut' uses mean disk intensity (robust for noisy data).
+            
+            Returns:
+                tuple: (SNR, mean_background, std_background)
+            """
             mean_donut = np.mean(values_donut.astype(float))
             std_donut = np.std(values_donut.astype(float))
-            SNR = (mean_disk - mean_donut) / std_donut if std_donut > 0 else 0
+            
+            if snr_method == 'peak':
+                # Standard SNR: use peak (maximum) pixel value as signal
+                max_disk = np.max(values_disk.astype(float))
+                signal = max_disk - mean_donut
+            else:
+                # disk_doughnut method: use mean disk intensity as signal
+                mean_disk = np.mean(values_disk.astype(float))
+                signal = mean_disk - mean_donut
+            
+            SNR = signal / std_donut if std_donut > 0 else 0
             return SNR, mean_donut, std_donut
 
         def disk_donut(values_disk, values_donut, spot_size):
@@ -1749,7 +1789,7 @@ class Intensity():
                 # Use the updated integer positions for the final intensity crop
                 crop_disk_and_donut = return_crop(frame_data[:,:,i], current_x_int, current_y_int, spot_range=crop_range)
                 values_donut = return_donut(crop_disk_and_donut, spot_size=best_size)
-                intensities_snr[sp,i], intensities_background_mean[sp,i], intensities_background_std[sp,i] = signal_to_noise_ratio(values_disk, values_donut)
+                intensities_snr[sp,i], intensities_background_mean[sp,i], intensities_background_std[sp,i] = signal_to_noise_ratio(values_disk, values_donut, self.snr_method)
                 # disk_donut calculation
                 intensities[sp,i], intensities_std[sp,i] = disk_donut(values_disk, values_donut, spot_size=best_size)
                 intensities_total[sp,i] = np.sum(values_disk)
@@ -1914,14 +1954,9 @@ class Cellpose():
         # Initialize Cellpose model
         if self.pretrained_model is None:
             if self.model_type == 'cyto3':
-                try:
-                    model = denoise.CellposeDenoiseModel(gpu=use_gpu, model_type="cyto3",
-                                         restore_type="denoise_cyto3")
-                    logging.debug('Cellpose: Model cyto3 loaded')
-                except Exception as e:
-                    logging.warning(f"Failed to load cyto3 model: {e}. Falling back to 'cyto2'.")
-                    self.model_type = 'cyto2'
-                    model = models.Cellpose(gpu=use_gpu, model_type='cyto2')
+                model = denoise.CellposeDenoiseModel(gpu=use_gpu, model_type="cyto3",
+                                     restore_type="denoise_cyto3")
+                logging.debug('Cellpose: Model cyto3 loaded')
             else:
                 model = models.Cellpose(gpu=use_gpu, model_type=self.model_type)  # model_type = 'cyto' or 'nuclei'
         else:

microlive/pipelines/pipeline_FRAP.py

@@ -1,7 +1,14 @@
-"""Pipeline module for MicroLive.
+"""Pipeline module for MicroLive FRAP analysis.
 
-This module is part of the microlive package.
+This module is part of the microlive package and provides functions for
+Fluorescence Recovery After Photobleaching (FRAP) analysis.
+
+The pipeline uses a pretrained Cellpose model for nuclei segmentation that
+is automatically downloaded from GitHub on first use.
 """
+import os
+import traceback
+
 from microlive.imports import *
 
 from skimage.feature import canny
@@ -12,6 +19,95 @@ from skimage.morphology import binary_opening, binary_closing
 from skimage.measure import label, regionprops
 from skimage.transform import hough_circle, hough_circle_peaks
 
+# Import model downloader with graceful fallback
+try:
+    from microlive.utils.model_downloader import get_frap_nuclei_model_path
+    _HAS_MODEL_DOWNLOADER = True
+except ImportError:
+    _HAS_MODEL_DOWNLOADER = False
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# GPU Detection and MPS Compatibility (aligned with microscopy.py)
+# =============================================================================
+
+class PatchMPSFloat64:
+    """
+    Context manager to safely monkeypatch torch.zeros on MPS devices 
+    to force float32 instead of float64 (which is not supported).
+    
+    Copied from microlive.microscopy for self-contained FRAP pipeline.
+    """
+    def __init__(self):
+        self.original_zeros = torch.zeros
+        self.is_mps = torch.backends.mps.is_available() and torch.backends.mps.is_built()
+
+    def __enter__(self):
+        if not self.is_mps:
+            return
+        
+        def patched_zeros(*args, **kwargs):
+            # Check if device is MPS (either string or torch.device)
+            device = kwargs.get('device', None)
+            is_target_device = False
+            if device is not None:
+                if isinstance(device, str) and 'mps' in device:
+                    is_target_device = True
+                elif isinstance(device, torch.device) and device.type == 'mps':
+                    is_target_device = True
+            
+            # Check if dtype is float64/double
+            dtype = kwargs.get('dtype', None)
+            is_target_dtype = (dtype == torch.float64 or dtype == torch.double)
+
+            if is_target_device and is_target_dtype:
+                kwargs['dtype'] = torch.float32
+            
+            return self.original_zeros(*args, **kwargs)
+        
+        torch.zeros = patched_zeros
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.is_mps:
+            torch.zeros = self.original_zeros
+
+
+def _detect_gpu():
+    """
+    Detect available GPU (CUDA or MPS) for Cellpose.
+    
+    Returns:
+        bool: True if GPU is available (CUDA or MPS), False otherwise.
+    """
+    os.environ['PYTORCH_ENABLE_MPS_FALLBACK'] = '1'
+    return torch.cuda.is_available() or torch.backends.mps.is_available()
+
+
+def _get_frap_nuclei_model():
+    """
+    Get the path to the pretrained FRAP nuclei segmentation model.
+    
+    Downloads from GitHub on first use, caches locally in ~/.microlive/models/.
+    Returns None if download fails, allowing fallback to default Cellpose model.
+    
+    Returns:
+        str or None: Path to the model file, or None if unavailable.
+    """
+    if not _HAS_MODEL_DOWNLOADER:
+        logger.debug("Model downloader not available, using default nuclei model")
+        return None
+    
+    try:
+        model_path = get_frap_nuclei_model_path()
+        logger.info(f"Using pretrained FRAP nuclei model: {model_path}")
+        return model_path
+    except Exception as e:
+        logger.warning(f"Could not load FRAP nuclei model: {e}. Using default.")
+        return None
+
 def read_lif_files_in_folder(folder_path):
     # create funtion that read all the .lif files in a folder and return the list of images
     list_folders = list(folder_path.glob('*.lif'))
@@ -160,43 +256,111 @@ def find_frap_coordinates(image_TXY, frap_time, stable_FRAP_channel, min_diamete
         return None, None
 
 
-def segment_image(image_TXY, step_size=5, pretrained_model_segmentation=None, frap_time=None, pixel_dilation_pseudo_cytosol=10,stable_FRAP_channel=0,min_diameter=10):
+def segment_image(image_TXY, step_size=5, pretrained_model_segmentation='auto', frap_time=None, pixel_dilation_pseudo_cytosol=10,stable_FRAP_channel=0,min_diameter=10):
+    """
+    Segment nuclei in FRAP image stack using Cellpose.
+    
+    Args:
+        image_TXY: 3D image array (Time, X, Y).
+        step_size: Number of frames between segmentations.
+        pretrained_model_segmentation: Model to use:
+            - 'auto' (default): Auto-download and use FRAP-optimized model from GitHub
+            - None or 'nuclei': Use default Cellpose nuclei model
+            - str path: Use custom pretrained model at given path
+        frap_time: Frame index of FRAP event.
+        pixel_dilation_pseudo_cytosol: Pixels to dilate for pseudo-cytosol.
+        stable_FRAP_channel: Channel index for stable signal.
+        min_diameter: Minimum ROI diameter in pixels.
+    
+    Returns:
+        Tuple of (masks_TXY, background_mask, pseudo_cytosol_masks_TXY).
+    """
     num_pixels_to_dilate = 1
-    use_gpu = False  # or True if you want to try MPS on Apple Silicon
-    if pretrained_model_segmentation is not None:
+    
+    # GPU detection (aligned with microscopy.py)
+    use_gpu = _detect_gpu()
+    logger.debug(f"FRAP Pipeline: GPU available = {use_gpu}")
+    
+    # Ensure image is float32 for MPS compatibility
+    image_TXY = image_TXY.astype(np.float32)
+    
+    # Determine which model to use
+    if pretrained_model_segmentation == 'auto':
+        # Auto-download FRAP-optimized model from GitHub
+        pretrained_model_segmentation = _get_frap_nuclei_model()
+    
+    # Helper function to run Cellpose with error handling
+    def _run_cellpose_eval(model, image, model_type_fallback=None, **kwargs):
+        """Run Cellpose evaluation with MPS error handling and CPU fallback."""
+        nonlocal use_gpu
+        try:
+            with PatchMPSFloat64():
+                return model.eval(image, **kwargs)[0]
+        except RuntimeError as e:
+            if "sparse" in str(e) and torch.backends.mps.is_available():
+                logger.warning(f"MPS sparse error detected: {e}. Retrying with resample=False.")
+                try:
+                    kwargs['resample'] = False
+                    with PatchMPSFloat64():
+                        return model.eval(image, **kwargs)[0]
+                except RuntimeError as e2:
+                    logger.warning(f"MPS error persisted: {e2}. Falling back to CPU.")
+                    # Reinitialize model on CPU
+                    if model_type_fallback is not None:
+                        model = models.CellposeModel(gpu=False, model_type=model_type_fallback)
+                    else:
+                        model = models.CellposeModel(gpu=False, pretrained_model=pretrained_model_segmentation)
+                    use_gpu = False
+                    kwargs.pop('resample', None)  # Reset resample
+                    return model.eval(image, **kwargs)[0]
+            else:
+                logger.error(f"Cellpose RuntimeError: {e}")
+                logger.error(traceback.format_exc())
+                return np.zeros(image.shape[:2], dtype=np.uint16)
+        except Exception as e:
+            logger.error(f"Cellpose error: {e}")
+            logger.error(traceback.format_exc())
+            return np.zeros(image.shape[:2], dtype=np.uint16)
+    
+    # Initialize models
+    if pretrained_model_segmentation is not None and pretrained_model_segmentation != 'nuclei':
+        logger.info(f"Using pretrained model for nuclei segmentation")
         model_nucleus = models.CellposeModel(
             gpu=use_gpu,
             pretrained_model=pretrained_model_segmentation
         )
     else:
+        logger.info("Using default Cellpose nuclei model")
         model_nucleus = models.CellposeModel(
             gpu=use_gpu,
             model_type='nuclei'
         )
-    #model_cyto = models.Cellpose(gpu=False, model_type='cyto2')
-    model_cyto = models.CellposeModel( gpu=use_gpu, model_type='cyto2')
+    model_cyto = models.CellposeModel(gpu=use_gpu, model_type='cyto2')
+    
     num_steps = (image_TXY.shape[0] + step_size - 1) // step_size
     list_masks = []
     list_selected_mask_id = []
     list_selected_masks = []
     list_masks_cyto = []
+    
     # If frap_time is provided, segment the FRAP images and select the mask with maximum intensity change
     if frap_time is not None:
         # Ensure frap_time is within valid range
         if frap_time < 1 or frap_time >= image_TXY.shape[0] - 1:
             raise ValueError("frap_time must be within the range of the image stack.")
         # Segment the image at frap_time
-        #masks_frap = model_nucleus.eval(image_TXY[frap_time], normalize=True, channels=[0,0], flow_threshold=0.8, diameter=150, min_size=100)[0]
-        masks_frap = model_nucleus.eval(
+        masks_frap = _run_cellpose_eval(
+            model_nucleus,
             image_TXY[frap_time],
-            channels=[0, 0],          # ← add this!
+            model_type_fallback='nuclei',
+            channels=[0, 0],
             normalize=True,
             flow_threshold=1,
             diameter=150,
             min_size=50
-        )[0]
+        )
         # remove all the maks that are touching the border
-        masks_frap =remove_border_masks(masks_frap,min_size=50)
+        masks_frap = remove_border_masks(masks_frap, min_size=50)
         # Get unique mask labels (excluding background)
         mask_labels = np.unique(masks_frap)
         mask_labels = mask_labels[mask_labels != 0]
@@ -210,13 +374,10 @@ def segment_image(image_TXY, step_size=5, pretrained_model_segmentation=None, fr
                     selected_mask_frap = binary_dilation(selected_mask_frap, iterations=num_pixels_to_dilate).astype('int')
                     break
             else:
-                #selected_mask_id_frap = None
                 selected_mask_frap = None
         else:
-            #selected_mask_id_frap = None
             selected_mask_frap = None
     else:
-        #selected_mask_id_frap = None
         selected_mask_frap = None
     if selected_mask_frap is None:
         return None, None, None
@@ -224,19 +385,29 @@ def segment_image(image_TXY, step_size=5, pretrained_model_segmentation=None, fr
     for step in range(num_steps):
         i = step * step_size
         # Detecting masks in i-th frame
-        masks = model_nucleus.eval(
+        masks = _run_cellpose_eval(
+            model_nucleus,
             image_TXY[i],
-            channels=[0, 0],         
+            model_type_fallback='nuclei',
+            channels=[0, 0],
             normalize=True,
             flow_threshold=1,
             diameter=150,
             min_size=50
-        )[0]
+        )
         list_masks.append(masks)
-        masks =remove_border_masks(masks,min_size=50)
+        masks = remove_border_masks(masks, min_size=50)
         # Detect cytosol masks only every `step_size` frames
         if step % 2 == 0:
-            masks_cyto = model_cyto.eval(image_TXY[i], normalize=True, flow_threshold=0.5, diameter=250, min_size=100)[0]
+            masks_cyto = _run_cellpose_eval(
+                model_cyto,
+                image_TXY[i],
+                model_type_fallback='cyto2',
+                normalize=True,
+                flow_threshold=0.5,
+                diameter=250,
+                min_size=100
+            )
             list_masks_cyto.append(masks_cyto)
         if frap_time is None:
             # Selecting the mask that is in the center of the image
@@ -311,7 +482,7 @@ def segment_image(image_TXY, step_size=5, pretrained_model_segmentation=None, fr
 
 
 
-def create_image_arrays(list_concatenated_images, selected_image=0, FRAP_channel_to_quantify=0,pretrained_model_segmentation=None,frap_time=None, starting_changing_frame=40, step_size_increase=5,min_diameter=10):
+def create_image_arrays(list_concatenated_images, selected_image=0, FRAP_channel_to_quantify=0,pretrained_model_segmentation='auto',frap_time=None, starting_changing_frame=40, step_size_increase=5,min_diameter=10):
     image_TZXYC = list_concatenated_images[selected_image] # shape (T Z Y X C)
     print('Image with shape (T Z Y X C):\n ' ,list_concatenated_images[selected_image].shape) # TZYXC
     print('Original Image pixel ', 'min: {:.2f}, max: {:.2f}, mean: {:.2f}, std: {:.2f}'.format(np.min(image_TZXYC), np.max(image_TZXYC), np.mean(image_TZXYC), np.std(image_TZXYC)) )

microlive/utils/__init__.py

@@ -2,6 +2,12 @@
 
 from .device import get_device, is_gpu_available, get_device_info, check_gpu_status
 from .resources import get_icon_path, get_model_path
+from .model_downloader import (
+    get_frap_nuclei_model_path,
+    cache_model,
+    list_cached_models,
+    MODEL_DIR,
+)
 
 __all__ = [
     "get_device",
@@ -10,4 +16,9 @@ __all__ = [
     "check_gpu_status",
     "get_icon_path",
     "get_model_path",
+    # Model downloader
+    "get_frap_nuclei_model_path",
+    "cache_model",
+    "list_cached_models",
+    "MODEL_DIR",
 ]

microlive/utils/model_downloader.py

@@ -0,0 +1,293 @@
+"""
+Model download utilities for MicroLive.
+
+This module provides functions to download and cache pretrained models from
+the MicroLive GitHub repository. It follows the same patterns used by Cellpose
+for robust model provisioning.
+
+Models are downloaded on first use and cached locally in ~/.microlive/models/
+to avoid repeated downloads.
+"""
+
+import os
+import ssl
+import shutil
+import tempfile
+import logging
+from pathlib import Path
+from urllib.request import urlopen
+from urllib.error import URLError, HTTPError
+
+logger = logging.getLogger(__name__)
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+# Base URL for raw GitHub content
+_GITHUB_RAW_BASE = "https://raw.githubusercontent.com/ningzhaoAnschutz/microlive/main"
+
+# Model URLs - Add new models here
+MODEL_URLS = {
+    "frap_nuclei": f"{_GITHUB_RAW_BASE}/modeling/cellpose_models/cellpose_models/FRAP_nuclei_model/models/cellpose_1728581750.581418",
+}
+
+# Local cache directory (similar to Cellpose's ~/.cellpose/models/)
+_MODEL_DIR_ENV = os.environ.get("MICROLIVE_LOCAL_MODELS_PATH")
+_MODEL_DIR_DEFAULT = Path.home() / ".microlive" / "models"
+MODEL_DIR = Path(_MODEL_DIR_ENV) if _MODEL_DIR_ENV else _MODEL_DIR_DEFAULT
+
+
+# =============================================================================
+# Download Utilities (adapted from Cellpose)
+# =============================================================================
+
+def download_url_to_file(url: str, dst: str, progress: bool = True) -> None:
+    """
+    Download object at the given URL to a local path.
+    
+    Adapted from Cellpose/torch implementation for robustness.
+    
+    Args:
+        url: URL of the object to download.
+        dst: Full path where object will be saved.
+        progress: Whether to display a progress bar. Default: True.
+    
+    Raises:
+        HTTPError: If the server returns an error status.
+        URLError: If the URL cannot be reached.
+    """
+    try:
+        from tqdm import tqdm
+        HAS_TQDM = True
+    except ImportError:
+        HAS_TQDM = False
+        progress = False
+    
+    file_size = None
+    
+    # Handle SSL certificate verification issues
+    ssl_context = ssl.create_default_context()
+    ssl_context.check_hostname = False
+    ssl_context.verify_mode = ssl.CERT_NONE
+    
+    try:
+        u = urlopen(url, context=ssl_context)
+    except URLError as e:
+        raise URLError(f"Failed to connect to {url}: {e}")
+    
+    meta = u.info()
+    if hasattr(meta, "getheaders"):
+        content_length = meta.getheaders("Content-Length")
+    else:
+        content_length = meta.get_all("Content-Length")
+    
+    if content_length is not None and len(content_length) > 0:
+        file_size = int(content_length[0])
+    
+    # Save to temp file first, then move (atomic operation)
+    dst = os.path.expanduser(dst)
+    dst_dir = os.path.dirname(dst)
+    os.makedirs(dst_dir, exist_ok=True)
+    
+    f = tempfile.NamedTemporaryFile(delete=False, dir=dst_dir)
+    try:
+        if HAS_TQDM and progress:
+            with tqdm(total=file_size, disable=not progress, unit="B", 
+                      unit_scale=True, unit_divisor=1024,
+                      desc=f"Downloading {Path(dst).name}") as pbar:
+                while True:
+                    buffer = u.read(8192)
+                    if len(buffer) == 0:
+                        break
+                    f.write(buffer)
+                    pbar.update(len(buffer))
+        else:
+            # Simple download without progress bar
+            while True:
+                buffer = u.read(8192)
+                if len(buffer) == 0:
+                    break
+                f.write(buffer)
+        
+        f.close()
+        shutil.move(f.name, dst)
+        logger.info(f"Successfully downloaded model to {dst}")
+        
+    except Exception as e:
+        f.close()
+        if os.path.exists(f.name):
+            os.remove(f.name)
+        raise RuntimeError(f"Download failed: {e}")
+    finally:
+        if os.path.exists(f.name):
+            try:
+                os.remove(f.name)
+            except OSError:
+                pass
+
+
+# =============================================================================
+# Model Cache Functions
+# =============================================================================
+
+def get_model_path(model_name: str) -> Path:
+    """
+    Get the local cache path for a model.
+    
+    Args:
+        model_name: Name of the model (e.g., "frap_nuclei").
+        
+    Returns:
+        Path to the cached model file.
+    """
+    return MODEL_DIR / model_name
+
+
+def is_model_cached(model_name: str) -> bool:
+    """
+    Check if a model is already cached locally.
+    
+    Args:
+        model_name: Name of the model.
+        
+    Returns:
+        True if the model exists locally, False otherwise.
+    """
+    return get_model_path(model_name).exists()
+
+
+def cache_model(model_name: str, force_download: bool = False) -> str:
+    """
+    Ensure a model is cached locally, downloading if necessary.
+    
+    This function follows the Cellpose pattern:
+    1. Check if model exists in local cache
+    2. If not (or force_download=True), download from GitHub
+    3. Return the local path
+    
+    Args:
+        model_name: Name of the model (must be in MODEL_URLS).
+        force_download: If True, re-download even if cached.
+        
+    Returns:
+        String path to the cached model file.
+        
+    Raises:
+        ValueError: If model_name is not recognized.
+        RuntimeError: If download fails.
+    """
+    if model_name not in MODEL_URLS:
+        available = ", ".join(MODEL_URLS.keys())
+        raise ValueError(f"Unknown model '{model_name}'. Available: {available}")
+    
+    MODEL_DIR.mkdir(parents=True, exist_ok=True)
+    cached_file = get_model_path(model_name)
+    
+    if not cached_file.exists() or force_download:
+        url = MODEL_URLS[model_name]
+        logger.info(f"Downloading model '{model_name}' from {url}")
+        print(f"Downloading MicroLive model '{model_name}' (first time only)...")
+        
+        try:
+            download_url_to_file(url, str(cached_file), progress=True)
+        except (HTTPError, URLError) as e:
+            raise RuntimeError(
+                f"Failed to download model '{model_name}' from GitHub. "
+                f"Error: {e}\n\n"
+                f"If this persists, you can manually download from:\n"
+                f"  {url}\n"
+                f"And place it at:\n"
+                f"  {cached_file}"
+            )
+    else:
+        logger.debug(f"Model '{model_name}' already cached at {cached_file}")
+    
+    return str(cached_file)
+
+
+# =============================================================================
+# Convenience Functions for Specific Models
+# =============================================================================
+
+def get_frap_nuclei_model_path() -> str:
+    """
+    Get the path to the FRAP nuclei segmentation model.
+    
+    Downloads the model from GitHub if not already cached locally.
+    The model is stored in ~/.microlive/models/frap_nuclei
+    
+    Returns:
+        String path to the FRAP nuclei model file.
+        
+    Example:
+        >>> from microlive.utils.model_downloader import get_frap_nuclei_model_path
+        >>> model_path = get_frap_nuclei_model_path()
+        >>> # Use with Cellpose
+        >>> from cellpose import models
+        >>> model = models.CellposeModel(pretrained_model=model_path)
+    """
+    return cache_model("frap_nuclei")
+
+
+# =============================================================================
+# Verification and Diagnostics
+# =============================================================================
+
+def verify_model_integrity(model_name: str) -> bool:
+    """
+    Verify that a cached model file exists and has non-zero size.
+    
+    Args:
+        model_name: Name of the model to verify.
+        
+    Returns:
+        True if the model file exists and is valid.
+    """
+    model_path = get_model_path(model_name)
+    if not model_path.exists():
+        return False
+    
+    # Check file size (should be > 1MB for a real model)
+    size_bytes = model_path.stat().st_size
+    if size_bytes < 1_000_000:
+        logger.warning(f"Model file seems too small ({size_bytes} bytes): {model_path}")
+        return False
+    
+    return True
+
+
+def list_cached_models() -> dict:
+    """
+    List all cached models and their status.
+    
+    Returns:
+        Dictionary mapping model names to their cache status and size.
+    """
+    result = {}
+    for name in MODEL_URLS:
+        path = get_model_path(name)
+        if path.exists():
+            size_mb = path.stat().st_size / (1024 * 1024)
+            result[name] = {"cached": True, "size_mb": round(size_mb, 2), "path": str(path)}
+        else:
+            result[name] = {"cached": False, "size_mb": 0, "path": str(path)}
+    return result
+
+
+def clear_model_cache(model_name: str = None) -> None:
+    """
+    Clear cached models.
+    
+    Args:
+        model_name: Specific model to clear, or None to clear all.
+    """
+    if model_name:
+        path = get_model_path(model_name)
+        if path.exists():
+            path.unlink()
+            logger.info(f"Cleared cached model: {model_name}")
+    else:
+        if MODEL_DIR.exists():
+            shutil.rmtree(MODEL_DIR)
+            logger.info(f"Cleared all cached models from {MODEL_DIR}")

{microlive-1.0.13.dist-info → microlive-1.0.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microlive
-Version: 1.0.13
+Version: 1.0.14
 Summary: Live-cell microscopy image analysis and single-molecule measurements
 Project-URL: Homepage, https://github.com/ningzhaoAnschutz/microlive
 Project-URL: Documentation, https://github.com/ningzhaoAnschutz/microlive/blob/main/docs/user_guide.md

{microlive-1.0.13.dist-info → microlive-1.0.14.dist-info}/RECORD

@@ -1,26 +1,28 @@
-microlive/__init__.py,sha256=PweOZmjrtCXXOrqfbZrT3ZBcVXJJldq6e0izKw-RCVo,1385
+microlive/__init__.py,sha256=ZAui2VsXaQAYA4fnc1FhYO1v3lfGGEFrmTJyZeBAY9E,1385
 microlive/imports.py,sha256=VAAMavSLIKO0LooadTXfCdZiv8LQbV_wITeIv8IHwxM,7531
-microlive/microscopy.py,sha256=IjV3ASuCEukrrty_DtygdxaT_1fmMbsHqiFowtDA2zI,708797
+microlive/microscopy.py,sha256=97T9tEOVwBhEbAZujlDSeC3jt5xSQSCGJ8kboI6ucho,710732
 microlive/ml_spot_detection.py,sha256=pVbOSGNJ0WWMuPRML42rFwvjKVZ0B1fJux1179OIbAg,10603
 microlive/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 microlive/data/icons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 microlive/data/icons/icon_micro.png,sha256=b5tFv4E6vUmLwYmYeM4PJuxLV_XqEzN14ueolekTFW0,370236
 microlive/data/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+microlive/data/models/spot_detection_cnn.pth,sha256=Np7vpPJIbKQmuKY0Hx-4IkeEDsnks_QEgs7TqaYgZmI,8468580
 microlive/gui/__init__.py,sha256=tB-CdDC7x5OwYFAQxLOUvfVnUThaXKXVRsB68YP0Y6Q,28
 microlive/gui/app.py,sha256=GTl2Iwe5uG603Ja6ykwfSG2kB7YaZJYQukLpC0DOurw,787890
 microlive/gui/main.py,sha256=b66W_2V-pclGKOozfs75pwrCGbL_jkVU3kFt8RFMZIc,2520
 microlive/gui/micro_mac.command,sha256=TkxYOO_5A2AiNJMz3_--1geBYfl77THpOLFZnV4J2ac,444
 microlive/gui/micro_windows.bat,sha256=DJUKPhDbCO4HToLwSMT-QTYRe9Kr1wn5A2Ijy2klIrw,773
 microlive/pipelines/__init__.py,sha256=VimchYrIWalFs_edRmjR1zBHIg2CcpRceZoRmB1e8kA,764
-microlive/pipelines/pipeline_FRAP.py,sha256=GH5CqX6so1eWE07PXRCJZLAAqCzOqW-AoCqGXifapYE,56280
+microlive/pipelines/pipeline_FRAP.py,sha256=jBGzb7m3RzbuKtmD-KCrpSZCbypuLHeUacm88-XlUUU,62691
 microlive/pipelines/pipeline_folding_efficiency.py,sha256=0PTogfXHRtO2kXOeQXb5-VBb46DQsj6namGVEkMGI0g,22550
 microlive/pipelines/pipeline_particle_tracking.py,sha256=euPTLH6O9I66HkUb4Izah8ZF_aOdQLRyyR8vo1jSkFA,28245
 microlive/pipelines/pipeline_spot_detection_no_tracking.py,sha256=t-p1xCQvThnVKMJZgk3Xhk3k6cvp1VgwTJ0ZIbfzNG0,19087
-microlive/utils/__init__.py,sha256=5Ut2PeA0V5dM0VysmPpGH9OB-nmWDydzDkpRUwXfMHw,323
+microlive/utils/__init__.py,sha256=metAf2zPS8w23d8dyM7-ld1ovrOKBdx3y3zu5IVrzIg,564
 microlive/utils/device.py,sha256=tcPMU8UiXL-DuGwhudUgrbjW1lgIK_EUKIOeOn0U6q4,2533
+microlive/utils/model_downloader.py,sha256=EruviTEh75YBekpznn1RZ1Nj8lnDmeC4TKEnFLOow6Y,9448
 microlive/utils/resources.py,sha256=Jz7kPI75xMLCBJMyX7Y_3ixKi_UgydfQkF0BlFtLCKs,1753
-microlive-1.0.13.dist-info/METADATA,sha256=sgQ6afsn23JqQOZZLerdv4QItOPbkahw1Mj-SXbATDo,12434
-microlive-1.0.13.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-microlive-1.0.13.dist-info/entry_points.txt,sha256=Zqp2vixyD8lngcfEmOi8fkCj7vPhesz5xlGBI-EubRw,54
-microlive-1.0.13.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
-microlive-1.0.13.dist-info/RECORD,,
+microlive-1.0.14.dist-info/METADATA,sha256=mxn3h5atEOVG_u04F48N-H2ORlMJLC0c4aJQ9bGbB5c,12434
+microlive-1.0.14.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+microlive-1.0.14.dist-info/entry_points.txt,sha256=Zqp2vixyD8lngcfEmOi8fkCj7vPhesz5xlGBI-EubRw,54
+microlive-1.0.14.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+microlive-1.0.14.dist-info/RECORD,,