mvs-story-generator 0.0.1

A Python library for generating MolViewSpec JSON (MVSJ) files for molecular visualizations

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

pip install mvs-story-generator

Quick Start

Basic Protein Visualization

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

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

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

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

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

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:

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

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=mvs_story_generator

Code Quality

# 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 [e-mail]

Links

• MolViewSpec Documentation
• PDBe API