octopi 1.4.0__py3-none-any.whl

octopi/processing/evaluate.py

@@ -0,0 +1,302 @@
+from copick_utils.io import readers
+from scipy.spatial import distance
+import copick, json, os, yaml   
+from typing import List
+import numpy as np
+
+class evaluator:
+
+    def __init__(self, 
+                 copick_config: str,
+                 ground_truth_user_id: str,
+                 ground_truth_session_id: str,
+                 prediction_user_id: str,
+                 predict_session_id: str,
+                 voxel_size: float = 10,
+                 beta: float = 4,
+                 object_names: List[str] = None):
+        
+        self.root = copick.from_file(copick_config)
+        print('Running Evaluation on the Following Copick Project: ', copick_config)
+
+        self.ground_truth_user_id = ground_truth_user_id
+        self.ground_truth_session_id = ground_truth_session_id
+        self.prediction_user_id = prediction_user_id
+        self.predict_session_id = predict_session_id
+        self.voxel_size = voxel_size
+        self.beta = beta
+        print(f'\nGround Truth Query: \nUserID: {ground_truth_user_id}, SessionID: {ground_truth_session_id}')
+        print(f'\nSubmitted Picks: \nUserID: {prediction_user_id}, SessionID: {predict_session_id}\n')
+
+        # Save input parameters
+        self.input_params = {
+            "copick_config": copick_config,
+            "ground_truth_user_id": ground_truth_user_id,
+            "ground_truth_session_id": ground_truth_session_id,
+            "prediction_user_id": prediction_user_id,
+            "predict_session_id": predict_session_id,
+        }
+
+        # Get objects that can be Picked
+        if not object_names:
+            print('No object names provided, using all pickable objects')
+            self.objects = [(obj.name, obj.radius) for obj in self.root.pickable_objects if obj.is_particle]
+        else:
+            # Get valid pickable objects with their radii
+            valid_objects = {obj.name: obj.radius for obj in self.root.pickable_objects if obj.is_particle}
+            
+            # Filter and validate provided object names
+            invalid_objects = [name for name in object_names if name not in valid_objects]
+            if invalid_objects:
+                print('WARNING: The following object names are not valid pickable objects:', invalid_objects)
+                print('Valid objects are:', list(valid_objects.keys()))
+            
+            self.objects = [(name, valid_objects[name]) for name in object_names if name in valid_objects]
+            
+            if not self.objects:
+                raise ValueError("None of the provided object names are valid pickable objects")
+                
+        print('Using the following valid objects:', [name for name, _ in self.objects])
+
+        # Define object-specific weights
+        self.weights = {
+            "apo-ferritin": 1,
+            "beta-amylase": 0,  # Excluded from scoring
+            "beta-galactosidase": 2,
+            "ribosome": 1,
+            "thyroglobulin": 2,
+            "virus-like particle": 1,
+        }
+
+    def run(self, 
+            save_path: str = None,
+            distance_threshold_scale: float = 0.8,
+            runIDs: List[str] = None):
+    
+        # Type check for runIDs
+        if runIDs is not None and not (isinstance(runIDs, list) and all(isinstance(x, str) for x in runIDs)):
+            raise TypeError("runIDs must be a list of strings")
+
+        run_ids = runIDs if runIDs else [run.name for run in self.root.runs]
+        print('\nRunning Metrics Evaluation on the Following RunIDs: ', run_ids)
+
+        metrics = {}
+        summary_metrics = {name: {'precision': [], 'recall': [], 'f1_score': [], 'fbeta_score': [], 'accuracy': [], 
+                                'true_positives': [], 'false_positives': [], 'false_negatives': []} for name, _ in self.objects}
+        
+        # For storing the aggregated counts per particle type (across all runs)
+        aggregated_counts = {name: {'total_tp': 0, 'total_fp': 0, 'total_fn': 0} for name, _ in self.objects}
+
+        for runID in run_ids:
+            # Initialize the nested dictionary for this runID
+            metrics[runID] = {}
+            run = self.root.get_run(runID)
+
+            for name, radius in self.objects:
+                
+                # Get Ground Truth and Predicted Coordinates
+                gt_coordinates = readers.coordinates(
+                    run, name, 
+                    self.ground_truth_user_id, self.ground_truth_session_id, 
+                    self.voxel_size, raise_error=False
+                )
+                pred_coordinates = readers.coordinates(
+                    run, name,
+                    self.prediction_user_id, self.predict_session_id, 
+                    self.voxel_size, raise_error=False
+                )
+                
+                # If no reference (GT) points, all candidate points are false positives
+                if gt_coordinates is None or len(gt_coordinates) == 0:
+                    num_pred_points = pred_coordinates.shape[0] if pred_coordinates is not None else 0
+                    metrics[runID][name] = {'precision': 0, 'recall': 0, 'fbeta_score': 0, 'true_positives': 0, 'false_positives': num_pred_points, 'false_negatives': 0}
+                    
+                    # Update aggregated counts
+                    aggregated_counts[name]['total_fp'] += num_pred_points
+                    
+                    continue
+
+                # If no candidate (predicted) points, all reference points are false negatives
+                if pred_coordinates is None or len(pred_coordinates) == 0:
+                    num_gt_points = gt_coordinates.shape[0] if gt_coordinates is not None else 0
+                    metrics[runID][name] = {'precision': 0, 'recall': 0, 'fbeta_score': 0, 'true_positives': 0, 'false_positives': 0, 'false_negatives': num_gt_points}
+                    
+                    # Update aggregated counts
+                    aggregated_counts[name]['total_fn'] += num_gt_points
+                    
+                    continue
+
+                # Compute Distance Threshold Based on Particle Radius
+                distance_threshold = (radius/self.voxel_size) * distance_threshold_scale
+                metrics[runID][name] = self.compute_metrics(gt_coordinates, pred_coordinates, distance_threshold)         
+
+                # Collect metrics for summary statistics
+                for key in summary_metrics[name]:
+                    summary_metrics[name][key].append(metrics[runID][name][key])
+                
+                # Update aggregated counts
+                aggregated_counts[name]['total_tp'] += metrics[runID][name]['true_positives']
+                aggregated_counts[name]['total_fp'] += metrics[runID][name]['false_positives']
+                aggregated_counts[name]['total_fn'] += metrics[runID][name]['false_negatives']
+
+        # Create a new dictionary for summarized metrics
+        final_summary_metrics = {}
+
+        # Compute average metrics and standard deviations across runs for each object
+        for name, _ in self.objects:
+            # Initialize the final summary for the object
+            final_summary_metrics[name] = {}
+
+            for key in summary_metrics[name]:
+                mu_val = float(np.mean(summary_metrics[name][key]))
+                std_val = float(np.std(summary_metrics[name][key]))
+
+                # Populate the new dictionary with structured data
+                final_summary_metrics[name][key] = {
+                    'mean': mu_val,
+                    'std': std_val
+                }
+
+        print('\nAverage Metrics Summary:')
+        self.print_metrics_summary(final_summary_metrics)          
+        
+        # Compute Final Kaggle Submission Score using reference approach
+        aggregate_fbeta = 0.0
+        total_weight = 0.0
+        
+        print('\nCalculating Final F-beta Score using per-particle approach:')
+        for name, counts in aggregated_counts.items():
+            tp = counts['total_tp']
+            fp = counts['total_fp']
+            fn = counts['total_fn']
+            
+            # Calculate precision and recall for this particle type
+            precision = tp / (tp + fp) if (tp + fp) > 0 else 0
+            recall = tp / (tp + fn) if (tp + fn) > 0 else 0
+            
+            # Calculate F-beta for this particle type
+            particle_fbeta = (1 + self.beta**2) * (precision * recall) / \
+                            ((self.beta**2 * precision) + recall) if \
+                            ((self.beta**2 * precision) + recall) > 0 else 0
+            
+            # Get the weight for this particle type
+            weight = self.weights.get(name, 1)
+            
+            # Accumulate weighted F-beta score
+            aggregate_fbeta += particle_fbeta * weight
+            total_weight += weight
+            
+            print(f"  {name}: TP={tp}, FP={fp}, FN={fn}, Precision={precision:.3f}, " + 
+                f"Recall={recall:.3f}, F-beta={particle_fbeta:.3f}, Weight={weight}")
+        
+        # Normalize by total weight
+        final_fbeta = aggregate_fbeta / total_weight if total_weight > 0 else 0
+        
+        print(f'\nFinal Kaggle Submission Score: {final_fbeta:.3f}')   
+
+        # Save average and detailed metrics with parameters included        
+        if save_path:
+            self.parameters = {
+                "distance_threshold_scale": distance_threshold_scale,
+                "runIDs": runIDs,
+            }    
+            
+            os.makedirs(save_path, exist_ok=True)
+            summary_metrics = { "input": self.input_params, 
+                                "final_fbeta_score": final_fbeta,  
+                                "aggregated_particle_scores": {    # Optionally add per-particle details
+                                    name: {
+                                        "tp": counts['total_tp'],
+                                        "fp": counts['total_fp'], 
+                                        "fn": counts['total_fn'],
+                                        "weight": self.weights.get(name, 1)
+                                    } for name, counts in aggregated_counts.items()
+                                },
+                                "summary_metrics": final_summary_metrics, 
+                                "parameters": self.parameters,  }
+
+            # Save average metrics to YAML file
+            with open(os.path.join(save_path, 'average_metrics.yaml'), 'w') as f:
+                yaml.dump(summary_metrics, f, indent=4, default_flow_style=False, sort_keys=False)
+            print(f'\nAverage Metrics saved to {os.path.join(save_path, "average_metrics.yaml")}')
+            
+            detailed_metrics = { "input": self.input_params,  
+                                  "metrics": metrics,
+                                 "parameters": self.parameters, }
+            with open(os.path.join(save_path, 'metrics.json'), 'w') as f:
+                json.dump(detailed_metrics, f, indent=4)
+            print(f'Metrics saved to {os.path.join(save_path, "metrics.json")}')
+
+    def compute_metrics(self, 
+                        gt_points, 
+                        pred_points, 
+                        threshold):
+        
+        gt_points = np.array(gt_points)
+        pred_points = np.array(pred_points)
+        
+        # Calculate distances
+        if gt_points.shape[0] == 0:
+            # No ground truth points: all predictions are false positives
+            fp = pred_points.shape[0]
+            fn = 0
+            tp = 0
+        elif pred_points.shape[0] == 0:
+            # No predictions: all ground truth points are false negatives
+            fp = 0
+            fn = gt_points.shape[0]
+            tp = 0
+        else:    
+            # Calculate distances
+            dist_matrix = distance.cdist(pred_points, gt_points, 'euclidean')
+
+            # Determine matches within the threshold
+            tp = np.sum(np.min(dist_matrix, axis=1) < threshold)
+            fp = np.sum(np.min(dist_matrix, axis=1) >= threshold)
+            fn = np.sum(np.min(dist_matrix, axis=0) >= threshold)
+        
+        # Precision, Recall, F1 Score
+        precision = tp / (tp + fp) if tp + fp > 0 else 0
+        recall = tp / (tp + fn) if tp + fn > 0 else 0
+        f1_score = 2 * (precision * recall) / (precision + recall) if precision + recall > 0 else 0
+        accuracy = tp / (tp + fp + fn)  # Note: TN not considered here
+
+         # Compute F_beta using the formula
+        if (self.beta**2 * precision + recall) > 0:
+            fbeta = (1 + self.beta**2) * (precision * recall) / (self.beta**2 * precision + recall)
+        else:
+            fbeta = 0
+        
+        return {
+            'precision': precision,
+            'recall': recall,
+            'f1_score': f1_score,
+            'fbeta_score': fbeta,
+            'accuracy': accuracy, 
+            'true_positives': int(tp),
+            'false_positives': int(fp),
+            'false_negatives': int(fn)
+        }
+    
+    def print_metrics_summary(self, metrics_dict):
+        for name, metrics in metrics_dict.items():
+            recall = metrics['recall']
+            precision = metrics['precision']
+            f1_score = metrics['f1_score']
+            fbeta_score = metrics['fbeta_score']
+            false_positives = metrics['false_positives']
+            false_negatives = metrics['false_negatives']
+            
+            # Format the metrics for the current object
+            formatted_metrics = (
+                f"Recall: {recall['mean']:.3f} ± {recall['std']:.3f}, "
+                f"Precision: {precision['mean']:.3f} ± {precision['std']:.3f}, "
+                f"F1 Score: {f1_score['mean']:.3f} ± {f1_score['std']:.3f}, "
+                f"F_beta Score: {fbeta_score['mean']:.3f} ± {fbeta_score['std']:.3f}, "
+                f"False_Positives: {false_positives['mean']:.1f} ± {false_positives['std']:.1f}, "
+                f"False_Negatives: {false_negatives['mean']:.1f} ± {false_negatives['std']:.1f}"
+            )
+            
+            # Print the object name and its metrics
+            print(f"{name}: [{formatted_metrics}]")
+        print()

