3D Pipeline API

3D Pipeline API#

Cell Neighbor Detection & Graph Construction (3D)#

interscellar.api.wrapper_3d.find_cell_neighbors_3d(ome_zarr_path: str, metadata_csv_path: str, max_distance_um: float = 0.5, voxel_size_um: tuple = (0.56, 0.28, 0.28), centroid_prefilter_radius_um: float = 75.0, cell_id: str = 'CellID', cell_type: str = 'phenotype', centroid_x: str = 'X_centroid', centroid_y: str = 'Y_centroid', centroid_z: str = 'Z_centroid', db_path: str | None = None, output_csv: str | None = None, output_anndata: str | None = None, n_jobs: int = 1, return_connection: bool = False, save_surfaces_pickle: str | None = None, load_surfaces_pickle: str | None = None, save_graph_state_pickle: str | None = None) → Tuple[DataFrame | None, object | None, object | None][source]#
interscellar.api.wrapper_3d.find_cell_neighbors_centroid_3d(metadata_csv_path: str, radius_um: float, voxel_size_um: tuple = (0.56, 0.28, 0.28), db_path: str | None = None, output_csv: str | None = None, output_cells_csv: str | None = None, output_anndata: str | None = None, cell_id: str = 'CellID', cell_type: str = 'phenotype', centroid_x: str = 'X_centroid', centroid_y: str = 'Y_centroid', centroid_z: str = 'Z_centroid', return_connection: bool = False) → Tuple[DataFrame | None, object | None, object | None][source]#
interscellar.api.wrapper_3d.compute_interscellar_volumes_3d(ome_zarr_path: str, neighbor_pairs_csv: str, global_surface_pickle: str | None = None, halo_bboxes_pickle: str | None = None, neighbor_db_path: str | None = None, voxel_size_um: tuple = (0.56, 0.28, 0.28), db_path: str | None = None, output_csv: str | None = None, output_anndata: str | None = None, output_mesh_zarr: str | None = None, output_cell_only_zarr: str | None = None, max_distance_um: float = 3.0, intracellular_threshold_um: float = 1.0, n_jobs: int = 4, return_connection: bool = False, intermediate_results_dir: str = 'intermediate_interscellar_results', resume: bool | None = None, output_name_tag: str = 'absolute') → Tuple[DataFrame | None, object | None, object | None][source]#
interscellar.api.wrapper_3d.compute_interscellar_volumes_3d_adaptive(ome_zarr_path: str, neighbor_pairs_csv: str, voxel_size_um: tuple = (0.56, 0.28, 0.28), max_distance_um: float = 3.0, surface_distance_um: float = 0.5, rho_threshold: float = 0.5, contact_rim_um: float = 0.0, max_inward_um: float | None = None, output_csv: str | None = None, output_mesh_zarr: str | None = None, rejected_csv: str | None = None, output_dir: str | None = None, output_name_tag: str = 'adaptive', global_surface_pickle: str | None = None, halo_bboxes_pickle: str | None = None, exclude_truncated: bool = False, reject_unbridged: bool = True, preview: bool = True, chunk_size: int = 500, workers_load_volume: bool = False, resume: bool = False, n_jobs: int = 1) → DataFrame | None[source]#

Compute interscellar volumes with the adaptive pathway.

Each volume is the extracellular corridor between two neighboring cells plus the intracellular rind reaching into each cell. Unlike compute_interscellar_volumes_3d, which reaches a fixed distance into each cell, the adaptive pathway dilates inwards from the cell surface by a depth ratio relative to the cell's maximum reach.

Parameters:

  • ome_zarr_path -- 3D segmentation label volume (.zarr or .npy).

  • neighbor_pairs_csv -- Neighbor pairs CSV or neighbor graph .db from find_cell_neighbors_3d.

  • voxel_size_um -- (z, y, x) voxel size in micrometers.

  • max_distance_um -- Maximum surface-to-surface distance the corridor may span.

  • surface_distance_um -- Distance from the surface that defines each cell's rim.

  • rho_threshold -- Depth ratio, relative to the cell's maximum reach, that the volume extends into each cell.

  • contact_rim_um -- Extra rim width around direct-contact interfaces.

  • max_inward_um -- Optional cap on how far the volume reaches into a cell.

  • output_csv -- Per-pair volumes CSV. Defaults to <stem>_adaptive_volumes.csv.

  • output_mesh_zarr -- Pair-labeled volumes zarr. Defaults to <stem>_adaptive_interscellar_volumes.zarr.

  • rejected_csv -- CSV of rejected pairs. Defaults to <stem>_adaptive_rejected_pairs.csv.

  • output_dir -- Directory for auto-named outputs. Defaults to the directory of neighbor_pairs_csv.

  • output_name_tag -- Tag inserted into auto-named outputs.

  • global_surface_pickle -- Optional surfaces .pkl; must match the mask shape.

  • halo_bboxes_pickle -- Optional halo bounding boxes .pkl; must lie inside the mask.

  • exclude_truncated -- Skip pairs where either cell touches a face of the volume.

  • reject_unbridged -- Reject pairs with no extracellular corridor reaching both cells. Disable only for comparison.

  • preview -- Write the dense interscellar_meshes/overlap_count arrays alongside the lossless per-pair archive.

  • chunk_size -- Pairs processed per chunk.

  • workers_load_volume -- Each worker loads the whole volume instead of reading pair crops lazily.

  • resume -- Skip pairs already in output_csv and append to existing outputs.

  • n_jobs -- Number of worker processes.

Returns:

DataFrame of per-pair volume measurements read back from output_csv.

Note

Interscellar volumes may overlap; a voxel shared by several pairs belongs to each of them in the per-pair archive, which calculate_interscellar_scores_3d reads. The dense interscellar_meshes array can show only one pair per voxel.

interscellar.api.wrapper_3d.compute_cell_only_volumes_3d(ome_zarr_path: str, interscellar_volumes_zarr: str, output_zarr_path: str | None = None, neighbor_db_path: str | None = None) → DataFrame[source]#
interscellar.api.wrapper_3d.calculate_interscellar_scores_3d(interscellar_volumes_zarr: str, spot_zarrs: Any, biomarker: str | None = None, volumes_csv: str | None = None, output_csv: str | None = None, voxel_size_um: Tuple[float, float, float] | None = None, n_jobs: int = 1, decay_power: float = 1.0, reference_distance_um: Any = None, pair_batch: int = 32, per_point_csv: str | None = None) → DataFrame[source]#