From 8e0c7d6d84b8209215cab8013c7e98e23fbe1dd6 Mon Sep 17 00:00:00 2001 From: NCCU-Schultz-Lab Date: Sat, 18 Apr 2026 13:03:36 -0400 Subject: [PATCH] Doc updates reflecting Dash migration Key changes: - Add dash and dash-bootstrap-components to requirements.txt and environment.yml; remove streamlit entries. - Update README (logo URL, GUI launch command, examples, roadmap link) and fix code formatting/indentation. - Update documentation (about.md, installation.md, contributing.md, tutorials/index.md): switch Streamlit references to Dash, bump docs version, update installation Python minimum, and adjust contribution/test instructions and links. - Bump project version to 0.2.1 in pyproject.toml and remove explicit author email; add CHANGELOG entry for 0.2.1. - Raise black minimum to >=24.3.0 in requirements.txt. - Update tests/test_performance.py to reflect Dash and new caching guidance. These changes migrate the GUI stack, ensure docs and CI/dev tooling align with the new GUI, and bump the package version. --- CHANGELOG.md | 13 +++++++++++++ README.md | 34 +++++++++++++++++++--------------- docs/about.md | 13 +++++++------ docs/contributing.md | 17 ++++++++++------- docs/installation.md | 4 ++-- docs/tutorials/index.md | 2 +- environment.yml | 3 ++- pyproject.toml | 6 +++--- requirements.txt | 7 ++++--- tests/test_performance.py | 4 ++-- 10 files changed, 63 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 02c635b..1dfb62b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,10 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.1] - 2026-04-18 + ### Changed - GUI migrated from Streamlit to Dash — launch with `python examples/gui_app.py` - `gui` optional dependency updated: `dash>=2.14.0` + `dash-bootstrap-components>=1.5.0` (replaces `streamlit`) - `launch_app.bat` and `stop_app.bat` updated for Dash process management +- Bumped `black` minimum from `>=23.0.0` to `>=24.3.0` in `requirements.txt` + +### Fixed +- Removed stale `streamlit` dependency from `requirements.txt` and `environment.yml` +- Corrected all remaining Streamlit references in docs to Dash (`about.md`, `installation.md`, `contributing.md`, `tutorials/index.md`) +- Updated version number from 0.1.0 to 0.2.0 in `docs/about.md` (including BibTeX citation) +- Fixed Python minimum version in `docs/installation.md` (3.8 → 3.9) +- Updated author contact email to `The-Schultz-Lab@users.noreply.github.com` in `docs/about.md` +- Replaced broken `docs/ROADMAP.md` and `docs/PERFORMANCE_TESTING_GUIDE.md` links in `README.md` and `docs/contributing.md` +- Updated stale Streamlit cache reference in `tests/test_performance.py` +- Fixed logo not rendering on PyPI by replacing relative `logo.svg` path with absolute raw GitHub URL ## [0.2.0] - 2026-04-04 diff --git a/README.md b/README.md index 4214c6a..cd51951 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # plotlyMol

- plotlyMol Logo + plotlyMol Logo