octopi/processing/importers.py

@@ -0,0 +1,116 @@
+import rich_click as click
+
+def import_tomos(
+    config, 
+    path,
+    tomo_alg,
+    ivs = 10,
+    ovs = None):
+    """
+    Import MRC tomograms from a folder into a copick project.
+    
+    Args:
+        config (str): Path to the copick configuration file
+        path (str): Path to the folder containing the tomograms
+        tomo_alg (str): Local tomogram type name to save in your Copick project
+        ivs (float): Original voxel size of the tomograms
+        ovs (float): Desired output voxel size for downsampling (optional)
+    """
+    from octopi.utils.progress import _progress, print_summary
+    from octopi.processing.downsample import FourierRescale
+    from copick_utils.io import writers
+    import copick, os, glob, mrcfile
+
+    # Either load the config file or create a new project
+    if os.path.isfile(config):
+        root = copick.from_file(config)
+    else:
+        raise ValueError('Config file does not exist')
+
+    # If we want to save the tomograms at a different voxel size, we need to rescale the tomograms
+    if ovs is not None and ovs > ivs:
+        rescale = FourierRescale(ivs, ovs)
+    else:
+        rescale = None
+
+    # Print Parameter Summary
+    print_summary(
+        "Import Tomograms",
+        path=path, tomo_alg=tomo_alg,
+        config=config, ivs=ivs, ovs=ovs,
+    )
+    
+    # Get the list of tomograms in the folder
+    tomograms = glob.glob(os.path.join(path, '*.mrc'))
+
+    # Check if no tomograms were found
+    if len(tomograms) == 0:
+        raise ValueError('No tomograms found in the folder')
+
+    # Main Loop
+    for tomogram in _progress(tomograms):
+
+        # Read the tomogram and the associated runID
+        with mrcfile.open(tomogram) as mrc:
+            vol = mrc.data.copy()
+            vs = float(mrc.voxel_size.x) # Assuming cubic voxels
+        
+        # Check if the voxel size in the tomogram matches the provided input voxel size
+        if vs != ivs and rescale is not None:
+            print('[WARNING] Voxel size in tomogram does not match the provided input voxel size. Using voxel size from tomogram for downsampling.')
+            ivs = vs  # Override voxel size if it doesn't match the expected input voxel size
+            rescale = FourierRescale(vs, ovs)
+        # Assume that if a voxel size is 1, the MRC didnt' have a voxel size set
+        elif vs != 1 and vs != ivs: 
+            ivs = vs
+
+        # If we want to save the tomograms at a different voxel size, 
+        # we need to rescale the tomograms
+        if ovs is not None:
+            vol = rescale.run(vol)
+
+        # Get the runID from the tomogram name
+        runID = tomogram.split('/')[-1].split('.')[0]
+
+        # Get the run from the project, create new run if it doesn't exist
+        run = root.get_run(runID)
+        if run is None:
+            run = root.new_run(runID)
+
+        # Add the tomogram to the project
+        writers.tomogram(run, vol, ovs if ovs is not None else ivs, tomo_alg)
+    
+    print(f'✅ Import Complete! Imported {len(tomograms)} tomograms')
+
+
+@click.command('import')
+# Input Arguments
+@click.option('-p', '--path', type=click.Path(exists=True), default=None, required=True,
+              help="Path to the folder containing the tomograms")
+@click.option('-c', '--config', type=click.Path(exists=True), default=None,
+              help="Path to the copick configuration file (alternative to datasetID)")
+# Tomogram Settings
+@click.option('-alg', '--tomo-alg', type=str, default='denoised',
+              help="Local tomogram type name to save in your Copick project.")
+# Voxel Settings
+@click.option('-ovs', '--output-voxel-size', type=float, default=None,
+              help="Desired output voxel size for downsampling (optional)")
+@click.option('-ivs', '--input-voxel-size', type=float, default=10,
+              help="Original voxel size of the tomograms")
+def cli(config, tomo_alg,
+        input_voxel_size, output_voxel_size, path):
+    """
+    Import MRC tomograms from a folder into a copick project.
+    
+    This command imports MRC tomograms from a folder into a copick project.
+    
+    Example Usage:
+    
+    octopi import -c config.json -p /path/to/tomograms -alg denoised -ivs 5 -ovs 10 (downsample to 10Å)
+    
+    octopi import -c config.json -p /path/to/tomograms -alg denoised -ovs 10 (will read the voxel size from the tomograms)
+    """
+
+    print(f'🚀 Starting Tomogram Import...')
+    import_tomos(config=config, path=path, tomo_alg=tomo_alg, ivs=input_voxel_size, ovs=output_voxel_size)
+

