plotmind 0.1.0__tar.gz

plotmind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PlotMind Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plotmind-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include plotmind *.py

plotmind-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: plotmind
+Version: 0.1.0
+Summary: Convert any CSV into meaningful graphs automatically.
+Home-page: https://github.com/yourusername/plotmind
+Author: PlotMind Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/plotmind
+Project-URL: Issues, https://github.com/yourusername/plotmind/issues
+Keywords: csv,visualization,charts,graphs,data,plotly,matplotlib
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: kaleido>=0.2.1
+Provides-Extra: seaborn
+Requires-Dist: seaborn>=0.11.0; extra == "seaborn"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PlotMind 📊
+
+> **Convert any CSV into meaningful graphs automatically.**
+
+PlotMind analyses your CSV, detects column types, recommends the best chart, and generates it — with zero manual configuration. It supports interactive charts via Plotly and static charts via Matplotlib, and can export to PNG, PDF, or HTML.
+
+---
+
+## Installation
+
+```bash
+pip install plotmind
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/plotmind
+cd plotmind
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### Python API
+
+```python
+from plotmind import load_csv, clean_dataframe, plot, export
+
+# 1. Load
+df = load_csv("sales.csv")
+
+# 2. Clean (handles missing values, duplicates, type coercion)
+df = clean_dataframe(df, verbose=True)
+
+# 3. Plot – auto-detects best chart
+fig = plot(df)
+
+# 4. Export
+export(fig, "sales_chart.html")
+export(fig, "sales_chart.png")
+```
+
+### Command-Line Interface
+
+```bash
+# Auto-detect best chart and display
+plotmind sales.csv
+
+# Choose a specific chart type
+plotmind sales.csv --chart bar
+
+# Specify axes
+plotmind sales.csv --chart scatter --x revenue --y profit
+
+# Export to file without displaying
+plotmind sales.csv --chart line --export output.html
+
+# Use matplotlib backend
+plotmind sales.csv --backend matplotlib --export chart.png
+
+# Show column info and recommendation
+plotmind sales.csv --info
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Auto-chart selection** | Detects the best chart based on column types |
+| **Column type detection** | Identifies numerical, categorical, datetime, boolean columns |
+| **Data cleaning** | Fills missing values, removes duplicates, fixes types |
+| **Interactive charts** | Plotly backend for zoom/hover/pan |
+| **Static charts** | Matplotlib backend for PNG/PDF output |
+| **Export** | PNG, PDF, HTML, SVG |
+| **CLI** | Full command-line interface |
+
+---
+
+## Chart Types
+
+PlotMind supports these chart types (auto-selected or manually chosen):
+
+| Chart | When auto-selected |
+|---|---|
+| `histogram` | Single numerical column |
+| `bar` | Categorical + numerical (high cardinality) |
+| `pie` | Categorical + numerical (≤6 unique categories) |
+| `scatter` | Two numerical columns |
+| `line` | Datetime + numerical |
+| `heatmap` | Many numerical columns (correlation matrix) |
+| `box` | Box plot for distribution |
+
+---
+
+## API Reference
+
+### `load_csv(filepath, **kwargs) → DataFrame`
+Load a CSV and validate it.
+
+```python
+df = load_csv("data.csv")
+```
+
+---
+
+### `clean_dataframe(df, verbose=False) → DataFrame`
+Clean: fill missing values, remove duplicates, coerce types.
+
+```python
+df = clean_dataframe(df, verbose=True)
+```
+
+---
+
+### `detect_columns(df) → dict`
+Return a dict of `{column_name: type}` for each column.
+Types: `numerical`, `categorical`, `datetime`, `boolean`, `unknown`.
+
+```python
+from plotmind import detect_columns
+types = detect_columns(df)
+# {'age': 'numerical', 'city': 'categorical', ...}
+```
+
+---
+
+### `recommend_chart(df, x=None, y=None) → (chart, x_col, y_col)`
+Recommend the best chart. Returns a tuple.
+
+```python
+from plotmind import recommend_chart
+chart, x, y = recommend_chart(df)
+print(chart)  # e.g. 'scatter'
+```
+
+---
+
+### `plot(df, chart=None, x=None, y=None, title=None, backend='plotly', show=True) → Figure`
+Generate a chart. Returns the figure object.
+
+```python
+fig = plot(df, chart="bar", x="city", y="sales", title="Sales by City")
+fig = plot(df, backend="matplotlib", show=False)  # static, no display
+```
+
+---
+
+### `export(fig, path, fmt=None) → str`
+Export the figure. Format is inferred from the file extension.
+
+```python
+export(fig, "chart.png")    # PNG (requires kaleido for Plotly)
+export(fig, "chart.pdf")    # PDF
+export(fig, "chart.html")   # Interactive HTML (Plotly) or embedded HTML (Matplotlib)
+export(fig, "chart.svg")    # SVG
+```
+
+---
+
+## Utils
+
+```python
+from plotmind.utils import preview, column_stats, filter_columns
+
+preview(df)               # Print head
+column_stats(df)          # Summary DataFrame with null counts, unique values, etc.
+filter_columns(df, types=["number"])  # Get only numeric column names
+```
+
+---
+
+## Testing
+
+```bash
+pip install plotmind[dev]
+pytest tests/ -v
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.8
+- pandas ≥ 1.3
+- plotly ≥ 5.0
+- matplotlib ≥ 3.4
+- kaleido ≥ 0.2.1  *(for Plotly static image export)*
+
+Optional:
+- seaborn *(for nicer heatmaps with `pip install plotmind[seaborn]`)*
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+---
+
+## Roadmap
+
+- **v0.2** – CLI improvements + test coverage
+- **v0.3** – Docs + PyPI release
+- **v0.4** – AI prompt-based visualization (`plot(df, prompt="Show me trends over time")`)
+- **v0.5** – Smart dashboards & auto-insights
+
+---
+
+## License
+
+MIT

plotmind-0.1.0/README.md

@@ -0,0 +1,220 @@
+# PlotMind 📊
+
+> **Convert any CSV into meaningful graphs automatically.**
+
+PlotMind analyses your CSV, detects column types, recommends the best chart, and generates it — with zero manual configuration. It supports interactive charts via Plotly and static charts via Matplotlib, and can export to PNG, PDF, or HTML.
+
+---
+
+## Installation
+
+```bash
+pip install plotmind
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/plotmind
+cd plotmind
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### Python API
+
+```python
+from plotmind import load_csv, clean_dataframe, plot, export
+
+# 1. Load
+df = load_csv("sales.csv")
+
+# 2. Clean (handles missing values, duplicates, type coercion)
+df = clean_dataframe(df, verbose=True)
+
+# 3. Plot – auto-detects best chart
+fig = plot(df)
+
+# 4. Export
+export(fig, "sales_chart.html")
+export(fig, "sales_chart.png")
+```
+
+### Command-Line Interface
+
+```bash
+# Auto-detect best chart and display
+plotmind sales.csv
+
+# Choose a specific chart type
+plotmind sales.csv --chart bar
+
+# Specify axes
+plotmind sales.csv --chart scatter --x revenue --y profit
+
+# Export to file without displaying
+plotmind sales.csv --chart line --export output.html
+
+# Use matplotlib backend
+plotmind sales.csv --backend matplotlib --export chart.png
+
+# Show column info and recommendation
+plotmind sales.csv --info
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Auto-chart selection** | Detects the best chart based on column types |
+| **Column type detection** | Identifies numerical, categorical, datetime, boolean columns |
+| **Data cleaning** | Fills missing values, removes duplicates, fixes types |
+| **Interactive charts** | Plotly backend for zoom/hover/pan |
+| **Static charts** | Matplotlib backend for PNG/PDF output |
+| **Export** | PNG, PDF, HTML, SVG |
+| **CLI** | Full command-line interface |
+
+---
+
+## Chart Types
+
+PlotMind supports these chart types (auto-selected or manually chosen):
+
+| Chart | When auto-selected |
+|---|---|
+| `histogram` | Single numerical column |
+| `bar` | Categorical + numerical (high cardinality) |
+| `pie` | Categorical + numerical (≤6 unique categories) |
+| `scatter` | Two numerical columns |
+| `line` | Datetime + numerical |
+| `heatmap` | Many numerical columns (correlation matrix) |
+| `box` | Box plot for distribution |
+
+---
+
+## API Reference
+
+### `load_csv(filepath, **kwargs) → DataFrame`
+Load a CSV and validate it.
+
+```python
+df = load_csv("data.csv")
+```
+
+---
+
+### `clean_dataframe(df, verbose=False) → DataFrame`
+Clean: fill missing values, remove duplicates, coerce types.
+
+```python
+df = clean_dataframe(df, verbose=True)
+```
+
+---
+
+### `detect_columns(df) → dict`
+Return a dict of `{column_name: type}` for each column.
+Types: `numerical`, `categorical`, `datetime`, `boolean`, `unknown`.
+
+```python
+from plotmind import detect_columns
+types = detect_columns(df)
+# {'age': 'numerical', 'city': 'categorical', ...}
+```
+
+---
+
+### `recommend_chart(df, x=None, y=None) → (chart, x_col, y_col)`
+Recommend the best chart. Returns a tuple.
+
+```python
+from plotmind import recommend_chart
+chart, x, y = recommend_chart(df)
+print(chart)  # e.g. 'scatter'
+```
+
+---
+
+### `plot(df, chart=None, x=None, y=None, title=None, backend='plotly', show=True) → Figure`
+Generate a chart. Returns the figure object.
+
+```python
+fig = plot(df, chart="bar", x="city", y="sales", title="Sales by City")
+fig = plot(df, backend="matplotlib", show=False)  # static, no display
+```
+
+---
+
+### `export(fig, path, fmt=None) → str`
+Export the figure. Format is inferred from the file extension.
+
+```python
+export(fig, "chart.png")    # PNG (requires kaleido for Plotly)
+export(fig, "chart.pdf")    # PDF
+export(fig, "chart.html")   # Interactive HTML (Plotly) or embedded HTML (Matplotlib)
+export(fig, "chart.svg")    # SVG
+```
+
+---
+
+## Utils
+
+```python
+from plotmind.utils import preview, column_stats, filter_columns
+
+preview(df)               # Print head
+column_stats(df)          # Summary DataFrame with null counts, unique values, etc.
+filter_columns(df, types=["number"])  # Get only numeric column names
+```
+
+---
+
+## Testing
+
+```bash
+pip install plotmind[dev]
+pytest tests/ -v
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.8
+- pandas ≥ 1.3
+- plotly ≥ 5.0
+- matplotlib ≥ 3.4
+- kaleido ≥ 0.2.1  *(for Plotly static image export)*
+
+Optional:
+- seaborn *(for nicer heatmaps with `pip install plotmind[seaborn]`)*
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+---
+
+## Roadmap
+
+- **v0.2** – CLI improvements + test coverage
+- **v0.3** – Docs + PyPI release
+- **v0.4** – AI prompt-based visualization (`plot(df, prompt="Show me trends over time")`)
+- **v0.5** – Smart dashboards & auto-insights
+
+---
+
+## License
+
+MIT

