Metadata-Version: 2.4
Name: carrotcake
Version: 0.3.0
Summary: Automatic data quality reports, cleaning, and EDA reports for messy pandas DataFrames
Author-email: Aaryan Koradia <aaryanhkoradia@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AaryanKoradia/carrotcake
Project-URL: Repository, https://github.com/AaryanKoradia/carrotcake
Keywords: pandas,data-cleaning,data-quality,eda,data-science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Dynamic: license-file

# carrotcake

Automatic data quality reports, cleaning, and EDA reports for messy pandas DataFrames.

Point it at a DataFrame or CSV and it scans every column for the problems that quietly break analyses: inconsistent categorical spellings, missing values, zeros used as a stand-in for missing, numbers stored as text, statistical outliers, and duplicate rows. One function call fixes what it finds, another turns the same data into a full HTML exploratory report. No manual `.value_counts()` archaeology, no hand-written imputation logic.

## CLI

```bash
pip install carrotcake
```
Installs the `carrotcake` command alongside the Python package.

```bash
carrotcake clean data.csv -o data_clean.csv
carrotcake eda data.csv -o report.html
carrotcake report data.csv
```
`clean` writes a cleaned CSV, `eda` writes an HTML exploratory report, `report` prints a quality report straight to your terminal. No Python script required for any of it.

**Few Variations:**

```bash
carrotcake report data.csv --json
carrotcake clean data.csv -o data_clean.csv --group-by Item_Type --handle-outliers --clean-column-names
```

## Features

| Function | What it does | Why it matters |
|---|---|---|
| `quality_report(df)` | Detects missing values, inconsistent category spellings, zero-as-missing columns, numeric-as-text columns, statistical outliers (IQR), and duplicate rows | One call replaces 5-6 manual checks you'd otherwise write by hand for every new dataset |
| `autoclean(df)` | Standardizes categories, imputes missing values (group-aware via `group_by`), fixes zero-as-missing columns, drops duplicates in the correct order | Turns an hour of defensive cleaning code into one function call with sensible, overridable defaults |
| `clean_column_names(df)` | Converts messy headers like `"Item Weight "` or `"Sales($)"` into `item_weight`, `sales` | No more `.str.strip().str.lower()` boilerplate or KeyErrors from a stray trailing space |
| `handle_outliers=True` | Clips statistical outliers (IQR method) to the nearest acceptable bound | Catches data-entry errors and sensor glitches before they skew a mean or a chart axis |
| `compare(df_before, df_after)` | Reports exactly what changed between two versions of a DataFrame: missing values fixed, categories standardized, zeros fixed, rows dropped | Lets you verify `autoclean()` did the right thing instead of trusting it blindly |
| `eda_report(df, output=...)` | Generates a self-contained HTML report: summary stats, histograms, correlation table, category breakdowns | Shareable with anyone, no Jupyter required to view it, pure HTML/CSS so it adds no dependency |
| `report.to_dict()` / `.to_json()` | Machine-readable version of the quality report | Drop into a CI pipeline as a data-quality gate |
| CLI (`carrotcake ...`) | Same functionality from the terminal | Check or clean a CSV without opening an editor |

Zero extra dependencies beyond pandas and numpy, including `eda_report`, whose charts are rendered as plain HTML/CSS rather than through a plotting library.

## Quick start (Python)

```python
import pandas as pd
from carrotcake import quality_report, autoclean

df = pd.read_csv("sales.csv")

print(quality_report(df))
# carrotcake quality report: 8523 rows x 12 columns
#   [missing] Item_Weight: 5.2% missing
#   [inconsistent_categories] Item_Fat_Content: 3 variants: ['LF', 'Low Fat', 'low fat']
#   [zero_as_missing] Item_Visibility: 8.1% zero values
#   [outliers] Item_MRP: 1.8% of values are statistical outliers
#   [duplicates] <rows>: 3 duplicate rows

df_clean = autoclean(df, group_by="Item_Type")
```

`autoclean` will:

- Standardize inconsistent categorical spellings to their most frequent
  original form
- Treat suspiciously frequent zeros in numeric columns as missing values
- Impute missing values (group mean/mode when `group_by` is given, falling
  back to the overall column median/mode)
- Drop exact duplicate rows (run last, since standardizing values above can
  turn near-duplicate rows into exact duplicates)

Two more steps are available but off by default, since they're stronger,
more opinionated transformations:

```python
autoclean(df, clean_column_names=True, handle_outliers=True)
```

- `clean_column_names`: standardizes messy headers like `"Item Weight "` or
  `"Sales($)"` into `item_weight`, `sales`
- `handle_outliers`: clips statistical outliers (IQR method) to the nearest
  acceptable bound

Every step can be disabled individually:

```python
autoclean(df, fix_categories=False, fix_zero_as_missing=False)
```

## EDA reports

```python
from carrotcake import eda_report

eda_report(df, output="report.html")
```

Generates a self-contained HTML report: dataset summary, missing-value
table, per-column stats, a histogram for every numeric column, a
color-graded correlation table, and bar charts of the most common values
per categorical column. Pure HTML/CSS, no plotting library, so the output
file is a few KB rather than a few hundred. Opens in any browser, no server
needed.

## Auditing what changed

```python
from carrotcake import compare

print(compare(df, df_clean))
# carrotcake compare: 8523 -> 8519 rows (4 dropped)
#   [missing_fixed] Item_Weight: 443 -> 0 missing values
#   [categories_standardized] Item_Fat_Content: 5 -> 2 unique values
#   [zero_fixed] Item_Visibility: 526 -> 0 zero values
```

Compares aggregate column-level statistics rather than diffing individual
cells, so it stays meaningful even after row dropping/reordering.

## Programmatic use

```python
report = quality_report(df)
report.to_dict()   # plain dict
report.to_json()   # JSON string, e.g. for a CI data-quality gate
```

## Why

Built after hand-writing this exact cleaning logic across multiple data
analysis projects (retail sales, hotel bookings). `carrotcake` packages it up
so it doesn't need to be rewritten for every new dataset.

## License

MIT