octopi/processing/segmentation_from_picks.py

@@ -0,0 +1,167 @@
+# This code is adapted from the copick-utils project,
+# originally available at: https://github.com/copick/copick-utils/blob/main/src/copick_utils/segmentation/segmentation_from_picks.py
+# Licensed under the MIT License.
+
+# Copyright (c) 2023 The copick-utils authors
+
+import numpy as np
+import zarr
+from scipy.ndimage import zoom
+import copick
+
+def from_picks(pick,
+               seg_volume,
+               radius: float = 10.0,
+               label_value: int = 1,
+               voxel_spacing: float = 10):
+    """
+    Paints picks into a segmentation volume as spheres.
+
+    Parameters:
+    -----------
+    pick : copick.models.CopickPicks
+        Copick object containing `points`, where each point has a `location` attribute with `x`, `y`, `z` coordinates.
+    seg_volume : numpy.ndarray
+        3D segmentation volume (numpy array) where the spheres are painted. Shape should be (Z, Y, X).
+    radius : float, optional
+        The radius of the spheres to be inserted in physical units (not voxel units). Default is 10.0.
+    label_value : int, optional
+        The integer value used to label the sphere regions in the segmentation volume. Default is 1.
+    voxel_spacing : float, optional
+        The spacing of voxels in the segmentation volume, used to scale the radius of the spheres. Default is 10.
+    Returns:
+    --------
+    numpy.ndarray
+        The modified segmentation volume with spheres inserted at pick locations.    
+    """
+    def create_sphere(shape, center, radius, val):
+        zc, yc, xc = center
+        z, y, x = np.indices(shape)
+        distance_sq = (x - xc)**2 + (y - yc)**2 + (z - zc)**2
+        sphere = np.zeros(shape, dtype=np.float32)
+        sphere[distance_sq <= radius**2] = val
+        return sphere
+
+    def get_relative_target_coordinates(center, delta, shape):
+        low = max(int(np.floor(center - delta)), 0)
+        high = min(int(np.ceil(center + delta + 1)), shape)
+        return low, high
+
+    # Adjust radius for voxel spacing
+    radius_voxel = max(radius / voxel_spacing, 1)
+    delta = int(np.ceil(radius_voxel))
+
+    # Paint each pick as a sphere
+    for point in pick.points:
+        # Convert the pick's location from angstroms to voxel units
+        cx, cy, cz = point.location.x / voxel_spacing, point.location.y / voxel_spacing, point.location.z / voxel_spacing
+
+        # Calculate subarray bounds
+        xLow, xHigh = get_relative_target_coordinates(cx, delta, seg_volume.shape[2])
+        yLow, yHigh = get_relative_target_coordinates(cy, delta, seg_volume.shape[1])
+        zLow, zHigh = get_relative_target_coordinates(cz, delta, seg_volume.shape[0])
+
+        # Subarray shape
+        subarray_shape = (zHigh - zLow, yHigh - yLow, xHigh - xLow)
+        if any(dim <= 0 for dim in subarray_shape):
+            continue
+
+        # Compute the local center of the sphere within the subarray
+        local_center = (cz - zLow, cy - yLow, cx - xLow)
+        sphere = create_sphere(subarray_shape, local_center, radius_voxel, label_value)
+
+        # Assign Sphere to Segmentation Target Volume
+        seg_volume[zLow:zHigh, yLow:yHigh, xLow:xHigh] = np.maximum(seg_volume[zLow:zHigh, yLow:yHigh, xLow:xHigh], sphere)
+
+    return seg_volume
+
+
+def downsample_to_exact_shape(array, target_shape):
+    """
+    Downsamples a 3D array to match the target shape using nearest-neighbor interpolation.
+    Ensures that the resulting array has the exact target shape.
+    """
+    zoom_factors = [t / s for t, s in zip(target_shape, array.shape)]
+    return zoom(array, zoom_factors, order=0)
+
+
+def segmentation_from_picks(radius, painting_segmentation_name, run, voxel_spacing, tomo_type, pickable_object, pick_set, user_id="paintedPicks", session_id="0"):
+    """
+    Paints picks from a run into a multiscale segmentation array, representing them as spheres in 3D space.
+
+    Parameters:
+    -----------
+    radius : float
+        Radius of the spheres in physical units.
+    painting_segmentation_name : str
+        The name of the segmentation dataset to be created or modified.
+    run : copick.Run
+        The current Copick run object.
+    voxel_spacing : float
+        The spacing of the voxels in the tomogram data.
+    tomo_type : str
+        The type of tomogram to retrieve.
+    pickable_object : copick.models.CopickObject
+        The object that defines the label value to be used in segmentation.
+    pick_set : copick.models.CopickPicks
+        The set of picks containing the locations to paint spheres.
+    user_id : str, optional
+        The ID of the user creating the segmentation. Default is "paintedPicks".
+    session_id : str, optional
+        The session ID for this segmentation. Default is "0".
+
+    Returns:
+    --------
+    copick.Segmentation
+        The created or modified segmentation object.
+    """
+    # Fetch the tomogram and determine its multiscale structure
+    tomogram = run.get_voxel_spacing(voxel_spacing).get_tomogram(tomo_type)
+    if not tomogram:
+        raise ValueError("Tomogram not found for the given parameters.")
+
+    # Use copick to create a new segmentation if one does not exist
+    segs = run.get_segmentations(user_id=user_id, session_id=session_id, is_multilabel=True, name=painting_segmentation_name, voxel_size=voxel_spacing)
+    if len(segs) == 0:
+        seg = run.new_segmentation(voxel_spacing, painting_segmentation_name, session_id, True, user_id=user_id)
+    else:
+        seg = segs[0]
+
+    segmentation_group = zarr.open(seg.zarr(), mode="a")
+    highest_res_name = "0"
+
+    # Get the highest resolution dimensions and create a new array if necessary
+    tomogram_zarr = zarr.open(tomogram.zarr(), "r")
+
+    highest_res_shape = tomogram_zarr[highest_res_name].shape
+    if highest_res_name not in segmentation_group:
+        segmentation_group.create(highest_res_name, shape=highest_res_shape, dtype=np.uint16, overwrite=True)
+
+    # Initialize or load the highest resolution array
+    highest_res_seg = segmentation_group[highest_res_name][:]
+    highest_res_seg.fill(0)
+
+    # Paint picks into the highest resolution array
+    highest_res_seg = from_picks(pick_set, highest_res_seg, radius, pickable_object.label, voxel_spacing)
+
+    # Write back the highest resolution data
+    segmentation_group[highest_res_name][:] = highest_res_seg
+
+    # Downsample to create lower resolution scales
+    multiscale_metadata = tomogram_zarr.attrs.get('multiscales', [{}])[0].get('datasets', [])
+    for level_index, level_metadata in enumerate(multiscale_metadata):
+        if level_index == 0:
+            continue
+
+        level_name = level_metadata.get("path", str(level_index))
+        expected_shape = tuple(tomogram_zarr[level_name].shape)
+
+        # Compute scaling factors relative to the highest resolution shape
+        scaled_array = downsample_to_exact_shape(highest_res_seg, expected_shape)
+
+        # Create/overwrite the Zarr array for this level
+        segmentation_group.create_dataset(level_name, shape=expected_shape, data=scaled_array, dtype=np.uint16, overwrite=True)
+
+        segmentation_group[level_name][:] = scaled_array
+
+    return seg