Skip to content

PEP 13: Refactor PySAL Using Submodules

Sergio Rey edited this page Jan 16, 2017 · 4 revisions

PEP 13: Refactor PySAL Using Submodules

PEP 13
Title Refactor PySAL Using Submodules
Author Serge Rey
Status Draft
Type Infrastructure
Created 2016-12-16
Post-History 2016-12-20



This is a concrete proposal in response to PEP 12: Refactor PySAL Code Base that relies on submodules.

Structure of PySAL Organizational account

The public PySAL repositories would consist of

Repository Description
pysal meta-package
pysal_core base library modules
esda exploratory spatial data analysis
mapclassify map classification
spreg spatial econometrics
spatial_dynamics Markov and event modules
inequality inequality
pysal-viz visualization
spint spatial interaction
pysal-points point pattern analysis
pysal-network spatial analysis on networks
region regionalization
pysal-examples example datasets


The pysal package would have each of the remaining packages as submodules.

Each of the remaining packages, other than pysal-core, would have pysal-core as a dependency via import.

This would facilitate different types of use cases for the library as well as the individual packages.

Use cases

All in one installation

pip install pysal


conda install pysal

Pick and choose

pip install pysal-points pysal-viz


conda install pysal-points pysal-viz

Package naming conventions

In some cases (i.e., pysal-points) the name has been extended to differentiate pysal from a general library name (points). This is because each of the repositories should be a package in its own right and thus installable via pip where an unambiguous name is required.

Standards for Top-Level PySAL repositories

To faciliate use of the top level projects within the PySAL meta-package, the former repositories may consider the following conventions.

Code layout


Testing conventions

PySAL has relied on nose for integration tests, so the directory structure given above would allow for integration testing under the new organization scheme.


In contrast to the current approach where documentation is built across all the submodules to generate the PySAL documentation, this new model would have lighter weight documentation for the meta project that would simply link to the documentation of the individual modules. Maintainers would be reponsible for the documentation of each module.

Example of refactoring

This example uses the points-contrib module:

git clone pysal-copy
mv pysal-copy pysal-points
cd pysal-points
git fetch origin
git branch -a
git checkout -b points origin/points_contrib
git filter-branch --subdirectory-filter pysal/contrib/points -- --all

You can’t perform that action at this time.