mvs-story-generator 0.0.1
A Python library for generating MolViewSpec JSON (MVSJ) files for molecular visualizations
License: MIT
Requires Python: >=3.9
Keywords: molecular, visualization, molviewspec, mvsj, protein, chemistry

# MVS Story Generator

A Python library for generating MolViewSpec JSON (MVSJ) files for molecular visualizations and multi-state stories.

## Overview

MVS Story Generator provides a programmatic interface for creating molecular visualizations using the MolViewSpec JSON format. It enables you to generate single-state visualizations and complex multi-state molecular stories with support for various representation types including cartoons, surfaces, ball-and-stick models, and hybrid visualizations.

## Features

- **Single-state visualizations**: Create protein cartoons, ligand views, multi-component visualizations, and surface representations
- **Multi-state stories**: Build animated molecular stories with transitions between different visualization states
- **Surface support**: Generate molecular surfaces with customizable opacity, probe radius, and hybrid representations
- **Comprehensive validation**: Input validation for colors, selectors, camera angles, and visualization parameters
- **Example generation**: Built-in examples for common molecular visualization scenarios
- **Type safety**: Full type annotations and TypedDict support

## Installation

```bash
pip install mvs-story-generator
```

## Quick Start

### Basic Protein Visualization

```python
from mvs_story_generator import protein_cartoon, save_json

# Create a protein cartoon visualization
url = "https://www.ebi.ac.uk/pdbe/entry-files/1atp.bcif"
viz = protein_cartoon(url, title="PKA Structure", color="blue")

# Save to file
save_json(viz, "protein_view.mvsj")
```

### Multi-state Story

```python
from mvs_story_generator import create_multi_state_story

# Define states for a rotation story
configs = [
    {"url": url, "viz_type": "protein_cartoon", "color": "blue", "camera_angle": "up", "title": "Top View"},
    {"url": url, "viz_type": "protein_cartoon", "color": "blue", "camera_angle": "right", "title": "Side View"},
    {"url": url, "viz_type": "protein_cartoon", "color": "blue", "camera_angle": "flip_horizontal", "title": "Back View"}
]

story = create_multi_state_story(configs, title="Protein Rotation Story")
save_json(story, "rotation_story.mvsj")
```

### Surface Visualization

```python
from mvs_story_generator import protein_surface_with_cartoon

# Create hybrid protein visualization with both cartoon and surface
hybrid_viz = protein_surface_with_cartoon(
    url=url,
    title="Protein Structure with Surface",
    cartoon_color="#4577B2",
    surface_color="#D0D0D0", 
    surface_opacity=0.4
)

save_json(hybrid_viz, "hybrid_protein.mvsj")
```

## API Reference

### Basic Visualizations

- `protein_cartoon()` - Protein cartoon representation with optional surface
- `ligand_view()` - Ligand ball-and-stick visualization with optional surface
- `multi_component_colored_view()` - Multi-component visualization with different colors
- `multi_component_ligand_focus()` - Ligand-focused view with protein context

### Surface Visualizations

- `protein_surface()` - Standalone protein surface visualization
- `ligand_surface()` - Standalone ligand surface visualization  
- `protein_surface_with_cartoon()` - Hybrid protein cartoon + surface
- `ligand_surface_with_sticks()` - Hybrid ligand ball-and-stick + surface

### Multi-state Stories

- `create_multi_state_story()` - Create custom multi-state molecular stories
- `protein_rotation_story()` - Protein rotation with multiple camera angles
- `structure_comparison_story()` - Compare multiple molecular structures
- `protein_surface_evolution_story()` - Surface opacity evolution
- `ligand_representation_transition_story()` - Ligand representation transitions
- `protein_ligand_surface_story()` - Protein-ligand surface interactions
- `hybrid_representation_showcase_story()` - Showcase different representation types

### Utilities

- `save_json()` - Save MVSJ data to JSON file
- `generate_examples()` - Generate example visualizations

## Examples

### Generate Built-in Examples

```python
from mvs_story_generator import generate_examples

# Generate kinase protein examples
generate_examples("kinases", output_dir="examples/kinases")

# Generate surface visualization examples  
generate_examples("surface_examples", output_dir="examples/surfaces")

# Generate multi-state stories
generate_examples("multi_state_stories", output_dir="examples/stories")

# Generate surface-focused stories
generate_examples("surface_stories", output_dir="examples/surface_stories")
```

### Custom Labels and Highlighting

```python
from mvs_story_generator import multi_component_colored_view

# Add labels and highlight specific residues
labels = [
    {"text": "Active Site", "selector": "ligand"},
    {"text": "Key Residue", "selector": {"label_asym_id": "A", "label_seq_id": 72}}
]

highlight_residues = [("A", 72), ("A", 95)]

viz = multi_component_colored_view(
    url=url,
    title="Annotated Structure", 
    labels=labels,
    highlight_residues=highlight_residues,
    highlight_color="#ff0000"
)
```

### Surface Parameters

```python
from mvs_story_generator import ligand_surface

# Customize surface properties
surface_viz = ligand_surface(
    url=url,
    title="Ligand Surface",
    color="#90EE90",
    opacity=0.7,
    probe_radius=1.4,  # Probe radius for surface calculation
    camera_angle="right"
)
```

## Type Definitions

The library provides TypedDict classes for configuration:

```python
from mvs_story_generator import LabelConfig, StateConfig

# Label configuration
label: LabelConfig = {
    "text": "Binding Site",
    "selector": "ligand",
    "color": "#ff0000"  # optional
}

# State configuration for multi-state stories
state: StateConfig = {
    "url": "https://www.ebi.ac.uk/pdbe/entry-files/1atp.bcif",
    "viz_type": "protein_cartoon",
    "color": "blue",
    "camera_angle": "up",
    "title": "Overview",
    "duration": 3000,  # ms
    "transition_duration": 1000,  # ms
    "include_surface": True,
    "surface_opacity": 0.3
}
```

## Supported Parameters

### Colors
- Named colors: `"red"`, `"blue"`, `"green"`, `"protein_orange"`, `"nucleic_blue"`, `"ligand_green"`, etc.
- Hex colors: `"#ff0000"`, `"#4577B2"`, etc.

### Camera Angles
- `"up"`, `"down"`, `"left"`, `"right"`
- `"flip_horizontal"`, `"flip_vertical"`

### Selectors
- Static selectors: `"all"`, `"polymer"`, `"protein"`, `"nucleic"`, `"ligand"`, `"ion"`, `"water"`
- ComponentExpression dictionaries: `{"label_asym_id": "A", "label_seq_id": 72}`

### Representation Types
- `"cartoon"`, `"ball_and_stick"`, `"surface"`, `"spacefill"`, `"ribbon"`, `"tube"`, `"line"`

## Development

### Running Tests

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mvs_story_generator
```

### Code Quality

```bash
# Format code
black mvs_story_generator/

# Lint code  
flake8 mvs_story_generator/

# Type checking
mypy mvs_story_generator/
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Authors

- Brian <brian@junction.bio>

## Links

- [MolViewSpec Documentation](https://molviewspec.org/)
- [PDBe API](https://www.ebi.ac.uk/pdbe/)