Reimplementation of static plotting in GeoPandas

[martinfleis]

Project

geopandas

Summary

GeoPandas' plotting method suffers from years of additions, rendering its maintenance cumbersome and the addition of new features problematic. This project proposes a reimplementation of static plotting to overcome the issues while ensuring higher flexibility for downstream users.

submitter

Martin Fleischmann

project lead

@jorisvandenbossche, @martinfleis

Community benefit

Static plotting features in GeoPandas, a core component of the spatial data science ecosystem, have been expanding over time with limited work focused on refactoring its internal components. At the same time, it has always been suboptimal in terms of functionality, generating a long list of feature requests and bug reports. This has reached a situation where the day-to-day maintenance of the related code base has become cumbersome. As a result, changes in terms of both bug fixing and new development have mostly stalled. The plotting tooling requires refactoring because this situation is unsustainable over the long term.

The proposed project should deliver a partial reimplementation of the tooling for static plotting in GeoPandas aimed at easier maintainability, extendability, and an enhanced user experience, while resolving known bugs and feature requests the project is currently tracking.

Given the large user base of GeoPandas, it is expected that the project will result in significantly improved user experience of geospatial plotting. The users will no longer need to manually customise many aspects of the resulting figures, from the unaligned colorbar legends GeoPandas currently produces, to proper ability to map colors to values, and direct registration of symbology with Matplotlib for proper legend handling. Occasionally, users are currently forced to come up with complicated workarounds or rely on other software like QGIS to generate the map outputs. The new plotting implementation proposed in this project should minimize this need.

The result should primarily benefit end users in the production of map outputs. However, it should at the same time simplify depending on GeoPandas plotting in downstream packages like EOmaps or Xvec, which are building on top of existing plotting methods, and streamline integration with other tools for geospatial plotting as Xarray and Cartopy.

Amount requested

9800

Execution plan

The project will be primarily implemented by Martin Fleischmann (@martinfleis), one of the GeoPandas maintainers, in collaboration with the rest of the GeoPandas team and a wider community. The hourly rate used in the development is $70/hr.

The project implementation is divided into five consecutive steps:

1. API design

The current APIs of the GeoDataFrame.plot and GeoSeries.plot methods are bloated from the incremental addition of new features and are no longer sustainable to maintain and expand. Its implementation is hard to follow for new users, with many arguments being applied only conditionally, depending on the underlying geometry type or nature of the data. The API should be revised to ensure it can maintain long-term clarity and expandability. Given GeoPandas already includes an accessor mechanism to expose Pandas plotting methods on GeoPandas objects, one of the designs to be explored is splitting various plotting cases into their own methods.

The API design will be openly discussed with the community in three ways. First, we will reach out to community members heavily involved in geospatial plotting to gather their targeted feedback for the existing and proposed API. Second, we will outline the API on GitHub and use social media and mailing lists to gather feedback on the proposal. This needs to be thoroughly discussed with the community because it may introduce some breaking changes to the current API. Third, we will use the project's community calls to have a synchronous discussion with both team members and a wider community.

Budget allocation: 20 hours / $1,400
Timeline: Month 1-3

2. Refactoring of key building blocks

The key building blocks of the plotting tooling will be refactored with the new API in mind, while ensuring closer integration with Matplotlib's tooling from axes to legend handling, both of which are currently done semi-manually in the GeoPandas code.

The initial implementation will likely be done outside of the code base of GeoPandas’ main branch for faster iteration and limited adverse impact of the attempts at compatibility with the existing implementation. This is a similar approach used in the development of the explore method before, which proved to be efficient. The code will be merged with the main branch in step 5. The existing GeoPandas test suite will be continually used to test the functionality, while new tests will be written alongside.

Budget allocation: 60 hours / $4,200
Timeline: Month 4-6

3. Bug resolution

Some of the bugs in plotting code currently reported in the GeoPandas issue tracker are expected to be fixed alongside the refactoring of step 2. However, others might need specific focus. The third implementation step should therefore resolve existing known bugs to eliminate the current backlog.

Budget allocation: 30 hours / $2,100
Timeline: Month 7-8

4. New functionality

The project will further implement new functionality that has been requested for a long time. This relates to easier customisation of colour mapping, topological colouring, easier inclusion of contextual background maps, among others.

Budget allocation: 20 hours / $1,400
Timeline: Month 9-10

5. Code merge and migration strategy

The final step is to merge the newly developed tooling back into the GeoPandas code base and definition of the migration strategy. Given the API will likely be partially changed, we need to define a way of migrating from the legacy plotting code to the new one, while minimising the impact on users. This strategy will be discussed within the development team and implemented as the last step of the proposed project.

Budget allocation: 10 hours / $700
Timeline: Month 11-12