[![Tests](https://github.com/The-Schultz-Lab/plotlyMol/actions/workflows/test.yml/badge.svg)](https://github.com/The-Schultz-Lab/plotlyMol/actions/workflows/test.yml) @@ -20,11 +20,15 @@ Interactive molecular visualizations with Plotly. Supports SMILES, XYZ, MOL/PDB, - Static displacement arrows - Animated vibrations with interactive controls - Heatmap coloring by displacement magnitude -- Streamlit GUI for interactive exploration +- Dash GUI for interactive exploration ## Installation -### From source (recommended for now) +```bash +pip install plotlymol +``` + +### From source (for development) ```bash git clone https://github.com/The-Schultz-Lab/plotlyMol.git @@ -68,13 +72,13 @@ fig.show() from plotlymol3d import draw_3D_rep fig = draw_3D_rep( - cubefile="path/to/file.cube", - molfile="path/to/file.mol", - mode="ball+stick", - ambient=0.1, - cubedraw="orbitals", - orbital_opacity=0.25, - orbital_colors=["darkorange", "darkblue"], + cubefile="path/to/file.cube", + molfile="path/to/file.mol", + mode="ball+stick", + ambient=0.1, + cubedraw="orbitals", + orbital_opacity=0.25, + orbital_colors=["darkorange", "darkblue"], ) fig.show() ``` @@ -167,10 +171,10 @@ for mode in vib_data.modes: ## GUI -Launch the Streamlit app for interactive controls: +Launch the Dash app for interactive controls: ```bash -streamlit run examples/gui_app.py +python examples/gui_app.py ``` ## Examples @@ -213,7 +217,7 @@ python tests/test_performance.py jupyter notebook examples/performance_benchmarking.ipynb ``` -**Full guide:** [Performance Testing Guide](docs/PERFORMANCE_TESTING_GUIDE.md) +**Full guide:** `docs/PERFORMANCE_TESTING_GUIDE.md` (coming soon) **Key metrics tracked:** @@ -227,7 +231,7 @@ Use these tools to identify bottlenecks and optimize GUI responsiveness. ## Repository layout -``` +```text plotlyMol/ ├─ src/ │ └─ plotlymol3d/ # Library package code + sample data files @@ -241,4 +245,4 @@ plotlyMol/ ## Roadmap -See the current roadmap in [docs/ROADMAP.md](docs/ROADMAP.md). +See [GitHub Issues](https://github.com/The-Schultz-Lab/plotlyMol/issues) for planned features and upcoming work. diff --git a/docs/about.md b/docs/about.md index 3fd8109..42932bb 100644 --- a/docs/about.md +++ b/docs/about.md @@ -9,7 +9,7 @@ plotlyMol is an open-source Python package for creating interactive 3D molecular **Jonathan Schultz** North Carolina Central University, Assistant Professor of Chemistry -**Benjamin Lear** +**[Benjamin Lear](https://github.com/ProfLear)** (The Pennsylvania State University, Professor of Chemistry) ## Motivation @@ -51,7 +51,7 @@ plotlyMol is built on industry-standard scientific Python libraries: ### Optional Components -- **[Streamlit](https://streamlit.io/)** - Web app framework for GUI +- **[Dash](https://dash.plotly.com/)** - Web app framework for GUI - **[Kaleido](https://github.com/plotly/Kaleido)** - Static image export - **pytest** - Testing framework - **black/ruff** - Code quality tools @@ -61,6 +61,7 @@ plotlyMol is built on industry-standard scientific Python libraries: ### Simplicity Simple things should be simple: + ```python from plotlymol3d import draw_3D_rep fig = draw_3D_rep(smiles="CCO") @@ -70,6 +71,7 @@ fig.show() ### Flexibility Complex things should be possible: + ```python fig = draw_3D_rep( cubefile="orbital.cube", @@ -139,7 +141,7 @@ Initial development by Prof. Lear focused on creating a modern molecular visuali ## Project Status -**Current Version**: 0.1.0 (Development) +**Current Version**: 0.2.0 (Development) **Status**: Pre-release @@ -194,7 +196,7 @@ Thanks to the developers of: plotlyMol is released under the [MIT License](https://github.com/The-Schultz-Lab/plotlyMol/blob/main/LICENSE). -``` +```text MIT License Copyright (c) 2026 Jonathan Schultz & Benjamin Lear @@ -214,7 +216,6 @@ copies or substantial portions of the Software. - **GitHub Issues**: [Report issues or request features](https://github.com/The-Schultz-Lab/plotlyMol/issues) - **GitHub Discussions**: [Ask questions or share ideas](https://github.com/The-Schultz-Lab/plotlyMol/discussions) -- **Email**: jonathanschultzNU@users.noreply.github.com ## Citation @@ -226,7 +227,7 @@ If you use plotlyMol in your research, please cite: author = {Schultz, Jonathan and Lear, Benjamin}, year = {2026}, url = {https://github.com/The-Schultz-Lab/plotlyMol}, - note = {Version 0.1.0} + note = {Version 0.2.0} } ``` diff --git a/docs/contributing.md b/docs/contributing.md index ddce0a1..f5d48d2 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,7 +4,7 @@ Thank you for your interest in contributing to plotlyMol! This guide will help y ## Ways to Contribute -### Report Bugs +### Report Bugs Found a bug? Please [open an issue](https://github.com/The-Schultz-Lab/plotlyMol/issues/new) with: @@ -14,7 +14,7 @@ Found a bug? Please [open an issue](https://github.com/The-Schultz-Lab/plotlyMol - System information (OS, Python version) - Minimal code example -### Suggest Features +### Suggest Features Have an idea? We'd love to hear it! [Open an issue](https://github.com/The-Schultz-Lab/plotlyMol/issues/new) describing: @@ -22,7 +22,7 @@ Have an idea? We'd love to hear it! [Open an issue](https://github.com/The-Schul - Why it would be valuable - Possible implementation approach (optional) -### Improve Documentation +### Improve Documentation Documentation improvements are always welcome: @@ -31,7 +31,7 @@ Documentation improvements are always welcome: - Improve API documentation - Translate documentation (future) -### Submit Code +### Submit Code Ready to code? Great! Follow the guidelines below. @@ -213,11 +213,13 @@ pre-commit run --all-files All pull requests must pass CI checks: #### Test Workflow + - Runs on Ubuntu, macOS, Windows - Tests Python 3.9, 3.10, 3.11, 3.12 - Runs full test suite with coverage #### Lint Workflow + - Black formatting check - Ruff linting - Mypy type checking @@ -297,6 +299,7 @@ Your PR should: To add support for a new file format: 1. Add parser function in `plotlyMol3D.py`: + ```python def newformat_to_rdkitmol(filepath: str) -> Chem.Mol: """Parse new format file to RDKit Mol.""" @@ -320,10 +323,10 @@ To add new visualization features: #### 3. GUI Features -To enhance the Streamlit GUI: +To enhance the Dash GUI: 1. Modify `src/plotlymol3d/app.py` -2. Test manually with `streamlit run` +2. Test manually with `python examples/gui_app.py` 3. Update user guide ## Documentation @@ -397,7 +400,7 @@ We use [Semantic Versioning](https://semver.org/): ## Development Roadmap -See [ROADMAP.md](roadmap.md) for planned features and improvements. +See [GitHub Issues](https://github.com/The-Schultz-Lab/plotlyMol/issues) for planned features and improvements. ## Recognition diff --git a/docs/installation.md b/docs/installation.md index 8690561..a1d1a43 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ ## Requirements -plotlyMol requires **Python 3.8 or higher**. +plotlyMol requires **Python 3.9 or higher**. ## Install from Source @@ -50,7 +50,7 @@ This includes: - **black** - Code formatting - **ruff** - Fast linting - **mypy** - Type checking -- **streamlit** - GUI application +- **dash** + **dash-bootstrap-components** - GUI application ## Verify Installation diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index ed0ae37..f82466b 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -87,7 +87,7 @@ Comprehensive tutorials are currently in development! Check back soon for: - Embedding visualizations - Building web apps - API integration - - Streamlit deployment + - Dash deployment ## Jupyter Notebooks diff --git a/environment.yml b/environment.yml index 78b7e49..a0ae230 100644 --- a/environment.yml +++ b/environment.yml @@ -11,7 +11,8 @@ dependencies: - numpy>=1.20.0 # GUI - - streamlit>=1.30.0 + - dash>=2.14.0 + - dash-bootstrap-components>=1.5.0 # Testing - pytest>=7.0.0 diff --git a/pyproject.toml b/pyproject.toml index 0271790..a2cd2c8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta" [project] name = "plotlymol" -version = "0.2.0" +version = "0.2.1" description = "A package to create interactive molecular visualizations using Plotly" readme = "README.md" authors = [ - {name = "Jonathan Schultz", email = "jonathanschultzNU@users.noreply.github.com"}, + {name = "Jonathan Schultz"}, {name = "Benjamin Lear"} ] license = {text = "MIT"} @@ -154,7 +154,7 @@ ignore = [ ] [tool.ruff.lint.per-file-ignores] -"tests/*" = ["ARG", "S101"] +"tests/*" = ["ARG", "S101", "E402"] "src/plotlymol3d/__init__.py" = ["F403"] "src/plotlymol3d/test.py" = ["ALL"] "src/plotlymol3d/Cube_to_Blender*" = ["ALL"] diff --git a/requirements.txt b/requirements.txt index 8ba36a2..ea38571 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,7 +9,7 @@ pytest>=7.0.0 pytest-cov>=4.0.0 # Linting and Formatting -black>=23.0.0 +black>=24.3.0 ruff>=0.1.0 flake8>=6.0.0 @@ -19,8 +19,9 @@ mypy>=1.0.0 # Optional: Pre-commit hooks pre-commit>=3.0.0 -# GUI for visual testing -streamlit>=1.30.0 +# GUI +dash>=2.14.0 +dash-bootstrap-components>=1.5.0 # Documentation mkdocs>=1.5.0 diff --git a/tests/test_performance.py b/tests/test_performance.py index 0b56045..5be777b 100644 --- a/tests/test_performance.py +++ b/tests/test_performance.py @@ -515,10 +515,10 @@ def analyze_performance_results(results: dict[str, pd.DataFrame]): # General recommendations print("\n6. GENERAL RECOMMENDATIONS:") - print(" For GUI/Streamlit Performance:") + print(" For GUI/Dash Performance:") print(" • Use resolution=16 for interactive preview (2-3x faster)") print(" • Switch to resolution=32 for final figures") - print(" • Cache parsed vibration files with @st.cache_resource") + print(" • Cache parsed vibration files using session state") print(" • Use 'stick' mode for molecules >50 atoms") print(" • Limit animations to 20-30 frames during development") print(" • Consider 'vdw' mode for very large systems (>100 atoms)")