network

CityNetwork

to_geopandas

Return a GeoDataFrame with the original input LineString geometries. The returned GeoDataFrame contains all computed columns (centrality metrics, layer results, etc.) joined to the original edge geometries rather than the midpoint representations used internally.

Returns

Notes

cn.centrality_shortest(distances=[800])
result_gdf = cn.to_geopandas()

# result_gdf has LineString geometries (not midpoint Points)
print(result_gdf.geometry.geom_type.unique())  # ['LineString']

# All computed columns are present
print(result_gdf["cc_harmonic_800"])

# Export to file
result_gdf.to_file("centrality_results.gpkg")

from_wkts

Construct a CityNetwork from a dictionary of WKT strings or Shapely geometries.

Parameters

Returns

Raises

Notes

from shapely.geometry import LineString
from cityseer.network import CityNetwork

wkts = {
    "street_a": LineString([(0, 0), (100, 0)]),
    "street_b": LineString([(100, 0), (100, 100)]),
    "street_c": LineString([(100, 0), (200, 0)]),
}
cn = CityNetwork.from_wkts(wkts, crs=32632)
cn.centrality_shortest(distances=[200])

from_geopandas

Construct a CityNetwork from a GeoDataFrame of LineString geometries. Extra columns from the input GeoDataFrame are carried through to the internal nodes GeoDataFrame. The CRS is read from the GeoDataFrame unless explicitly overridden.

Parameters

Returns

Raises

Notes

An optional imp_factor column on the input GeoDataFrame is propagated to each dual edge as the length-weighted mean of the two adjacent primal segments’ impedances; omit it to leave every dual edge at the default 1.0. See the Edge Impedance section of the guide.

import geopandas as gpd
from shapely.geometry import LineString
from cityseer.network import CityNetwork

gdf = gpd.GeoDataFrame(
    {
        "geometry": [
            LineString([(0, 0), (100, 0)]),
            LineString([(100, 0), (100, 100)]),
            LineString([(100, 0), (200, 0)]),
        ]
    },
    crs="EPSG:32632",
)
cn = CityNetwork.from_geopandas(gdf)
cn.centrality_shortest(distances=[200])
print(cn.nodes_gdf[["cc_harmonic_200", "cc_betweenness_200"]])

With directed one-way streets:

gdf = gpd.GeoDataFrame(
    {
        "geometry": [
            LineString([(0, 0), (100, 0)]),
            LineString([(100, 0), (200, 0)]),
        ],
        "oneway": [True, False],
    },
    crs="EPSG:32632",
)
cn = CityNetwork.from_geopandas(gdf, directed=True)

from_nx

Construct a CityNetwork from a cityseer-compatible NetworkX graph. The input graph must be a primal edge graph (not a dual graph) with geom attributes on edges and a crs attribute on the graph. Node live attributes are preserved.

When a MultiDiGraph is passed, directed mode is enabled automatically: each directed edge becomes its own one-way dual node (in the coordinate order of the directed edge). Two-way streets should be represented as two reciprocal edges (A to B and B to A), which produce two separate dual nodes.

Parameters

Returns

Raises

Notes

From an undirected graph:

import networkx as nx
from shapely.geometry import LineString
from cityseer.network import CityNetwork

G = nx.MultiGraph(crs="EPSG:32632")
G.add_node("a", x=0.0, y=0.0)
G.add_node("b", x=100.0, y=0.0)
G.add_node("c", x=200.0, y=0.0)
G.add_edge("a", "b", geom=LineString([(0, 0), (100, 0)]))
G.add_edge("b", "c", geom=LineString([(100, 0), (200, 0)]))

cn = CityNetwork.from_nx(G)

From a directed MultiDiGraph (e.g. via OSMnx):

G = nx.MultiDiGraph(crs="EPSG:32632")
G.add_node("a", x=0.0, y=0.0)
G.add_node("b", x=100.0, y=0.0)
# One-way: a -> b only
G.add_edge("a", "b", key=0, geom=LineString([(0, 0), (100, 0)]))
cn = CityNetwork.from_nx(G)
assert cn.is_directed

from_osm

Construct a CityNetwork from OpenStreetMap data within a bounding polygon. Downloads the road network and converts it to a dual CityNetwork.

For directed (one-way) routing with OSM data, fetch a directed graph via OSMnx <https://osmnx.readthedocs.io/>_ and pass it to :meth:from_nx or convert it with :func:io.nx_from_osm_nx(directed=True) <cityseer.tools.io.nx_from_osm_nx>.

Parameters

Returns

Notes

from shapely.geometry import box
from cityseer.network import CityNetwork

