momepy API reference#

The current version of momepy includes two implementations of most of the functionality due to the ongoing migration period moving from the legacy class-based API to a new function-based API. This page outlines the stable API. For the legacy functionality, see Legacy API.

Managing morphological elements#

Momepy allows creation of a small subset of bespoke morphological geometric features.

morphological_tessellation(geometry[, clip, ...])

Generate morphological tessellation.

enclosed_tessellation(geometry, enclosures)

Generate enclosed tessellation

enclosures(primary_barriers[, limit, ...])

Generate enclosures based on passed barriers.

generate_blocks(tessellation, edges, buildings)

Generate blocks based on buildings, tessellation, and street network.

Additionally, it contains tools supporting these.

buffered_limit(gdf[, buffer, min_buffer, ...])

Define limit for tessellation as a buffer around buildings.

verify_tessellation(tesselation, geometry)

Check whether result matches buildings and contains only Polygons.

And tools linking various elements together.

get_nearest_street(buildings, streets[, ...])

Identify the nearest street for each building.

get_network_ratio(df, edges[, initial_buffer])

Link polygons to network edges based on the proportion of overlap (if a cell intersects more than one edge).

get_node_id(objects, nodes, edges, node_id)

Snap each building to the closest street network node on the closest network edge.

Measuring dimension#

A set of functions to measure dimensions of geometric elements:

courtyard_area(geometry)

Calculates area of holes within geometry - area of courtyards.

floor_area(area, height[, floor_height])

Calculates floor area of each object based on height and area.

longest_axis_length(geometry)

Calculates the length of the longest axis of object.

perimeter_wall(geometry[, graph])

Calculate the perimeter wall length the joined structure.

street_profile(streets, buildings[, ...])

Calculates the street profile characters.

volume(area, height)

Calculates volume of each object in given GeoDataFrame based on its height and area.

weighted_character(y, area, graph)

Calculates the weighted character.

Measuring shape#

A set of functions to measure shape of geometric elements:

centroid_corner_distance(geometry[, eps, ...])

Calculates the centroid-corner distance of each object given its geometry.

circular_compactness(geometry)

Calculates the circular compactness of each object given its geometry.

compactness_weighted_axis(geometry[, ...])

Calculates the compactness-weighted axis of each object in a given GeoDataFrame.

convexity(geometry)

Calculates the convexity of each object given its geometry.

corners(geometry[, eps, include_interiors])

Calculates the number of corners of each object given its geometry.

courtyard_index(geometry[, courtyard_area])

Calculates the courtyard index of each object given its geometry.

elongation(geometry)

Calculates the elongation of each object given its geometry.

equivalent_rectangular_index(geometry)

Calculates the equivalent rectangular index of each object given its geometry.

facade_ratio(geometry)

Calculates the facade ratio of each object given its geometry.

form_factor(geometry, height)

Calculates the form factor of each object given its geometry and height.

fractal_dimension(geometry)

Calculates fractal dimension based on area and perimeter.

linearity(geometry)

Calculates the linearity of each LineString

rectangularity(geometry)

Calculates the rectangularity of each object given its geometry.

shape_index(geometry[, longest_axis_length])

Calculates the shape index of each object given its geometry.

square_compactness(geometry)

Calculates the square compactness of each object given its geometry.

squareness(geometry[, eps, include_interiors])

Calculates the squareness of each object given its geometry.

Measuring spatial distribution#

A set of functions to measure spatial distribution of geometric elements:

alignment(orientation, graph)

Calculate the mean deviation of orientation adjacent elements

building_adjacency(contiguity_graph, ...)

Calculate the level of building adjacency.

cell_alignment(left_orientation, ...)

Calculate the difference between cell orientation and the orientation of object.

mean_interbuilding_distance(geometry, ...)

Calculate the mean distance between adjacent geometries within a set neighborhood

neighbor_distance(geometry, graph)

Calculate the mean distance to adjacent elements.

neighbors(geometry, graph[, weighted])

Calculate the number of neighbours captured by graph.

orientation(geometry)

Calculate the orientation of objects.

shared_walls(geometry)

Calculate the length of shared walls of adjacent elements (typically buildings).

street_alignment(building_orientation, ...)

Calulate the deviation of the building orientation from the street orientation.

Measuring intensity#

A set of functions to measure intensity characters:

courtyards(geometry, graph)

Calculate the number of courtyards within the joined structure.

node_density(nodes, edges, graph[, weighted])

Calculate the density of a node's neighbours (for all nodes) on the street network defined in graph.

Note that additional intensity characters can be directly derived using libpysal.graph.Graph.describe() and functions describe_agg() and describe_reached_agg() belonging to the diversity module.

