Metadata-Version: 2.4
Name: radviz-plotly
Version: 0.3.0
Summary: A Python package for 2D and 3D Radial Visualization using Plotly with attribute sorting
License: MIT
License-File: LICENSE
Keywords: visualization,radviz,plotly,data-science,3d-visualization
Author: elewah
Author-email: abdelrahman.elewah@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: numpy (>=1.18.0)
Requires-Dist: pandas (>=1.0.0)
Requires-Dist: plotly (>=4.0.0)
Requires-Dist: scikit-learn (>=0.24.0)
Requires-Dist: transformations (>=2020.1.1)
Project-URL: Homepage, https://github.com/elewah/RadViz-Plotly
Project-URL: Repository, https://github.com/elewah/RadViz-Plotly.git
Description-Content-Type: text/markdown

# RadViz-Plotly

<table>
    <tr>
        <td>Latest Release</td>
        <td>
            <a href="https://pypi.org/project/RadViz-Plotly/">
            <img src="https://badge.fury.io/py/RadViz-Plotly.svg" alt="PyPI version badge"/>
            </a>
        </td>
    </tr>
    <tr>
        <td>Examples</td>
        <td>
            <a href="https://colab.research.google.com/github/elewah/RadViz-Plotly/blob/master/examples/BreastCancer_Demo.ipynb">
            <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
            </a>
        </td>
    </tr>
    <tr>
        <td>PyPI Downloads</td>
        <td>
            <a href="https://pepy.tech/project/RadViz-Plotly">
            <img src="https://pepy.tech/badge/RadViz-Plotly" alt="PyPI Downloads badge"/>
            </a>
        </td>
    </tr>
    <tr>
        <td>License</td>
        <td>
            <a href="https://opensource.org/licenses/MIT">
            <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License badge"/>
            </a>
        </td>
    </tr>
</table>

## Overview
RadViz-Plotly is an open-source Python package designed for data scientists to create 2D and 3D Radial Visualization (RadViz) plots for high-dimensional datasets. These visualizations provide a comprehensive view of data distribution across dimensions, enabling better understanding and discovery of hidden insights. The package leverages the powerful interactive tools of the Plotly library.

### Key Features
- **2DRadViz**: Generates 2D Radial Visualizations.
- **3DRadViz**: Creates 3D Radial Visualizations.
- **3DRadViz with Attribute Sorting**: Creates 3D Radial Visualizations with intelligent attribute sorting based on correlation analysis.
- **Interactive Visualizations**: Zoom, filter labels, and rotate 3D graphs.
- **Correlation-Based Grouping**: Automatically groups highly correlated attributes and separates negatively correlated ones.

## Quickstart

### Try Online with Google Colab (Recommended)

Click the Colab badge above to open an interactive notebook demonstrating all three RadViz functions with the Breast Cancer dataset. No installation required - runs entirely in the cloud!

**Steps:**
1. Click the Colab badge in the table above
2. Wait for the notebook to load (~10 seconds)
3. Run all cells (Runtime → Run all)
4. Explore interactive visualizations

### Try with Binder (Alternative)

Alternatively, you can try RadViz-Plotly using Binder:

