| Name | FlatProt JSON |
| Version |
2.4.9
JSON |
| download |
| home_page | None |
| Summary | Python package for creating simplified 2D protein visualizations. Specialized on showing differences and similarities between proteins of the same protein family. |
| upload_time | 2025-07-31 08:51:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.14,>=3.11 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FlatProt
<img width="910" alt="image" src=".github/images/family_fixed.png">
FlatProt is a tool for 2D protein visualization aimed at improving the comparability of protein structures through standardized 2D visualizations. FlatProt focuses on creating highly comparable representations for same-family proteins.
## 📚 Documentation
**[📖 Full Documentation](https://t03i.github.io/FlatProt/)** - Complete guide with examples, API reference, and tutorials
**[🔬 Interactive Examples](https://t03i.github.io/FlatProt/examples/)** - Jupyter notebooks with Google Colab integration
**[🧬 Try Now: UniProt to Visualization](https://colab.research.google.com/github/t03i/FlatProt/blob/main/examples/uniprot_alphafold.ipynb)** - From any UniProt ID to beautiful 2D visualization in minutes!
## 🚀 Quick Start
### Installation
FlatProt requires Python 3.11-3.13. Install using [uv](https://github.com/astral-sh/uv) (recommended):
**Option 1: Install and use persistently (recommended)**
```bash
# Install FlatProt (makes 'flatprot' command available)
uv tool add FlatProt
# Now you can use flatprot directly
flatprot --help
```
**Option 2: Run without installation**
```bash
# Run FlatProt without installing (use 'uvx flatprot' instead of 'flatprot')
uvx flatprot --help
```
### Dependencies
**Required:**
- [Foldseek](https://github.com/steineggerlab/foldseek) - for structure alignment
- [DSSP](https://pdb-redo.eu/dssp/download) - mkdssp version 4.4.0 (available via brew on macOS)
**Optional:**
- [Cairo](https://cairographics.org/) - for PNG/PDF output from overlay command
### Basic Usage
Generate a 2D protein visualization from a structure file:
```bash
# Option 1: AlphaFold structures (no DSSP needed - secondary structure included!)
flatprot project AF-P69905-F1-model_v4.cif --output protein_2d.svg
# Option 2: PDB/CIF files (add secondary structure first)
mkdssp your_protein.cif your_protein_with_dssp.cif
flatprot project your_protein_with_dssp.cif --output protein_2d.svg
# Note: If using without installation, replace 'flatprot' with 'uvx flatprot'
```
For detailed installation and usage instructions, see the [documentation](https://t03i.github.io/FlatProt/installation/).
## 📊 Example Visualizations
<img width="409" alt="Cobra protein visualization" src=".github/images/cobra.png">
<img width="409" alt="Protein overlay visualization" src=".github/images/overlay.png">
## Contributing
We welcome contributions to FlatProt! If you'd like to contribute, please follow these steps:
1. **Fork the repository:** Create your own fork of the FlatProt repository on GitHub.
2. **Create a branch:** Make your changes in a dedicated branch in your fork.
3. **Submit a pull request:** Open a pull request from your branch to the `staging` branch of the t03i/FlatProt repository.
Please ensure your contributions adhere to the project's coding style and include tests where appropriate. For major changes, please open an issue first to discuss what you would like to change.
See [CONTRIBUTING.md](CONTRIBUTING.md) for more detailed guidelines.
## 📖 Citation & Data
If you use FlatProt in your research, please cite our preprint:
> **FlatProt: 2D visualization eases protein structure comparison**
> Tobias Olenyi, Constantin Carl, Tobias Senoner, Ivan Koludarov, Burkhard Rost
> *bioRxiv* 2025.04.22.650077; doi: [https://doi.org/10.1101/2025.04.22.650077](https://doi.org/10.1101/2025.04.22.650077)
**Datasets and supplementary data** are available on Zenodo:
[](https://doi.org/10.5281/zenodo.15697296)
## 🔧 CLI Commands
FlatProt provides four main commands:
- `flatprot project` - Create 2D SVG projections from protein structures
- `flatprot align` - Align protein structures using rotation
- `flatprot overlay` - Create overlay visualizations from multiple structures
- `flatprot split` - Extract and align structural regions for comparison
See the [CLI documentation](https://t03i.github.io/FlatProt/commands/project/) for detailed usage.
## 🔄 Common Workflows
**Note:** The following examples assume you've installed FlatProt with `uv tool add FlatProt`. If you're using the no-install option, replace `flatprot` with `uvx flatprot` in all commands.
### Single Structure Visualization
```bash
# AlphaFold structures (recommended - no preprocessing needed!)
flatprot project AF-P69905-F1-model_v4.cif --output protein_2d.svg
# Traditional PDB/CIF files (requires DSSP preprocessing)
mkdssp your_protein.cif your_protein_with_dssp.cif
flatprot project your_protein_with_dssp.cif --output protein_2d.svg
```
### Aligned Structure Visualization
```bash
# 1. Find optimal family alignment
flatprot align protein.cif -m alignment_matrix.npy
# 2. Create aligned 2D projection
flatprot project protein.cif --matrix alignment_matrix.npy -o aligned_protein.svg
```
### Family Comparison Workflow
```bash
# 1. Find optimal alignment for family
flatprot align reference_protein.cif -i family_info.json
# 2. Extract family ID from results
family_id=$(jq -r '.best_hit.target_id' family_info.json)
# 3. Create conserved overlay using fixed family ID
flatprot overlay "family_proteins/*.cif" --family "$family_id" -o family_overlay.png
```
### Domain Analysis Workflow
```bash
# 1. Create full structure view
flatprot project protein.cif -o full_structure.svg
# 2. Extract and align specific domains
flatprot split protein.cif --regions "A:1-100,A:150-250" --show-database-alignment -o domains.svg
# 3. Create domain overlay for comparison
flatprot overlay "domain_structures/*.cif" --family 3000114 -o domain_comparison.png
```
### Custom Alignment Workflow
```bash
# 1. Generate alignment matrix from first structure
flatprot align reference.cif -m alignment_matrix.npy
# 2. Apply same alignment to all structures
for file in *.cif; do
flatprot project "$file" --matrix alignment_matrix.npy -o "aligned_${file%.cif}.svg"
done
```
## License
FlatProt is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "FlatProt",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Tobias O <tobias.olenyi@tum.de>, Constantin C <ge37goy@mytum.de>",
"download_url": "https://files.pythonhosted.org/packages/fd/ec/61157594aaef4dca5c45b6e2e77fbd7cbd214b8b9e5e686e28003aeca163/flatprot-2.4.9.tar.gz",
"platform": null,
"description": "# FlatProt\n\n<img width=\"910\" alt=\"image\" src=\".github/images/family_fixed.png\">\n\nFlatProt is a tool for 2D protein visualization aimed at improving the comparability of protein structures through standardized 2D visualizations. FlatProt focuses on creating highly comparable representations for same-family proteins.\n\n## \ud83d\udcda Documentation\n\n**[\ud83d\udcd6 Full Documentation](https://t03i.github.io/FlatProt/)** - Complete guide with examples, API reference, and tutorials\n\n**[\ud83d\udd2c Interactive Examples](https://t03i.github.io/FlatProt/examples/)** - Jupyter notebooks with Google Colab integration\n\n**[\ud83e\uddec Try Now: UniProt to Visualization](https://colab.research.google.com/github/t03i/FlatProt/blob/main/examples/uniprot_alphafold.ipynb)** - From any UniProt ID to beautiful 2D visualization in minutes!\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\nFlatProt requires Python 3.11-3.13. Install using [uv](https://github.com/astral-sh/uv) (recommended):\n\n**Option 1: Install and use persistently (recommended)**\n```bash\n# Install FlatProt (makes 'flatprot' command available)\nuv tool add FlatProt\n\n# Now you can use flatprot directly\nflatprot --help\n```\n\n**Option 2: Run without installation**\n```bash\n# Run FlatProt without installing (use 'uvx flatprot' instead of 'flatprot')\nuvx flatprot --help\n```\n\n### Dependencies\n\n**Required:**\n- [Foldseek](https://github.com/steineggerlab/foldseek) - for structure alignment\n- [DSSP](https://pdb-redo.eu/dssp/download) - mkdssp version 4.4.0 (available via brew on macOS)\n\n**Optional:**\n- [Cairo](https://cairographics.org/) - for PNG/PDF output from overlay command\n\n### Basic Usage\n\nGenerate a 2D protein visualization from a structure file:\n\n```bash\n# Option 1: AlphaFold structures (no DSSP needed - secondary structure included!)\nflatprot project AF-P69905-F1-model_v4.cif --output protein_2d.svg\n\n# Option 2: PDB/CIF files (add secondary structure first)\nmkdssp your_protein.cif your_protein_with_dssp.cif\nflatprot project your_protein_with_dssp.cif --output protein_2d.svg\n\n# Note: If using without installation, replace 'flatprot' with 'uvx flatprot'\n```\n\nFor detailed installation and usage instructions, see the [documentation](https://t03i.github.io/FlatProt/installation/).\n\n## \ud83d\udcca Example Visualizations\n\n<img width=\"409\" alt=\"Cobra protein visualization\" src=\".github/images/cobra.png\">\n\n<img width=\"409\" alt=\"Protein overlay visualization\" src=\".github/images/overlay.png\">\n\n## Contributing\n\nWe welcome contributions to FlatProt! If you'd like to contribute, please follow these steps:\n\n1. **Fork the repository:** Create your own fork of the FlatProt repository on GitHub.\n2. **Create a branch:** Make your changes in a dedicated branch in your fork.\n3. **Submit a pull request:** Open a pull request from your branch to the `staging` branch of the t03i/FlatProt repository.\n\nPlease ensure your contributions adhere to the project's coding style and include tests where appropriate. For major changes, please open an issue first to discuss what you would like to change.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more detailed guidelines.\n\n## \ud83d\udcd6 Citation & Data\n\nIf you use FlatProt in your research, please cite our preprint:\n\n> **FlatProt: 2D visualization eases protein structure comparison**\n> Tobias Olenyi, Constantin Carl, Tobias Senoner, Ivan Koludarov, Burkhard Rost\n> *bioRxiv* 2025.04.22.650077; doi: [https://doi.org/10.1101/2025.04.22.650077](https://doi.org/10.1101/2025.04.22.650077)\n\n**Datasets and supplementary data** are available on Zenodo:\n\n[](https://doi.org/10.5281/zenodo.15697296)\n\n## \ud83d\udd27 CLI Commands\n\nFlatProt provides four main commands:\n\n- `flatprot project` - Create 2D SVG projections from protein structures\n- `flatprot align` - Align protein structures using rotation\n- `flatprot overlay` - Create overlay visualizations from multiple structures\n- `flatprot split` - Extract and align structural regions for comparison\n\nSee the [CLI documentation](https://t03i.github.io/FlatProt/commands/project/) for detailed usage.\n\n## \ud83d\udd04 Common Workflows\n\n**Note:** The following examples assume you've installed FlatProt with `uv tool add FlatProt`. If you're using the no-install option, replace `flatprot` with `uvx flatprot` in all commands.\n\n### Single Structure Visualization\n```bash\n# AlphaFold structures (recommended - no preprocessing needed!)\nflatprot project AF-P69905-F1-model_v4.cif --output protein_2d.svg\n\n# Traditional PDB/CIF files (requires DSSP preprocessing)\nmkdssp your_protein.cif your_protein_with_dssp.cif\nflatprot project your_protein_with_dssp.cif --output protein_2d.svg\n```\n\n### Aligned Structure Visualization\n```bash\n# 1. Find optimal family alignment\nflatprot align protein.cif -m alignment_matrix.npy\n\n# 2. Create aligned 2D projection\nflatprot project protein.cif --matrix alignment_matrix.npy -o aligned_protein.svg\n```\n\n### Family Comparison Workflow\n```bash\n# 1. Find optimal alignment for family\nflatprot align reference_protein.cif -i family_info.json\n\n# 2. Extract family ID from results\nfamily_id=$(jq -r '.best_hit.target_id' family_info.json)\n\n# 3. Create conserved overlay using fixed family ID\nflatprot overlay \"family_proteins/*.cif\" --family \"$family_id\" -o family_overlay.png\n```\n\n### Domain Analysis Workflow\n```bash\n# 1. Create full structure view\nflatprot project protein.cif -o full_structure.svg\n\n# 2. Extract and align specific domains\nflatprot split protein.cif --regions \"A:1-100,A:150-250\" --show-database-alignment -o domains.svg\n\n# 3. Create domain overlay for comparison\nflatprot overlay \"domain_structures/*.cif\" --family 3000114 -o domain_comparison.png\n```\n\n### Custom Alignment Workflow\n```bash\n# 1. Generate alignment matrix from first structure\nflatprot align reference.cif -m alignment_matrix.npy\n\n# 2. Apply same alignment to all structures\nfor file in *.cif; do\n flatprot project \"$file\" --matrix alignment_matrix.npy -o \"aligned_${file%.cif}.svg\"\ndone\n```\n\n\n## License\n\nFlatProt is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for more details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package for creating simplified 2D protein visualizations. Specialized on showing differences and similarities between proteins of the same protein family.",
"version": "2.4.9",
"project_urls": {
"Documentation": "https://t03i.github.io/FlatProt/",
"Repository": "https://github.com/t03i/FlatProt",
"Zenodo": "https://doi.org/10.5281/zenodo.15264810"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5299365837be0e1b862dea9fba780b96fe40b0095059040742af931565a475b2",
"md5": "ba6a623b71f11d87885151e35f02750a",
"sha256": "c5c489f5d83e78aab3f6828886aa41236ccdfce1cd1f29ab5f0fc82cb9dd1fbb"
},
"downloads": -1,
"filename": "flatprot-2.4.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba6a623b71f11d87885151e35f02750a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 141498,
"upload_time": "2025-07-31T08:51:26",
"upload_time_iso_8601": "2025-07-31T08:51:26.538081Z",
"url": "https://files.pythonhosted.org/packages/52/99/365837be0e1b862dea9fba780b96fe40b0095059040742af931565a475b2/flatprot-2.4.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fdec61157594aaef4dca5c45b6e2e77fbd7cbd214b8b9e5e686e28003aeca163",
"md5": "39f750e2ed9951551a5ba86ae29a0c56",
"sha256": "4545a51c88275f0a7e792c201574587b53100c46afe3721be082605bb99d81df"
},
"downloads": -1,
"filename": "flatprot-2.4.9.tar.gz",
"has_sig": false,
"md5_digest": "39f750e2ed9951551a5ba86ae29a0c56",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 28594093,
"upload_time": "2025-07-31T08:51:29",
"upload_time_iso_8601": "2025-07-31T08:51:29.283801Z",
"url": "https://files.pythonhosted.org/packages/fd/ec/61157594aaef4dca5c45b6e2e77fbd7cbd214b8b9e5e686e28003aeca163/flatprot-2.4.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 08:51:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "t03i",
"github_project": "FlatProt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flatprot"
}