Measuring diversity#

A set of functions to measure spatial diversity of elements and their values:

describe_agg(y, aggregation_key[, ...])

Describe the distribution of values within the groups of an aggregation.

describe_reached_agg(y, graph_index, graph)

Describe the distribution of values reached on a neighbourhood graph.

gini(y, graph[, q])

Calculates the Gini index of values within neighbours defined in graph.

percentile(y, graph[, q])

Calculates linearly weighted percentiles of y values using the neighbourhoods and weights defined in graph.

shannon(y, graph[, binning, categorical, ...])

Calculates the Shannon index of values within neighbours defined in graph.

simpson(y, graph[, binning, gini_simpson, ...])

Calculates the Simpson's diversity index of values within neighbours defined in graph.

theil(y, graph[, q])

Calculates the Theil measure of inequality of values within neighbours defined in graph.

values_range(y, graph[, q])

Calculates the range of values within neighbours defined in graph.

Underlying components of shannon() and simpson() are also exposed for direct use:

shannon_diversity(data[, bins, categorical, ...])

Calculates the Shannon's diversity index of data.

simpson_diversity(values[, bins, categorical])

Calculates the Simpson's diversity index of data.

Measuring connectivity#

A set of functions for the analysis of connectivity and configuration of street networks:

betweenness_centrality(graph[, name, mode, ...])

Calculates the shortest-path betweenness centrality for nodes.

cds_length(graph[, radius, mode, name, ...])

Calculates length of cul-de-sacs for subgraph around each node if radius is set, or for whole graph, if radius=None.

closeness_centrality(graph[, name, weight, ...])

Calculates the closeness centrality for nodes.

clustering(graph[, name])

Calculates the squares clustering coefficient for nodes.

cyclomatic(graph[, radius, name, distance, ...])

Calculates cyclomatic complexity for subgraph around each node if radius is set, or for whole graph, if radius=None.

edge_node_ratio(graph[, radius, name, ...])

Calculates edge / node ratio for subgraph around each node if radius is set, or for whole graph, if radius=None.

gamma(graph[, radius, name, distance, verbose])

Calculates connectivity gamma index for subgraph around each node if radius is set, or for whole graph, if radius=None.

mean_node_degree(graph[, radius, name, ...])

Calculates mean node degree for subgraph around each node if radius is set, or for whole graph, if radius=None.

mean_node_dist(graph[, name, length, verbose])

Calculates mean distance to neighbouring nodes.

mean_nodes(graph, attr)

Calculates mean value of nodes attr for each edge.

meshedness(graph[, radius, name, distance, ...])

Calculates meshedness for subgraph around each node if radius is set, or for whole graph, if radius=None.

node_degree(graph[, name])

Calculates node degree for each node.

proportion(graph[, radius, three, four, ...])

Calculates the proportion of intersection types for subgraph around each node if radius is set, or for whole graph, if radius=None.

straightness_centrality(graph[, weight, ...])

Calculates the straightness centrality for nodes.

subgraph(graph[, radius, distance, ...])

Calculates all subgraph-based characters.

COINS(edge_gdf[, angle_threshold])

Calculates natural continuity and hierarchy of street networks in a given GeoDataFrame using the COINS algorithm.

With utilities allowing conversion between networkx objects and GeoPandas objects.

gdf_to_nx(gdf_network[, approach, length, ...])

Convert a LineString GeoDataFrame to a networkx.MultiGraph or other Graph as per specification.

nx_to_gdf(net[, points, lines, ...])

Convert a networkx.Graph to a LineString GeoDataFrame and Point GeoDataFrame.

Data preprocessing#

Most of the algorithms have certain expectations about the quality of input data. The preprocessing module helps adapting the input data and fixing common issues.

close_gaps(gdf, tolerance)

Close gaps in LineString geometry where it should be contiguous.

extend_lines(gdf, tolerance[, target, ...])

Extends lines from gdf to itself or target within a set tolerance

remove_false_nodes(gdf)

Clean topology of existing LineString geometry by removal of nodes of degree 2.

consolidate_intersections(graph[, ...])

Consolidate close street intersections into a single node, collapsing short edges.

roundabout_simplification(edges[, polys, ...])

Selects the roundabouts from polys to create a center point to merge all incoming edges.

Additionally, there are methods for data assessment.

CheckTessellationInput(gdf[, shrink, ...])

Check input data for Tessellation for potential errors.

FaceArtifacts(gdf[, index, height_mins, ...])

Identify face artifacts in street networks

Further analysis can be done directly using methods available in libpysal.graph.Graph.