synthpop-py 1.0.0 release notes

Released on DATE.
First stable public release of synthpop-py.

What’s new in synthpop-py 1.0.0

synthpop-py 1.0.0 is the first stable public release of synthpop-py, providing a native Python implementation of sequential modelling for creating synthetic tabular data.

The release provides a modular workflow for fitting synthesis models to a pandas.DataFrame and generating new synthetic datasets. It supports numeric and non-numeric variables, including floating-point, integer, boolean, string, and categorical variables, as well as missing values.

The initial release provides the core synthesis workflow, configurable synthesis methods, automatic data preparation, reproducible generation, and utility evaluation tools.

✨ New features

Synthesiser

The Synthesiser class is the core of synthpop-py. It provides the main interface for configuring synthesis methods, fitting models to original data, and generating synthetic datasets.

Key capabilities include:

• configurable random_seed for reproducible model fitting and data generation;

• configurable column_order controlling the sequence in which variables are synthesised;

• a configurable default synthesis method through default_syn_method.

• the ability to assign specific synthesis methods to individual variables through special_syn_method.

• generation of a configurable number of synthetic observations; and

• generation of multiple synthetic datasets from the same fitted synthesiser.

The basic workflow is:

from synthpop import Synthesiser

synth = Synthesiser(random_seed=42)
synth.fit(original_data)
synthetic_data = synth.generate(n=1000)

Sequential modelling

synthpop-py uses sequential modelling rather than modelling the joint distribution of all variables simultaneously. Variables are synthesised in a defined order. Each variable can be synthesised conditionally on variables that have already been generated, allowing the model to capture dependencies between variables.

Configurable column ordering

Users can control the order in which variables are synthesised by providing column names or integer column indices through column_order.

Synthesis methods

This release provides three synthesis methods:

• CartMethod: the default method, using Classification and Regression Trees (CART) to model conditional distributions.

• SampleMethod: a sampling-based synthesis method that takes values from the empirical distribution of a variable without using predictors.

• CopyMethod: a copying-based synthesis method that reproduces values directly from the observed data.

Synthesis methods can be configured globally or selected for individual variables. The synthesis-method architecture is designed to be extensible, allowing additional methods to be developed and integrated in future releases. All methods inherit from the base class BaseSynthMethod.

Supported data types

The initial release supports tabular data containing numeric variables, such as floating-point, integer and boolean variables, and non-numeric variables, such as string and categorical variables, as well as missing values. Automatic preprocessing converts data to the representations required by the underlying synthesis models and restores the appropriate data representation in the generated dataset.

Automatic data preparation

Preprocessing required by synthesis methods is handled internally during fitting and generation. This includes:

• Two encoder methods for categorical predictors, PCAEncoder and MeanEncoder;

• two ways to handle missing values in targets, MissingValuePredictor and ReplaceMissingWithValue;

• fitting auxiliary models for numeric target missingness; and

• restoring encoded and missing-value representations after synthesis.

Users generally do not need to perform these steps manually.

Categorical encoding

This release provides two encoding strategies for categorical predictors: PCA encoding for categorical targets and mean encoding for numeric targets.

Missing-value generation

Missing values are explicitly represented during synthesis rather than simply being discarded or imputed. This allows for the generation of missing values in te synthetic data. For categorical targets, missingness can be represented as a target category. For numeric targets, missingness is modelled separately so that synthetic datasets can contain missing values with patterns related to the predictor variables.

Reproducibility

Synthesis can be configured with random_seed to support reproducible results. Random-state handling is managed internally through the synthesis workflow (through RandomStateManager). Reproducibility is expected when using the same data, configuration, software versions and relevant dependencies.

Utility evaluation

This release provides the following utility evaluation functionality in synthpop-py:

• univariate distribution evaluation: compare the distributions of individual variables in the original and synthetic datasets using plot_univariate_distributions.

• pairwise relationship evaluation: quantitatively evaluate the pairwise relationships between variables using the Standardised propensity Mean Squared Error (S_pMSE). The pairwise_spmse measures differences between pairwise joint distributions in the original and synthetic datasets and can be plotted using plot_spmse.

Plotting functionalities

This release provides plotting functionalities for univariate distributions plots and pairwise S_pMSE heatmaps.

🐛 Bug fixes

This is the first stable release of synthpop-py; there are no previous released versions to report bug fixes against.

🔄 API changes

This is the first stable public API release of synthpop-py.

The primary public interface introduced by this release is the Synthesiser class, including its fit(), and generate() workflow and configuration through parameters such as random_seed, column_order, default_syn_method and special_syn_method.

📝 Known issues

We have done our best to make synthpop-py 1.0.0 as solid as possible, but unfortunately there is a known issue in this release:

• Very large datasets may result in memory allocation issues.

⚠️ Deprecation

No deprecations in this release.

💥 Breaking changes

No breaking changes. This is the first stable public release.

⚡ Performance

The initial release focuses on establishing the core synthesis functionality and extensible architecture.

For very large datasets, memory usage may become a limiting factor. Performance characteristics may vary depending on dataset size, variable types, synthesis methods, and model configuration.

📚 Documentation

The release includes documentation covering:

• installation and requirements;

• getting started with synthetic data generation;

• preparing data for synthesis;

• configuring synthesis methods;

• generating synthetic datasets;

• evaluating synthetic data utility;

• examples and configuration options;

• the public Python API; and

• development and contribution workflows.

🧪 Testing/developer tooling

The project is developed with an emphasis on maintainability, reproducibility, testing and extensibility.

The package targets Python 3.11 or later and integrates with the Python data science ecosystem through pandas, scikit-learn and plotly.

🔧 Internal/maintenance

The 1.0.0 release establishes the internal architecture required to support extensible synthesis methods, preprocessing components, reproducible random-state handling, and utility evaluation. These components provide a foundation for extending the synthesis and evaluation capabilities in future releases.