# Bounding box in WGS84 (lon/lat)
polygon = box(-0.13, 51.51, -0.12, 51.52)
cn = CityNetwork.from_osm(polygon, to_crs_code=32630)
cn.centrality_shortest(distances=[400, 800])

set_boundary

Set live/dead node status based on a boundary polygon. Nodes whose midpoints fall inside the polygon are marked live; others are marked dead. Dead nodes participate in traversal but their own values are not reported. Closeness skips dead sources in exact mode (a cost saving); betweenness sources from every node so that routes through the study area — including those between dead nodes — credit the live nodes they traverse.

Parameters

Returns

set_all_live

Mark all nodes as live, clearing any boundary restriction.

Returns

save

Save the network to disk as a parquet/pickle pair. Creates two files: <path>.nodes.parquet (the nodes GeoDataFrame with all computed columns) and <path>.state.pkl (source and cleaned WKTs, boundary, cleaning parameters, and feature status). Use load to restore.

Parameters

Notes

cn.centrality_shortest(distances=[800])
cn.save("my_network")
# Creates: my_network.nodes.parquet, my_network.state.pkl

# Later, restore the full network with all metrics
cn_restored = CityNetwork.load("my_network")
print(cn_restored.nodes_gdf["cc_harmonic_800"])

load

Load a previously saved CityNetwork from disk. Reconstructs the graph topology from the saved cleaned geometries with cleaning disabled, so the loaded network is identical to the saved one (cleaning runs exactly once, at construction), and merges any previously computed columns (centrality metrics, layer results) from the saved nodes GeoDataFrame.

Parameters

Returns

centrality_shortest

Compute shortest-path (metric) centrality. Wraps centrality_shortest. All keyword arguments are forwarded; see that function for the full parameter list including distances, minutes, closeness, betweenness, cycles, postprocess, segment_weighted, sample, and epsilon.

Returns

Notes

# Multiple distance thresholds
cn.centrality_shortest(distances=[400, 800, 1600])

# With segment-length weighting
cn.centrality_shortest(distances=[400, 800], segment_weighted=True)

# With sampling for large networks
cn.centrality_shortest(
    distances=[800, 2000, 5000],
    sample=True,
    epsilon=0.05,
)

# Custom closeness metric
cn.centrality_shortest(
    distances=[800],
    closeness={"harmonic": "1/c", "gravity": "exp(-0.005 * c)"},
    betweenness={},
)

By default this emits just cc_harmonic_{d} (closeness) and cc_betweenness_{d}, with cycles off. Pass closeness / betweenness expression dicts (and cycles=True) to compute any of the metrics below (see Column Naming Conventions):

centrality_simplest

Compute simplest-path (angular) centrality. Wraps centrality_simplest. All keyword arguments are forwarded; see that function for the full parameter list.

Returns

Notes

cn.centrality_simplest(distances=[400, 800, 1600])

By default this emits just cc_harmonic_{d}_ang (closeness) and cc_betweenness_{d}_ang. Pass closeness / betweenness expression dicts to compute any of the metrics below (note the _ang suffix):

build_od_matrix

Build an origin-destination (OD) matrix for OD-weighted betweenness. In standard betweenness, every pair of nodes contributes equally. OD-weighted betweenness instead weights each pair by observed trip counts between their respective zones (e.g. commuter cycling counts), so streets carrying more actual traffic receive higher scores.

Wraps build_od_matrix. See that function for the full parameter list.

Parameters

Returns

betweenness_od

Compute OD-weighted betweenness centrality. Weights betweenness by actual origin-destination trip counts rather than treating all paths equally. Only source nodes with outbound trips are traversed, and each shortest-path contribution is scaled by the corresponding OD weight.

Wraps betweenness_od. See that function for the full parameter list.

Parameters

Returns

betweenness_demand

Compute demand-weighted (flow) betweenness from a spatial interaction model. Trips are allocated between weighted origins (e.g. population) and weighted destinations (e.g. attractors) using a singly (origin-)constrained spatial interaction model, then routed along shortest network paths so intermediate streets accumulate the flow passing through them. This is the modelled-matrix counterpart to betweenness_od: the per-pair weights are derived from the network distances revealed during routing, rather than supplied as an explicit OD matrix.

Wraps betweenness_demand. All additional keyword arguments are forwarded; see that function for the full parameter list including distances, minutes, decay_fn, closest_destination, participation, metric_name, max_netw_assign_dist, and barriers_gdf. Origins and destinations are assigned to the network with the same workflow as the data layers (representation-aware nearest-street assignment, offsets included in routed distances). The model has two distance levers, each with one job: decay_fn shapes destination choice within the allocation, and participation (the share of people at a typical location who make a trip; 1.0 by default, e.g. 0.2 for pedestrian flows) makes trip generation accessibility-elastic via a stay-home option in the choice set. The output is a single conserved cc_demand_{distance} column. For externally weighted or bespoke flow conventions use betweenness_od, which retains full expression support.

