# HMASynthesizer The HMA Synthesizer uses hierarchical ML algorithm to learn from real data and generate synthetic data. The algorithm uses classical statistics. ```python from sdv.multi_table import HMASynthesizer synthesizer = HMASynthesizer(metadata) synthesizer.fit(data) synthetic_data = synthesizer.sample() ``` {% hint style="warning" %} **Is the HMASynthesizer suited for your dataset?** The HMASynthesizer is designed to capture correlations between different tables with high quality. The algorithm is optimized for datasets with around 5 tables and 1 level of depth (eg. a parent and its child table). If you have a complex schema, use the [`simplify_schema`](https://docs.sdv.dev/sdv/data-preparation/loading-data#simplify_schema) function to create a smaller, simpler dataset for HMASynthesizer. **Want to model more complex graphs?** You can [reach out to us](https://datacebo.com/support/) to inquire about our paid SDV plans. SDV Enterprise supports work many more tables, so you will not have to use `simplify_schema` on the paid plan. {% endhint %} ## Creating a synthesizer When creating your synthesizer, you are required to pass in a [Metadata](https://docs.sdv.dev/sdv/multi-table-data/data-preparation/creating-metadata) object as the first argument. ```python synthesizer = HMASynthesizer(metadata) ``` All other parameters are optional. You can include them to customize the synthesizer. ### Parameter Reference **`locales`**: A list of locale strings. Any PII columns will correspond to the locales that you provide.
(default) ['en_US']Generate PII values in English corresponding to US-based concepts (eg. addresses, phone numbers, etc.)
<list>

Create data from the list of locales. Each locale string consists of a 2-character code for the language and 2-character code for the country, separated by an underscore.

For example ["en_US", "fr_CA"].

For all options, see the Faker docs.

