octopi 1.4.0__py3-none-any.whl

octopi/entry_points/run_evaluate.py

@@ -0,0 +1,99 @@
+from octopi.utils import parsers
+from octopi import cli_context
+import rich_click as click
+from typing import List
+
+def my_evaluator(
+    copick_config_path: str,
+    ground_truth_user_id: str,
+    ground_truth_session_id: str,
+    predict_user_id: str,
+    predict_session_id: str,
+    save_path: str,
+    distance_threshold_scale: float,
+    object_names: List[str] = None,
+    runIDs: List[str] = None
+    ):
+    import octopi.processing.evaluate as evaluate
+
+    eval = evaluate.evaluator(
+        copick_config_path,
+        ground_truth_user_id,
+        ground_truth_session_id,
+        predict_user_id,
+        predict_session_id, 
+        object_names=object_names
+    )
+
+    eval.run(save_path=save_path, distance_threshold_scale=distance_threshold_scale, runIDs=runIDs)
+
+
+@click.command('evaluate', context_settings=cli_context)
+# Output Arguments
+@click.option('-o','--output', type=click.Path(), default='scores',
+              help="Path to save evaluation results")
+# Evaluation Parameters
+@click.option('-names','--object-names', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_list(value) if value else None,
+              help="Optional list of object names to evaluate, e.g., ribosome,apoferritin")
+@click.option('-dts','--distance-threshold-scale', type=float, default=0.8,
+              help="Compute Distance Threshold Based on Particle Radius")
+# Input Arguments
+@click.option('--run-ids', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_list(value) if value else None,
+              help="Optional list of run IDs to evaluate, e.g., run1,run2,run3 or [run1,run2,run3]")
+@click.option('-psid', '--predict-session-id', type=str,
+              default='1', help="Session ID for prediction data")
+@click.option('-puid','--predict-user-id', type=str, required=True,
+              default='octopi', help="User ID for prediction data")
+@click.option('-gtsid','--ground-truth-session-id', type=str, default=None,
+              help="Session ID for ground truth data")
+@click.option('-gtuid','--ground-truth-user-id', type=str, required=True,
+              help="User ID for ground truth data")
+@click.option('-c', '--config', type=click.Path(exists=True), required=True,
+              help="Path to the copick configuration file")
+def cli(config, ground_truth_user_id, ground_truth_session_id,
+        predict_user_id, predict_session_id, run_ids,
+        distance_threshold_scale, object_names,
+        output):
+    """
+    Evaluate particle localization performance against ground truth annotations.
+    
+    This command compares predicted particle picks against expert annotations using distance-based 
+    matching. A prediction is considered correct (true positive) if it falls within a specified 
+    distance threshold of a ground truth annotation. The threshold is defined as a fraction of 
+    the particle's radius (default: 0.8 = 80% of radius).
+    
+    Computed metrics include:
+      • Precision: Fraction of predictions that match ground truth
+      • Recall: Fraction of ground truth particles that were detected
+      • F-beta scores: Harmonic mean of precision and recall (with configurable beta)
+    
+    Results are saved as a YAML file containing per-object and aggregate statistics, making it 
+    easy to track model performance across experiments and compare different localization methods.
+    
+    \b
+    Examples:
+      # Evaluate predictions against Data Portal annotations
+      octopi evaluate -c config.json \\
+        -gtuid data-portal -gtsid 0 \\
+        -puid octopi -psid 1 \\
+        -o evaluation_results.yaml
+    """
+
+    # Call the evaluate function with parsed arguments
+    my_evaluator(
+        copick_config_path=config,
+        ground_truth_user_id=ground_truth_user_id,
+        ground_truth_session_id=ground_truth_session_id,
+        predict_user_id=predict_user_id,
+        predict_session_id=predict_session_id,
+        save_path=output,
+        distance_threshold_scale=distance_threshold_scale,
+        object_names=object_names,
+        runIDs=run_ids
+    )
+
+
+if __name__ == "__main__":
+    cli()

octopi/entry_points/run_extract_mb_picks.py

