{"id":8272,"library":"libpysal","title":"PySAL Core Library (libpysal)","description":"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.","status":"active","version":"4.14.1","language":"en","source_language":"en","source_url":"https://github.com/pysal/libpysal","tags":["spatial analysis","geospatial","weights","graph","pysal","computational geometry","GIS"],"install":[{"cmd":"pip install libpysal","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Fundamental package for numerical computing.","package":"numpy","optional":false},{"reason":"Scientific computing library, used for spatial algorithms and sparse matrices.","package":"scipy","optional":false},{"reason":"Data manipulation and analysis, often used with GeoDataFrames.","package":"pandas","optional":false},{"reason":"Required for geometric operations and object manipulation.","package":"shapely","optional":false},{"reason":"Essential for working with geospatial vector data (GeoDataFrames), especially when creating spatial weights from polygons or points.","package":"geopandas","optional":true},{"reason":"Graph theory library, used for graph-based operations and conversions.","package":"networkx","optional":true}],"imports":[{"symbol":"libpysal","correct":"import libpysal"},{"note":"Since PySAL 2.0, functionality is split into sub-packages. Directly import from `libpysal.weights` instead of the metapackage's `pysal.lib`.","wrong":"from pysal.lib import weights","symbol":"weights","correct":"import libpysal.weights\nfrom libpysal.weights import Queen"},{"note":"Directly importing `get_path` is idiomatic for accessing example datasets.","wrong":"import libpysal.examples; libpysal.examples.get_path(...)","symbol":"get_path","correct":"from libpysal.examples import get_path"},{"symbol":"Graph","correct":"from libpysal.graph import Graph"}],"quickstart":{"code":"import libpysal\nimport geopandas as gpd\nfrom libpysal.weights import Queen\n\n# Load example dataset\nurl = libpysal.examples.get_path('columbus.shp')\ngdf = gpd.read_file(url)\n\n# Create queen contiguity weights\nweights = Queen.from_dataframe(gdf)\n\n# Print summary of weights\nprint(weights.summary())","lang":"python","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"4.9.2"},{"fix":"Upgrade to `libpysal>=4.14.1` to resolve the regression in `Graph.build_kernel`.","message":"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.","severity":"breaking","affected_versions":"4.14.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"4.12.0 onwards"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All 4.x versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `geopandas`: `pip install geopandas` or `pip install libpysal[plus]` for common optional dependencies.","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.","error":"ModuleNotFoundError: No module named 'geopandas'"},{"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.","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.","error":"KeyError: 'Some ID' (or similar error when accessing weight attributes)"},{"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']`.","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.","error":"ValueError: Geometry must be a Point or Polygon for weights construction."}]}