```python synthesizer = HMASynthesizer( metadata, locales=['en_US', 'en_CA', 'fr_CA'] ) ``` `verbose`: A boolean describing whether or not to show the progress when fitting the synthesizer.
(default) TrueShow the progress when fitting the synthesizer. You'll see printed progress bars during every stage of the fitting process: Preprocessing, learning relationships and modeling tables.
FalseDo not show progress. The synthesizer will fit the data silently.
### set\_table\_parameters The HMA Synthesizer is a multi-table algorithm that models each individual table as well as the connections between them. You can get and set the parameters for each individual table. **Parameters** * (required) `table_name`: A string describing the name of the table * `table_parameters`: A dictionary mapping the name of the parameter (string) to the value of the parameter (various). See [GaussianCouplaSynthesizer](https://docs.sdv.dev/sdv/single-table-data/modeling/synthesizers/gaussiancopulasynthesizer#parameter-reference) for more details. **Output** (None) ```python synthesizer.set_table_parameters( table_name='guests', table_parameters={ 'enforce_min_max_values': True, 'default_distribution': 'truncnorm', 'numerical_distributions': { 'checkin_date': 'uniform', 'amenities_fee': 'beta' } } ) ``` {% hint style="warning" %} **Which distributions can I use with the HMA?** Please note that the HMA algorithm is only compatible with parametric distributions that have a predefined number of parameters. You will not be able to use the `'gaussian_kde'` distribution with HMA. {% endhint %} ### get\_parameters Use this function to access the all parameters your synthesizer uses -- those you have provided as well as the default ones. **Parameters** (None) **Output** A dictionary with the table names and parameters for each table. {% hint style="info" %} These parameters are only for the multi-table synthesizer. To get individual table-level parameters, use the `get_table_parameters` function. The returned parameters are a copy. Changing them will not affect the synthesizer. {% endhint %} ```python synthesizer.get_parameters() ``` ```python { 'locales': ['en_US', 'fr_CA'], ... } ``` ### get\_table\_parameters Use this function to access the all parameters a table synthesizer uses -- those you have provided as well as the default ones. **Parameters** * (required) `table_name`: A string describing the name of the table **Output** A dictionary with the parameter names and the values ```python synthesizer.get_table_parameters(table_name='users') ``` ```python { 'synthesizer_name': 'GaussianCopulaSynthesizer', 'synthesizer_parameters': { 'default_distribution': 'beta', ... } } ``` ### get\_metadata Use this function to access the metadata object that you have included for the synthesizer **Parameters** None **Output** A [Metadata](https://docs.sdv.dev/sdv/multi-table-data/data-preparation/creating-metadata) object ```python metadata = synthesizer.get_metadata() ``` {% hint style="info" %} The returned metadata is a copy. Changing it will not affect the synthesizer. {% endhint %} ## Learning from your data To learn a machine learning model based on your real data, use the `fit` method. ### fit **Parameters** * (required) `data`: A dictionary mapping each table name to a pandas.DataFrame containing the real data that the machine learning model will learn from **Output** (None) {% hint style="info" %} **Technical Details:** HMA, which stands for *Hierarchical Modeling Algorithm*, uses a recursive technique to model the parent-child relationships of a multi-table datasets. At a base level, it uses Gaussian Copulas to model individual tables. See: * [GaussianCopulaSynthesizer](https://docs.sdv.dev/sdv/single-table-data/modeling/synthesizers/gaussiancopulasynthesizer) for more information on the GaussianCopula framework * The [Synthetic Data vault paper](https://dai.lids.mit.edu/wp-content/uploads/2018/03/SDV.pdf), published in the International Conference on Data Science and Advance Analytics, October 2016 {% endhint %} ### get\_learned\_distributions After fitting this synthesizer, you can access the marginal distributions that were learned to estimate the shape of each column. **Parameters** * (required) `table_name`: A string with the name of the table **Output** A dictionary that maps the name of each learned column to the distribution that estimates its shape ```python synthesizer.get_learned_distributions(table_name='guests') ``` ``` { 'amenities_fee': { 'distribution': 'beta', 'learned_parameters': { 'a': 2.22, 'b': 3.17, 'loc': 0.07, 'scale': 48.5 } }, 'checkin_date': { ... }, ... } ``` For more information about the distributions and their parameters, visit the[ Copulas library](https://sdv.dev/Copulas/). {% hint style="info" %} Learned parameters are only available for parametric distributions. For eg. you will not be able to access learned distributions for the `'gaussian_kde'` technique. In some cases, the synthesizer may not be able to fit the exact distribution shape you requested, so you may see another distribution shape (eg. `'truncnorm'` instead of `'beta'`). {% endhint %} ## Saving your synthesizer Save your trained synthesizer for future use. ### save Use this function to save your trained synthesizer as a Python pickle file. **Parameters** * (required) `filepath`: A string describing the filepath where you want to save your synthesizer. Make sure this ends in `.pkl` **Output** (None) The file will be saved at the desired location ```python synthesizer.save( filepath='my_synthesizer.pkl' ) ``` ### load (utility function) Use this utility function to load a trained synthesizer from a Python pickle file. After loading your synthesizer, you'll be able to sample synthetic data from it. **Parameters** * (required) `filepath`: A string describing the filepath of your saved synthesizer **Output** Your synthesizer object ```python from sdv.utils import load_synthesizer synthesizer = load_synthesizer( filepath='my_synthesizer.pkl' ) ``` *This utility function works for any SDV synthesizer.* ## What's next? After training your synthesizer, you can now sample synthetic data. See the [Sampling](https://docs.sdv.dev/sdv/multi-table-data/sampling) section for more details. ```python synthetic_data = synthesizer.sample(scale=1.0) ``` {% hint style="info" %} **Want to improve your synthesizer?** Input logical rules in the form of constraints, and customize the transformations used for pre- and post-processing the data. For more details, see [Advanced Features](https://docs.sdv.dev/sdv/multi-table-data/modeling/customizations). {% endhint %} ## FAQs
How do I cite the HMA? *Neha Patki, Roy Wedge, Kalyan Veeramachaneni.* **The Synthetic data vault.** DSAA, 2016. ``` @inproceedings{ HMA, title={The Synthetic data vault}, author={Patki, Neha and Wedge, Roy and Veeramachaneni, Kalyan}, booktitle={IEEE International Conference on Data Science and Advanced Analytics (DSAA)}, year={2016}, pages={399-410}, doi={10.1109/DSAA.2016.49}, month={Oct} } ```
What happens if columns don't contain numerical data? This synthesizer models non-numerical columns, including columns with missing values. Although the HMA algorithm is designed for only numerical data, this synthesizer converts other data types using Reversible Data Transforms (RDTs). To access and modify the transformations, see [Advanced Features](https://docs.sdv.dev/sdv/multi-table-data/modeling/customizations).