protspace 2.2.0__tar.gz → 2.3.0__tar.gz

{protspace-2.2.0 → protspace-2.3.0}/CHANGELOG.md

@@ -1,6 +1,56 @@
 # CHANGELOG
 
 
+## v2.3.0 (2025-09-30)
+
+### Documentation
+
+* docs: Update README and CLI help to enhance feature extraction guidance
+
+- Added a new section in README for the JavaScript frontend
+- Revised the "Quick Start" section for clarity and updated usage examples for querying UniProt and processing local data.
+- Expanded help text in CLI for feature extraction to include available UniProt, InterPro, and Taxonomy features. ([`56e17b2`](https://github.com/tsenoner/protspace/commit/56e17b28b60827be2cf4f63f083a52a85f2ac166))
+
+### Features
+
+* feat(umap): add random_state parameter for reproducibility
+
+Add random_state parameter with default value of 42 to ensure
+reproducible UMAP results across runs.
+
+- Add random_state field to DimensionReductionConfig (default: 42)
+- Update UMAPReducer to pass random_state to UMAP constructor
+- Add --random_state CLI argument to protspace-local and protspace-query
+- Update base_data_processor to include random_state in valid config keys
+- All 53 tests passing
+
+Fixes #16 ([`63b7df8`](https://github.com/tsenoner/protspace/commit/63b7df80ea480e661e73052c3f2e395f93976a6c))
+
+* feat: enhance taxonomy feature retrieval with error handling and cache management
+
+- Added error handling in get_taxonomy_features to log and return an empty mapping on fetch errors.
+- Improved _initialize_taxdb to support environment variable for cache directory and implemented a safe refresh strategy for the taxonomy database.
+- Updated logic to handle first-time setup and cache refresh without losing existing data. ([`47826e9`](https://github.com/tsenoner/protspace/commit/47826e9b796e840282d1263d3ae85a31a56c5d18))
+
+### Refactoring
+
+* refactor: simplify download_plot and save_plot functions
+
+- Remove strict width/height requirements for 2D plots
+- Eliminate unused parameters in download_plot callback
+- Add proper HTML file handling in generate_plot
+- Improve code maintainability and compatibility ([`8c3f3e9`](https://github.com/tsenoner/protspace/commit/8c3f3e9df07a98a2ee0a85d91d592f001feb9139))
+
+### Unknown
+
+* Merge branch 'stage' ([`5716992`](https://github.com/tsenoner/protspace/commit/57169922e79968b7c5257f8841185de113982197))
+
+* chor: update image generation to include PCA_3 projection
+
+- Changed the projection list to use only "PCA_3" for image generation.
+- Added support for HTML file format in the image output. ([`36551f3`](https://github.com/tsenoner/protspace/commit/36551f3748ca0e74447c91db98a5c24c9d845dd4))
+
+
 ## v2.2.0 (2025-08-07)
 
 ### Documentation

{protspace-2.2.0 → protspace-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protspace
-Version: 2.2.0
+Version: 2.3.0
 Summary: A visualisation tool for protein embeddings from pLMs
 Author-email: Tobias Senoner <tobias.senoner@tum.de>
 License-Expression: GPL-3.0
@@ -45,6 +45,8 @@ ProtSpace is a visualization tool for exploring **protein embeddings** or **simi
 
 **Web Interface**: https://protspace.rostlab.org/
 
+**New JavaScript Frontend** _(in development)_: https://tsenoner.github.io/protspace_d3/ -> Drag & drop `.parquetbundle` files
+
 ## 🚀 Quick Start with Google Colab
 
 **Note**: Use Chrome or Firefox for best experience.
@@ -67,41 +69,30 @@ pip install protspace
 pip install "protspace[frontend]"
 ```
 
-## 🎯 Usage
+## 🎯 Quick Start
 
 ### 1. Query UniProt directly
 
 ```bash
-# Search and analyze proteins from UniProt with available protein features
-protspace-query -q "insulin AND organism_id:9606 AND reviewed:true" -o output_dir -m pca2,umap3
+# Retrieve and analyze proteins from UniProt using sequence similarity (mmmseqs2)
+protspace-query -q "(ft_domain:phosphatase) AND (reviewed:true)" -o output_dir -m pca2,pca3,umap2 -f "protein_families,fragment,kingdom,superfamily" --n_neighbors 30 --min_dist 0.4
 ```
 
 ### 2. Process local data
 
 ```bash
-# Process your own embeddings or similarity matrices with the protein features you want
-protspace-local -i embeddings.h5 -f signal_peptide,pfam -o output_dir -m pca2,pca3
+# Analyse and vizualise your locally stored embeddings
+protspace-local -i embeddings.h5 -o output_dir -m pca2,umap2
 ```
 
 ### 3. Launch visualization
 
 ```bash
-# Auto-detects JSON files or Arrow directories
 protspace output_dir
-protspace output.json
 ```
 
 Access at `http://localhost:8050`
 
-## ✨ Features
-
-- **Interactive visualization**: 2D/3D plots with multiple dimensionality reduction methods (PCA, UMAP, t-SNE, MDS, PaCMAP)
-- **Feature-based styling**: Color-code and shape proteins by various features
-- **Structure integration**: View 3D protein structures alongside embeddings
-- **Search & highlight**: Find and highlight specific proteins
-- **Export options**: High-quality SVG (2D) and interactive HTML (3D)
-- **Responsive interface**: Works on desktop and mobile
-
 ## 📊 Example Outputs
 
 ### 2D Scatter Plot
@@ -112,6 +103,23 @@ Access at `http://localhost:8050`
 
 [View 3D Example](https://tsenoner.github.io/protspace/examples/out/3FTx/UMAP3_major_group.html)
 
+## ✨ Features
+
+- **Multiple projections**: PCA, UMAP, t-SNE, MDS, PaCMAP in 2D/3D
+- **Automatic feature extraction**: Use `-f` to color-code proteins by UniProt, InterPro, or Taxonomy features
+- **3D structure viewer**: Integrated protein structure visualization
+- **Export**: SVG (2D) and HTML (3D) formats
+
+### Available Features (use with `-f`)
+
+**UniProt**: `annotation_score`, `fragment`, `length_fixed`, `length_quantile`, `protein_existence`, `protein_families`, `reviewed`
+
+**InterPro**: `cath`, `superfamily`, `signal_peptide`
+
+**Taxonomy**: `kingdom`, `phylum`, `class`, `order`, `family`, `genus`, `species`
+
+_Note: Some taxonomy parsing may have minor issues. Additional features in development._
+
 ## 🔧 Advanced Usage
 
 ### Command Options

{protspace-2.2.0 → protspace-2.3.0}/README.md

@@ -12,6 +12,8 @@ ProtSpace is a visualization tool for exploring **protein embeddings** or **simi
 
 **Web Interface**: https://protspace.rostlab.org/
 
+**New JavaScript Frontend** _(in development)_: https://tsenoner.github.io/protspace_d3/ -> Drag & drop `.parquetbundle` files
+
 ## 🚀 Quick Start with Google Colab
 
 **Note**: Use Chrome or Firefox for best experience.
@@ -34,41 +36,30 @@ pip install protspace
 pip install "protspace[frontend]"
 ```
 
-## 🎯 Usage
+## 🎯 Quick Start
 
 ### 1. Query UniProt directly
 
 ```bash
-# Search and analyze proteins from UniProt with available protein features
-protspace-query -q "insulin AND organism_id:9606 AND reviewed:true" -o output_dir -m pca2,umap3
+# Retrieve and analyze proteins from UniProt using sequence similarity (mmmseqs2)
+protspace-query -q "(ft_domain:phosphatase) AND (reviewed:true)" -o output_dir -m pca2,pca3,umap2 -f "protein_families,fragment,kingdom,superfamily" --n_neighbors 30 --min_dist 0.4
 ```
 
 ### 2. Process local data
 
 ```bash
-# Process your own embeddings or similarity matrices with the protein features you want
-protspace-local -i embeddings.h5 -f signal_peptide,pfam -o output_dir -m pca2,pca3
+# Analyse and vizualise your locally stored embeddings
+protspace-local -i embeddings.h5 -o output_dir -m pca2,umap2
 ```
 
 ### 3. Launch visualization
 
 ```bash
-# Auto-detects JSON files or Arrow directories
 protspace output_dir
-protspace output.json
 ```
 
 Access at `http://localhost:8050`
 
-## ✨ Features
-
-- **Interactive visualization**: 2D/3D plots with multiple dimensionality reduction methods (PCA, UMAP, t-SNE, MDS, PaCMAP)
-- **Feature-based styling**: Color-code and shape proteins by various features
-- **Structure integration**: View 3D protein structures alongside embeddings
-- **Search & highlight**: Find and highlight specific proteins
-- **Export options**: High-quality SVG (2D) and interactive HTML (3D)
-- **Responsive interface**: Works on desktop and mobile
-
 ## 📊 Example Outputs
 
 ### 2D Scatter Plot
@@ -79,6 +70,23 @@ Access at `http://localhost:8050`
 
 [View 3D Example](https://tsenoner.github.io/protspace/examples/out/3FTx/UMAP3_major_group.html)
 
+## ✨ Features
+
+- **Multiple projections**: PCA, UMAP, t-SNE, MDS, PaCMAP in 2D/3D
+- **Automatic feature extraction**: Use `-f` to color-code proteins by UniProt, InterPro, or Taxonomy features
+- **3D structure viewer**: Integrated protein structure visualization
+- **Export**: SVG (2D) and HTML (3D) formats
+
+### Available Features (use with `-f`)
+
+**UniProt**: `annotation_score`, `fragment`, `length_fixed`, `length_quantile`, `protein_existence`, `protein_families`, `reviewed`
+
+**InterPro**: `cath`, `superfamily`, `signal_peptide`
+
+**Taxonomy**: `kingdom`, `phylum`, `class`, `order`, `family`, `genus`, `species`
+
+_Note: Some taxonomy parsing may have minor issues. Additional features in development._
+
 ## 🔧 Advanced Usage
 
 ### Command Options

{protspace-2.2.0 → protspace-2.3.0}/examples/image_creation.py

@@ -19,7 +19,8 @@ def main():
     #     print("Available projection names:", reader.get_projection_names())
 
     # Generate images for specific projections and features
-    projections = ["PCA_2"]
+    # projections = ["PCA_2", "PCA_3"]
+    projections = ["PCA_3"]
     features = ["protein_existence", "annotation_score"]
 
     # Create the output directory if it doesn't exist
@@ -34,6 +35,7 @@ def main():
                 filename=output_dir / f"{projection}_{feature}",
                 width=1600,
                 height=1000,
+                file_format="html",
             )
             print(f"Generated image for {projection} - {feature}")