SpatialDeform

SpatialDeform is a scikit-learn-style Python library for turning a cost-weighted geographic network into a spatial deformation or travel-time cartogram.

It accepts a GeoPandas edge table, computes graph shortest-path costs, embeds the graph using geographically regularized MDS or Isomap-style classical scaling, and smoothly warps every vertex in the line geometry.

from spatialdeform import SpatialDeformer

model = SpatialDeformer(
    backend="mds",
    cost="travel_time_s",
    source="source",
    target="target",
    geo_weight=0.1,
)

warped_edges = model.fit_transform(edges)
warped_nodes = model.get_nodes()

Why SpatialDeform?

• GeoPandas-native. Input and output are GeoDataFrames; attributes and CRS are preserved.
• Network-aware. Edge costs become all-pairs graph shortest-path distances, not straight-line distances.
• Recognizable geography. Geographic anchoring prevents the unconstrained rotations and extreme distortions typical of ordinary MDS.
• Scikit-learn conventions. Hyperparameters live in the constructor; learned state uses trailing underscores; estimators support cloning, get_params, and set_params.
• Complete line warping. Interior LineString and MultiLineString vertices follow a smooth displacement field instead of collapsing into straight chords.
• Comparable scenarios. Reusing scale_ allows free-flow and congested networks to contract and expand in a common frame.

Choose a path

If you want to…	Start here
install the package or a development checkout	Install
produce your first deformation	Getting started
understand the required GeoDataFrame columns	Input data
compare MDS with Isomap	MDS and Isomap
animate several travel-time states	Multiple scenarios
inspect every estimator parameter and attribute	API reference

Alpha status

The current version is 0.1.0a1. The API is usable and tested, but may change before the first stable release.