maheeds 0.1.1

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

maheeds 📊

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

---

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

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

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

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

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

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

---

📜 License

MIT © 2026 Maheed