Metadata-Version: 2.4
Name: dataSandbox
Version: 0.1.0
Summary: A user-friendly synthetic data generator with automatic topological sorting
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0

# 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.