@@ -0,0 +1,191 @@
+from typing import List, Tuple, Optional
+from octopi.utils import parsers
+import rich_click as click
+
+def extract_membrane_bound_picks(
+    config: str,
+    voxel_size: float,
+    distance_threshold: float,
+    picks_info: Tuple[str, str, str],
+    organelle_info: Tuple[str, str, str],
+    membrane_info: Tuple[str, str, str],
+    save_user_id: str,
+    save_session_id: str,
+    runIDs: List[str],
+    n_procs: int = None
+    ):  
+    from octopi.extract import membranebound_extract as extract
+    import multiprocess as mp
+    from tqdm import tqdm
+    import copick
+
+    # Load Copick Project for Writing 
+    root = copick.from_file(config) 
+    
+    # Either Specify Input RunIDs or Run on All RunIDs
+    if runIDs:  print('Extracting Membrane Bound Proteins on the Following RunIDs: ', runIDs)
+    run_ids = runIDs if runIDs else [run.name for run in root.runs]
+    n_run_ids = len(run_ids)    
+
+    # Determine the number of processes to use
+    if n_procs is None:
+        n_procs = min(mp.cpu_count(), n_run_ids)
+    print(f"Using {n_procs} processes to parallelize across {n_run_ids} run IDs.")   
+    
+    # Run Membrane-Protein Isolation - Main Parallelization Loop
+    with mp.Pool(processes=n_procs) as pool:
+        with tqdm(total=n_run_ids, desc="Membrane-Protein Isolation", unit="run") as pbar:
+            worker_func = lambda run_id: extract.process_membrane_bound_extract(
+                root.get_run(run_id),  
+                voxel_size, 
+                picks_info, 
+                membrane_info,
+                organelle_info,
+                save_user_id, 
+                save_session_id,
+                distance_threshold
+            )
+
+            for _ in pool.imap_unordered(worker_func, run_ids, chunksize=1):
+                pbar.update(1)
+
+    print('Extraction of Membrane-Bound Proteins Complete!')
+
+
+def save_parameters(config: str,
+                    voxel_size: float,
+                    picks_info: tuple,
+                    membrane_info: tuple,
+                    organelle_info: tuple,
+                    save_user_id: str,
+                    save_session_id: str,
+                    distance_threshold: float,
+                    runIDs: list,
+                    output_path: str):
+    import octopi.utils.io as io
+    import pprint
+
+    params_dict = {
+        "input": {
+            "config": config,
+            "voxel_size": voxel_size,
+            "picks_info": picks_info,
+            "membrane_info": membrane_info,
+            "organelle_info": organelle_info
+        },
+        "output": {
+            "save_user_id": save_user_id,
+            "save_session_id": save_session_id
+        },
+        "parameters": {
+            "distance_threshold": distance_threshold,
+            "runIDs": runIDs
+        }
+    }
+
+    # Print the parameters
+    print(f"\nParameters for Extraction of Membrane-Bound Picks:")
+    pprint.pprint(params_dict); print()
+
+    # Save parameters to YAML file
+    io.save_parameters_yaml(params_dict, output_path)
+
+
+@click.command('membrane-extract')
+# Output Arguments
+@click.option('--save-session-id', type=str, required=True,
+              help="Session ID to save the new picks")
+@click.option('--save-user-id', type=str, default=None,
+              help="User ID to save the new picks (defaults to picks user ID)")
+# Parameters
+@click.option('--n-procs', type=int, default=None,
+              help="Number of processes to use (defaults to CPU count)")
+@click.option('--distance-threshold', type=float, default=10,
+              help="Distance threshold for membrane proximity")
+# Input Arguments
+@click.option('--runIDs', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_list(value) if value else None,
+              help="List of run IDs to process")
+@click.option('--organelle-info', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_target(value) if value else None,
+              help='Query for the organelles segmentations (e.g., "name" or "name,user_id,session_id")')
+@click.option('--membrane-info', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_target(value) if value else None,
+              help='Query for the membrane segmentation (e.g., "name" or "name,user_id,session_id")')
+@click.option('--picks-info', type=str, required=True,
+              callback=lambda ctx, param, value: parsers.parse_target(value),
+              help='Query for the picks (e.g., "name" or "name,user_id,session_id")')
+@click.option('-vs', '--voxel-size', type=float, default=10,
+              help="Voxel size")
+@click.option('-c', '--config', type=click.Path(exists=True), required=True,
+              help="Path to the configuration file")
+def cli(config, voxel_size, picks_info, membrane_info, organelle_info, runIDs,
+        distance_threshold, n_procs,
+        save_user_id, save_session_id):
+    """
+    Extract membrane-bound picks based on proximity to organelle or membrane segmentation.
+    
+    This command isolates membrane-bound proteins from segmented volumes by finding 
+    particles that are within a specified distance threshold of the membrane segmentation. 
+    The resulting picks are saved as zarr arrays in your copick project, organized by 
+    segmentation name, user ID, and session ID for easy tracking and comparison.
+    
+    \b
+    Examples:
+      # Extract membrane-bound picks with default distance threshold
+      octopi membrane-extract -c config.json \\
+        --picks-info predictions,octopi,1 \\
+        --membrane-info membrane,octopi,1 \\
+        --organelle-info organelle,octopi,1 \\
+        --save-user-id octopi \\
+        --save-session-id 1
+    """
+
+    run_mb_extract(
+        config, voxel_size,
+        picks_info, membrane_info, organelle_info,
+        runIDs, distance_threshold, n_procs,
+        save_user_id, save_session_id
+    )
+
+
+def run_mb_extract(
+    config, voxel_size, picks_info, membrane_info, 
+    organelle_info, runIDs, distance_threshold, n_procs,
+    save_user_id, save_session_id):
+    
+    # Default save_user_id to picks_info user_id if not specified
+    if save_user_id is None: 
+        save_user_id = picks_info[1]
+
+    # Save parameters
+    output_yaml = f'membrane-extract_{save_user_id}_{save_session_id}.yaml'
+    save_parameters(
+        config=config,
+        voxel_size=voxel_size,
+        picks_info=picks_info,
+        membrane_info=membrane_info,
+        organelle_info=organelle_info,
+        save_user_id=save_user_id,
+        save_session_id=save_session_id,
+        distance_threshold=distance_threshold,
+        runIDs=runIDs,
+        output_path=output_yaml
+    )
+
+    extract_membrane_bound_picks(
+        config=config,
+        voxel_size=voxel_size,
+        distance_threshold=distance_threshold,
+        picks_info=picks_info,
+        membrane_info=membrane_info,
+        organelle_info=organelle_info,
+        save_user_id=save_user_id,
+        save_session_id=save_session_id,
+        runIDs=runIDs,
+        n_procs=n_procs,
+    )
+
+
+if __name__ == "__main__":
+    cli()