1. Click [here](https://mybinder.org/v2/gh/elewah/RadViz-Plotly-Examples/master) to access interactive Jupyter notebooks. This repository contains three folders, each with datasets and a Jupyter notebook demonstrating RadViz-Plotly.
   - **Note**: The Jupyter environment may take some time to load.
2. Open one of the folders (e.g., Car Evaluation Dataset, Election Dataset, or Iris Dataset).
3. Open the file with the `.ipynb` extension (Jupyter notebook).
4. From the **Cell** menu in the toolbar, select **Run All** to execute the notebook.

**Hints:**
- The first run may take time to install dependencies.
- The package supports interactive features like zooming, filtering labels, and rotating 3D graphs.
- RadViz-Plotly depends on the [Plotly](https://plot.ly/python) library.

### With Local Installation

1. Install RadViz-Plotly using pip:
   ```bash
   pip install RadViz-Plotly
   ```
2. Clone the examples repository:
   ```bash
   git clone https://github.com/elewah/RadViz-Plotly-Examples.git
   ```
   Alternatively, download the repository as a ZIP file [here](https://github.com/elewah/RadViz-Plotly-Examples/archive/master.zip).
3. Run the examples using Jupyter Lab to understand how to use the RadViz-Plotly package.

## Gallery

<p align="center">
<img src="https://elewah.github.io/RadViz-Plotly/image/3D-1.gif" width="400" alt="3D RadViz Example 1">
<img src="https://elewah.github.io/RadViz-Plotly/image/3D-2.gif" width="400" alt="3D RadViz Example 2">
<img src="https://elewah.github.io/RadViz-Plotly/image/Slide3.PNG" width="400" alt="2D RadViz Example">
<img src="https://elewah.github.io/RadViz-Plotly/image/Slide2.PNG" width="400" alt="3D RadViz Example">
</p>

## Interactive Visualizations

Explore live interactive HTML visualizations using the Breast Cancer dataset. These demos run directly in your browser with full Plotly interactivity (zoom, pan, rotate, filter labels):

- **[2D RadViz Demo](https://htmlpreview.github.io/?https://github.com/elewah/RadViz-Plotly/blob/master/iframe_figures/BreastCancer_2D_RadViz.html)** - 2D radial visualization on a circle
- **[3D RadViz Demo](https://htmlpreview.github.io/?https://github.com/elewah/RadViz-Plotly/blob/master/iframe_figures/BreastCancer_3D_RadViz.html)** - 3D radial visualization on a sphere
- **[3D RadViz with Sorting Demo](https://htmlpreview.github.io/?https://github.com/elewah/RadViz-Plotly/blob/master/iframe_figures/BreastCancer_3D_RadViz_Sorted.html)** - 3D visualization with intelligent correlation-based attribute sorting

*Note: HTML files are ~5MB each and may take a few seconds to load.*

## Usage Examples

### Basic 2D RadViz
```python
import pandas as pd
from radviz_plotly import RadViz2D

# Load your dataset
data = pd.read_csv('your_dataset.csv')
y = data['label']  # Labels column
X = data.drop(['label'], axis=1)  # Features

# Create 2D RadViz visualization
RadViz2D(y, X)
```

### Basic 3D RadViz
```python
import pandas as pd
from radviz_plotly import RadViz3D

# Load your dataset
data = pd.read_csv('your_dataset.csv')
y = data['label']  # Labels column
X = data.drop(['label'], axis=1)  # Features

# Create 3D RadViz visualization
RadViz3D(y, X, BPs=10000)  # BPs = Number of boundary points
```

### 3D RadViz with Attribute Sorting (New!)
This advanced feature automatically analyzes correlations between attributes and arranges the dimension anchors to minimize visual clutter and improve interpretability.

```python
import pandas as pd
from radviz_plotly import RadViz3D_withSorting

# Load your dataset
data = pd.read_csv('your_dataset.csv')
y = data['label']  # Labels column
X = data.drop(['label'], axis=1)  # Features

# Create 3D RadViz with intelligent attribute sorting
RadViz3D_withSorting(y, X, BPs=10000)
```

**How it works:**
1. Analyzes the correlation matrix of attributes
2. Groups highly correlated attributes together
3. Identifies negatively correlated attribute pairs
4. Uses K-means clustering to determine optimal anchor positions on the sphere
5. Arranges anchors to maximize distance between negatively correlated attributes

**Installation with sorting support:**
```bash
# Install with sorting dependencies
pip install RadViz-Plotly[sorting]

# Or install all extras including development tools
pip install RadViz-Plotly[sorting,dev]
```

**Requirements for sorting:**
- scikit-learn >= 0.24.0
- transformations >= 2020.1.1

**Example with the Breast Cancer Dataset:**
```python
import pandas as pd
from radviz_plotly import RadViz3D_withSorting

# Load dataset
data = pd.read_csv('tests/DataFolder/BreastCancer.csv')
y = data['diagnosis']
X = data.drop(['diagnosis', 'id'], axis=1)

# Create visualization with sorting
RadViz3D_withSorting(y, X, BPs=5000)
```

## About
RadViz-Plotly was developed by a research group at the IoT Lab, Ontario Tech University. It provides tools for creating 2D and 3D Radial Visualizations, enabling data scientists to explore high-dimensional datasets interactively.

## Citation
If you use RadViz-Plotly in your research, please cite the following paper:

[A. Elewah, A. A. Badawi, H. Khalil, S. Rahnamayan, and K. Elgazzar, "3D-RadViz: Three Dimensional Radial Visualization for Large-Scale Data Visualization," 2021 IEEE Congress on Evolutionary Computation (CEC), 2021, pp. 1037-1046, doi: 10.1109/CEC45853.2021.9504983.](https://ieeexplore.ieee.org/document/9504983)


## License
This project is licensed under the [MIT License](LICENSE).

<div style="display:flex; justify-content: center;">
<a href="https://ontariotechu.ca/">
<img src="https://elewah.github.io/RadViz-Plotly/image/ontariotechu-log.jpg" alt="Ontario Tech University Logo" width="250">
</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="https://iotresearchlab.ca/">
<img src="https://elewah.github.io/RadViz-Plotly/image/IoT-lab.png" width="300" alt="IoT Lab Logo">
</a>
</div>



