local_distances
local_distances ¶
local_distances(
gdf: GeoDataFrame,
spatial_weights: W,
normalize: bool = False,
id_col: str | None = None,
reductions: Sequence[str] = ("mean",),
weight_by_area: bool = False,
invert: bool = False,
parallel: bool = False,
num_processes: int = 1,
rm_nhood_cols: bool = True,
col_prefix: str | None = None,
create_copy: bool = True,
) -> gpd.GeoDataFrame
Aggregate distances from each node to its supplied graph neighbors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
Objects whose geometries and node IDs correspond to spatial_weights. Distances retain geometry coordinate units, usually pixels. |
required |
spatial_weights
|
W
|
Existing libpysal weights; graph construction is not required. Neighborhoods include each center node's self-distance. |
required |
normalize
|
bool
|
Quantile-normalize reduced values after aggregation. |
False
|
id_col
|
str | None
|
Unique node-ID column matching the weight keys. IDs need not equal table row labels. If None, assign running UIDs using set_uid. |
None
|
reductions
|
Sequence[str]
|
Reduction names: "sum", "mean", "median", "min", "max", "std". |
('mean',)
|
weight_by_area
|
bool
|
Apply existing normalized area weights before reduction. |
False
|
invert
|
bool
|
Use reciprocal distances, clipping below 1e-6 before inversion. |
False
|
parallel
|
bool
|
Use parallel apply instead of serial apply. |
False
|
num_processes
|
int
|
Worker count; -1 uses the existing automatic CPU selection. |
1
|
rm_nhood_cols
|
bool
|
Remove temporary neighborhood columns from the result. |
True
|
col_prefix
|
str | None
|
Optional prefix for result column names. |
None
|
create_copy
|
bool
|
Copy the input before adding columns. If False, use it directly. |
True
|
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
GeoDataFrame with reduced neighborhood distances. Supplying id_col |
GeoDataFrame
|
preserves the original table row labels and node IDs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If a reduction is unsupported or node IDs are not unique. |
KeyError
|
If a node ID, neighbor ID, or requested ID column is missing. |
Examples:
Compute the mean of eccentricity values for each neighborhood
>>> from histolytics.utils.gdf import set_uid
>>> from histolytics.data import cervix_nuclei
>>> from histolytics.spatial_graph.graph import fit_graph
>>> from histolytics.spatial_geom.shape_metrics import shape_metric
>>> from histolytics.spatial_agg.local_distances import local_distances
>>>
>>> # input data
>>> nuc = cervix_nuclei()
>>> nuc = set_uid(nuc)
>>>
>>> # Fit delaunay graph
>>> w, _ = fit_graph(nuc, "delaunay", id_col="uid", threshold=100, use_polars=True)
>>> # Compute local neighborhood distances for shape metrics
>>> nuc = local_distances(
... nuc,
... w,
... id_col="uid",
... reductions=["mean"],
... num_processes=6,
>>> )
>>> print(nuc.head(3))
geometry class_name uid uid
0 POLYGON ((940.01 5570.02, 939.01 5573, 939 559... connective 0
1 POLYGON ((906.01 5350.02, 906.01 5361, 908.01 ... connective 1
2 POLYGON ((866 5137.02, 862.77 5137.94, 860 513... squamous_epithel 2
nhood_dists_mean
uid
0 48.500637
1 55.802475
2 37.081177
Source code in src/histolytics/spatial_agg/local_distances.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | |