solvien-graph 0.1.4
Professional data visualization library - Optimized for bioinformatics and scientific analyses (D3.js/Vega-Lite/Altair based)
Requires Python: >=3.8

# Solvien Graph 

**Professional data visualization library** - Optimized for bioinformatics and scientific analyses, designed to create **D3.js/Vega-Lite based Altair charts**.

## Features

- **Professional Design**: Minimalist, corporate appearance
- **Fully Interactive**: D3.js/Vega-Lite based, zoom, pan, hover, export features
- **Bioinformatics Focused**: Gene expression, differential analysis and genomic data visualization
- **Comprehensive Chart Types**: Bar, Line, Scatter, Pie, Histogram, Heatmap, Volcano, MA Plot, Violin, Box Plot
- **Professional Themes**: Scientific, Publication, Bioinformatics and more
- **Publication Quality**: High resolution, optimized for scientific publications
- **Scientific Color Palettes**: Viridis, Plasma, Inferno, Magma, Cividis, Coolwarm, RdBu
- **D3.js Technology**: Altair with D3.js/Vega-Lite based, web standards compliant, professional charts

## Installation

```bash
pip install -e .
```

or

```bash
pip install solvien-graph
```

**Note**: Since it's based on Altair (D3.js/Vega-Lite), all charts are automatically interactive. Opens in Jupyter Notebook or web browser. Produces output in JSON format, web standards compliant.

## Quick Start

### Bar Chart (Interactive)

```python
import solvien_graph as sg

data = {
    "Python": 45,
    "JavaScript": 30,
    "Java": 20,
    "C++": 15
}

# Interactive chart - with hover, zoom, pan features (D3.js based)
chart = sg.quick_bar(data, title="Programming Languages Popularity")

# Save as HTML
chart.save("chart.html")
```

### Line Chart (Interactive)

```python
import numpy as np
import solvien_graph as sg

x = np.linspace(0, 10, 100)
y = np.sin(x)

# Interactive line chart - you can see values with hover (D3.js based)
chart = sg.quick_line(x, y, title="Sine Function")

# Save as HTML
chart.save("chart.html")

# Save as PNG/SVG (requires vega-cli)
chart.save("chart.png")
```

### Scatter Plot

```python
import numpy as np
import solvien_graph as sg

x = np.random.randn(100)
y = np.random.randn(100)

sg.quick_scatter(x, y, title="Random Distribution")
```

### Pie Chart

```python
import solvien_graph as sg

data = {
    "Mobile": 45,
    "Web": 30,
    "Desktop": 15,
    "Other": 10
}

sg.quick_pie(data, title="Platform Distribution")
```

### Histogram

```python
import numpy as np
import solvien_graph as sg

data = np.random.normal(100, 15, 1000)

sg.quick_hist(data, title="Normal Distribution", bins=30)
```

## Themes

Solvien Graph comes with professional themes:

- **scientific**: Theme optimized for scientific publications
- **publication**: For high quality black and white publications
- **bioinformatics**: Color palette optimized for bioinformatics analyses
- And more...

```python
sg.quick_bar(data)
```

## Biograph Module - Specialized Bioinformatics Toolkit

The `biograph` module provides a dedicated namespace for bioinformatics visualizations. This is the **recommended way** to use bioinformatics functions:

### Import Style

```python
# Recommended: Import biograph as a separate module
import solvien_graph.biograph as bg

# Alternative style
from solvien_graph import biograph as bg

# Direct function import
from solvien_graph.biograph import quick_heatmap, quick_volcano

# Backward compatibility (still works)
from solvien_graph import quick_heatmap, quick_volcano
```

### Why use biograph?

- **Clear namespace**: Separates bioinformatics functions from general plotting
- **Professional workflow**: `import solvien_graph.biograph as bg` is concise and clear
- **Specialized toolkit**: All bioinformatics-specific visualizations in one place
- **Easy to remember**: `bg.quick_heatmap()`, `bg.quick_volcano()`, etc.

## Bioinformatics Charts

### Heatmap (Gene Expression)

```python
import numpy as np
import solvien_graph.biograph as bg

# Gene expression data
gene_data = np.random.randn(20, 10) * 2 + 5
gene_names = [f"Gene_{i+1}" for i in range(20)]
sample_names = [f"Sample_{i+1}" for i in range(10)]

bg.quick_heatmap(gene_data, 
                title="Gene Expression Heatmap",
                cmap="viridis",
                xticklabels=sample_names,
                yticklabels=gene_names,
                cbar_label="Expression Level")
```

### Volcano Plot (Differential Expression)

```python
import numpy as np
import solvien_graph.biograph as bg

log2fc = np.random.randn(1000) * 2
pvalues = np.random.exponential(0.1, 1000)
pvalues = np.clip(pvalues, 0, 1)

bg.quick_volcano(log2fc, pvalues,
                title="Differential Gene Expression",
                fc_threshold=1.0,
                pvalue_threshold=0.05)
```

### MA Plot

```python
mean_expr = np.random.lognormal(5, 1, 1000)
log2fc = np.random.randn(1000) * 1.5

bg.quick_ma_plot(mean_expr, log2fc,
                title="MA Plot - Differential Expression")
```

### Violin Plot & Box Plot

```python
conditions = {
    "Control": np.random.normal(5, 1, 100),
    "Treatment A": np.random.normal(6.5, 1.2, 100),
    "Treatment B": np.random.normal(4.5, 0.8, 100)
}

bg.quick_violin(conditions, title="Gene Expression - Conditions")
bg.quick_boxplot(conditions, title="Gene Expression - Box Plot")
```

## Examples

The `examples/` directory contains organized, ready-to-run examples:

| File | Description |
|------|-------------|
| `01_basic_charts.py` | Bar, Line, Scatter, Pie, and Histogram charts |
| `02_bioinformatics.py` | Heatmap, Volcano, MA Plot, Violin, and Box Plot |
| `03_advanced_analysis.py` | PCA analysis and dimensionality reduction |
| `04_biograph_demo.py` | **Complete RNA-Seq analysis workflow demo** |

### Running Examples

```bash
cd examples

# Basic charts (getting started)
python 01_basic_charts.py

# Bioinformatics charts
python 02_bioinformatics.py

# Advanced PCA analysis
python 03_advanced_analysis.py

# Full biograph demo (recommended for bioinformatics users)
python 04_biograph_demo.py
```

### solvien_graph vs solvien_graph.biograph

| Feature | `solvien_graph` | `solvien_graph.biograph` |
|---------|-----------------|--------------------------|
| **Purpose** | General-purpose plotting | Bioinformatics-specific |
| **Chart Types** | Bar, Line, Scatter, Pie, Histogram | Heatmap, Volcano, MA, Violin, Boxplot |
| **Target Users** | General data visualization | Researchers, bioinformaticians |
| **Output Focus** | Interactive web charts | Publication-quality exports |
| **Annotations** | Basic tooltips | Statistical annotations (counts, medians) |
| **Color Palettes** | Standard | Scientific (Viridis, Coolwarm) |
| **Clustering** | Not available | Hierarchical clustering for heatmaps |

**When to use which:**

```python
# General data visualization
import solvien_graph as sg
sg.quick_bar(data, title="Sales by Region")
sg.quick_line(x, y, title="Time Series")

# Bioinformatics / Scientific work
import solvien_graph.biograph as bg
bg.quick_volcano(log2fc, pvalues, title="Differential Expression")
bg.quick_heatmap(gene_data, title="Gene Expression", cluster_rows=True)
```


## Advanced Usage

### Creating Chart Without Displaying

```python
# Create chart but don't display
chart = sg.quick_bar(data, show=False)

# You can perform additional operations on Altair chart
chart = chart.properties(title="New Title")
chart = chart.encode(y=alt.Y('Value:Q', title="New Y Label"))

# Then display
chart.show()
```

### Custom Colors

```python
sg.quick_bar(data, color="#FF5733")
# or
sg.quick_bar(data, color=["#FF5733", "#33FF57", "#3357FF"])
```

### Custom Sizes

```python
sg.quick_bar(data, figsize=(12, 8))
```

### Interactive Features

All charts are automatically interactive:
- **Hover**: Hover to see values
- **Zoom**: Zoom in/out on chart
- **Pan**: Pan the chart
- **Export**: Save as PNG, SVG, HTML
- **Legend**: Click legend to show/hide series

```python
# Create chart (D3.js/Vega-Lite based)
chart = sg.quick_bar(data, title="Analysis")

# Save as HTML
chart.save("analysis.html")

# Save as PNG/SVG (requires vega-cli)
chart.save("analysis.png")

# Save as JSON (Vega-Lite spec)
chart.save("analysis.json")

# Publication quality mode
chart = sg.quick_bar(data, publication_quality=True)
```

```bash
# Clone the repository
git clone https://github.com/Solvien-Open-Source/solvien-graph
cd solvien-graph

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/
```

## License

MIT License

## Contributing

We welcome your contributions! Please open an issue before sending a pull request.

## Contact

You can open an issue for questions.