# 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/)
Raw data
{
"_id": null,
"home_page": null,
"name": "mvs-story-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "molecular, visualization, molviewspec, mvsj, protein, chemistry",
"author": null,
"author_email": "Brian <brian@junction.bio>",
"download_url": "https://files.pythonhosted.org/packages/b8/d2/3659b9f857dedb13bf920991cfc3a020b27d2bcf844b5fa7044d518ac954/mvs-story-generator-0.0.1.tar.gz",
"platform": null,
"description": "# MVS Story Generator\n\nA Python library for generating MolViewSpec JSON (MVSJ) files for molecular visualizations and multi-state stories.\n\n## Overview\n\nMVS 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.\n\n## Features\n\n- **Single-state visualizations**: Create protein cartoons, ligand views, multi-component visualizations, and surface representations\n- **Multi-state stories**: Build animated molecular stories with transitions between different visualization states\n- **Surface support**: Generate molecular surfaces with customizable opacity, probe radius, and hybrid representations\n- **Comprehensive validation**: Input validation for colors, selectors, camera angles, and visualization parameters\n- **Example generation**: Built-in examples for common molecular visualization scenarios\n- **Type safety**: Full type annotations and TypedDict support\n\n## Installation\n\n```bash\npip install mvs-story-generator\n```\n\n## Quick Start\n\n### Basic Protein Visualization\n\n```python\nfrom mvs_story_generator import protein_cartoon, save_json\n\n# Create a protein cartoon visualization\nurl = \"https://www.ebi.ac.uk/pdbe/entry-files/1atp.bcif\"\nviz = protein_cartoon(url, title=\"PKA Structure\", color=\"blue\")\n\n# Save to file\nsave_json(viz, \"protein_view.mvsj\")\n```\n\n### Multi-state Story\n\n```python\nfrom mvs_story_generator import create_multi_state_story\n\n# Define states for a rotation story\nconfigs = [\n {\"url\": url, \"viz_type\": \"protein_cartoon\", \"color\": \"blue\", \"camera_angle\": \"up\", \"title\": \"Top View\"},\n {\"url\": url, \"viz_type\": \"protein_cartoon\", \"color\": \"blue\", \"camera_angle\": \"right\", \"title\": \"Side View\"},\n {\"url\": url, \"viz_type\": \"protein_cartoon\", \"color\": \"blue\", \"camera_angle\": \"flip_horizontal\", \"title\": \"Back View\"}\n]\n\nstory = create_multi_state_story(configs, title=\"Protein Rotation Story\")\nsave_json(story, \"rotation_story.mvsj\")\n```\n\n### Surface Visualization\n\n```python\nfrom mvs_story_generator import protein_surface_with_cartoon\n\n# Create hybrid protein visualization with both cartoon and surface\nhybrid_viz = protein_surface_with_cartoon(\n url=url,\n title=\"Protein Structure with Surface\",\n cartoon_color=\"#4577B2\",\n surface_color=\"#D0D0D0\", \n surface_opacity=0.4\n)\n\nsave_json(hybrid_viz, \"hybrid_protein.mvsj\")\n```\n\n## API Reference\n\n### Basic Visualizations\n\n- `protein_cartoon()` - Protein cartoon representation with optional surface\n- `ligand_view()` - Ligand ball-and-stick visualization with optional surface\n- `multi_component_colored_view()` - Multi-component visualization with different colors\n- `multi_component_ligand_focus()` - Ligand-focused view with protein context\n\n### Surface Visualizations\n\n- `protein_surface()` - Standalone protein surface visualization\n- `ligand_surface()` - Standalone ligand surface visualization \n- `protein_surface_with_cartoon()` - Hybrid protein cartoon + surface\n- `ligand_surface_with_sticks()` - Hybrid ligand ball-and-stick + surface\n\n### Multi-state Stories\n\n- `create_multi_state_story()` - Create custom multi-state molecular stories\n- `protein_rotation_story()` - Protein rotation with multiple camera angles\n- `structure_comparison_story()` - Compare multiple molecular structures\n- `protein_surface_evolution_story()` - Surface opacity evolution\n- `ligand_representation_transition_story()` - Ligand representation transitions\n- `protein_ligand_surface_story()` - Protein-ligand surface interactions\n- `hybrid_representation_showcase_story()` - Showcase different representation types\n\n### Utilities\n\n- `save_json()` - Save MVSJ data to JSON file\n- `generate_examples()` - Generate example visualizations\n\n## Examples\n\n### Generate Built-in Examples\n\n```python\nfrom mvs_story_generator import generate_examples\n\n# Generate kinase protein examples\ngenerate_examples(\"kinases\", output_dir=\"examples/kinases\")\n\n# Generate surface visualization examples \ngenerate_examples(\"surface_examples\", output_dir=\"examples/surfaces\")\n\n# Generate multi-state stories\ngenerate_examples(\"multi_state_stories\", output_dir=\"examples/stories\")\n\n# Generate surface-focused stories\ngenerate_examples(\"surface_stories\", output_dir=\"examples/surface_stories\")\n```\n\n### Custom Labels and Highlighting\n\n```python\nfrom mvs_story_generator import multi_component_colored_view\n\n# Add labels and highlight specific residues\nlabels = [\n {\"text\": \"Active Site\", \"selector\": \"ligand\"},\n {\"text\": \"Key Residue\", \"selector\": {\"label_asym_id\": \"A\", \"label_seq_id\": 72}}\n]\n\nhighlight_residues = [(\"A\", 72), (\"A\", 95)]\n\nviz = multi_component_colored_view(\n url=url,\n title=\"Annotated Structure\", \n labels=labels,\n highlight_residues=highlight_residues,\n highlight_color=\"#ff0000\"\n)\n```\n\n### Surface Parameters\n\n```python\nfrom mvs_story_generator import ligand_surface\n\n# Customize surface properties\nsurface_viz = ligand_surface(\n url=url,\n title=\"Ligand Surface\",\n color=\"#90EE90\",\n opacity=0.7,\n probe_radius=1.4, # Probe radius for surface calculation\n camera_angle=\"right\"\n)\n```\n\n## Type Definitions\n\nThe library provides TypedDict classes for configuration:\n\n```python\nfrom mvs_story_generator import LabelConfig, StateConfig\n\n# Label configuration\nlabel: LabelConfig = {\n \"text\": \"Binding Site\",\n \"selector\": \"ligand\",\n \"color\": \"#ff0000\" # optional\n}\n\n# State configuration for multi-state stories\nstate: StateConfig = {\n \"url\": \"https://www.ebi.ac.uk/pdbe/entry-files/1atp.bcif\",\n \"viz_type\": \"protein_cartoon\",\n \"color\": \"blue\",\n \"camera_angle\": \"up\",\n \"title\": \"Overview\",\n \"duration\": 3000, # ms\n \"transition_duration\": 1000, # ms\n \"include_surface\": True,\n \"surface_opacity\": 0.3\n}\n```\n\n## Supported Parameters\n\n### Colors\n- Named colors: `\"red\"`, `\"blue\"`, `\"green\"`, `\"protein_orange\"`, `\"nucleic_blue\"`, `\"ligand_green\"`, etc.\n- Hex colors: `\"#ff0000\"`, `\"#4577B2\"`, etc.\n\n### Camera Angles\n- `\"up\"`, `\"down\"`, `\"left\"`, `\"right\"`\n- `\"flip_horizontal\"`, `\"flip_vertical\"`\n\n### Selectors\n- Static selectors: `\"all\"`, `\"polymer\"`, `\"protein\"`, `\"nucleic\"`, `\"ligand\"`, `\"ion\"`, `\"water\"`\n- ComponentExpression dictionaries: `{\"label_asym_id\": \"A\", \"label_seq_id\": 72}`\n\n### Representation Types\n- `\"cartoon\"`, `\"ball_and_stick\"`, `\"surface\"`, `\"spacefill\"`, `\"ribbon\"`, `\"tube\"`, `\"line\"`\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=mvs_story_generator\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack mvs_story_generator/\n\n# Lint code \nflake8 mvs_story_generator/\n\n# Type checking\nmypy mvs_story_generator/\n```\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Authors\n\n- Brian <brian@junction.bio>\n\n## Links\n\n- [MolViewSpec Documentation](https://molviewspec.org/)\n- [PDBe API](https://www.ebi.ac.uk/pdbe/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for generating MolViewSpec JSON (MVSJ) files for molecular visualizations",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/JunctionBioscience/mvs-story-generator",
"Issues": "https://github.com/JunctionBioscience/mvs-story-generator/issues",
"Repository": "https://github.com/JunctionBioscience/mvs-story-generator"
},
"split_keywords": [
"molecular",
" visualization",
" molviewspec",
" mvsj",
" protein",
" chemistry"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9041f051001d52aa48833424c697808e5b10dd80c976e70dfd2e7aa7d609b4c6",
"md5": "ca8193c86ba7af8ef337ef6976977348",
"sha256": "d9dff64f859e27a52395bb824a346bbd838b1261edd9d0bdc6c9d192ad584e51"
},
"downloads": -1,
"filename": "mvs_story_generator-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca8193c86ba7af8ef337ef6976977348",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 86147,
"upload_time": "2025-07-20T15:22:55",
"upload_time_iso_8601": "2025-07-20T15:22:55.723162Z",
"url": "https://files.pythonhosted.org/packages/90/41/f051001d52aa48833424c697808e5b10dd80c976e70dfd2e7aa7d609b4c6/mvs_story_generator-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b8d23659b9f857dedb13bf920991cfc3a020b27d2bcf844b5fa7044d518ac954",
"md5": "dbfc899a5327b129abe6b7b90e390d2c",
"sha256": "7981f598a17c38a6ddb0115cb3c540b72f115a49542717355422bf0b2589c741"
},
"downloads": -1,
"filename": "mvs-story-generator-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "dbfc899a5327b129abe6b7b90e390d2c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26190,
"upload_time": "2025-07-20T15:22:56",
"upload_time_iso_8601": "2025-07-20T15:22:56.897608Z",
"url": "https://files.pythonhosted.org/packages/b8/d2/3659b9f857dedb13bf920991cfc3a020b27d2bcf844b5fa7044d518ac954/mvs-story-generator-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 15:22:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JunctionBioscience",
"github_project": "mvs-story-generator",
"github_not_found": true,
"lcname": "mvs-story-generator"
}
JSON
