API Reference

This page provides detailed documentation for all functions and classes in InterSCellar.

Main API

The main API functions are available directly from the interscellar package:

• 3D Pipeline API
  • Cell Neighbor Detection & Graph Construction (3D)
• 2D Pipeline API
  • Cell Neighbor Detection & Graph Construction (2D)

API

interscellar.find_cell_neighbors_2d(polygon_json_path: str, metadata_csv_path: str, max_distance_um: float = 1.0, pixel_size_um: float = 0.1085, centroid_prefilter_radius_um: float = 75.0, cell_id: str = 'cell_id', cell_type: str = 'subclass', centroid_x: str = 'X', centroid_y: str = 'Y', 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]

interscellar.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]

interscellar.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]

interscellar.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]

interscellar.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

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.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, nuclei_segmentation_zarr: str | None = None, slab: int = 16, n_jobs: int = 1) → DataFrame

Compute cell-only volumes: each cell minus every interscellar volume.

A voxel keeps its cell label unless it lies in any interscellar volume, or, when nuclei_segmentation_zarr is given, in any nucleus. Works with the output of either pathway: an absolute store (label array '0') or an adaptive store (the interscellar_meshes grid, or the lossless pair archive when the store was written with preview=False). The volume is processed in Z-slabs, so memory stays at a few slabs per worker regardless of dataset size.

Parameters:

• ome_zarr_path -- Cell segmentation zarr (cell IDs as labels).

• interscellar_volumes_zarr -- Interscellar volumes zarr from compute_interscellar_volumes_3d or compute_interscellar_volumes_3d_adaptive.

• output_zarr_path -- Output zarr. Defaults to the interscellar zarr's name with _interscellar_volumes replaced by _cell_only_volumes (plus _nuclei_excluded when nuclei are given), in the same directory.

• neighbor_db_path -- Optional neighbor graph .db; supplies the cell_type column.

• nuclei_segmentation_zarr -- Optional nuclei segmentation zarr on the same grid; every voxel inside a nucleus is also removed.

• slab -- Z slices processed at a time.

• n_jobs -- Number of worker processes, each handling one Z-slab at a time.

Returns:

cell_id, cell_only_volume_voxels, cell_only_volume_um3 and cell_type.

Return type:

DataFrame with one row per cell that keeps any voxels

Note

Only the union of the interscellar volumes is subtracted, so overlapping adaptive volumes remove each shared voxel once. Cells lying entirely inside interscellar volumes (or nuclei) have no row. Volumes in um3 use the voxel size recorded in the interscellar zarr, or (0.56, 0.28, 0.28) when it has none.

interscellar.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

interscellar.extract_features_3d(argv: List[str] | None = None) → None

interscellar.combine_cell_and_interscellar_volumes_3d(cell_only_zarr: str, interscellar_zarr: str, output_zarr_path: str | None = None) → str

interscellar.visualize_all_3d()

interscellar.visualize_pair_3d()

interscellar.exclude_nuclei(input_zarr: str, nuclei_segmentation_zarr: str, output_zarr_path: str | None = None, input_key: str | None = None, nuclei_key: str | None = None, reference_zarr: str | None = None)

Subtract nuclei from any label zarr. Returns (result, output_path).

Adaptive interscellar stores (with a 'pair_volumes' archive) are carved pair by pair, so overlapping volumes each keep their shared voxels; the result is then a summary dict. Any other label zarr is carved as a single label volume and the result is the carved array.