Metadata-Version: 2.4
Name: maheeds
Version: 0.1.1
Summary: A beginner-friendly dataset understanding library for Data Science learners.
Author: Maheed
License: MIT
Project-URL: Homepage, https://github.com/yourusername/maheeds
Project-URL: Documentation, https://github.com/yourusername/maheeds/tree/main/docs
Project-URL: Repository, https://github.com/yourusername/maheeds
Project-URL: Bug Tracker, https://github.com/yourusername/maheeds/issues
Keywords: data science,pandas,eda,exploratory data analysis,beginner,education,dataset understanding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.25
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# maheeds 📊

> **A beginner-friendly dataset understanding library for Data Science learners.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](pyproject.toml)

---

## Project Vision

Most students struggle when they receive a dataset for the first time.They don't know:

- What the dataset actually contains
- Which columns are numbers vs categories
- Which columns have missing values
- What to use as the **target variable**
- What **questions** they can even ask

**maheeds** solves this.

One function call — `md.understand(df)` — gives you a complete, beginner-friendly
analysis of your dataset so you know exactly where to begin.

---

## Quick Start

```python
import pandas as pd
import maheeds as md

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

# Run the full analysis
report = md.understand(df)

# View the summary table
print(report.summary)

# Get all details as a dictionary
data = report.to_dict()

# Save a beautiful HTML report
report.to_html("my_report.html")
```

---

## Installation

```bash
# Install from PyPI
pip install maheeds

# Or install locally from source
git clone https://github.com/yourusername/maheeds.git
cd maheeds
pip install -e .
```

**Requirements:** Python 3.11+, pandas 2.0+, numpy 1.25+

---

## Example Output

Given a placement dataset, `report.summary` returns:

```
          Metric                    Value
            Rows                      200
         Columns                        9
Numerical Columns                        3
Categorical Columns                      5
Datetime Columns                         0
 Missing Columns                         1
   Missing Cells                         9
  Duplicate Rows                         3
Constant Columns                         1
Potential Target Columns          placed, internship
```

### Suggested Questions

```
❓ Does cgpa affect placed?
❓ Does department affect placed?
❓ Does attendance affect placed?
❓ Does internship affect placed?
❓ Is there a relationship between cgpa and attendance?
❓ What is the distribution of cgpa?
```

### HTML Report

Call `report.to_html("report.html")` to save a styled, browser-ready HTML report
with colour-coded badges, missing value detail, target suggestions, and questions.

---

## 🔌 Full API Reference

### `md.understand(df)`

Analyses a pandas DataFrame and returns an `UnderstandReport` object.

```python
report = md.understand(df)
```

**Parameters**

| Parameter | Type             | Description            |
| --------- | ---------------- | ---------------------- |
| `df`    | `pd.DataFrame` | The dataset to analyse |

**Raises**

| Exception      | When                          |
| -------------- | ----------------------------- |
| `TypeError`  | If `df` is not a DataFrame  |
| `ValueError` | If `df` is completely empty |

---

### `UnderstandReport` attributes

| Attribute                | Type          | Description                 |
| ------------------------ | ------------- | --------------------------- |
| `rows`                 | `int`       | Total row count             |
| `columns`              | `int`       | Total column count          |
| `numerical_columns`    | `list[str]` | Numerical column names      |
| `categorical_columns`  | `list[str]` | Categorical column names    |
| `datetime_columns`     | `list[str]` | Datetime column names       |
| `missing_columns`      | `list[str]` | Columns with missing values |
| `missing_cells_count`  | `int`       | Total missing cells         |
| `missing_per_column`   | `dict`      | Missing count per column    |
| `constant_columns`     | `list[str]` | Constant (useless) columns  |
| `duplicate_rows_count` | `int`       | Duplicate row count         |
| `potential_targets`    | `list[str]` | Suggested target columns    |
| `target_reasons`       | `dict`      | Reason per suggestion       |
| `questions`            | `list[str]` | Beginner EDA questions      |

---

### `UnderstandReport` methods

| Method                          | Returns          | Description                 |
| ------------------------------- | ---------------- | --------------------------- |
| `report.summary`              | `pd.DataFrame` | Tidy Metric → Value table  |
| `report.to_dict()`            | `dict`         | Full results as dictionary  |
| `report.to_html()`            | `str`          | HTML string                 |
| `report.to_html("path.html")` | `str`          | HTML string + saves to file |

---

## 📁 Package Structure

```
maheeds/
├── core/
│   ├── shape.py          # Row / column count
│   ├── datatype.py       # Numerical / categorical / datetime detection
│   ├── missing.py        # Missing value analysis
│   ├── uniqueness.py     # Constant columns + duplicate rows
│   ├── target.py         # Target column suggestions
│   └── questions.py      # Beginner question generation
├── reports/
│   ├── dataframe_report.py   # Summary DataFrame builder
│   └── html_report.py        # HTML report renderer
├── models/
│   └── report.py             # UnderstandReport dataclass
├── understand.py             # Public API entry point
└── __init__.py
```

---

## Running Tests

```bash
# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=maheeds --cov-report=term-missing
```

---

## Future Roadmap

### Version 0.2 – Correlation Insights

- Automatically compute correlations between numerical columns
- Highlight the top positive and negative correlations
- Warn about multicollinearity

### Version 0.3 – Visualization Suggestions

- Recommend the right chart type for each column pair
- Generate matplotlib / seaborn chart code snippets
- Export a visual EDA starter notebook

### Version 0.4 – Dataset Health Score

- A 0–100 score rating data quality
- Breakdown by completeness, consistency, uniqueness, and relevance
- Actionable improvement tips

### Version 0.5 – Beginner EDA Assistant

- Interactive CLI / notebook widget
- Step-by-step guided EDA workflow
- Integrated with pandas-profiling style deep dives

---

## 🤝 Contributing

Pull requests are welcome!
Please open an issue first to discuss what you'd like to change.

```bash
git clone https://github.com/yourusername/maheeds.git
cd maheeds
pip install -e ".[dev]"
pytest
```

---

## 📜 License

[MIT](LICENSE) © 2026 Maheed
