GSoC Week 9 & 10: Deprecations, How-To Guides, and Plotting Refactors

Hi everyone! Here’s my update for Weeks 9 and 10 of my GSoC 2025 journey with the sbi project. These two weeks were focused on adding deprecation warnings, improving documentation with how-to guides, and starting the refactor of plotting utilities.

Deprecation Warnings and Migration to Dataclasses

With the introduction of posterior parameter dataclasses, users still had the option to configure posteriors using either dictionaries or the new dataclasses. Since dictionary support will be removed in a future release, I worked on making this transition smoother by:

• Adding deprecation warnings for dictionary-based parameters in the build_posterior method across all trainer classes (PR #1627).
• Linking the deprecation warning to a new how-to guide that explains how to migrate to dataclasses.
• Updating tests and tutorials to use dataclasses by default, while keeping dictionary support until it’s fully removed.

This ensures users are aware of the upcoming change and have clear documentation to guide them through the migration.

Improving Documentation

To complement the deprecation work, I:

• Added a dedicated how-to guide on using the new dataclasses.
• Updated the tutorials across the project to reflect the recommended workflow with posterior parameter dataclasses instead of dictionaries.

Refactoring Plotting Utilities

Another major focus was beginning the refactor of plotting utilities, specifically pairplot and marginal_pairplot (PR #1631).

The goals were to modularize the code, introduce typed configurations, and improve maintainability while keeping backward compatibility. Key changes include:

• Introducing new dataclasses for plot configuration:
  • Diagonal plots: KdeDiagOptions, HistDiagOptions, ScatterDiagOptions.
  • Off-diagonal plots: KdeOffDiagOptions, HistOffDiagOptions, ScatterOffDiagOptions, ContourOffDiagOptions, PlotOffDiagKwargs.
  • Figure-level options: FigOptions.
• Extracted helper functions into a separate file to keep the main plotting module focused and easier to navigate.
• Modularizing repeated logic and restructuring the flow of the pairplot and marginal_pairplot APIs.
• Ensuring backward compatibility with dictionary configurations.
• Updating the plotting tutorial to use the new dataclass-based API.

To support this, I also reviewed matplotlib’s plotting methods and updated the docstrings for figure-level customization fields with direct links to the relevant matplotlib documentation for better discoverability.

Density Estimator Flexibility

I opened a follow-up PR (PR #1633) to update the DensityEstimatorBuilder protocol. The refactor makes the builder more flexible, enabling it to work seamlessly with different types of density estimators.

These two weeks were a mix of user-facing improvements (deprecation warnings, tutorials, how-to guides), refactoring core utilities (plotting functions with typed dataclasses), and API improvements (flexible density estimator builder). Together, these changes improve both usability and maintainability, while preparing the codebase for smoother transitions in future releases.