Parameters

Returns

Notes

cn.betweenness_demand(
    origins_gdf=population_gdf,
    destinations_gdf=amenities_gdf,
    origin_weight_col="population",
    destination_weight_col="weight",
    distances=[800],
    decay_fn="exp(-0.002 * c)",
)
result_gdf = cn.to_geopandas()  # cc_demand_800 projected onto the street segments

compute_accessibilities

Compute land-use accessibility metrics. Counts how many instances of each specified land-use category (e.g. retail, parks) are reachable within each distance threshold, and records the nearest distance to each category.

Wraps compute_accessibilities. All additional keyword arguments are forwarded; see that function for the full parameter list including landuse_column_label, accessibility_keys, distances, minutes, decay_fn, and angular. decay_fn accepts a single expression or a {label: expression} dict that computes several decay variants in one network traversal, each label suffixing its output columns.

Parameters

Returns

Notes

from cityseer import decay

cn, landuses_gdf = cn.compute_accessibilities(
    data_gdf=landuses_gdf,
    landuse_column_label="category",
    accessibility_keys=["retail", "cafe", "park"],
    distances=[400, 800],
    decay_fn=decay.exponential(),
)
# Count of reachable "retail" within 800m
print(cn.nodes_gdf["cc_retail_800"])
# Nearest distance to "park" at the maximum threshold
print(cn.nodes_gdf["cc_park_nearest_max_800"])

compute_mixed_uses

Compute mixed-use diversity metrics. Measures the diversity of land-use categories reachable from each node using Hill numbers: q=0 counts how many distinct types are present, q=1 measures diversity accounting for how evenly types are represented, and q=2 gives greater weight to the most common types.

Wraps compute_mixed_uses. All additional keyword arguments are forwarded; see that function for the full parameter list including landuse_column_label, distances, minutes, compute_hill, compute_shannon, compute_gini, decay_fn, and angular. decay_fn accepts a single expression or a {label: expression} dict that computes several decay variants in one network traversal, each label suffixing its output columns (only the Hill measures vary with decay).

Parameters

Returns

Notes

cn, landuses_gdf = cn.compute_mixed_uses(
    data_gdf=landuses_gdf,
    landuse_column_label="category",
    distances=[400, 800],
)
# Hill q=0 (count of distinct land-use types) at 800m
print(cn.nodes_gdf["cc_hill_q0_800"])

compute_stats

Compute statistical aggregations of numerical data over the network. Aggregates numerical attributes (e.g. property prices, floor areas) within network-distance thresholds, computing weighted statistics (mean, sum, min, max, variance, etc.) at each node.

Wraps compute_stats. All additional keyword arguments are forwarded; see that function for the full parameter list including stats_column_labels, distances, minutes, decay_fn, and angular. decay_fn accepts a single expression or a {label: expression} dict that computes several decay variants in one network traversal, each label suffixing its output columns.

Parameters

Returns

Notes

from cityseer import decay

cn, prices_gdf = cn.compute_stats(
    data_gdf=prices_gdf,
    stats_column_labels=["price", "floor_area"],
    distances=[800, 1600],
    decay_fn=decay.exponential(),
)
# Weighted mean of "price" at 800m
print(cn.nodes_gdf["cc_price_mean_800"])
# Weighted sum of "floor_area" at 1600m
print(cn.nodes_gdf["cc_floor_area_sum_1600"])

add_gtfs

Add GTFS (General Transit Feed Specification) public transport data to the network. Integrates transit stops and routes so that centrality and accessibility analyses account for public transport connections.

Wraps io.add_transport_gtfs.

Parameters

Returns

to_nx

Convert the network to a NetworkX MultiGraph (or MultiDiGraph if directed). If the network was built with from_nx, returns a copy of the original graph with computed centrality and layer columns added to each edge’s data dictionary. Otherwise builds a new cityseer-compatible undirected graph from the internal GeoDataFrame.

Returns

Raises

Notes

cn = CityNetwork.from_nx(G)
cn.centrality_shortest(distances=[800])

# Round-trip: get back a NetworkX graph with metrics on edges
G_with_metrics = cn.to_nx()
u, v, k, data = list(G_with_metrics.edges(keys=True, data=True))[0]
print(data["cc_harmonic_800"])