PySAL Core Library (libpysal)

4.14.1 · active · verified Thu Apr 16

libpysal is the foundational package of the PySAL (Python Spatial Analysis Library) ecosystem. It provides core algorithms and data structures for spatial analysis, including computational geometry, spatial weights matrix creation, and access to built-in example datasets. It serves as a building block for many higher-level PySAL packages and is under active development, with frequent minor releases.

Common errors

```
ModuleNotFoundError: No module named 'geopandas'
```
cause `libpysal` often relies on `geopandas` for reading spatial data from files (e.g., shapefiles) and creating weights from GeoDataFrames, but `geopandas` is an optional dependency and not installed by default.

fix Install `geopandas`: `pip install geopandas` or `pip install libpysal[plus]` for common optional dependencies.
```
KeyError: 'Some ID' (or similar error when accessing weight attributes)
```
cause This usually occurs when trying to access attributes or neighbors of a `libpysal.weights.W` object using IDs that are not present in its `id_order` attribute. This can happen if the input data's index was not properly aligned or handled during weights creation, or if IDs were remapped.

fix Ensure the IDs used to query the `W` object match the `W.id_order`. When creating weights from a DataFrame, ensure `use_index=True` if you intend to use the DataFrame's index. If IDs were remapped, use the remapped IDs or the `remap_ids` method.
```
ValueError: Geometry must be a Point or Polygon for weights construction.
```
cause Some weights construction methods (e.g., `Queen.from_dataframe`, `KNN.from_dataframe`) expect specific geometry types (e.g., polygons for contiguity, points for distance-based). If your GeoDataFrame contains mixed geometries or an unexpected type, this error will occur.

fix Filter your GeoDataFrame to include only the expected geometry types before constructing the weights, or use a weights constructor appropriate for your data. For example, use `gdf[gdf.geometry.geom_type == 'Polygon']` or `gdf[gdf.geometry.geom_type == 'Point']`.

Warnings

breaking In v4.9.2, internal refactoring, particularly around `libpysal.common`, caused issues with star imports (`from libpysal.common import *`) in downstream packages, leading to broken production environments if dependencies were not updated properly. This was addressed by explicit imports in dependent packages.
Fix: Avoid `from libpysal.common import *`. Ensure all numpy and other common imports are explicit, e.g., `import numpy as np`, rather than relying on `libpysal.common`.
breaking The `Graph.build_kernel` method experienced regressions in v4.14.0 that were fixed in v4.14.1. If you implemented custom kernel building or relied on its precise behavior, verify functionality after upgrading from v4.14.0.
Fix: Upgrade to `libpysal>=4.14.1` to resolve the regression in `Graph.build_kernel`.
deprecated A new `Graph` class is being introduced, intended to eventually replace the legacy `Weights` objects in `libpysal.weights`. While `Weights` objects are still fully supported, users are encouraged to explore the `Graph` class for new developments.
Fix: Consult the 'W and Graph Components' documentation for a migration guide and details on the new `Graph` class when building new spatial analysis workflows.
gotcha When creating spatial weights (e.g., contiguity weights), it's common to encounter a `UserWarning: The weights matrix is not fully connected`. This indicates that some spatial units in your dataset have no neighbors according to the chosen contiguity rule (e.g., islands, isolated points).
Fix: This is often not an error but an informative warning. You can inspect `weights.islands` to identify disconnected components. Depending on your analysis, you might need to adjust the contiguity rule (e.g., use K-Nearest Neighbors), drop isolated observations, or handle them specifically.

Install

pip install libpysal Install stable version

Imports

libpysal
```
import libpysal
```
weights
wrong:
```
from pysal.lib import weights
```
correct:
```
import libpysal.weights
from libpysal.weights import Queen
```
Since PySAL 2.0, functionality is split into sub-packages. Directly import from `libpysal.weights` instead of the metapackage's `pysal.lib`.
get_path
wrong:
```
import libpysal.examples; libpysal.examples.get_path(...)
```
correct:
```
from libpysal.examples import get_path
```
Directly importing `get_path` is idiomatic for accessing example datasets.
Graph
```
from libpysal.graph import Graph
```

Quickstart

This quickstart demonstrates loading a built-in geospatial dataset using `libpysal.examples`, then creating a Queen contiguity spatial weights matrix from a GeoDataFrame using `libpysal.weights`.

import libpysal
import geopandas as gpd
from libpysal.weights import Queen

# Load example dataset
url = libpysal.examples.get_path('columbus.shp')
gdf = gpd.read_file(url)

# Create queen contiguity weights
weights = Queen.from_dataframe(gdf)

# Print summary of weights
print(weights.summary())

view raw JSON →