FAQ
===

Here, we've compiled answers to commonly asked questions about MetaSynth and its development. If you have any other questions, need further assistance, or want to discuss something related to MetaSynth, don't hesitate to contact us directly. You can find our contact details on the :doc:`contact page </about/contact>`. We're more than happy to assist you and provide any additional information you may need.

**I found a bug/issue, where can I report it?**
-----------------------------------------------
If you encounter any bugs or have identified an issue with MetaSynth, we encourage you to report it on our `GitHub issue tracker <https://github.com/sodascience/metasynth/issues>`_. This allows us to track and address the problem efficiently. Alternatively, you can find out how to contact us through the details provided in our :doc:`contact page </about/contact>`.

**I would like to contribute to the project, how do I get started?**
---------------------------------------------------------------------
That's fantastic! We welcome and appreciate contributions from the community. To get started with contributing to MetaSynth, please refer to our detailed guide in the :doc:`/developer/developer` section. It contains all the information you need to start contributing.

**Can I use pandas DataFrames with MetaSynth?**
-----------------------------------------------
Yes, you can use pandas DataFrames with MetaSynth. However, please note that MetaSynth internally utilizes polars for consistent typing and handling of non-existing data. Although supplying pandas DataFrames is supported, there may be conversion issues, particularly in certain edge cases. To ensure optimal functionality, we recommend creating polars DataFrames. The synthetic datasets generated by MetaSynth are always in the form of polars DataFrames. If needed, you can easily convert them back to pandas DataFrames using the `df_pandas = df_polars.to_pandas()` method.

**What is the classification of MetaSynth's synthetic datasets?**
------------------------------------------------------------------
MetaSynth's synthetically generated datasets are classified as `Synthetically-Augmented Plausible datasets <https://www.ons.gov.uk/methodology/methodologicalpublications/generalmethodology/onsworkingpaperseries/onsmethodologyworkingpaperseriesnumber16syntheticdatapilot>`__, as categorized by the Office for National Statistics (ONS).

.. epigraph:: ONS criteria for a Synthetically-augmented plausible dataset:
   
   * Preserve the format and record-level plausibility as detailed previously and replicate marginal (univariate) distributions where possible.
   * Constructed based on the real dataset, values are generated based on observed distributions (with added fuzziness and smoothing) but no attempt made to preserve relationships.
   * Missing value codes and their frequency is to be preserved.
   * Disclosure control evaluation is necessary case by case, special care to be taken with names and so on.
   * To be used for extended code testing, minimal analytical value, non-negligible disclosure risk.

**What is a MetaFrame?**
-------------------------
A MetaFrame is a fitted model that describes the aggregate structure and characteristics of a dataset. It functions like (statistical) metadata for the dataset, providing information about the dataset without revealing the actual data itself. When MetaSynth is fed a dataset (as DataFrame), it generates this MetaFrame to capture certain key aspects of the data.

Key elements encapsulated in a MetaFrame include variable names, their data types, the proportion of missing values, and the parameters of the distributions that these variables follow in the dataset. This information is sufficient to understand the overall structure and attributes of the data, without divulging the exact data points.

When a MetaFrame is created from an input dataset, it can be exported for auditing or manual editing. 

In the MetaSynth workflow, once you have a MetaFrame, MetaSynth can generate synthetic data that aligns with the MetaFrame. This synthetic data shares the structural and distributional characteristics (as defined in the MetaFrame) with the original data but does not contain any actual data points from the original dataset, thus preserving privacy.

The process of generating synthetic data solely from the MetaFrame ensures that this synthetic data is separate and independent from the original sensitive source data, thereby reducing privacy concerns while sharing or distributing this synthetic data.

**I encountered the warning: "Variable PassengerId seems unique, but not set to be unique." What should I do?**
-----------------------------------------------------------------------------------------------------------------
This warning occurs when MetaSynth detects a column, that seems to have unique values in the real dataset but isn't specified to be unique in the fitting of the :obj:`MetaFrame<metasynth.dataset.MetaFrame>`. To address this, you can use the `spec` parameter to create a specification dictionary and indicate that the column should have unique values. Here's an example of how to do this (in this example ``PassengerId`` is the column with unique values):

.. code-block:: python

   # Create a specification dictionary, and specify the column as unique:
   var_spec = {
      "PassengerId": {"unique": True}
   }

   # Call the fit_dataframe() function, passing in the `var_spec` dictionary as the `spec` argument
   mf = MetaFrame.fit_dataframe(df, spec=var_spec)

More information on how to use the optional parameters in the :meth:`metasynth.MetaFrame.fit_dataframe() <metasynth.dataset.MetaFrame.fit_dataframe>` function can be found in :doc:`/usage/generating_metaframes`.