plotmind-0.1.0/plotmind/__init__.py

@@ -0,0 +1,13 @@
+"""
+PlotMind – Convert any CSV into meaningful graphs automatically.
+"""
+
+from .loader import load_csv
+from .cleaner import clean_dataframe
+from .detector import detect_columns
+from .recommender import recommend_chart
+from .plotter import plot
+from .exporter import export
+
+__version__ = "0.1.0"
+__all__ = ["load_csv", "clean_dataframe", "detect_columns", "recommend_chart", "plot", "export"]

plotmind-0.1.0/plotmind/cleaner.py

@@ -0,0 +1,68 @@
+"""
+cleaner.py – Handles missing values, duplicates, and data type fixes.
+"""
+
+import pandas as pd
+
+
+def clean_dataframe(df: pd.DataFrame, verbose: bool = False) -> pd.DataFrame:
+    """
+    Clean a DataFrame by handling missing values, duplicates, and data types.
+
+    Args:
+        df: Input DataFrame.
+        verbose: If True, prints a cleaning summary.
+
+    Returns:
+        A cleaned copy of the DataFrame.
+    """
+    df = df.copy()
+    report = {}
+
+    # --- Remove duplicate rows ---
+    before = len(df)
+    df = df.drop_duplicates()
+    report["duplicates_removed"] = before - len(df)
+
+    # --- Fix data types: try numeric coercion on object columns ---
+    for col in df.select_dtypes(include=["object", "string"]).columns:
+        # Try parsing as datetime first
+        try:
+            parsed = pd.to_datetime(df[col], infer_datetime_format=True)
+            if parsed.notna().sum() > len(df) * 0.5:
+                df[col] = parsed
+                continue
+        except Exception:
+            pass
+
+        # Try parsing as numeric
+        coerced = pd.to_numeric(df[col], errors="coerce")
+        if coerced.notna().sum() > len(df) * 0.5:
+            df[col] = coerced
+            continue
+
+    # --- Handle missing values ---
+    missing_before = df.isnull().sum().sum()
+
+    for col in df.columns:
+        if df[col].isnull().sum() == 0:
+            continue
+
+        if pd.api.types.is_numeric_dtype(df[col]):
+            df[col] = df[col].fillna(df[col].median())
+        elif pd.api.types.is_datetime64_any_dtype(df[col]):
+            df[col] = df[col].fillna(method="ffill").fillna(method="bfill")
+        else:
+            mode = df[col].mode()
+            fill_val = mode[0] if not mode.empty else "Unknown"
+            df[col] = df[col].fillna(fill_val)
+
+    report["missing_filled"] = missing_before
+
+    if verbose:
+        print("[PlotMind Cleaner]")
+        print(f"  Duplicates removed : {report['duplicates_removed']}")
+        print(f"  Missing values filled : {report['missing_filled']}")
+        print(f"  Final shape : {df.shape}")
+
+    return df

