{"id":25772965,"url":"https://github.com/robaina/protscout","last_synced_at":"2026-06-23T12:04:34.900Z","repository":{"id":277500508,"uuid":"924822948","full_name":"Robaina/ProtScout","owner":"Robaina","description":"Filter protein sequences by predicted protein properties","archived":false,"fork":false,"pushed_at":"2025-10-19T16:49:35.000Z","size":7954,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T03:45:09.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Robaina.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-30T18:01:35.000Z","updated_at":"2026-01-06T10:48:27.000Z","dependencies_parsed_at":"2025-07-19T13:05:14.683Z","dependency_job_id":"b5bf47f2-0144-4b1e-a92d-6c270808beea","html_url":"https://github.com/Robaina/ProtScout","commit_stats":null,"previous_names":["robaina/proteinrank","robaina/protscout"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Robaina/ProtScout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robaina%2FProtScout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robaina%2FProtScout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robaina%2FProtScout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robaina%2FProtScout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Robaina","download_url":"https://codeload.github.com/Robaina/ProtScout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robaina%2FProtScout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34686739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-27T04:28:46.533Z","updated_at":"2026-06-23T12:04:34.882Z","avatar_url":"https://github.com/Robaina.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"text-align: center; width: 100%\"\u003e\n    \u003cimg src=\"imgs/protscout_logo.png\" max-width=400px height=\"auto\"\u003e\n\u003c/div\u003e\n\n## 🎯 About\n\nProtScout is a Python package that enables ranking of protein sequences based on multiple properties predicted by state-of-the-art AI models. It provides a unified interface to assess and compare proteins using various characteristics such as stability, solubility, catalytic efficiency, and thermal properties.\n\n## ✨ Features\n\n- 🧬 Comprehensive protein property analysis (structure, embeddings, catalytic activity, kinetic parameters, thermal stability, melting temperature, environmental tolerances, solubility, classical properties)\n- 🐳 Containerized execution of prediction tools with Docker\n- 🚀 Modular, parallel workflow with configurable steps and automatic resume\n- 🔄 Automatic retry and resume support for robust execution\n- ✅ Validation and dry-run modes to preview workflow\n- 🔧 Fully configurable via YAML files and environment variable overrides\n- 📈 Detailed logging and resource monitoring\n\n## 🚀 Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Docker (for running containerized prediction tools)\n- NVIDIA GPU with CUDA support (recommended)\n- Conda or Poetry for environment management\n\n### Install with Poetry (Recommended)\n\n```bash\n# Clone repository\ngit clone https://github.com/Robaina/ProtScout.git\ncd ProtScout\n\n# Install Poetry if you haven't already\npip install poetry\n\n\n# Install package and dependencies\npoetry install\n\n# Activate the virtual environment\npoetry shell\n```\n\n### Install with pip\n\n```bash\n# Clone repository\ngit clone https://github.com/Robaina/ProtScout.git\ncd ProtScout\n\n\n# Install in development mode\npip install -e .\n```\n\n## 📋 Quick Start\n\nGenerate a configuration file:\n\n```bash\nprotscout init -o my_config.yaml\n```\n\nEdit the configuration file with your paths and settings:\n\n```yaml\ncondition: ultra\nworkdir: /path/to/your/workdir\nmodeldir: /path/to/model/weights\npython_executable: /path/to/conda/env/bin/python\nmemory: 100g\nworkers: 2\nquiet: true\nmax_retries: 2\npreserve_artifacts: false\n```\n\nValidate your setup:\n\n```bash\nprotscout validate -c my_config.yaml\n```\n\nRun the workflow:\n\n```bash\nprotscout run -c my_config.yaml\n```\n\n## 📖 Usage Examples\n\n### Basic Workflow\n\n```bash\n# Run complete workflow\nprotscout run -c config.yaml\n\n# Run specific steps only\nprotscout run -c config.yaml -s clean_sequences -s esmfold\n\n# Override condition from command line\nprotscout run -c config.yaml --condition ultra\n```\n\n### Advanced Features\n\n```bash\n# Resume from last successful step after failure\nprotscout run -c config.yaml --resume\n\n# Dry run to see what would be executed\nprotscout run -c config.yaml --dry-run\n\n# Monitor logs in real-time\nprotscout logs logs/protscout_run_20240112_143022.log -f\n```\n\n### Parallel Execution\n\nThe workflow automatically runs compatible steps in parallel:\n\n- ESMFold and ESM-2 run simultaneously\n- All prediction tools (CatPred, Catapro, Temberture, Temstapro, GeoPoc, GATSol) run in parallel\n- Result processing steps are parallelized\n\n## 🔧 Configuration\n\nProtScout uses YAML configuration files for workflow management. Key configuration sections:\n\n```yaml\n# Analysis condition\ncondition: ultra\n\n# Core directories\nworkdir: /path/to/your/workdir\nmodeldir: /path/to/model/weights\n\n# Execution settings\npython_executable: /path/to/conda/env/bin/python\nmemory: 100g\nworkers: 2\nquiet: true\nmax_retries: 2\npreserve_artifacts: false\n\n# Container images (optional overrides)\ncontainers:\n  esmfold:\n    image: ghcr.io/new-atlantis-labs/esmfold:latest\n    max_containers: 1\n  # ... other containers: esm2, catpred, catapro, temberture, temstapro, geopoc, gatsol\n\n# GPU and shared memory settings\nresources:\n  gpus: all\n  shm_size: 100g\n\n# Workflow steps\nsteps:\n  - clean_sequences\n  - esmfold\n  - esm2\n  - remove_sequences_without_pdb\n  - prepare_catpred\n  - catpred\n  - catapro\n  - temberture\n  - temstapro\n  - geopoc\n  - gatsol\n  - classical_properties\n  - process_temberture\n  - process_temstapro\n  - process_geopoc\n  - process_gatsol\n  - process_catpred\n  - process_catapro\n  - consolidate_results\n```\n\nSee `configs/example_workflow.yaml` for a complete example.\n\n## 🛠️ Workflow Steps\n\n- `clean_sequences` - Clean and deduplicate input sequences\n- `esmfold` - Predict protein structures using ESMFold\n- `esm2` - Generate protein embeddings using ESM-2\n- `remove_sequences_without_pdb` - Filter sequences without structures\n- `prepare_catpred` - Prepare inputs for catalytic prediction\n- `catpred` - Predict catalytic properties\n- `catapro` - Predict kinetic parameters (KM, Kcat, catalytic efficiency)\n- `temberture` - Predict temperature stability\n- `temstapro` - Predict melting temperature\n- `geopoc` - Predict environmental conditions (temp, pH, salt)\n- `gatsol` - Predict solubility\n- `classical_properties` - Calculate classical protein properties\n- `process_*` - Process results from each tool\n- `consolidate_results` - Create final output tables\n\n## 📊 Output Structure\n\n```\n\u003cartifacts_dir\u003e/                  # raw outputs (artifacts)\n├── structures/                   # PDB files from ESMFold\n├── embeddings/                   # ESM-2 embeddings\n├── clean_sequences/              # cleaned FASTA files\n├── catpred_data/                 # prepared inputs for CatPred\n├── catpred/                      # CatPred raw output\n├── catapro/                      # Catapro kinetic predictions (KM, Kcat, efficiency)\n├── temberture/                   # temperature stability predictions\n├── temstapro/                    # melting temperature predictions\n├── geopoc/                       # environmental predictions (temp, pH, salt)\n└── gatsol/                       # solubility predictions\n\n\u003cresults_dir\u003e/                    # processed results\n├── classical_properties_results/ # classical property outputs\n├── temberture_results/            # processed temperature results\n├── temstapro_results/             # processed melting temperature results\n├── geopoc_results/                # processed environmental results\n├── gatsol_results/                # processed solubility results\n├── catpred_results/               # processed CatPred results\n├── catapro_results/               # processed Catapro kinetic results\n└── consolidated_results/          # final consolidated tables\n```\n\n## 🔄 Resume Capability\n\nProtScout automatically saves workflow state and can resume from failures:\n\n```bash\n# If workflow fails at step 'gatsol'\nprotscout run -c config.yaml --resume\n# Workflow will skip completed steps and continue from 'gatsol'\n```\n\n## 📝 Logging\n\nComprehensive logging with multiple levels:\n\n- Console output: INFO level (progress and important messages)\n- Log file: DEBUG level (detailed execution information)\n\nLogs are saved to: `{workdir}/logs/protscout_run_YYYYMMDD_HHMMSS.log`\n\n## 🐛 Troubleshooting\n\n### Docker Issues\n\n```bash\n# Check if Docker is running\ndocker info\n\n# Ensure user has Docker permissions\nsudo usermod -aG docker $USER\n```\n\n### GPU Issues\n\n```bash\n# Check GPU availability\nnvidia-smi\n\n# Verify CUDA installation\nnvcc --version\n```\n\n### Memory Issues\n\n- Reduce `max_containers` in configuration\n- Decrease `toks_per_batch` for ESM-2\n- Lower batch sizes for prediction tools\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nThis project is licensed under the GPL-3.0 License - see the LICENSE file for details.\n\n## 📚 Citation\n\nIf you use ProtScout in your research, please cite:\n\n```bibtex\n@software{protscout2024,\n  author = {Robaina-Estévez, Semidán},\n  title = {ProtScout: AI-powered protein sequence ranking},\n  year = {2025},\n  url = {https://github.com/Robaina/ProtScout}\n}\n```\n\n## 🙏 Acknowledgments\n\nProtScout integrates several state-of-the-art protein prediction tools:\n\n- ESMFold for structure prediction\n- ESM-2 for sequence embeddings\n- CatPred for catalytic activity prediction\n- Catapro for kinetic parameters (KM, Kcat, catalytic efficiency)\n- Temberture for thermal stability prediction\n- Temstapro for melting temperature prediction\n- GeoPoc for environmental condition prediction\n- GATSol for solubility prediction","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobaina%2Fprotscout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobaina%2Fprotscout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobaina%2Fprotscout/lists"}