octopi/entry_points/run_extract_midpoint.py

@@ -0,0 +1,143 @@
+from octopi.extract import midpoint_extract
+from typing import List, Tuple, Optional
+import argparse, pprint, copick
+from octopi import utils
+import multiprocess as mp
+from tqdm import tqdm
+
+def extract_midpoint(
+    config: str,
+    voxel_size: float,
+    picks_info: Tuple[str, str, str],
+    organelle_info: Tuple[str, str, str],
+    distance_min: float,
+    distance_max: float,
+    distance_threshold: float,
+    save_session_id: str,
+    runIDs: List[str],
+    n_procs: int = None
+    ):  
+
+    # Load Copick Project for Writing 
+    root = copick.from_file( config ) 
+    
+    # Either Specify Input RunIDs or Run on All RunIDs
+    if runIDs:  print('Extracting Midpoints on the Following RunIDs: ', runIDs)
+    run_ids = runIDs if runIDs else [run.name for run in root.runs]
+    n_run_ids = len(run_ids)   
+
+    # Determine the number of processes to use
+    if n_procs is None:
+        n_procs = min(mp.cpu_count(), n_run_ids)
+    print(f"Using {n_procs} processes to parallelize across {n_run_ids} run IDs.")   
+
+    # Initialize tqdm progress bar
+    with tqdm(total=n_run_ids, desc="Mid-Point SuperComplex Extraction", unit="run") as pbar:
+        for _iz in range(0, n_run_ids, n_procs):
+
+            start_idx = _iz
+            end_idx = min(_iz + n_procs, n_run_ids)  # Ensure end_idx does not exceed n_run_ids
+            print(f"\nProcessing runIDs from {start_idx} -> {end_idx } (out of {n_run_ids})")
+
+            processes = []                
+            for _in in range(n_procs):
+                _iz_this = _iz + _in
+                if _iz_this >= n_run_ids:
+                    break
+                run_id = run_ids[_iz_this]
+                run = root.get_run(run_id)
+                p = mp.Process(
+                    target=midpoint_extract.process_midpoint_extract,
+                    args=(run,  
+                          voxel_size, 
+                          picks_info, 
+                          organelle_info,
+                          distance_min,
+                          distance_max,
+                          distance_threshold,
+                          save_session_id)
+                )
+                processes.append(p)
+
+            for p in processes:
+                p.start()
+
+            for p in processes:
+                p.join()
+
+            for p in processes:
+                p.close()
+
+            # Update tqdm progress bar
+            pbar.update(len(processes))
+
+    print('Extraction of Midpoints Complete!')        
+
+def cli():
+    parser = argparse.ArgumentParser(
+        description='Extract membrane-bound picks based on proximity to segmentation.',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument('--config', type=str, required=True, help='Path to the configuration file.')
+    parser.add_argument('--voxel-size', type=float, required=False, default=10, help='Segmentation Voxel size.')
+    parser.add_argument('--picks-info', type=utils.parse_target, required=True, help='Query for the picks (e.g., "name" or "name,user_id,session_id".).')
+    parser.add_argument('--organelle-info', type=utils.parse_target, required=False, help='Query for the organelles segmentations (e.g., "name" or "name,user_id,session_id".).')
+    parser.add_argument('--distance-min', type=float, required=False, default=10, help='Minimum distance for valid nearest neighbors.') 
+    parser.add_argument('--distance-max', type=float, required=False, default=70, help='Maximum distance for valid nearest neighbors.')
+    parser.add_argument('--distance-threshold', type=float, required=False, default=25, help='Distance threshold for picks to associated organelles.')
+    parser.add_argument('--save-session-id', type=str, required=False, default=None, help='(Optional)SessionID to save the new picks. If none provided, will use the sessionID from the picks.')
+    parser.add_argument('--runIDs', type=utils.parse_list, required=False, help='(Optional) List of run IDs to process.')
+    parser.add_argument('--n-procs', type=int, required=False, default=None, help='Number of processes to use. In none providd, will use the total number of CPUs available.')
+
+    args = parser.parse_args()
+
+    # Increment session ID for the second class
+    if args.save_session_id is None: 
+        args.save_session_id = args.picks_info[2]
+    args.save_user_id = args.picks_info[1]       
+
+    # Save JSON with Parameters
+    output_yaml = f'midpoint-extract_{args.picks_info[1]}_{args.save_session_id}.yaml'
+    save_parameters(args, output_yaml)
+
+
+    extract_midpoint(
+        config=args.config,
+        voxel_size=args.voxel_size,
+        picks_info=args.picks_info,
+        organelle_info=args.organelle_info,
+        distance_min=args.distance_min,
+        distance_max=args.distance_max,
+        distance_threshold=args.distance_threshold,
+        save_session_id=args.save_session_id,
+        runIDs=args.runIDs,
+        n_procs=args.n_procs,
+    )
+
+def save_parameters(args: argparse.Namespace, 
+                    output_path: str):
+
+    params_dict = {
+        "input": {
+            k: getattr(args, k) for k in [
+                "config", "voxel_size", "picks_info", 
+                "organelle_info"
+            ]
+        },
+        "output": {
+            k: getattr(args, k) for k in ["save_user_id", "save_session_id"]
+        },
+        "parameters": {
+            k: getattr(args, k) for k in ["distance_min", "distance_max", "distance_threshold", "runIDs"]
+        }
+    }
+
+    # Print the parameters
+    print(f"\nParameters for Extraction of Membrane-Bound Picks:")
+    pprint.pprint(params_dict); print()
+
+    # Save parameters to YAML file
+    utils.save_parameters_yaml(params_dict, output_path) 
+
+if __name__ == "__main__":
+    cli()

octopi/entry_points/run_localize.py

@@ -0,0 +1,176 @@
+from octopi.utils import parsers
+from typing import List, Tuple
+import rich_click as click
+
+def pick_particles(
+    copick_config_path: str,
+    method: str,
+    seg_info: Tuple[str, str, str],
+    voxel_size: float,
+    pick_session_id: str,
+    pick_user_id: str,
+    radius_min_scale: float,
+    radius_max_scale: float,
+    filter_size: float,
+    pick_objects: List[str],
+    runIDs: List[str],
+    n_procs: int,
+    ):
+    from octopi.workflows import localize
+
+    # Run 3D Localization
+    localize(
+        copick_config_path, voxel_size, seg_info, pick_user_id, pick_session_id, n_procs,
+        method, filter_size, radius_min_scale, radius_max_scale, 
+        run_ids = runIDs, pick_objects = pick_objects
+    )
+
+
+def save_parameters(seg_info: Tuple[str, str, str],
+                    config: str,
+                    voxel_size: float,
+                    pick_session_id: str,
+                    pick_user_id: str,
+                    method: str,
+                    radius_min_scale: float,
+                    radius_max_scale: float,
+                    filter_size: float,
+                    output_path: str):
+
+    import octopi.utils.io as io
+    import pprint
+
+    # Organize parameters into categories
+    params = {
+        "input": {
+            "config": config,
+            "seg_name": seg_info[0],
+            "seg_user_id": seg_info[1],
+            "seg_session_id": seg_info[2],
+            "voxel_size": voxel_size
+        },
+        "output": {
+            "pick_session_id": pick_session_id,
+            "pick_user_id": pick_user_id
+        },
+        "parameters": {
+            "method": method,
+            "radius_min_scale": radius_min_scale,
+            "radius_max_scale": radius_max_scale,
+            "filter_size": filter_size,
+        }
+    }
+
+    # Print the parameters
+    print(f"\nParameters for Localization:")
+    pprint.pprint(params); print()
+
+    # Save to YAML file
+    io.save_parameters_yaml(params, output_path)
+
+
+@click.command('localize')
+# Output Arguments
+@click.option('-pui', '--pick-user-id', type=str, default='octopi',
+              help="User ID for the particle picks")
+@click.option('-psid', '--pick-session-id', type=str, default='1',
+              help="Session ID for the particle picks")
+# Localize Arguments
+@click.option('-np', '--n-procs', type=int, default=8,
+              help="Number of CPU processes to parallelize runs across. Defaults to the max number of cores available or available runs")
+@click.option('-obj', '--pick-objects', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_list(value) if value else None,
+              help="Specific Objects to Find Picks for")
+@click.option('-fs', '--filter-size', type=int, default=10,
+              help="Filter size for localization")
+@click.option('-rmax','--radius-max-scale', type=float, default=1.0,
+              help="Maximum radius scale for particles")
+@click.option('-rmin', '--radius-min-scale', type=float, default=0.5,
+              help="Minimum radius scale for particles")
+# Input Arguments
+@click.option('--runIDs', type=str, default=None,
+              callback=lambda ctx, param, value: parsers.parse_list(value) if value else None,
+              help="List of runIDs to run inference on, e.g., run1,run2,run3 or [run1,run2,run3]")
+@click.option('-vs', '--voxel-size', type=float, default=10,
+              help="Voxel size for localization")
+@click.option('-sinfo', '--seg-info', type=str, default='predict,octopi,1',
+              callback=lambda ctx, param, value: parsers.parse_target(value),
+              help='Query for the organelles segmentations (e.g., "name" or "name,user_id,session_id")')
+@click.option('-m', '--method', type=click.Choice(['watershed', 'com'], case_sensitive=False), 
+              default='watershed',
+              help="Localization method to use")
+@click.option('-c', '--config', type=click.Path(exists=True), required=True,
+              help="Path to the CoPick configuration file")
+def cli(config, method, seg_info, voxel_size, runids,
+        radius_min_scale, radius_max_scale, filter_size, pick_objects, n_procs,
+        pick_session_id, pick_user_id):
+    """
+    Convert Segmentation Masks to 3D Particle Coordinates. 
+
+    This command converts segmentation masks into 3D particle coordinates using size-based filtering. 
+    It supports two localization methods: watershed and center of mass. The resulting particle coordinates 
+    in your copick project, organized by segmentation name, user ID, and session ID for easy tracking and comparison.
+    
+    \b
+    Examples:
+      # Localize particles with default settings
+      octopi localize -c config.json --seg-info predict,octopi,1
+    """
+
+    run_localize(config, method, seg_info, voxel_size, runids,
+        radius_min_scale, radius_max_scale, filter_size, pick_objects, n_procs,
+        pick_session_id, pick_user_id)
+    
+
+def run_localize(config, method, seg_info, voxel_size, runids,
+        radius_min_scale, radius_max_scale, filter_size, pick_objects, n_procs,
+        pick_session_id, pick_user_id):
+    """
+    Run the localize command.
+    """
+    import octopi.utils.io as io
+    import multiprocess as mp
+    import copick, os
+    
+    # Save JSON with Parameters
+    root = copick.from_file(config)
+    overlay_root = io.remove_prefix(root.config.overlay_root)
+    basepath = os.path.join(overlay_root, 'logs')
+    os.makedirs(basepath, exist_ok=True)
+    output_path = os.path.join(basepath, f'localize-{pick_user_id}_{pick_session_id}.yaml')
+    
+    save_parameters(
+        seg_info=seg_info,
+        config=config,
+        voxel_size=voxel_size,
+        pick_session_id=pick_session_id,
+        pick_user_id=pick_user_id,
+        method=method,
+        radius_min_scale=radius_min_scale,
+        radius_max_scale=radius_max_scale,
+        filter_size=filter_size,
+        output_path=output_path
+    )
+
+    # Set multiprocessing start method
+    mp.set_start_method("spawn")
+    
+    pick_particles(
+        copick_config_path=config,
+        method=method,
+        seg_info=seg_info,
+        voxel_size=voxel_size,
+        pick_session_id=pick_session_id,
+        pick_user_id=pick_user_id,
+        radius_min_scale=radius_min_scale,
+        radius_max_scale=radius_max_scale,
+        filter_size=filter_size,
+        runIDs=runids,
+        pick_objects=pick_objects,
+        n_procs=n_procs,
+    )
+
+
+if __name__ == "__main__":
+    cli()
+