Confusing explanation and output for momepy.neighbors

[iboates]

On the page for momepy.neighbors, firstly I think there is a typo because the first parameter is listed as gdf when in the signature it is geometry.

I also get a confusing result when I run it with the following code:

def neighbors_metrics(
    buildings_gdf: gpd.GeoDataFrame,
    cell_polygon: Polygon,
    equal_area_crs: CRS | str | int | None = None,
    equidistant_crs: CRS | str | int | None = None,
    conformal_crs: CRS | str | int | None = None,
) -> gpd.GeoDataFrame:
    """Compute number of tessellation neighbors.

    Primarily topological. Uses equidistant CRS.
    """
    prepared = prepare_buildings(
        buildings_gdf, cell_polygon, equal_area_crs, equidistant_crs, conformal_crs
    )
    if prepared.equidistant.empty:
        return prepared.cell_gdf

    buildings = prepared.equidistant
    tessellation, contiguity, _ = _build_graphs(buildings)
    if tessellation is None or contiguity is None:
        return prepared.cell_gdf

    s = momepy.neighbors(tessellation, contiguity)
    stats = aggregate_stats(s, prefix="neighbors", include_sum=True)
    for k, v in stats.items():
        prepared.cell_gdf[k] = v
    return prepared.cell_gdf

For reference, prepared.equidistant is the building geometries proejcted to an equidistant CRS, and _build_graphs does this:

def _build_graphs(buildings: gpd.GeoDataFrame):
    """Build tessellation, contiguity, and neighborhood graphs for distribution metrics."""
    try:
        limit = momepy.buffered_limit(buildings)
        tessellation = momepy.morphological_tessellation(buildings, clip=limit)
    except Exception:
        return None, None, None

    try:
        contiguity = Graph.build_contiguity(tessellation, rook=False)
    except Exception:
        contiguity = None

    try:
        knn = Graph.build_knn(buildings.centroid, k=min(15, len(buildings)))
    except Exception:
        knn = None

    return tessellation, contiguity, knn

As far as I can tell, I am building the tessellation and contiguity graphs the same as the example, but if I join the result back to the buildings to inspect the results visually with:

pd.merge(left=prepared.equidistant, right=s, left_index=True, right_index=True).to_file("/path/to/neighbors.gpkg")

And the result looks like this:

This street alone looks crazy to me, how can these buildings have such wildly different numbers of neighbours when they are just row buildings?

Is it just not appropriate to join the results back to the source geometries like this? Or is there some subtlety about this algorithm that I am missing?

[martinfleis]

It captures precisely what the docstring says (besides the gdf/geometry mistake), that is the number of neighbours captured by graph, i.e. it just calls graph.cardinalities. If that graph is generated on tessellation, that is number of neighbours that tessellation cell has. Not a number of neighbours a building does. If you generate contiguity from buildings, then it gives you info on how many other buildings it touches but that is not what you're supposed to get from tessellation graph.

[iboates]

Ah ok I see now, it is capturing the neighbours of the "parcels" created by the tessellation, thank you.

[martinfleis]

Yes. If you plot it on the tessellation, it will make more sense. You can technically link it to buildings but it is harder to interpret that way.