dataSandbox 0.1.0

A user-friendly synthetic data generator with automatic topological sorting

DataSandbox: Synthetic Data Generator

A lightweight, rule-based engine for generating realistic synthetic datasets. It allows you to define complex relationships between variables using a straightforward mathematical schema, ensuring your generated data maintains logical consistency and statistical correlations.

---

1. Why is this needed?

In modern data science and software development, getting access to high-quality, realistic data is often difficult due to privacy regulations, data scarcity, or security concerns. This tool is essential for:

• Protecting Privacy: Generate mock datasets that mirror real user behavior without exposing sensitive or personally identifiable information.
• Testing Machine Learning Models: Create controlled, synthetic environments with known correlations to evaluate how well your models capture specific patterns.
• Stress-Testing Applications: Rapidly produce thousands or millions of rows of relational data to validate database performance and system scalability.
• Automating Mock Data: Replace tedious manual mock-data creation with an automated, reproducible, and mathematically sound architecture.

---

2. What tasks does it perform?

• Dependency Resolution: Automatically calculates the correct execution order for your columns. If one column depends on another, the engine guarantees the parent data is generated first.
• Distribution Generation: Seamlessly produces normal, uniform, integer, or weighted categorical distributions based on your statistical parameters.
• Linear Combinations: Calculates continuous variables based on the weighted sum of parent variables, while injecting realistic statistical noise.
• Conditional Branching: Routes data generation through entirely different logic paths depending on the discrete category of a parent column.
• DataFrame Export: Compiles all generated relationships directly into a clean, ready-to-use tabular format.

---

3. User Guide: Understanding Mathematical Categories

The core philosophy of this tool is that every column in your dataset is defined by a specific mathematical rule. You organize these rules into a schema, and the engine handles the rest.

Here are the three mathematical categories you can apply to your columns, what they represent, and how they function:

A. The Independent Rule

What it means: This is a base-level generator. A column with this rule relies on absolutely nothing else in the dataset; it is mathematically independent. When to use it: Use this for foundational data points that kick off your logic tree, such as Age, Gender, Base Economy, or starting geographic zones. How to apply it: You define the core statistical method you want to use (such as generating random integers, floats, or picking from a list of choices) and provide the necessary statistical boundaries, like minimums, maximums, or probability weights.

B. The Conditional Rule

What it means: This is a branching generator. The output of a conditional column changes entirely depending on the specific value generated by a single parent column. When to use it: This is perfect for cascading categorical logic. For example, a person's expected education level or housing status might have completely different probability distributions depending on which city tier they live in. How to apply it: You specify which parent column to watch, and then provide a map of conditions. For every possible value the parent column might output, you assign a brand new Independent rule to dictate how the child column should behave in that specific scenario.

C. The Linear Rule

What it means: This is a continuous correlation generator. It creates numerical values by applying mathematical weights to one or more parent columns, adding a starting baseline, and injecting random standard deviation to make the data look organic. When to use it: Use this when numerical values naturally scale based on other numbers in your dataset. For instance, a salary typically increases as years of experience increase, or a monthly spend increases based on a combination of salary and credit score. How to apply it: You define exactly which parent columns influence the result and by what multiplier. Then, you provide a base bias (the starting value before any additions) and define the noise level to ensure the resulting correlation isn't perfectly artificial.