Pandas Matplotlib Explorer

A polished desktop data exploration app built from the original Pandas-Matplotlib-Examples repository

Turned from two script-style demos into a cleaner, testable, maintainable analytics experience — while keeping the original repo's educational spirit intact.

---

Overview

This project starts from the original Pandas + Matplotlib example repo and evolves it into a more serious desktop application.

Instead of scattered plotting scripts and repeated button flows, the repo now provides:

• a single tabbed Tkinter application
• reusable analytics modules
• a cleaner UI/UX layer
• automated tests and CI
• structured docs for setup, risks, manual QA, and architecture

The goal is simple: keep the project beginner-friendly, but make the codebase strong enough to feel like a real software project.

---

Why this rewrite exists

The original repository was useful as a quick demo, but it had the usual limitations of example-style code:

• UI logic and data logic were tightly coupled
• there was no real package structure
• testing was missing
• repeated plot actions created friction in the UX
• future changes would have become messy fast

This version keeps the same learning value, but adds the engineering discipline missing from a one-file demo.

---

Highlights

Product / UX

• One app, two datasets: Netflix and Pokemon are now accessible from a single shell
• Tabbed interface instead of many disconnected actions
• In-window charts instead of extra matplotlib popup chaos
• Metric cards for faster scanning
• Preview tables for quick data validation
• Save current chart as PNG directly from the UI
• Cleaner dark theme for a more modern desktop feel

Engineering

• src/-based package structure
• isolated loaders, analytics, chart renderers, and UI modules
• linting with Ruff
• automated tests with Pytest
• packaging via pyproject.toml
• GitHub Actions CI
• compatibility launchers retained for the original script entry points

---

What you can explore

Netflix dataset

• titles by type
• top countries
• rating mix
• top genres
• release trend

Pokemon dataset

• top types
• species mix
• tallest Pokemon
• heaviest Pokemon
• easiest to catch
• friendliest Pokemon
• fastest Pokemon
• attack vs defense comparison

---

Tech stack

• Python 3.11+
• Tkinter for the desktop UI
• Pandas for data wrangling
• Matplotlib for charts
• Pytest for tests
• Ruff for linting and formatting

---

Project structure

.
├── 1-Pandas-Matplotlib-examples-CSV.py
├── 2-Pandas-Matplotlib-examples-JSON-pokemons.py
├── data/
│   ├── netflix_titles.csv
│   └── pokemon_db_dataset.json
├── docs/
│   ├── ADR.md
│   ├── MANUAL_TEST_PLAN.md
│   ├── PROJECT_HEALTH_CHECK.md
│   ├── RISK_REGISTER.md
│   ├── SECURITY_AUDIT.md
│   └── SETUP_GUIDE.md
├── src/
│   ├── pandas_matplotlib_explorer/
│   │   ├── analytics/
│   │   ├── charts/
│   │   ├── data/
│   │   ├── ui/
│   │   └── app.py
│   └── tests/
├── .github/workflows/
├── CONTRIBUTING.md
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txt

---

Architecture at a glance

Datasets
   ↓
Loaders
   ↓
Analytics services
   ↓
Chart renderers
   ↓
Tkinter UI

Layer responsibilities

• Loaders: read and normalize dataset input
• Analytics: calculate summaries, filters, rankings, and chart-ready outputs
• Renderers: generate Matplotlib figures consistently
• UI: manage layout, controls, preview tables, and export flow

This separation is what makes the app easier to test and extend.

---

Quick start

1) Create a virtual environment

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

2) Install dependencies

pip install -r requirements.txt -r requirements-dev.txt
pip install -e .

3) Run the app

python -m pandas_matplotlib_explorer.app

---

Legacy launchers

To preserve the original repo entry experience, the old script names still work as compatibility launchers:

python 1-Pandas-Matplotlib-examples-CSV.py
python 2-Pandas-Matplotlib-examples-JSON-pokemons.py

---

Development workflow

Run lint and format checks

ruff check .
ruff format --check .

Run tests

pytest

Build distributables

python -m build --sdist --wheel

---

Manual QA checklist

Before pushing visual changes, verify:

1. the app launches without errors
2. both tabs render correctly
3. dropdown filters update charts as expected
4. preview tables remain readable
5. chart export creates a PNG successfully
6. no extra matplotlib popup windows appear unexpectedly

See the full manual plan in docs/MANUAL_TEST_PLAN.md.

---

Documentation

• Setup guide
• Architecture decisions
• Project health check
• Risk register
• Security audit
• Contribution guide

---

Quality gates

This repo is designed to be more than a visual demo.

Expected baseline:

• lint passes
• format checks pass
• test suite passes
• packaging works
• manual smoke checks are documented

---

Roadmap ideas

Potential next upgrades:

• search within tables
• richer filtering controls
• dataset import from user-selected files
• chart presets and favorites
• lightweight settings persistence
• screenshot section in the README

---

Contributing

If you want to improve the app, start here:

1. read CONTRIBUTING.md
2. review the docs in docs/
3. run the checks before opening a PR

---

Acknowledgements

• the original Pandas-Matplotlib-Examples repository for the initial learning-oriented concept
• the dataset sources and their original licenses/attribution requirements

---

License

This repository is intended for educational and portfolio use. If you redistribute the datasets or publish a derivative project, keep the original dataset licensing and attribution requirements intact.