plotmind-0.1.0/plotmind/cli.py

@@ -0,0 +1,112 @@
+"""
+cli.py – Command-line interface for PlotMind.
+
+Usage:
+    plotmind data.csv
+    plotmind data.csv --chart bar
+    plotmind data.csv --chart scatter --x col1 --y col2
+    plotmind data.csv --chart line --export output.html
+    plotmind data.csv --backend matplotlib --export chart.png
+"""
+
+import argparse
+import sys
+
+from .loader import load_csv
+from .cleaner import clean_dataframe
+from .recommender import recommend_chart, CHART_TYPES
+from .plotter import plot
+from .exporter import export
+from .detector import summarize_columns
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="plotmind",
+        description="PlotMind – Convert any CSV into meaningful graphs automatically.",
+    )
+    parser.add_argument("csv", help="Path to the CSV file")
+    parser.add_argument(
+        "--chart", "-c",
+        choices=CHART_TYPES,
+        default=None,
+        help="Chart type (default: auto-recommended)",
+    )
+    parser.add_argument("--x", default=None, help="Column for x-axis")
+    parser.add_argument("--y", default=None, help="Column for y-axis")
+    parser.add_argument(
+        "--export", "-e",
+        default=None,
+        metavar="FILE",
+        help="Export path (e.g. chart.png, chart.html, chart.pdf)",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=["plotly", "matplotlib"],
+        default="plotly",
+        help="Rendering backend (default: plotly)",
+    )
+    parser.add_argument(
+        "--no-clean",
+        action="store_true",
+        help="Skip data cleaning step",
+    )
+    parser.add_argument(
+        "--info",
+        action="store_true",
+        help="Show column type info and exit",
+    )
+    parser.add_argument(
+        "--title",
+        default=None,
+        help="Custom chart title",
+    )
+
+    args = parser.parse_args()
+
+    # Load
+    try:
+        df = load_csv(args.csv)
+        print(f"[PlotMind] Loaded {args.csv}  ({df.shape[0]} rows × {df.shape[1]} cols)")
+    except (FileNotFoundError, ValueError) as e:
+        print(f"[PlotMind] Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Info mode
+    if args.info:
+        summarize_columns(df)
+        chart, x, y = recommend_chart(df, x=args.x, y=args.y)
+        print(f"\n[PlotMind] Recommended: {chart.upper()}  x={x}  y={y}")
+        return
+
+    # Clean
+    if not args.no_clean:
+        df = clean_dataframe(df, verbose=True)
+
+    # Plot
+    show = args.export is None  # Only show interactively if not exporting
+    try:
+        fig = plot(
+            df,
+            chart=args.chart,
+            x=args.x,
+            y=args.y,
+            title=args.title,
+            backend=args.backend,
+            show=show,
+        )
+    except Exception as e:
+        print(f"[PlotMind] Plot error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Export
+    if args.export:
+        try:
+            export(fig, args.export)
+        except Exception as e:
+            print(f"[PlotMind] Export error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()