Metadata-Version: 2.1
Name: quicksea
Version: 0.1.1
Summary: Fast and intuitive 2D/3D interactive visualizations and exploratory data analysis using Plotly.
Home-page: https://github.com/lennox/quicksea
Author: Lennox
Author-email: lennox@example.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plotly>=5.0.0
Requires-Dist: pandas>=1.0.0
Provides-Extra: jupyter
Requires-Dist: ipython>=7.0.0; extra == "jupyter"

# quicksea 🌊

[![PyPI version](https://img.shields.io/pypi/v/quicksea.svg)](https://pypi.org/project/quicksea/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**quicksea** is a lightweight Python library for fast, interactive 2D and 3D exploratory data visualization powered by Plotly.

---

## Features

- **2D Multi-Pair Scatter Plots**: Batch-plot multiple feature pairs in interactive Plotly figures with a single line of code.
- **3D Feature Exploration**: Generate interactive 3D scatter plots across triplets of features with color encoding.
- **EDA Utilities**: Quick data profiling for missing values and summary statistics.
- **Jupyter & Script Compatible**: Works out-of-the-box in Jupyter Notebooks, Google Colab, and standard Python scripts.

---

## Installation

Install `quicksea` from PyPI:

```bash
pip install quicksea
```

To include Jupyter notebook dependencies:

```bash
pip install "quicksea[jupyter]"
```

---

## Quickstart

```python
import pandas as pd
from quicksea import Visualizer

# Sample data
df = pd.DataFrame({
    "age": [22, 38, 26, 35, 54],
    "fare": [7.25, 71.28, 7.92, 53.10, 51.86],
    "pclass": [3, 1, 3, 1, 1],
    "survived": [0, 1, 1, 1, 0]
})

# Initialize visualizer with a color column (e.g. classification target)
viz = Visualizer(color_column="survived")

# 1. Quick EDA: missing values and descriptive statistics
viz.check_nan_describe(df)

# 2. 2D Scatter plots
pairs = [("age", "fare"), ("pclass", "fare")]
viz.scatter_2d(df, pairs)

# 3. 3D Scatter plot
triplets = [("age", "fare", "pclass")]
viz.scatter_3d(df, triplets)
```

---

## API Reference

### `Visualizer(color_column=None)`
- **`color_column`** *(str, optional)*: DataFrame column name used to group/color markers.

### Methods

#### `scatter_2d(X, two_d_plot_cols, show=True)`
- **`X`** *(pd.DataFrame)*: Input dataset.
- **`two_d_plot_cols`** *(list of (str, str))*: List of `(x_column, y_column)` tuples.
- **`show`** *(bool, default=True)*: Whether to display each figure with `fig.show()`.
- **Returns**: `List[plotly.graph_objects.Figure]`

#### `scatter_3d(X, three_d_plot_cols, show=True)`
- **`X`** *(pd.DataFrame)*: Input dataset.
- **`three_d_plot_cols`** *(list of (str, str, str))*: List of `(x_column, y_column, z_column)` tuples.
- **`show`** *(bool, default=True)*: Whether to display each figure with `fig.show()`.
- **Returns**: `List[plotly.graph_objects.Figure]`

#### `check_nan_describe(df)`
- **`df`** *(pd.DataFrame)*: Displays NaN count and descriptive summary.

---

## License

MIT License. See [LICENSE](LICENSE) for details.



